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 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/interfaces inherited from interface net.jini.jeri.ServerEndpoint

ServerEndpoint.ListenContext, ServerEndpoint.ListenCookie, ServerEndpoint.ListenEndpoint, ServerEndpoint.ListenHandle

Method Summary

Modifier and Type	Method and Description
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.
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 UnknownHostException, this method throws an UnknownHostException. 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.

Overrides:

hashCode in class Object

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.

Overrides:

equals in class 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.

Overrides:

toString in class Object

Returns:

a string representation of this TcpServerEndpoint