com.neeve.link
Interface ILnkClientEndpointCore

All Known Implementing Classes:

LnkLayeredClientEndpoint, LnkLclClientEndpoint, LnkMultiClientEndpoint, LnkNwClientEndpoint

public interface ILnkClientEndpointCore

The Link Client Endpoint Core interface.

The LnkClientEndpoint class implements the ILnkClientEndpoint interface. Internally, the implementation consists of a portion that is common to all client endpoint implementations and a portion that is link type specific. This interface is a subset of ILnkClientEndpoint, is intended to be implemented by link type specific client endpoint implementations and is used by LnkClientEndpoint (referred to as the 'user' in the method documentation below) to carry out link type specific operations. Generally, the creation of a client endpoint first instantiates the type specific client endpoint followed by wrapping an instance of LnkClientEndpoint around the instantiated type specific endpoint to generate a full implementation of ILnkClientEndpoint that is returned to the user.

This interface is not directly accessed by an end user of a client endpoint. It is intended for use by link type specific client endpoint implementers that use LnkClientEndpoint in their implementation.

Threading:

A link type specific client endpoint implementation 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.

Method Summary

void	close() Close a client endpoint.
void	connectCancel(int flags) Cancel a previously posted connect.
void	connectPost(IEmxDispatcher dispatcher, ILnkEventHandlerCore handler, int flags) Post a connect to a listening server endpoint.

Method Detail

connectPost

void connectPost(IEmxDispatcher dispatcher,
                 ILnkEventHandlerCore handler,
                 int flags)
                 throws ELnkOpFailedException

Post a connect to a listening server endpoint.

Parameters:

dispatcher - The dispatcher in whose context the completion event is to be dispatched. The user will ensure that the the invoking thread is the owner of this dispatcher.

handler - The event handler to which the completion event is to be dispatched.

flags - Flags that qualify the connect operation. The following flags can be set on invocation of this method:
- ILnkEndpoint.IOFLAG_NO_ASYNC: In case this flag is specified and the connect operation could not be completed prior to return from this call, the method should not schedule the connect for asynchronous completion and just return without throwing any exception.

Throws:

ELnkOpFailedException - This exception should be thrown in case a failure was encountered in the establishment of the connection.

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 should be thrown to indicate a failure due to a permanent condition. Failures due to transient conditions should be reported via the ELnkOpFailedException.

This method should establish the link connection to a listening server endpoint. The result of the connection establishment should be notified through the dispatch of the LnkEvents.EVENT_CONNECT_COMPLETE event to the provided event handler. It is permissible to dispatch the completion event prior to returning from this method in case the connect could be completed synchronously with success. In the event that the completion event was not dispatched prior to return from this method and the method does not throw an exception, the caller will drive the supplied dispatcher until the completion event is dispatched or the connect is cancelled.

The caller will ensure the following prior to invoking this method:
- Parameter integrity including calling thread validity
- State integrity i.e. this method will never be invoked on a closed endpoint or at any point subsequent to the successful invocation of this method irrespective of the subsequent outcome of the connect operation.

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

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 never invoked concurrently with any other thread and will always be the owner thread of the provided dispatcher.

connectCancel

void connectCancel(int flags)

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 will always specify a value of 0 in this parameter.

This method should cancel a previously posted connect operation. A successful return from this method indicates that the connect operation has been cancelled. No completion event for the connect should be dispatched once the connect has been cancelled.

See Also:

connectPost(com.neeve.emx.IEmxDispatcher, com.neeve.link.ILnkEventHandlerCore, int)

Threading:

This method is never invoked concurrently with any other thread and will always be the owner thread of the provided dispatcher.

close

void close()
           throws ELnkOpFailedException

Close a client endpoint.

Throws:

ELnkOpFailedException - This exception should be 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. This method will never be invoked on a connecting or connected endpoint. The purpose of this method is to release all underlying resources upon abandonment of the connection establishment process.

Threading:

This method is never invoked concurrently with any other thread.