com.neeve.emx
Interface IEmxNwLnkPeerEndpoint

All Superinterfaces:

IEmxNwLnkEndpoint

public interface IEmxNwLnkPeerEndpoint
extends IEmxNwLnkEndpoint

The EMX Network Link Peer Endpoint interface.

An EMX network link peer endpoint represents an endpoint in a peer-peer network link. It specifies the API and semantics using which two peer entities can perform the bidirectional exchange of arbitrary unstructured data.

Creation
The mechanism used to create peer endpoints is the client-server model. In this model, server entities listen for link connection establishment requests using the IEmxNwLnkServerEndpoint. On the other end of the link, the user uses the IEmxNwLnkClientEndpoint to establish the link connection to the listening server endpoint. Upon successful establishment, both the client and the server endpoints create a peer endpoint each and hand it to the user. These peer endpoints are then used for the bidirectional exchange of data through the connected link.

Data Exchange
The link peer endpoint exports two primitives for data exchange i.e. read(java.nio.ByteBuffer, com.neeve.emx.EmxNwLnkOpWaitCond) and write(java.nio.ByteBuffer[], int, com.neeve.emx.EmxNwLnkOpWaitCond). Both primitives are synchronous non-blocking in nature. See the method documentation for details.

Link Configuration & Control The link peer endpoint implements the ICommandHandler interface enabling the user to configure and control the the endpoint and the underlying network link at runtime.

Closing
When a user is done using an endpoint, it closes it using the close() method. This method should always be called prior to releasing the endpoint for garbage collection to release any underlying operating system resources associated with the link.

Threading:

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

Method Summary

void	close() Close a peer endpoint.
int	read(ByteBuffer buffer, EmxNwLnkOpWaitCond waitCond) Reads data from the underlying network link.
long	write(ByteBuffer[] buffers, int count, EmxNwLnkOpWaitCond waitCond) Writes data to the underlying link.

Method Detail

read

int read(ByteBuffer buffer,
         EmxNwLnkOpWaitCond waitCond)
         throws EEmxInvalidStateException,
                EEmxNwLnkClosedGracefullyException,
                EEmxNwLnkOpFailedException

Reads data from the underlying network link.

Parameters:

buffer - The buffer into which data is to be read. The data is read into the buffer starting at the position marker upto but excluding the limit marker. Upon return from this call the position marker is updated to point to one byte beyond the last byte read in.

waitCond - This parameter (has to be non-null) is used to communicate wait conditions to the caller to determine when there is more data to be read through the endpoint. The caller should parse this parameter, wait on the conditions specified and reinvoke this method when the conditions have been satisfied.

Returns:

A return value > 0 indicates that some data was read into the provided buffer and is equal to the number of bytes successfully read through the link. A value of 0 indicates that no data is available to be read from the link and the caller should try at a later time (non-blocking I/O semantics). This method never returns a negative value. An exception is thrown if an error in encountered while reading data through the link.

Throws:

EEmxInvalidStateException - This exception is thrown in case the endpoint has been closed.

EEmxNwLnkClosedGracefullyException - Thrown if the underlying link was closed gracefully by the peer.

EEmxNwLnkOpFailedException - Thrown if an error was encountered while reading data from the link.

Threading:

This method is not safe for concurrent access by multiple threads

write

long write(ByteBuffer[] buffers,
           int count,
           EmxNwLnkOpWaitCond waitCond)
           throws EEmxInvalidStateException,
                  EEmxNwLnkOpFailedException

Writes data to the underlying link.

Parameters:

buffers - The buffers containing the data to be written. For each buffer in this parameter, data is written starting at the position marker upto but not including the limit marker. Upon return from the method, the position marker for each buffer is updated to point to one byte beyond the last byte written from that buffer. This implies that, for every successfully written buffer, the position marker will be set to the limit marker.

count - The number of buffers to write from the buffers array.

waitCond - This parameter (has to be non-null) is used to communicate wait conditions to the caller to determine when data can be written through the link. The caller should parse this parameter, wait on the conditions specified and reinvoke this method when the conditions have been satisfied.

Returns:

A return value > 0 indicates that some data was written from the provided buffers and equals the number of bytes successfully written through the link . A value of 0 indicates that no data could be written through the link and the caller should try at a later time (non-blocking I/O semantics). An exception is thrown if an error in encountered while writing data through the connection.

Throws:

EEmxInvalidStateException - This exception is thrown in case the endpoint has been closed.

EEmxNwLnkOpFailedException - Thrown if an error was encountered while writing data to the link.

Threading:

This method is not safe for concurrent access by multiple threads

close

void close()
           throws EEmxInvalidStateException,
                  EEmxNwLnkOpFailedException

Close a peer endpoint.

Specified by:

close in interface IEmxNwLnkEndpoint

Throws:

EEmxInvalidStateException - This exception is never thrown by a peer endpoint i.e. it is permissible to close a peer endpoint at any point after creation.

EEmxNwLnkOpFailedException - Thrown in case an error was encountered during the closing of the endpoint.

Threading:

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