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.tcp
Class TcpServerEndpoint

    java.lang.Object
      net.jini.jeri.tcp.TcpServerEndpoint

All Implemented Interfaces:
  ServerCapabilities, ServerEndpoint

public final class TcpServerEndpoint
extends Object
implements ServerEndpoint

An implementation of the `ServerEndpoint` abstraction that uses TCP sockets (instances of `ServerSocket`) for the underlying communication mechanism.

`TcpServerEndpoint` instances contain a host name and a TCP port number, as well as an optional `ServerSocketFactory` for customizing the type of `ServerSocket` to use and an optional `SocketFactory` for customizing the type of `Socket` that client endpoints will use. The port number is the local TCP port to bind to when listening for incoming socket connections. If the port number is zero, then each listen operation will bind to a free (non-zero) port, which will be the port number contained in the resulting `TcpEndpoint`. The host name contained in a `TcpServerEndpoint` controls the host name that will be contained in the `TcpEndpoint` instances produced when `enumerateListenEndpoints` is invoked to listen on the `TcpServerEndpoint` (this host name does not affect the behavior of listen operations themselves). If the host name in a `TcpServerEndpoint` is `null`, then the host name in the `TcpEndpoint` instances that it produces will be the IP address string obtained from `InetAddress.getLocalHost` when `enumerateListenEndpoints` is invoked.

`TcpServerEndpoint` uses the Jini(TM) extensible remote invocation (Jini ERI) multiplexing protocol to map incoming requests to socket connections.

A `ServerSocketFactory` used with a `TcpServerEndpoint` must implement `Object.equals` to obey the guidelines that are specified for `equals` methods of `ListenEndpoint` instances. A `SocketFactory` used with a `TcpServerEndpoint` 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:
  `TcpEndpoint`

Nested Class Summary

Nested classes inherited from class net.jini.jeri.ServerEndpoint
`ServerEndpoint.ListenContext, ServerEndpoint.ListenCookie, ServerEndpoint.ListenEndpoint, ServerEndpoint.ListenHandle`

Method Summary
`InvocationConstraints` | `checkConstraints(InvocationConstraints constraints)` Verifies that this instance supports the transport layer aspects of all of the specified requirements (both in general and in the current security context), and returns the requirements that must be at least partially implemented by higher layers in order to fully satisfy all of the specified requirements. This method may also return preferences that must be at least partially implemented by higher layers in order to fully satisfy some of the specified preferences. For any given constraint, there must be a clear delineation of which aspects (if any) must be implemented by the transport layer. This method must not return a constraint (as a requirement or a preference, directly or as an element of another constraint) unless this instance can implement all of those aspects. Also, this method must not return a constraint for which all aspects must be implemented by the transport layer. Most of the constraints in the `net.jini.core.constraint` package must be fully implemented by the transport layer and thus must not be returned by this method; the one exception is `Integrity`, for which the transport layer is responsible for the data integrity aspect and higher layers are responsible for the code integrity aspect. For any `ConstraintAlternatives` in the specified constraints, this method should only return a corresponding constraint if all of the alternatives supported by this instance need to be at least partially implemented by higher layers in order to be fully satisfied. The constraints passed to this method may include constraints based on relative time.
`Endpoint` | `enumerateListenEndpoints(ServerEndpoint.ListenContext listenContext)` Passes the `ListenEndpoint` for this `TcpServerEndpoint` to `listenContext`, which will ensure an active listen operation on the endpoint, and returns a `TcpEndpoint` instance corresponding to the listen operation chosen by `listenContext`.
`boolean` | `equals(Object obj)` Compares the specified object with this `TcpServerEndpoint` for equality.
`String` | `getHost()` Returns the host name that will be used in `TcpEndpoint` instances produced by listening on this `TcpServerEndpoint`, or `null` if the IP address string obtained from `InetAddress.getLocalHost` will be used.
`static TcpServerEndpoint` | `getInstance(int port)` Returns a `TcpServerEndpoint` instance for the given TCP port number.
`static TcpServerEndpoint` | `getInstance(String host, int port)` Returns a `TcpServerEndpoint` instance for the given host name and TCP port number.
`static TcpServerEndpoint` | `getInstance(String host, int port, SocketFactory sf, ServerSocketFactory ssf)` Returns a `TcpServerEndpoint` instance for the given host name and TCP port number that contains the given `SocketFactory` and `ServerSocketFactory`.
`int` | `getPort()` Returns the TCP port that this `TcpServerEndpoint` listens on.
`ServerSocketFactory` | `getServerSocketFactory()` Returns the `ServerSocketFactory` that this endpoint uses to create `ServerSocket` objects.
`SocketFactory` | `getSocketFactory()` Returns the `SocketFactory` that `TcpEndpoint` objects produced by listening on this `TcpServerEndpoint` will use to create `Socket` objects.
`int` | `hashCode()` Returns the hash code value for this `TcpServerEndpoint`.
`String` | `toString()` Returns a string representation of this `TcpServerEndpoint`.

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

