com.neeve.link
Interface ILnkClientEndpoint

All Superinterfaces:

ILnkEndpoint

All Known Implementing Classes:

LnkClientEndpoint

public interface ILnkClientEndpoint
extends ILnkEndpoint

The Link Client Endpoint interface.

A link client endpoint is the active participant in the client-server mechanism used to create a peer endpoint i.e. establish a link connection. Link connections are established to listening server endpoints. All address related information as to which server side endpoint to connect to is provided at the client endpoint creation time and is implementation specific.

The connectPost(com.neeve.emx.IEmxDispatcher, com.neeve.link.ILnkEventHandler, int, int) method is used to establish the link connection. Upon the successful establishment of the connection, the client endpoint provides the user with a peer endpoint (ILnkPeerEndpoint) that can be used to exchange packets with the link's other peer endpoint.

The connection establishment operation is asynchronous in nature. The user initiates the establishment of the connection using the connectPost(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 background completion of the connection establishment. Upon completion of the connection establishment, the user is notified of the completion status via the dispatch of a completion event to the supplied event handler.

The user can cancel a posted connect using the connectCancel(int) method. A successful return from that method indicates that the client endpoint has initiated a cancel of the connect. A cancellation of a connect terminates the background connect operation and the user will subsequently receive a completion event contaning ELnkOpCancelledException indicating that the connect was cancelled by the user.

The user can specify a timeout when initiating a connection establishment. In the event that the connection could not be established within the specified timeout, the connection establishment is automatically cancelled and a completion event containing ELnkOpTimeoutException indicating that the operation timed out is dispatched to the user.

The user is permitted to successfully initiate the connection establishment (irrespective of its outcome) only once in the lifetime of a client endpoint. Once the connection establishment has been successfully initiated, the user should wait for the connection completion event. In the event that the connection completion event indicates a failure, the user should close the endpoint and release it for garbage collection. A new client endpoint object should be created in case the user wishes to retry the connection establishment.

It is illegal to close an endpoint that either has a connect operation in progress or has successfully established the connection. Therefore, an endpoint can be closed only before a successful invocation to connectPost() or after a successful invocation to connectPost() that is followed by a completion event indicating a connection establishment failure. The user should use the close() method to close an unconnected link and the ILnkPeerEndpoint.close(short) method on the peer endpoint handed to the user upon successful establishment of the connection to close a connected link. Closing a connecting or connected client endpoint will result in an invalid state exception.

Threading:

A link client endpoint is not safe for concurrent access by multiple threads i.e. the different threads cannot be invoked concurrently by different threads. Refer to the method documentation for information regarding the threading and concurrency models for each of the methods.

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	close() Close a client endpoint.
void	connectCancel(int flags) Cancel a previously posted connect.
void	connectPost(IEmxDispatcher dispatcher, ILnkEventHandler handler, int timeout, int flags) Post a connect to a listening server endpoint.

Method Detail

connectPost

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

Post a connect to a listening server endpoint.

Parameters:

dispatcher - The dispatcher in whose context the 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 attempt to establish the connection. If the connection could not be established within the specified time, the connection establishment 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 for the connection establishment.

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

Throws:

ELnkInvalidStateException - Thrown in case there is a connect operation already in progress or the connection has already been successfully established.

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 connection establishment could not be successfully initiated.

RuntimeException - A connection attempt can fail due to a variety of reasons. Broadly these causes can be categorized as 'permanent' or 'non-permanent'. 'Permanent' causes are those that are cause by incorrect configuration and will not go away with repeated connection attempts e.g. an unresolvable hostname was specified in the link descriptor. 'Non-permanent' causes are those that are transient in nature and a repeated connect attempt can be successful e.g. the target host is down or the network is congested. A RuntimeException thrown to indicate a failure due to a permanent condition. Failures due to transient conditions are reported via the ELnkOpFailedException.

This method initiates the establishment of a link connection to a listening server endpoint. A successful return from this method indicates that the connection establishment has been successfully initiated. The connect operation establishment 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 connect operation, the completion status will be notified to the caller through the dispatch of the LnkEvents.EVENT_CONNECT_COMPLETE completion event 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 establishment could not be successfully initiated. The completion events is not dispatched if this method returns with an exception.

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.

The user can invoke this method attempt as many times as desired as long as this method returns with an exception. It is illegal to invoke this method subsequent to a successful invocation irrespective of the final outcome of the connect operation.

See Also:

connectCancel(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.

connectCancel

void connectCancel(int flags)
                   throws ELnkInvalidStateException,
                          ELnkNotOwnerException

Cancel a previously posted connect.

Parameters:

flags - Flags that qualify the connect 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 - Thrown in case the user is attempting a cancellation of a connect operation 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 connectPost(com.neeve.emx.IEmxDispatcher, com.neeve.link.ILnkEventHandler, int, int).

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

See Also:

connectPost(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 connect operation.

close

void close()
           throws ELnkInvalidStateException,
                  ELnkNotOwnerException,
                  ELnkOpFailedException

Close a client endpoint.

Throws:

ELnkInvalidStateException - Thrown in case the user is attempting to close an endpoint that is either connected or has a connect currently in progress in the background.

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

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

This method is used to close an unconnected client endpoint and release all operating system resources allocated to the client endpoint. It is illegal to invoke this method on a connected endpoint. The purpose of this method is to allow the user to release all underlying resources upon abandonment of the connection establishment process.

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 connect operation in case a connect in in progress.