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

    public 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

    public 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`

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