net.jini.jeri.http
Class HttpEndpoint

java.lang.Object
  extended by net.jini.jeri.http.HttpEndpoint
All Implemented Interfaces:
Serializable, Endpoint, TrustEquivalence

public final class HttpEndpoint
extends Object
implements Endpoint, TrustEquivalence, Serializable

An implementation of the 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.

Since:
2.0
Author:
Sun Microsystems, Inc.
See Also:
HttpServerEndpoint, Serialized Form

Nested Class Summary
private  class HttpEndpoint.Connection
          HTTP connection for sending requests.
private static interface HttpEndpoint.ConnectionAction
          Describes an action to be performed on a Connection.
private static class HttpEndpoint.SocketFactoryAdapter
          SocketFactory -> HttpClientSocketFactory adapter.
 
Field Summary
private static HttpClientManager clientManager
          HTTP client manager
private  Set connections
          idle connection cache
private static ConnectionTimer connTimer
          idle connection timer
private  String host
          The host that this HttpEndpoint connects to.
private static Map internTable
          set of canonical instances
private static Logger logger
          client transport logger
private  boolean persist
          true if using persistent connections
private  int port
          The TCP port that this HttpEndpoint connects to.
private  String proxyHost
          current proxy host, or empty string if not proxied
private  int proxyPort
          current proxy port, or -1 if not proxied
private static long serialVersionUID
           
private  SocketFactory sf
          The socket factory that this HttpEndpoint uses to create Socket objects.
private  long timeLastVerified
          Time at which the server endpoint was last pinged.
 
Constructor Summary
private HttpEndpoint(String host, int port, SocketFactory sf)
          Constructs a new (not fully initialized) instance.
 
Method Summary
private  void checkResolvePermission()
           
 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.
private  Object connectionAction(Constraints.Distilled distilled, String phost, int pport, boolean ppersist, HttpEndpoint.ConnectionAction action)
          Find an existing connection and perform the specified action on the connection.
 boolean equals(Object obj)
          Compares the specified object with this HttpEndpoint for equality.
 String getHost()
          Returns the host that this HttpEndpoint connects to.
(package private) static HttpSettings getHttpSettings()
          Returns current HTTP system property settings.
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.
private  void init()
          Initializes new instance obtained either from private constructor or deserialization.
private static HttpEndpoint intern(HttpEndpoint endpoint)
          Returns canonical instance equivalent to given instance.
 OutboundRequestIterator newRequest(InvocationConstraints constraints)
          Returns an OutboundRequestIterator to use to send a new request to this remote endpoint using the specified constraints.
private  OutboundRequest nextRequest(Constraints.Distilled distilled)
           
private  OutboundRequest nextRequest(InvocationConstraints constraints)
           
private  void readObject(ObjectInputStream in)
           
private  Object readResolve()
           
private static void setSocketOptions(Socket socket)
          Attempts to set desired socket options for a connected socket (TCP_NODELAY and SO_KEEPALIVE); ignores SocketException.
private  void shedConnections()
          Closes all idle connections cached by this HTTP endpoint.
 String toString()
          Returns a string representation of this HttpEndpoint.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

serialVersionUID

private static final long serialVersionUID
See Also:
Constant Field Values

internTable

private static final Map internTable
set of canonical instances


clientManager

private static final HttpClientManager clientManager
HTTP client manager


connTimer

private static final ConnectionTimer connTimer
idle connection timer


logger

private static final Logger logger
client transport logger


host

private final String host
The host that this HttpEndpoint connects to.


port

private final int port
The TCP port that this HttpEndpoint connects to.


sf

private final SocketFactory sf
The socket factory that this HttpEndpoint uses to create Socket objects.


connections

private transient Set connections
idle connection cache


proxyHost

private transient String proxyHost
current proxy host, or empty string if not proxied


proxyPort

private transient int proxyPort
current proxy port, or -1 if not proxied


persist

private transient boolean persist
true if using persistent connections


timeLastVerified

private transient long timeLastVerified
Time at which the server endpoint was last pinged.

Constructor Detail

HttpEndpoint

private HttpEndpoint(String host,
                     int port,
                     SocketFactory sf)
Constructs a new (not fully initialized) instance.

Method Detail

getInstance

public static HttpEndpoint getInstance(String host,
                                       int port)
Returns an 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.

Parameters:
host - the host for the endpoint to connect to
port - the TCP port on the given host for the endpoint to connect to
Returns:
an HttpEndpoint instance
Throws:
IllegalArgumentException - if the port number is out of the range 1 to 65535 (inclusive)
NullPointerException - if host is null

getInstance

public 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. 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.

