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

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
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
 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,

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


Copyright 2007, multiple authors.
Licensed under the Apache License, Version 2.0, see the NOTICE file for attributions.