com.neeve.link
Interface ILnkPeerEndpointCore

public interface ILnkPeerEndpointCore

The Link Peer Endpoint Core interface.

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

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

Threading:

LnkPeerEndpoint serializes access to the various methods of this interface. However, implementers of this interface still need to protect for the dispatch of events concurrently with the invocation of methods in this interface.

Method Summary

void	close() Close the endpoint.
boolean	enque(PktPacket packet, ILnkPeerEndpoint.FlushContext flushContext, int flags) Enque a packet for flush at a later point.
void	flush(ILnkPeerEndpoint.FlushContext flushContext) Flush enqueued packets to the remote endpoint.
int	getEnqueuedSize() Return the serialized length of packets enqueued with the endpoint.
short	getLtp() Get the endpoint LTP.
String	getName() Get the endpoint name.
short	getPeerLtp() Get the peer endpoint's LTP.
ILnkRootEndpoint	getRootEndpoint() Get the root endpoint of the endpoint's link tree.
boolean	isGroupEndpoint() Get whether this endpoint can pariticipate in group communication.
boolean	isRootEndpoint() Get whether this endpoint is a root endpoint in the link tree.
void	join(short ltp) Indicates that a peer endpoint has joined the link tree.
void	leave(short ltp) Indicates that a peer endpoint has left the link tree.
void	setEventHandler(ILnkEventHandlerCore handler) Install an event handler.

Method Detail

getName

String getName()

Get the endpoint name.

Returns:

Returns the name that uniquely identifies the endpoint. This name will be used to index the endpoint in the link registry.

Threading:

This method is safe for concurrent access by multiple threads independent of the threading model of the endpoint's link tree.

getLtp

short getLtp()

Get the endpoint LTP.

Returns:

Returns the identifier of this link endpoint as a node in a link tree. Each link peer endpoint has a unique LTP within the link tree to which it belongs.

Threading:

This method should be safe for concurrent access by multiple threads independent of the threading model of the endpoint's link tree. Also, this method may be invoked concurrently with any other method in this interface.

getPeerLtp

short getPeerLtp()

Get the peer endpoint's LTP.

Returns:

Returns the identifier of this link endpoint's peer as a node in a link tree. Each link peer endpoint has a unique LTP within the link tree to which it belongs.

Threading:

This method should be safe for concurrent access by multiple threads independent of the threading model of the endpoint's link tree. Also, this method may be invoked concurrently with any other method in this interface.

isGroupEndpoint

boolean isGroupEndpoint()

Get whether this endpoint can pariticipate in group communication.

Returns:

true if this endpoint connects to an entity that manages communication groups.

Some link implementations connect to entities that manage communication groups. With such links, the user can join one or more communication groups and communicate with other members of the group. Groups are addressed using topics that are wildcard enabled hierarchical strings. The group communication semantics e.g. delivery reliability and ordering, membership management etc is defined by the link implementation. This method should return true in case the link enables group communication.

Threading:

This method should be safe for concurrent access by multiple threads independent of the threading model of the endpoint's link tree. Also, this method may be invoked concurrently with any other method in this interface.

isRootEndpoint

boolean isRootEndpoint()

Get whether this endpoint is a root endpoint in the link tree.

Returns:

Return true if this is a root endpoint of the link tree to which the endpoint belongs.

Threading:

This method should be safe for concurrent access by multiple threads independent of the threading model of the endpoint's link tree. Also, this method may be invoked concurrently with any other method in this interface.

getRootEndpoint

ILnkRootEndpoint getRootEndpoint()

Get the root endpoint of the endpoint's link tree.

Returns:

Returns the root endpoint in the endpoint's link tree.

Threading:

This method should be safe for concurrent access by multiple threads independent of the threading model of the endpoint's link tree. Also, this method may be invoked concurrently with any other method in this interface.

getEnqueuedSize

int getEnqueuedSize()

Return the serialized length of packets enqueued with the endpoint.

Returns:

Returns the serialized length of the enqueued packets.

Threading:

This method is never invoked concurrently with any other thread. Also, this method is never invoked concurrently with the setEventHandler(com.neeve.link.ILnkEventHandlerCore), enque(com.neeve.pkt.PktPacket, com.neeve.link.ILnkPeerEndpoint.FlushContext, int), flush(com.neeve.link.ILnkPeerEndpoint.FlushContext) or the close() methods.

setEventHandler

void setEventHandler(ILnkEventHandlerCore handler)

Install an event handler.

Parameters:

handler - The event handler to install.

Upon startup, LnkPeerEndpoint uses this method to install its event handler with the link type peer endpoint implementation. All events generated by the link type peer endpoint implementation or received from endpoints lower down in the endpoint's link tree should be dispatched to LnkPeerEndpoint through this event handler.

Threading:

This method is invoked only once during the lifetime of a peer endpoint. It is invoked from the LnkPeerEndpoint constructor and, therefore, is invoked from the thread that is constructing the endpoint.

join

void join(short ltp)
          throws ELnkAlreadyJoinedException,
                 ELnkMaxUsersReachedException

Indicates that a peer endpoint has joined the link tree.

Parameters:

ltp - The LTP identifying the endpoint that has joined the tree.

Throws:

ELnkAlreadyJoinedException - The link type specific implementation may receive this exception from underlying endpoints in case an endpoint with the same ltp has joined from somewhere else in the tree. This exception should be propagated upwards to the LnkPeerEndpoint.

ELnkMaxUsersReachedException - The link type specific implementation may receive this exception from underlying endpoints in case an endpoint lower down in the tree has maxed out its users. This exception should be propagated upwards to the LnkPeerEndpoint.