Parameters:
host - the host for the endpoint to connect to
port - the TCP port on the given host for the endpoint to connect to
sf - the SocketFactory to use for this HttpEndpoint, or null
Returns:
an HttpEndpoint instance
Throws:
IllegalArgumentException - if the port number is out of the range 1 to 65535 (inclusive)
NullPointerException - if host is null

intern

private static HttpEndpoint intern(HttpEndpoint endpoint)
Returns canonical instance equivalent to given instance.


readResolve

private Object readResolve()

init

private void init()
Initializes new instance obtained either from private constructor or deserialization.


getHost

public String getHost()
Returns the host that this HttpEndpoint connects to.

Returns:
the host that this endpoint connects to

getPort

public int getPort()
Returns the TCP port that this HttpEndpoint connects to.

Returns:
the TCP port that this endpoint connects to

getSocketFactory

public SocketFactory getSocketFactory()
Returns the SocketFactory that this endpoint uses to create Socket objects.

Returns:
the socket factory that this endpoint uses to create sockets, or null if this endpoint creates sockets directly

newRequest

public OutboundRequestIterator newRequest(InvocationConstraints constraints)
Returns an 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 the createSocket methods on the SocketFactory of this HttpEndpoint (which produced this iterator) if non-null, or it will create a Socket 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, this HttpEndpoint'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 IOException or (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 IOException or a 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.getAllByName would throw an UnknownHostException), the implementation still makes an attempt to connect the Socket to that host name, which could result in an UnknownHostException. If the final connection attempt fails with an IOException or a 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 SecurityException.

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 this HttpEndpoint'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 checkConnect method is invoked with this HttpEndpoint's host and -1 for the port; if this results in a SecurityException, 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 a SecurityException for that attempt. (Note that the implementation may carry out these security checks indirectly, such as through invocations of InetAddress.getAllByName or Socket's constructors or connect 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 this HttpEndpoint's host and -1 for the port without resulting in a SecurityException, and it also must be possible to invoke checkConnect with the remote IP address and port of the Socket without 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.

Throws NoSuchElementException if this iterator does not support making another attempt to communicate the request (that is, if hasNext would return false).

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 its checkConnect method fails.

Specified by:
newRequest in interface Endpoint
Parameters:
constraints - the complete, absolute constraints
Returns:
an OutboundRequestIterator to use to send a new request to this remote endpoint
Throws:
NullPointerException - if constraints is null

nextRequest

private OutboundRequest nextRequest(InvocationConstraints constraints)
                             throws IOException
Throws:
IOException

connectionAction

private Object connectionAction(Constraints.Distilled distilled,
                                String phost,
                                int pport,
                                boolean ppersist,
                                HttpEndpoint.ConnectionAction action)
                         throws IOException
Find an existing connection and perform the specified action on the connection. If there is no suitable existing connection, then create a connection meeting the specified constraints and perform the specified action on the connection.

Throws:
IOException

nextRequest

private OutboundRequest nextRequest(Constraints.Distilled distilled)
                             throws IOException
Throws:
IOException

shedConnections

private void shedConnections()
Closes all idle connections cached by this HTTP endpoint.


checkResolvePermission

private void checkResolvePermission()

hashCode

public int hashCode()
Returns the hash code value for this HttpEndpoint.

Overrides:
hashCode in class Object
Returns:
the hash code value for this HttpEndpoint

equals

public boolean equals(Object obj)
Compares the specified object with this HttpEndpoint for equality.

This method returns true if and only if

Overrides:
equals in class Object
Parameters:
obj - the object to compare with
Returns:
true if obj is equivalent to this object; false otherwise

checkTrustEquivalence

public 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.

This method returns true if and only if

Specified by:
checkTrustEquivalence in interface TrustEquivalence
Parameters:
obj - object to check that is not yet known to be trusted
Returns:
true if 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 false otherwise

toString

public String toString()
Returns a string representation of this HttpEndpoint.

Overrides:
toString in class Object
Returns:
a string representation of this HttpEndpoint

readObject

private void readObject(ObjectInputStream in)
                 throws IOException,
                        ClassNotFoundException
Throws:
InvalidObjectException - if the host name is null or if the port number is out of the range 1 to 65535 (inclusive)
IOException
ClassNotFoundException

getHttpSettings

static HttpSettings getHttpSettings()
Returns current HTTP system property settings.


setSocketOptions

private static void setSocketOptions(Socket socket)
Attempts to set desired socket options for a connected socket (TCP_NODELAY and SO_KEEPALIVE); ignores SocketException.



Copyright 2007-2010, multiple authors.
Licensed under the Apache License, Version 2.0, see the NOTICE file for attributions.