com.neeve.emx
Interface IEmxNwLnkClientEndpoint

All Superinterfaces:

IEmxNwLnkEndpoint

public interface IEmxNwLnkClientEndpoint
extends IEmxNwLnkEndpoint

The EMX Network Link Client Endpoint interface.

An EMX network link client endpoint is used to establish an EMX network 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 connection establishment operation is non-blocking in nature. The user requests the establishment of the connection using the connect(com.neeve.emx.EmxNwLnkOpWaitCond) method. If successful, the method returns a IEmxNwLnkPeerEndpoint for use to exchange data with the established link's other peer endpoint. If the establishment could not be completed at this point in time, the method returns null with enough information in the context parameter passed to the connect method to inform the caller with all the conditions the caller needs to wait for before invoking the connect method again. In such a case, it is a responsibility of the caller to parse the context parameter and wait on the specified conditions (using an EMX dispatcher) and reinvoke the connect method when the conditions have been satisfied. The method throws an exception in case the connection attempt failed for some reason.

The user is free to attempt to retry a failed connection establishment. However, once the connection has been successfully established, the client endpoint object becomes inert and the user should release it for garbage collection.

In the event that the link connection could not be successfully established and the user does not wish to retry the connection establishment any more, the user should close the client endpoint (using close()) prior to releasing it for garbage collection. This will release all operating system resources allocated to the client endpoint. It is illegal to close the client endpoint subsequent to a successful connection establishment. In case the user wishes to close a successfully established link, the user should invoke the IEmxNwLnkPeerEndpoint.close() method on the peer endpoint handed to the user when the connection was successfully established.

The link client endpoint implements the ICommandHandler interface enabling the user to configure and control the the endpoint and the underlying network link at runtime. Commands cannot be issued to a client link endpoint subsequent to a successful connect or closure of the endpoint.

Threading:

An EMX network link client endpoint is not safe for concurrent access by multiple threads.

Method Summary

void	close() Close a client endpoint.
IEmxNwLnkPeerEndpoint	connect(EmxNwLnkOpWaitCond waitCond) Connect to a listening server endpoint.

Method Detail

connect

IEmxNwLnkPeerEndpoint connect(EmxNwLnkOpWaitCond waitCond)
                              throws EEmxInvalidStateException,
                                     EEmxNwLnkOpFailedException

Connect to a listening server endpoint.

Parameters:

waitCond - This parameter (has to be non-null) is used to communicate wait conditions to the caller in the event that the connection establishment could not be completed immediately. In case the method returns null i.e. indicating that the establishment could not be completed immediately, the caller should parse this context, wait on the conditions specified in the context and reinvoke this method when the conditions have been satisfied. In the event that this method returns non-null, the contents of this parameter should be ignored.

Returns:

Returns an IEmxNwLnkPeerEndpoint object in case the link connection was successfully established. Returns null in case the establishment could not be completed immediately. In this case, the waitCond parameter contains the conditions on which the caller needs to wait before retrying the connection establishment.

Throws:

EEmxInvalidStateException - This exception is thrown in case the link connection has already been successfully established.

EEmxNwLnkOpFailedException - 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 EEmxNwLnkOpFailedException.

This method establishes the network link connection to a listening server endpoint. A successful return from this method, indicated by a non-null return value, signifies that the connection has been successfully established and the user can use the returned peer endpoint to exchange data with the other link endpoint. In case this method returns null, the method would have populated the provided wait conditions object with the appropriate set of conditions that the caller needs to wait on before retrying the connect again. Retrying the connect upon the satisfaction of the specified conditions does not guarantee that the connection will be successfully established. It is permissible for this method to return null on successive invocations even if the caller has waited on all specified conditions between invocations.

The user can attempt to establish an unconnected link as many times as desired using this method. Once connected, any attempt to invoke this method will return with an exception. For all practical purposes, a client endpoint is useless subsequent to the successful establishment of the link connection and should be released for garbage collection.

Threading:

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

close

void close()
           throws EEmxInvalidStateException,
                  EEmxNwLnkOpFailedException

Close a client endpoint.

Specified by:

close in interface IEmxNwLnkEndpoint

Throws:

EEmxInvalidStateException - This exception is thrown in case the user is attempting to close a connected link.

EEmxNwLnkOpFailedException - 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.