This method is used by LnkPeerEndpoint to communicate that an endpoint identified by the specified ltp has joined the tree somewhere upstream in the tree. A layered link type specific endpoint implementation should chain this information dowstream by installing its own event handler with the endpoint on which it is layered. It should do so using ILnkPeerEndpoint.join(short, com.neeve.link.ILnkEventHandler) with the supplied ltp as the source. This will cause the join information to propagate to the base of the link tree installing event handlers appropriately so events targeted to the newly joined peer endpoint is appropriately routed to the endpoint.

Threading:

This method is never invoked concurrently with any other thread. Also, this method is never invoked concurrently with the getEnqueuedSize(), leave(short), enque(com.neeve.pkt.PktPacket, com.neeve.link.ILnkPeerEndpoint.FlushContext, int), flush(com.neeve.link.ILnkPeerEndpoint.FlushContext) or the close() methods.

leave

void leave(short ltp)

Indicates that a peer endpoint has left the link tree.

Parameters:

ltp - The LTP identifying the endpoint that has left the tree.

This method is used by LnkPeerEndpoint to communicate that an endpoint identified by the specified LTP has left the tree somewhere upstream in the tree. A layered link type specific endpoint implementation should chain this information dowstream by uniinstalling its own event handler from the endpoint on which it is layered. It should do so using ILnkPeerEndpoint.leave(short, int) with the supplied ltp as the source. This will cause the leave information to propagate to the base of the link tree uninstalling event handlers appropriately so events targeted to the peer endpoint that has left endpoint are dropped.

Threading:

This method is never invoked concurrently with any other thread. Also, this method is never invoked concurrently with the getEnqueuedSize(), join(short), enque(com.neeve.pkt.PktPacket, com.neeve.link.ILnkPeerEndpoint.FlushContext, int), flush(com.neeve.link.ILnkPeerEndpoint.FlushContext) or the close() methods.

enque

boolean enque(PktPacket packet,
              ILnkPeerEndpoint.FlushContext flushContext,
              int flags)
              throws ELnkOpFailedException

Enque a packet for flush at a later point.

Parameters:

packet - The packet to enque.

flushContext - A context object indicating the IO semantics to be used in case the link is automatically flushed from within this method (due to some policy implemented by the endpoint such as auto flush based on packet queue size) alongwith runtime context information related to the flush

flags - Flags used to qualify the enque operation. The following flags are permissible for use here:
- ILnkEndpoint.IOFLAG_FLUSH_SUPPRESS

Returns:

Return true in case the method did attempt to automatically flush the packet queue. Return false in case the packet was only enqueued and no flush was attempted.

This method should serialize and enque a packet at the endpoint for flush at a later point. Once serialized the packet queue should be conditionally flushed depending on internal auto flush policies implemented by the endpoint. See flush(com.neeve.link.ILnkPeerEndpoint.FlushContext) for more information on how the flushContext parameter should be used and updated by the endpoint in case of an auto flush.

Throws:

ELnkOpFailedException - Thrown in case an error was encountered during the enqueing or, more likely, the automatic flushing of the endpoint.

Threading:

This method is never invoked concurrently with any other thread. Also, this method is never invoked concurrently with the getEnqueuedSize(), join(short), leave(short), flush(com.neeve.link.ILnkPeerEndpoint.FlushContext) or the close() methods.

flush

void flush(ILnkPeerEndpoint.FlushContext flushContext)
           throws ELnkOpFailedException

Flush enqueued packets to the remote endpoint.

Parameters:

flushContext - A context object indicating the IO semantics to be used alongwith runtime context information related to the flush.

Throws:

ELnkOpFailedException - Thrown in case an error was encountered during the flushing of the endpoint.

This method should flush enqueued packets to the remote endpoint. The flush context determines the IO semantics used for the flush operation i.e. sync blocking, sync non-blocking or async. In case async flush is specified, the user will check the contents of the flush context upon return from this method. In case the flush did not complete synchronously, the user will drive the specified dispatcher till it receives the flush completion event. No packets will be enqueued or the endpoint flushed until the async flush has completed.

Threading:

This method is never invoked concurrently with any other thread. Also, this method is never invoked concurrently with the getEnqueuedSize(), join(short), leave(short), enque(com.neeve.pkt.PktPacket, com.neeve.link.ILnkPeerEndpoint.FlushContext, int) or the close() methods.

close

void close()
           throws ELnkOpFailedException

Close the endpoint.

Throws:

ELnkOpFailedException - Thrown in case an error was encountered during the failing of the endpoint.

The user (LnkPeerEndpoint) will invoke this method when the peer endpoint needs to be closed. The user first sets the endpoint state to ILnkPeerEndpoint.State.CLOSING before invoking this method and will update the state to ILnkPeerEndpoint.State.CLOSED when it receives the LnkEvents.EVENT_CLOSURE from this endpoint. In case this method can close the link type peer endpoint synchronously within this method itself, the method should dispatch the closure event prior to returning. In case the method returns without dispatching the closure event, the user will assume that the closure is pending completion and all dispatchers provided earlier for asynchronous flushes will be driven till the closure event is received. No method in this interface will be invoked while the endpoint is in a closing or closed state. Furthermore, the user will wait for any pending flush to complete before invoking this method.

Threading:

This method is never invoked concurrently with any other thread. Also, this method is never invoked concurrently with the getEnqueuedSize(), join(short), leave(short), enque(com.neeve.pkt.PktPacket, com.neeve.link.ILnkPeerEndpoint.FlushContext, int) or the flush(com.neeve.link.ILnkPeerEndpoint.FlushContext) methods.