Method Detail

### getInstance

    public static TcpServerEndpoint getInstance(int port)

  Returns a `TcpServerEndpoint` instance for the given TCP port number.

  The host name contained in the returned `TcpServerEndpoint` will be `null`, so that when its `enumerateListenEndpoints` method produces a `TcpEndpoint`, the `TcpEndpoint`'s host name will be the IP address string obtained from `InetAddress.getLocalHost`.

  The `ServerSocketFactory` contained in the returned `TcpServerEndpoint` will be `null`, indicating that this endpoint will create `ServerSocket` objects directly. The `SocketFactory` contained in the returned `TcpServerEndpoint` will also be `null`.

  Parameters:
    `port` - the TCP port on the local host to listen on
  Returns:
    a `TcpServerEndpoint` instance
  Throws:
    `IllegalArgumentException` - if the port number is out of the range `0` to `65535` (inclusive)

### getInstance

    public static TcpServerEndpoint getInstance(String host,
                                                int port)

  Returns a `TcpServerEndpoint` instance for the given host name and TCP port number.

  If `host` is `null`, then when the returned `TcpServerEndpoint`'s `enumerateListenEndpoints` method produces a `TcpEndpoint`, the `TcpEndpoint`'s host name will be the IP address string obtained from `InetAddress.getLocalHost`.

  The `ServerSocketFactory` contained in the returned `TcpServerEndpoint` will be `null`, indicating that this endpoint will create `ServerSocket` objects directly. The `SocketFactory` contained in the returned `TcpServerEndpoint` will also be `null`.

  Parameters:
    `host` - the host name to be used in `TcpEndpoint` instances produced by listening on the returned `TcpServerEndpoint`, or `null`
    `port` - the TCP port on the local host to listen on
  Returns:
    a `TcpServerEndpoint` instance
  Throws:
    `IllegalArgumentException` - if the port number is out of the range `0` to `65535` (inclusive)

### getInstance

    public static TcpServerEndpoint getInstance(String host,
                                                int port,
                                                SocketFactory sf,
                                                ServerSocketFactory ssf)

  Returns a `TcpServerEndpoint` instance for the given host name and TCP port number that contains the given `SocketFactory` and `ServerSocketFactory`.

  If `host` is `null`, then when the returned `TcpServerEndpoint`'s `enumerateListenEndpoints` method produces a `TcpEndpoint`, the `TcpEndpoint`'s host name will be the IP address string obtained from `InetAddress.getLocalHost`.

  If the server socket factory argument is `null`, then this endpoint will create `ServerSocket` objects directly.

  Parameters:
    `host` - the host name to be used in `TcpEndpoint` instances produced by listening on the returned `TcpServerEndpoint`, or `null`
    `port` - the TCP port on the local host to listen on
    `sf` - the `SocketFactory` to use for this `TcpServerEndpoint`, or `null`
    `ssf` - the `ServerSocketFactory` to use for this `TcpServerEndpoint`, or `null`
  Returns:
    a `TcpServerEndpoint` instance
  Throws:
    `IllegalArgumentException` - if the port number is out of the range `0` to `65535` (inclusive)

