public static interface ServerEndpoint.ListenEndpoint
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.
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. |
void checkPermissions()
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.
SecurityException
- if the current security context
does not have the permissions necessary to listen for
requests on this ListenEndpoint
InboundRequest.checkPermissions()
ServerEndpoint.ListenHandle listen(RequestDispatcher requestDispatcher) throws IOException
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.
requestDispatcher
- the RequestDispatcher
to use to dispatch incoming requests received on this
communication endpointListenHandle
that represents the
listen operation that was startedIOException
- 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
Copyright © 2016–2018. All rights reserved.