public final class HttpEndpoint extends Object implements Endpoint, TrustEquivalence, Serializable
Endpoint
abstraction that uses HTTP
messages sent over TCP sockets (instances of Socket
) for the
underlying communication mechanism.
HttpEndpoint
instances contain a host name and a
TCP port number, as well as an optional SocketFactory
for
customizing the type of Socket
to use. The host name
and port number are used as the remote address to connect to when
making socket connections. Note that constructing an
HttpEndpoint
with a SocketFactory
instance that produces SSL sockets does not result in an endpoint
that is fully HTTPS capable.
HttpEndpoint
instances map outgoing requests to HTTP
request/response messages; when possible, underlying TCP connections are
reused for multiple non-overlapping outgoing requests. Outbound request
data is sent as the entity-body
of an HTTP POST request;
inbound response data is received as the entity-body
of the
corresponding HTTP response message. For information on HTTP, refer to RFC 2616.
HttpEndpoint
can be configured via system properties to send
HTTP messages through an intermediary HTTP proxy server. It also supports
basic and digest HTTP authentication, specified in RFC 2617. The mechanisms
involved in configuring each of these features are the same as those used by
HttpURLConnection
; for details, see the
net.jini.jeri.http
package documentation.
A SocketFactory
used with an
HttpEndpoint
should be serializable and must implement
Object.equals
to obey the guidelines that are
specified for equals
methods of Endpoint
instances.
HttpServerEndpoint
,
Serialized FormConstructor and Description |
---|
HttpEndpoint(AtomicSerial.GetArg arg)
AtomicSerial constructor.
|
Modifier and Type | Method and Description |
---|---|
boolean |
checkTrustEquivalence(Object obj)
Returns
true if the specified object (which is not
yet known to be trusted) is equivalent in trust, content, and
function to this known trusted object, and false
otherwise. |
boolean |
equals(Object obj)
Compares the specified object with this
HttpEndpoint for equality. |
String |
getHost()
Returns the host that this
HttpEndpoint connects to. |
static HttpEndpoint |
getInstance(String host,
int port)
Returns an
HttpEndpoint instance for the given host name
and TCP port number. |
static HttpEndpoint |
getInstance(String host,
int port,
SocketFactory sf)
Returns an
HttpEndpoint instance for the given
host name and TCP port number that contains the given SocketFactory . |
int |
getPort()
Returns the TCP port that this
HttpEndpoint connects to. |
SocketFactory |
getSocketFactory()
Returns the
SocketFactory that this endpoint uses to
create Socket objects. |
int |
hashCode()
Returns the hash code value for this
HttpEndpoint . |
OutboundRequestIterator |
newRequest(InvocationConstraints constraints)
Returns an
OutboundRequestIterator to use to send
a new request to this remote endpoint using the specified
constraints. |
String |
toString()
Returns a string representation of this
HttpEndpoint . |
public HttpEndpoint(AtomicSerial.GetArg arg) throws IOException
arg
- IOException
public static HttpEndpoint getInstance(String host, int port)
HttpEndpoint
instance for the given host name
and TCP port number. Note that if HTTP proxying is in effect, then an
explicit host name or IP address (i.e., not "localhost") must be
provided, or else the returned HttpEndpoint
will be unable
to properly send requests through the proxy.
The SocketFactory
contained in the returned
HttpEndpoint
will be null
, indicating
that this endpoint will create Socket
objects directly.
host
- the host for the endpoint to connect toport
- the TCP port on the given host for the endpoint to
connect toHttpEndpoint
instanceIllegalArgumentException
- if the port number is out of
the range 1
to 65535
(inclusive)NullPointerException
- if host
is
null
public static HttpEndpoint getInstance(String host, int port, SocketFactory sf)
HttpEndpoint
instance for the given
host name and TCP port number that contains the given SocketFactory
. Note that if HTTP proxying is in effect, then
an explicit host name or IP address (i.e., not "localhost")
must be provided, or else the returned
HttpEndpoint
will be unable to properly send
requests through the proxy.
If the socket factory argument is null
, then
this endpoint will create Socket
objects directly.
host
- the host for the endpoint to connect toport
- the TCP port on the given host for the endpoint to
connect tosf
- the SocketFactory
to use for this
HttpEndpoint
, or null
HttpEndpoint
instanceIllegalArgumentException
- if the port number is out of
the range 1
to 65535
(inclusive)NullPointerException
- if host
is
null
public String getHost()
HttpEndpoint
connects to.public int getPort()
HttpEndpoint
connects to.public SocketFactory getSocketFactory()
SocketFactory
that this endpoint uses to
create Socket
objects.null
if this endpoint creates sockets
directlypublic OutboundRequestIterator newRequest(InvocationConstraints constraints)
OutboundRequestIterator
to 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.
The returned OutboundRequestIterator
's 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 thecreateSocket
methods on theSocketFactory
of thisHttpEndpoint
(which produced this iterator) if non-null
, or it will create aSocket
directly otherwise.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, thisHttpEndpoint
's host name) resolves to multiple addresses (according toInetAddress.getAllByName
), it attempts to connect to the first resolved address; if that attempt fails with anIOException
or (as is possible in the case that an HTTP proxy is not to be used) aSecurityException
, 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 anIOException
or aSecurityException
. 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.getAllByName
would throw anUnknownHostException
), the implementation still makes an attempt to connect theSocket
to that host name, which could result in anUnknownHostException
. If the final connection attempt fails with anIOException
or aSecurityException
, then if any connection attempt failed with anIOException
, this method throws anIOException
, and otherwise (if all connection attempts failed with aSecurityException
), this method throws aSecurityException
.If there is a security manager and an HTTP proxy is to be used for the communication, the security manager's
checkConnect
method is invoked with thisHttpEndpoint
's host and port; if this results in aSecurityException
, 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
checkConnect
method is invoked with thisHttpEndpoint
's host and-1
for the port; if this results in aSecurityException
, this method throws that exception.checkConnect
is 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 aSecurityException
for that attempt. (Note that the implementation may carry out these security checks indirectly, such as through invocations ofInetAddress.getAllByName
orSocket
's constructors orconnect
method.)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
checkConnect
in the current security context with thisHttpEndpoint
's host and-1
for the port without resulting in aSecurityException
, and it also must be possible to invokecheckConnect
with the remote IP address and port of theSocket
without resulting in aSecurityException
(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.Throws
NoSuchElementException
if this iterator does not support making another attempt to communicate the request (that is, ifhasNext
would returnfalse
).Throws
IOException
if an I/O exception occurs while performing this operation, such as if a connection attempt timed out or was refused.Throws
SecurityException
if there is a security manager and an invocation of itscheckConnect
method fails.
newRequest
in interface Endpoint
constraints
- the complete, absolute constraintsOutboundRequestIterator
to use to send
a new request to this remote endpointNullPointerException
- if constraints
is
null
public int hashCode()
HttpEndpoint
.public boolean equals(Object obj)
HttpEndpoint
for equality.
This method returns true
if and only if
HttpEndpoint
,
SocketFactory
or the SocketFactory
in
the specified object has the same class and is equal to the one
in this object.
public boolean checkTrustEquivalence(Object obj)
true
if the specified object (which is not
yet known to be trusted) is equivalent in trust, content, and
function to this known trusted object, and false
otherwise.
This method returns true
if and only if
HttpEndpoint
,
SocketFactory
or the SocketFactory
in
the specified object has the same class and is equal to the one
in this object.
checkTrustEquivalence
in interface TrustEquivalence
Copyright © 2016–2018. All rights reserved.