net.jini.jeri

Interface ServerEndpoint.ListenEndpoint

Enclosing interface:

ServerEndpoint

public static interface ServerEndpoint.ListenEndpoint

Represents a communication endpoint on the current (local) host to listen for and receive requests on.

A ListenEndpoint instance contains the information necessary to listen for requests on the communication endpoint. For example, a TCP-based ListenEndpoint implementation typically contains the TCP port to listen on. An implementation that supports authentication typically contains the Subject (if any) to use for server authentication.

The listen method can be used to start a listen operation on the communication endpoint that it represents, during which requests received on the endpoint will be dispatched to a supplied RequestDispatcher.

ListenEndpoint instances make up the discrete communication endpoints represented by a ServerEndpoint, and they are passed to a ListenContext as part of a ServerEndpoint.enumerateListenEndpoints invocation.

An instance of this interface should implement Object.equals to return true if and only if the argument is equivalent to the instance in trust, content, and function. The equals method should not invoke comparison methods (such as equals) on any pluggable component without first verifying that the component's implementation is at least as trusted as the implementation of the corresponding component in the equals argument (such as by verifying that the corresponding component objects have the same actual class). If any such verification fails, the equals method should return false without invoking a comparison method on the component. Furthermore, these guidelines should be recursively obeyed by the comparison methods of each such component for its subcomponents. To avoid opening a security hole, implementations should only compare object identity (==) of Subject instances, rather than comparing their contents.

The equivalence relation of a ListenEndpoint should not be a function of any state in an associated ServerEndpoint that only applies to the ServerEndpoint's template for producing Endpoint instances.

Method Summary

Methods

Modifier and Type	Method and Description
void	checkPermissions() Verifies that the current security context has all of the security permissions necessary to listen for requests on this ListenEndpoint.
ServerEndpoint.ListenHandle	listen(RequestDispatcher requestDispatcher) Listens for requests received on the communication endpoint represented by this ListenEndpoint, dispatching them to the supplied RequestDispatcher in the form of InboundRequest instances.

Method Detail

checkPermissions

void checkPermissions()

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

This method should be used when an invocation of ListenEndpoint.listen is used to receive requests for a variety of interested parties, each with potentially different security permissions possibly more limited than those granted to the code managing the shared endpoint, so that the managing code can enforce proper access control for each party.

Throws:

SecurityException - if the current security context does not have the permissions necessary to listen for requests on this ListenEndpoint

See Also:

InboundRequest.checkPermissions()

listen

ServerEndpoint.ListenHandle listen(RequestDispatcher requestDispatcher)
                                   throws IOException

Listens for requests received on the communication endpoint represented by this ListenEndpoint, dispatching them to the supplied RequestDispatcher in the form of InboundRequest instances.

This method starts a continuing listen operation and then immediately returns a ListenHandle that represents the listen operation that was started. For the duration of the listen operation, all requests received on the communication endpoint will be dispatched to the supplied RequestDispatcher as InboundRequest instances. The returned ListenHandle can be used to stop the listen operation and to obtain a ListenCookie to identify the listen operation as the return value of the ListenContext.addListenEndpoint method.

Typically, this method is invoked by a ListenContext implementation when its addListenEndpoint method is called as part of the execution of a ServerEndpoint.enumerateListenEndpoints invocation. The Endpoint instance that can be used to send requests to the communication endpoints represented by the ServerEndpoint (including this ListenEndpoint) is produced by the ServerEndpoint implementation given, in part, the ListenCookie obtained from the ListenHandle returned by this method.

This method verifies that the current security context has all of the security permissions necessary to listen for requests on this ListenEndpoint, as appropriate to the implementation of this interface (see checkPermissions()). Note that in addition to this security check, the implementation of this interface may also perform a further security check per request received (when the origin of a given request is known), to verify that the same security context also has all of the permissions necessary to receive requests from that particular origin (see InboundRequest.checkPermissions()). This interface does not provide an API for determining when such a security check has failed; the behavior will be as if the associated request never occurred.

Implementations of this method should provide robust behavior (such as continuing to listen for requests) in the event that the supplied RequestDispatcher's dispatch method throws an unchecked exception.

Requests may be dispatched in separate threads as necessary for requests received on this ListenEndpoint while others are still being processed by earlier dispatch invocations. The implementation of this interface must assume that there may be arbitrary execution dependencies between the processing of such concurrently received requests, and thus it must not attempt any particular serialization of their processing; therefore, a request received must be either dispatched or rejected within a reasonable period of time, rather than be queued indefinitely waiting for the return of earlier dispatch invocations.

Implementations of this method should generally dispatch a request in a daemon thread with a security context at least as restrictive as the one in which this method was invoked, and without holding visible synchronization locks.

Parameters:

requestDispatcher - the RequestDispatcher to use to dispatch incoming requests received on this communication endpoint

Returns:

a ListenHandle that represents the listen operation that was started

Throws:

IOException - if an I/O exception occurs while attempting to listen for requests on this ListenEndpoint. This could occur, for example, if an I/O resource associated with this communication endpoint is already in exclusive use, or if there are insufficient I/O resources for the operation.

SecurityException - if the current security context does not have the permissions necessary to listen for requests on this ListenEndpoint

NullPointerException - if requestDispatcher is null