### getHost

    public String getHost()

  Returns the host name that will be used in `TcpEndpoint` instances produced by listening on this `TcpServerEndpoint`, or `null` if the IP address string obtained from `InetAddress.getLocalHost` will be used.

  Returns:
    the host name to use in `TcpEndpoint` instances produced from this object, or `null`

### getPort

    public int getPort()

  Returns the TCP port that this `TcpServerEndpoint` listens on.

  Returns:
    the TCP port that this endpoint listens on

### getSocketFactory

    public SocketFactory getSocketFactory()

  Returns the `SocketFactory` that `TcpEndpoint` objects produced by listening on this `TcpServerEndpoint` will use to create `Socket` objects.

  Returns:
    the socket factory that client-side endpoints corresponding to this server endpoint will use to create sockets, or `null` if no factory will be used

### getServerSocketFactory

    public ServerSocketFactory getServerSocketFactory()

  Returns the `ServerSocketFactory` that this endpoint uses to create `ServerSocket` objects.

  Returns:
    the socket factory that this endpoint uses to create sockets, or `null` if no factory is used

### checkConstraints

    public InvocationConstraints checkConstraints(InvocationConstraints constraints)
                                           throws UnsupportedConstraintException

  Verifies that this instance supports the transport layer aspects of all of the specified requirements (both in general and in the current security context), and returns the requirements that must be at least partially implemented by higher layers in order to fully satisfy all of the specified requirements. This method may also return preferences that must be at least partially implemented by higher layers in order to fully satisfy some of the specified preferences.

  For any given constraint, there must be a clear delineation of which aspects (if any) must be implemented by the transport layer. This method must not return a constraint (as a requirement or a preference, directly or as an element of another constraint) unless this instance can implement all of those aspects. Also, this method must not return a constraint for which all aspects must be implemented by the transport layer. Most of the constraints in the `net.jini.core.constraint` package must be fully implemented by the transport layer and thus must not be returned by this method; the one exception is `Integrity`, for which the transport layer is responsible for the data integrity aspect and higher layers are responsible for the code integrity aspect.

  For any `ConstraintAlternatives` in the specified constraints, this method should only return a corresponding constraint if all of the alternatives supported by this instance need to be at least partially implemented by higher layers in order to be fully satisfied.

  The constraints passed to this method may include constraints based on relative time.

  Specified by:
    `checkConstraints` in interface `ServerCapabilities`
  Parameters:
    `constraints` - the constraints that must be supported
  Returns:
    the constraints that must be at least partially implemented by higher layers
  Throws:
    `NullPointerException` - if `constraints` is `null`
    `UnsupportedConstraintException` - if the transport layer aspects of any of the specified requirements are not supported by this instance (either in general or in the current security context)

