net.jini.jeri

Interface ServerEndpoint

All Superinterfaces:

ServerCapabilities

All Known Implementing Classes:

HttpServerEndpoint, HttpsServerEndpoint, KerberosServerEndpoint, SslServerEndpoint, TcpServerEndpoint

public interface ServerEndpoint
extends ServerCapabilities

Represents one or more communication endpoints on the current (local) host to listen for and receive requests on and a template for producing an Endpoint instance to send requests to those communication endpoints.

A ServerEndpoint instance contains the information necessary to listen for requests on the communication endpoints and to produce Endpoint instances. For example, a TCP-based ServerEndpoint implementation typically contains the TCP port to listen on and the host address to put in the Endpoint instances it produces. An implementation that supports authentication typically contains the Subject (if any) to use for server authentication.

The enumerateListenEndpoints method can be invoked to

• discover each of the discrete communication endpoints represented by this ServerEndpoint, which are individually represented as ListenEndpoint instances,
• ensure an active listen operation (see ListenEndpoint.listen) on each discrete communication endpoint by choosing, for each endpoint, either to start a new listen operation or to use an existing one, and
• obtain an Endpoint instance that corresponds to the chosen listen operations

The obtained Endpoint instance can then be used to send requests to the communication endpoints being listened on as a result of that enumerateListenEndpoints invocation.

Typically, a ServerEndpoint is just used to specify the transport layer implementation to use when exporting a remote object; for example, some constructors of BasicJeriExporter have a ServerEndpoint parameter to specify the transport layer implementation. The exporter implementation is then responsible for using the supplied ServerEndpoint to manage listen operations as necessary and to obtain an Endpoint instance for putting in the client-side proxy.

All aspects of the underlying communication mechanism that are not specified here are defined by the particular implementation of this interface.

Since:

2.0

Author:

Sun Microsystems, Inc.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	ServerEndpoint.ListenContext A callback object for passing to ServerEndpoint.enumerateListenEndpoints to receive the enumerated ListenEndpoint instances and to choose an active listen operation for each of them on behalf of the caller of enumerateListenEndpoints.
static interface	ServerEndpoint.ListenCookie A cookie to identify a listen operation as the return value of the ListenContext.addListenEndpoint method.
static interface	ServerEndpoint.ListenEndpoint Represents a communication endpoint on the current (local) host to listen for and receive requests on.
static interface	ServerEndpoint.ListenHandle Represents a listen operation that has been started on a ListenEndpoint.

Method Summary

Modifier and Type	Method and Description
Endpoint	enumerateListenEndpoints(ServerEndpoint.ListenContext listenContext) Enumerates the communication endpoints represented by this ServerEndpoint by passing the ListenEndpoint for each of them to listenContext, which will ensure an active listen operation on each endpoint, and returns an Endpoint instance corresponding to the listen operations chosen by listenContext.

Methods inherited from interface net.jini.jeri.ServerCapabilities

checkConstraints

Method Detail

enumerateListenEndpoints

Endpoint enumerateListenEndpoints(ServerEndpoint.ListenContext listenContext)
                           throws IOException

Enumerates the communication endpoints represented by this ServerEndpoint by passing the ListenEndpoint for each of them to listenContext, which will ensure an active listen operation on each endpoint, and returns an Endpoint instance corresponding to the listen operations chosen by listenContext.

This method uses listenContext to cooperate with the caller to ensure the appropriate listen operations. In this cooperation,

• the ServerEndpoint is responsible for declaring to the caller the discrete communication endpoints represented by this ServerEndpoint as ListenEndpoint instances passed to listenContext's addListenEndpoint method, and
• the caller is responsible for declaring the active listen operations to be used for this ServerEndpoint.enumerateListenEndpoints invocation corresponding to each discrete communication endpoint as ListenCookie instances returned from listenContext's addListenEndpoint method.

For each ListenEndpoint, the caller (through listenContext) may choose to start a new listen operation, or it may choose to reuse a previously started listen operation that it has a ListenCookie for.

This method sequentially invokes addListenEndpoint on listenContext once for each discrete communication endpoint represented by this ServerEndpoint, passing the ListenEndpoint representing that communication endpoint. If any of the invocations of ListenContext.addListenEndpoint throws an exception, this method throws that exception. Otherwise, this method returns an Endpoint instance that sends requests to be received by the listen operations chosen by listenContext.

Parameters:

listenContext - the ListenContext to pass this ServerEndpoint's ListenEndpoint instances to

Returns:

the Endpoint instance for sending requests to this ServerEndpoint's communication endpoints being listened on

Throws:

IOException - if an I/O exception occurs while attempting to listen for requests on the communication endpoints represented by this ServerEndpoint. This could occur, for example, if an I/O resource associated with one of the communication endpoints 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 one of the communication endpoints represented by this ServerEndpoint

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