com.neeve.link
Interface ILnkServerEndpoint

All Superinterfaces:

ILnkEndpoint

All Known Implementing Classes:

LnkServerEndpoint

public interface ILnkServerEndpoint
extends ILnkEndpoint

The Link Server Endpoint interface.

A link server endpoint is the passive participant in the client-server mechanism used to create peer endpoints i.e. establish link connections. Link connection requests are initiated by link client endpoints and are accepted via server endpoints. All address related information on which to listen for incoming connection requests is specified at the server endpoint creation time and is implementation specific.

The acceptPost(com.neeve.emx.IEmxDispatcher, com.neeve.link.ILnkEventHandler, int, int) method is used to accept an incoming connection request. Upon the successful acceptance of a connection, the server endpoint provides the user with a peer endpoint ILnkPeerEndpoint that can be used to exchange packets with the established link's other peer endpoint.

The connection acceptance operation is asynchronous in nature. The user initiates the acceptance of an incoming connection request using the acceptPost(com.neeve.emx.IEmxDispatcher, com.neeve.link.ILnkEventHandler, int, int) method. The method is passed a dispatcher object and an event handler. Upon return from the method, the user is responsible for driving the dispatcher that will, in turn, drive the acceptance of the incoming connection request. The acceptance of a connection is notified to the user via the dispatch of an event to the event handler.

The user can cancel a posted accept using the acceptCancel(int) method. A successful return from that method indicates that the server endpoint has initiated the cancel of the accept. A cancellation of an accept terminates the background accept operation and the user will subsequently receive an acceptance completion event with an exception indiicating that the accept was cancelled by the user.

The user is free to repost the accept subsequent to the receipt of the completion event of a previously posted accept. This would normally be the case since a server endpoint would typically be used to accept incoming connection requests from several client endpoints.

The user should invoke the close() method when done using the server endpoint. This will release all operating system resources allocated to the server endpoint. It is illegal to post accepts subsequent to closing the endpoint.

Threading:

A link server endpoint basically operates in the context of the owner thread of the dispatcher that drives the accept operation. Both the acceptPost(com.neeve.emx.IEmxDispatcher, com.neeve.link.ILnkEventHandler, int, int) and acceptCancel(int) methods require to be invoked by the dispatcher owner thread. Invoking the methods using any other thread has undefined behaviour.

Field Summary

Fields inherited from interface com.neeve.link.ILnkEndpoint

IOFLAG_FLUSH_FORCE, IOFLAG_FLUSH_SUPPRESS, IOFLAG_IMMEDIATE_DISPATCH, IOFLAG_NO_ASYNC, LVFLAG_ALLOW_FLUSH_PENDING, LVFLAG_SUPPRESS_IMPLICT_CLOSE

Method Summary

void	acceptCancel(int flags) Cancel a previously posted accept.
void	acceptPost(IEmxDispatcher dispatcher, ILnkEventHandler handler, int timeout, int flags) Post the accept of an incoming connection request.
void	close() Close a server endpoint.

Method Detail

acceptPost

void acceptPost(IEmxDispatcher dispatcher,
                ILnkEventHandler handler,
                int timeout,
                int flags)
                throws ELnkInvalidStateException,
                       ELnkNotOwnerException,
                       ELnkOpFailedException

Post the accept of an incoming connection request.

Parameters:

dispatcher - The dispatcher in whose context the accept completion event will be dispatched. It is required that the invoking thread be the owner of this dispatcher.

handler - The event handler that will receive the completion event.

timeout - The maximum time (in milliseconds) to wait for an incoming link connection establishment request. If no connection request is received within the specified time, the connection acceptance is aborted and a completion event is dispatched with an exception indicating a timeout. A value of 0 indicates that there is no time limit in accepting connection requests.

flags - Flags that qualify the accept operation. The following flags are permitted for use in this method:
- ILnkEndpoint.IOFLAG_IMMEDIATE_DISPATCH
- ILnkEndpoint.IOFLAG_NO_ASYNC

Throws:

ELnkInvalidStateException - This exception is thrown in case there is an accept is currently in progress.

ELnkNotOwnerException - Thrown in case this method is invoked by a thread that is not the owner of the specified dispatcher.

ELnkOpFailedException - This exception is thrown in case the listening for incoming connection requests could not be successfully initiated.

This method initiates the acceptance of an incoming link connection request. A successful return from this method indicates that the accept operation has been successfully initiated. The operation will continue asynchronously in the background driven by the specified dispatcher. It is the responsibility of the caller to drive the dispatcher subsequent to return from this method. Upon completion of the accept, the completion status will be notified to the caller via the an accept completion event (LnkEvents.EVENT_ACCEPT_COMPLETE) dispatched to the specified handler. The handler will always be invoked by the owner thread of the specified dispatcher. A failure (i.e. an exception thrown by the method) indicates that the accept operation could not be successfully initiated. A completion event is not dispatched if this method returns with an exception.

Upon completion of the accept operation, the user can repost the accept in case additional connection requests are to be accepted. It is permissible to repost from within the completion event handler.

The execution of this method can be qualified through the specification of certain flags in the flags parameter. Refer to the documentation of the permissible flags for a description of how those flags qualify the behaviour of this method.

In case the user has requested for immediate dispatch of the completion event, it is possible for the completion handler to be invoked with a completion event indicating a failure before this method returns.

See Also:

acceptCancel(int)

Threading:

This method is not safe for concurrent access by multiple threads. Furthermore, the calling thread must be the same as the owner thread of the provided dispatcher.

acceptCancel

void acceptCancel(int flags)
                  throws ELnkInvalidStateException,
                         ELnkNotOwnerException

Cancel a previously posted accept.

Parameters:

flags - Flags that qualify the accept cancellation operation. Currently, there are no supported flags for use. This parameter is present for future use. The user should specify a value of 0 in this parameter.

Throws:

ELnkInvalidStateException - This exception is thrown in case the user is attempting a cancellation of an accept that was not initiated.

ELnkNotOwnerException - Thrown in case this method is invoked by a thread that is not the owner of the dispatcher specified in the earlier call to acceptPost(com.neeve.emx.IEmxDispatcher, com.neeve.link.ILnkEventHandler, int, int).

This method cancels a previously posted accept operation. A successful return from this method indicates that the accept operation has been cancelled. The user will be dispatched an accept completion event containing an exception indicating that the accept operation was cancelled by the user.

See Also:

acceptPost(com.neeve.emx.IEmxDispatcher, com.neeve.link.ILnkEventHandler, int, int)

Threading:

This method is not safe for concurrent access by multiple threads. Furthermore, the calling thread must be the same as the owner thread of the dispatcher that is driving the accept operation.

close

void close()
           throws ELnkInvalidStateException,
                  ELnkNotOwnerException,
                  ELnkOpFailedException

Close a server endpoint.

Throws:

ELnkInvalidStateException - This exception is thrown in case the user is attempting to close an endpoint that has an accept currently in progress in the background.

ELnkNotOwnerException - Thrown in case an accept is currently in progress and this method is invoked by a thread that is not the owner of the dispatcher that is driving the accept operation.

ELnkOpFailedException - This exception is thrown in case an error was encountered while closing the server endpoint.

This method is used to close a server endpoint and release all underlying system resources allocated to the server endpoint. A user would invoke this method upon being done with accepting incoming connect requests and prior to releasing the endpoint for garbage collection. It is illegal to post an accept on a closed endpoint.

Threading:

This method is not safe for concurrent access by multiple threads.