### enumerateListenEndpoints

    public Endpoint enumerateListenEndpoints(ServerEndpoint.ListenContext listenContext)
                                      throws IOException

  Passes the `ListenEndpoint` for this `TcpServerEndpoint` to `listenContext`, which will ensure an active listen operation on the endpoint, and returns a `TcpEndpoint` instance corresponding to the listen operation chosen by `listenContext`.

  If this `TcpServerEndpoint`'s host name is not `null`, then the returned `TcpEndpoint` will contain that host name. If this `TcpServerEndpoint`'s host name is `null`, then this method invokes `InetAddress.getLocalHost` to obtain an `InetAddress` for the local host. If `InetAddress.getLocalHost` throws an exception, this method throws that exception. The returned `TcpEndpoint`'s host name will be the string returned by invoking `getHostAddress` on that `InetAddress`. If there is a security manager, its `checkConnect` method will be invoked with the string returned by invoking `getHostName` on that same `InetAddress` as the host argument and `-1` as the port argument; this could result in a `SecurityException`.

  This method invokes `addListenEndpoint` on `listenContext` once, passing a `ListenEndpoint` as described below. If `addListenEndpoint` throws an exception, then this method throws that exception. Otherwise, this method returns a `TcpEndpoint` instance with the host name described above, the TCP port number bound by the listen operation represented by the `ListenHandle` returned by `addListenEndpoint`, and the same `SocketFactory` as this `TcpServerEndpoint`.

  The `ListenEndpoint` passed to `addListenEndpoint` represents the TCP port number and `ServerSocketFactory` of this `TcpServerEndpoint`. Its methods behave as follows:

  `ListenHandle listen(RequestDispatcher)`:

  > Listens for requests received on this endpoint's TCP port, dispatching them to the supplied `RequestDispatcher` in the form of `InboundRequest` instances.

  > When the implementation of this method needs to create a new `ServerSocket`, it will do so by invoking one of the `createServerSocket` methods that returns a bound server socket on the contained `ServerSocketFactory` if non-`null`, or it will create a `ServerSocket` directly otherwise.

  > If there is a security manager, its `checkListen` method will be invoked with this endpoint's TCP port; this could result in a `SecurityException`. Furthermore, before a given `InboundRequest` gets dispatched to the supplied request dispatcher, the security manager's `checkAccept` method must have been successfully invoked in the security context of this `listen` invocation with the remote IP address and port of the `Socket` used to receive the request. The `checkPermissions` method of the dispatched `InboundRequest` also performs this latter security check. (Note that in some cases, the implementation may carry out these security checks indirectly, such as through invocations of `ServerSocket`'s constructors or `accept` method.)

  > Requests will be dispatched in a `PrivilegedAction` wrapped by a `SecurityContext` obtained when this method was invoked, with the `AccessControlContext` of that `SecurityContext` in effect.

  > Dispatched requests will implement `populateContext` to populate the given collection with an element that implements the `ClientHost` interface. That `ClientHost` element implements `getClientHost` to return the IP address of the `Socket` that the request was received over (see `Socket.getInetAddress()`).

  > Throws `IOException` if an I/O exception occurs while performing this operation, such as if the TCP port is already in use.

  > Throws `SecurityException` if there is a security manager and the invocation of its `checkListen` method fails.

  > Throws `NullPointerException` if `requestDispatcher` is `null`

  `void checkPermissions()`:

  > Verifies that the current security context has all of the security permissions necessary to listen for requests on this endpoint.

  > If there is a security manager, its `checkListen` method will be invoked with this endpoint's TCP port; this could result in a `SecurityException`.

  > Throws `SecurityException` if there is a security manager and the invocation of its `checkListen` method fails.

  `boolean equals(Object)`:

  > Compares the specified object with this `ListenEndpoint` for equality.

  > This method returns `true` if and only if

  > - the specified object is also a `ListenEndpoint` produced by a `TcpServerEndpoint`,
  > - the port in the specified object is equal to the port in this object, and
  > - either this object and the specified object both have no `ServerSocketFactory` or the `ServerSocketFactory` in the specified object has the same class and is equal to the one in this object.

  Specified by:
    `enumerateListenEndpoints` in interface `ServerEndpoint`
  Parameters:
    `listenContext` - the `ListenContext` to pass this `TcpServerEndpoint`'s `ListenEndpoint` to
  Returns:
    the `TcpEndpoint` instance for sending requests to this `TcpServerEndpoint`'s endpoint being listened on
  Throws:
    `UnknownHostException` - if this `TcpServerEndpoint`'s host name is `null` and `InetAddress.getLocalHost` throws an `UnknownHostException`
    `IOException` - if an I/O exception occurs while performing this operation, such as if the TCP port is already in use
    `SecurityException` - if there is a security manager and either the invocation of its `checkListen` method fails or this `TcpServerEndpoint`'s host name is `null` and the invocation of the security manager's `checkConnect` method fails
    `IllegalArgumentException` - if an invocation of the `addListenEndpoint` method on the supplied `ListenContext` returns a `ListenCookie` that does not correspond to the `ListenEndpoint` that was passed to it
    `NullPointerException` - if `listenContext` is `null`

### hashCode

    public int hashCode()

  Returns the hash code value for this `TcpServerEndpoint`.

  Returns:
    the hash code value for this `TcpServerEndpoint`

### equals

    public boolean equals(Object obj)

  Compares the specified object with this `TcpServerEndpoint` for equality.

  This method returns `true` if and only if

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

### toString

    public String toString()

  Returns a string representation of this `TcpServerEndpoint`.

  Returns:
    a string representation of this `TcpServerEndpoint`

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