public final class HttpsEndpoint extends Object implements Endpoint, Serializable, TrustEquivalence
Endpointthat uses HTTPS (HTTP over TLS/SSL) to support invocation constraints for communication through firewalls.
SslTrustVerifier trust verifier may be used for establishing
trust in remote proxies that use instances of this class.
This class supports at least the following constraints, possibly limited by the available cipher suites:
ClientMaxPrincipal, when it contains an
ClientMaxPrincipalType, when it contains
ClientMinPrincipal, when it contains a single
ClientMinPrincipalType, when it contains
ConfidentialityStrength, a provider-specific constraint for specifying weak or strong confidentiality
ConstraintAlternatives, if the elements all have the same actual class and at least one element is supported
Delegation.YES, trivially, for anonymous clients
DelegationAbsoluteTime, trivially, when delegation is not supported
ServerMinPrincipal, when it contains a single
getTypemethod returns "X.509", and for which calling
getSubjectDNon the certificate chain's first element returns that principal's name
X500PrivateCredential, stored as a private credential, whose
getCertificatemethod returns a value equal to the first element of the certificate chain, and whose
getPrivateKeymethod returns the associated private key
In addition, this class's
newRequest method will only
authenticate as a given principal if the caller has been granted
AuthenticationPermission with that principal as the local principal, the
principal representing the authenticated identity of the server as the peer
principal, and the
This class supports remote connections between authenticated servers and
authenticated or anonymous clients, and between anonymous servers and
anonymous clients. Connections between anonymous servers and authenticated
clients are not supported. Because of the suites available in the TLS/SSL
protocol, support for
Confidentiality.NO requires the server to
authenticate with an RSA public key.
This class permits specifying a
SocketFactory for creating the
Socket instances that it uses to make remote connections. These
socket factories should not be instances of
SSLSocket; it is the responsibility of the
implementation to establish a TLS/SSL connection over the socket it obtains
from the socket factory.
This class recognizes the following system properties:
*' wildcard characters in any position to match zero or more of any characters within the name. Multiple host names may be specified by separating the names with '
|' characters. The default is for all connections to use the proxy server if one is specified.
SslTrustVerifier, Serialized Form
This implementation uses the
ConnectionManager class to manage
This implementation uses the following
Logger instances in the
| ||problems with initializing JSSE|
| ||problems with outbound requests|
| ||exceptions caught involving authentication|
| ||authentication decisions; creating, choosing, expiring, or closing connections; or handling outbound requests|
| ||low level operation tracing|
This implementation uses the following security providers:
SSLContext, with the protocol specified by the
org.apache.river.jeri.ssl.sslProtocolsystem property, or
"TLS"if that property is not defined, to provide the TLS/SSL implementation. The
SSLContext.initmethod is called with
randomparameter to use the default
CertificateFactory, with type
"X.509", to generate
CertPathinstances from X.509 certificate chains
TrustManagerFactory, with the algorithm specified by the
org.apache.river.jeri.ssl.trustManagerFactoryAlgorithmsystem property, or the default algorithm if that property is not defined, to implement trust management for the TLS/SSL implementation. The factory must return trust managers that implement
The JSSE documentation also describes the system properties for configuring the location, type, and password of the truststore that this implementation uses, through JSSE, to make decisions about what certificate chains should be trusted.
This implementation recognizes the following system properties:
org.apache.river.jeri.ssl.maxClientSessionDuration- The maximum number of milliseconds a client-side TLS/SSL session should be used. The default is 23.5 hours. The value should be smaller than the maximum server session duration to allow the client to negotiate a new session before the server timeout occurs.
org.apache.river.jeri.ssl.sslProtocol- The secure socket protocol used when obtaining
SSLContextinstances. The default is
org.apache.river.jeri.ssl.trustManagerFactoryAlgorithm- The algorithm used when obtaining
TrustManagerFactoryinstances. The default is the value returned by
org.apache.river.jeri.ssl.cipherSuites- The TLS/SSL cipher suites that should be used for communication. The default is the list of suites supported by the JSSE implementation. The value should specify the suite names, separated by commas. The value will be ignored if it contains no suites or specifies suites that are not supported by the JSSE implementation. Suites appearing earlier in the list will be preferred to ones appearing later for suites that support the same requirements and preferences.
org.apache.river.jeri.https.idleConnectionTimeout- The number of milliseconds to retain idle client-side HTTPS connections before closing them. The default is
org.apache.river.jeri.https.responseAckTimeout- The number of milliseconds to keep track of acknowledgments that have not yet been sent for
AcknowledgmentSourceinstances. The default is
org.apache.river.jeri.https.pingProxyConnections- If the value is case-insensitive equal to
true, then if an HTTP proxy is being used, ping the server endpoint to verify whether it is alive and reachable. The ping occurs before the first request and before each subsequent request which follows the expiration of the ping proxy timeout period (below) following the previous ping. When using an HTTP proxy it is often impossible to distinguish between inability to reach the server endpoint (such as because the server process refused a connection by the HTTP proxy) and the lack of response from a delivered request (which might result in an UnmarshalException). The ping increases the likelihood that the inability to reach the server endpoint can be explicitly identified. The default value is
false, and no pings are done.
org.apache.river.jeri.https.pingProxyConnectionTimeout- The number of milliseconds from the time a server endpoint was last pinged before a ping will precede the next request. The default is
Long.MAX_VALUE(essentially meaning, ping only before the first request).
|Modifier and Type||Method and Description|
Two instances of this class are equal if they have the same values for server host and port; and have socket factories that are either both
Returns the server host that this endpoint connects to.
Returns an HTTPS endpoint for the specified server host and port.
Returns an HTTPS endpoint for the specified server host, port, and socket factory.
Returns the TCP port that this endpoint connects to.
Returns the socket factory that this endpoint uses to create
Returns a hash code value for this object.
Returns a string representation of this object.
public static HttpsEndpoint getInstance(String serverHost, int port)
nullsocket factory to create default sockets.
public static HttpsEndpoint getInstance(String serverHost, int port, SocketFactory socketFactory)
nulluses default sockets.
public String getHost()
public int getPort()
public SocketFactory getSocketFactory()
nullif it uses default sockets.
nullif it uses default sockets
public String toString()
public int hashCode()
public boolean equals(Object object)
null, or have the same actual class and are equal.
public OutboundRequestIterator newRequest(InvocationConstraints constraints)
OutboundRequestIteratorto use to send a new request to this remote endpoint using the specified constraints.
The constraints must be the complete, absolute constraints for the request.
next method behaves as follows:
Initiates an attempt to communicate the request to this remote endpoint.
When the implementation of this method needs to create a new
Socket, it will do so by invoking one of the
createSocketmethods on the
HttpsEndpoint(which produced this iterator) if non-
null, or it will create a
When the implementation needs to connect a
Socket, if the host name to connect to (if an HTTP proxy is to be used for the communication, the proxy's host name; otherwise, this
HttpsEndpoint's host name) resolves to multiple addresses (according to
InetAddress.getAllByName), it attempts to connect to the first resolved address; if that attempt fails with an
IOExceptionor (as is possible in the case that an HTTP proxy is not to be used) a
SecurityException, it then attempts to connect to the next address; and this iteration continues as long as there is another resolved address and the attempt to connect to the previous address fails with an
SecurityException. If the host name resolves to just one address, the implementation makes one attempt to connect to that address. If the host name does not resolve to any addresses (
InetAddress.getAllByNamewould throw an
UnknownHostException), the implementation still makes an attempt to connect the
Socketto that host name, which could result in an
UnknownHostException. If the final connection attempt fails with an
SecurityException, then if any connection attempt failed with an
IOException, this method throws an
IOException, and otherwise (if all connection attempts failed with a
SecurityException), this method throws a
If there is a security manager and an HTTP proxy is to be used for the communication, the security manager's
checkConnectmethod is invoked with this
HttpsEndpoint's host and port; if this results in a
SecurityException, this method throws that exception.
If there is a security manager and an HTTP proxy is not to be used for the communication:
- If a new connection is to be created, the security manager's
checkConnectmethod is invoked with this
HttpsEndpoint's host and
-1for the port; if this results in a
SecurityException, this method throws that exception.
checkConnectis also invoked for each connection attempt, with the remote IP address (or the host name, if it could not be resolved) and port to connect to; this could result in a
SecurityExceptionfor that attempt. (Note that the implementation may carry out these security checks indirectly, such as through invocations of
Socket's constructors or
In order to reuse an existing connection for the communication, the current security context must have all of the permissions that would be necessary if the connection were being created. Specifically, it must be possible to invoke
checkConnectin the current security context with this
HttpsEndpoint's host and
-1for the port without resulting in a
SecurityException, and it also must be possible to invoke
checkConnectwith the remote IP address and port of the
Socketwithout resulting in a
SecurityException(if the remote socket address is unresolved, its host name is used instead). If no existing connection satisfies these requirements, then this method must behave as if there are no existing connections.
NoSuchElementExceptionif this iterator does not support making another attempt to communicate the request (that is, if
IOExceptionif an I/O exception occurs while performing this operation, such as if a connection attempt timed out or was refused or there are unsupported or conflicting constraints.
SecurityExceptionif there is a security manager and an invocation of its
checkConnectmethod fails, or if the caller does not have the appropriate
public boolean checkTrustEquivalence(Object obj)
trueif the argument is an instance of
HttpsEndpointwith the same values for server host and port; and either both this instance and the argument have
nullsocket factories, or the factories have the same actual class and are equal; and returns
obj- object to check that is not yet known to be trusted
trueif the specified object (that is not yet known to be trusted) is equivalent in trust, content, and function to this known trusted object, and returns
Copyright 2007-2013, multiple authors.
Licensed under the Apache License, Version 2.0, see the NOTICE file for attributions.