Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## net.jini.jeri.http
Class HttpEndpoint

    java.lang.Object
      net.jini.jeri.http.HttpEndpoint

All Implemented Interfaces:
  Endpoint, Serializable, 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
See Also:
  `HttpServerEndpoint`, Serialized Form

Method Summary
`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. 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.
`String` | `toString()` Returns a string representation of this `HttpEndpoint`.

Methods inherited from class java.lang.Object
`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

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`

### 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 the `HttpEndpoint` that produced this iterator if non-`null`, or it will create a `Socket` directly otherwise.

  > If there is a security manager, its `checkConnect` method will be invoked with the remote IP address and port of the `Socket` to be used for the communication; this could result in a `SecurityException`.

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

  > Throws `ConnectException` if a failure occurs while connecting a socket to the remote host and port, such as if the connection was refused (no entity is listening on that port or the host is too busy).

  > Throws `IOException` if an I/O exception occurs while performing this operation.

  > Throws `SecurityException` if there is a security manager and the 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`

### hashCode

    public int hashCode()

  Returns the hash code value for this `HttpEndpoint`.

  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

  - the specified object is also an `HttpEndpoint`,
  - the host and port in the specified object are equal to the host and port in this object, and
  - either this object and the specified object both have no `SocketFactory` or the `SocketFactory` in the specified object has the same class and is equal to the one in this 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

  - the specified object is also an `HttpEndpoint`,
  - the host and port in the specified object are equal to the host and port in this object, and
  - either this object and the specified object both have no `SocketFactory` or the `SocketFactory` in the specified object has the same class and is equal to the one in this object.

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

  Returns:
    a string representation of this `HttpEndpoint`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2004 Sun Microsystems, Inc. All rights reserved