com.neeve.link
Class LnkSender

java.lang.Object
  com.neeve.root.RootObject
      com.neeve.link.LnkObject
          com.neeve.link.LnkSender

public final class LnkSender
extends LnkObject

Provides the ability to send messages over a link using different send semantics. The supported semantics are streaming sends, synchronous (i.e. blocking) request-reply or pipelined (non-blocking) request reply.

Each link sender object is associated with a link peer endpoint object. This association occurs when the sender object is created (create(com.neeve.link.ILnkPeerEndpoint)). Before being able to use a sender object, the user must first open it using open(). The open method injects an event handler into the underlying peer endpoint's event handler chain. It does so to intercept inbound link events (including inbound packets). While open, link events that are not of interest to the sender object (for example, inbound messages that are not responses to requests initiated by the sender object) are chained to the next handler in the peer endpoint's event handler chain (See ILnkPeerEndpoint for a description on how peer endpoint handler chaining works). The user should invoke close() when done using the sender object. The close method will remove the sender's handler from the underlying peer endpoint's event handler chain.

The user uses the sendSync(com.neeve.link.LnkRequest, int) method to perform synchronous request-reply message exchanges with the underlying link's peer. The method accepts a request object as input. The request object needs to be created and initialized before invoking the send method (createRequest(com.neeve.pkt.PktPacket) is used to create fresh request objects). sendSync(com.neeve.link.LnkRequest, int) sends the request packet (contained in the request object supplied to the send method) through the underlying link and then blocks until all replies to the request are received, an error or a timeout occurs. The send method accepts a timeout parameter that specifies the maximum time to wait for the replies to arrive. If a reply for a synchronous request is received after a timeout, the reply will be discarded. However, the sender has no control on what happens to a reply that arrives after the sender object is closed (since it has removed itself from the peer endpoint's event handler chain). Link events (including packets events) that are not replies to the issued request continued to get dispatched to the next handler in the link's event handler chain.

The user performs pipelined (non-blocking) request-reply exchanges with the underlying link's peer using the sendPipelined(com.neeve.link.LnkRequest, com.neeve.link.ILnkPeerEndpoint.FlushContext, int) method. The method, once again, accepts an initialized request object as input. The method enques the packet in the underlying link endpoint, records the request and returns immediately to the user. It is the responsibility of the user to continue to drive the link's read machinery. Once the request successfully completes (i.e. all responses for the request are received) or a failure occurs, the completed request is dispatched to the user via an LnkEvents.EVENT_REQUEST_COMPLETE event. The result of the request is recorded in the request object itself. The flags accepted by the sendPipelined(com.neeve.link.LnkRequest, com.neeve.link.ILnkPeerEndpoint.FlushContext, int) method are a superset of flags accepted by the underlying peer endpoint's ILnkPeerEndpoint.enque(short, com.neeve.pkt.PktPacket, com.neeve.link.ILnkPeerEndpoint.FlushContext, int) method. This allows the user to perform sophisticated batching related optimizations while performing pipelined sends.

The user performs streaming sends to the underlying link's peer using the sendStreaming(com.neeve.pkt.PktPacket, com.neeve.link.ILnkPeerEndpoint.FlushContext, int) method. The method just enques the packet in the link endpoint and returns to the caller. The flags accepted by this method are a superset of flags accepted by the underlying peer endpoint's enque method (ILnkPeerEndpoint.enque(short, com.neeve.pkt.PktPacket, com.neeve.link.ILnkPeerEndpoint.FlushContext, int)) once again allowing the user to perform sophisticated batching related optimizations while performing streaming sends.

The link sender is designed so that events that are not packets received from the underlying link's peer are are not of interest to the sender continue to be dispatched to the next handler in the link's event handler chain.

The user is responsible for ensuring that the read machinery of the link's tree is operational before sending messages synchronously or in a pipelined manner using the sender. Also, the link needs to be associated with a container when this method is invoked.

Threading:

Each of the send methods in this class is safe for concurrent access by multiple threads. Furthermore the class is safe for concurrent access by multiple threads across methods.

Nested Class Summary

static class	LnkSender.State Enumerates the different sender states
static class	LnkSender.Stats Stores request statistics

Method Summary

void	close() Close a link sender.
static LnkSender	create(ILnkPeerEndpoint pep) Create a link sender.
LnkRequest	createRequest(PktPacket packet) Create a new request context.
void	open() Open a link sender.
void	sendPipelined(LnkRequest request, ILnkPeerEndpoint.FlushContext flushContext, int flags) Initiate a pipelined (non-blocking) request-response exchange.
void	sendStreaming(PktPacket packet, ILnkPeerEndpoint.FlushContext flushContext, int flags) Stream a packet through the underlying link.
com.neeve.util.UtlList	sendSync(LnkRequest request, int timeout) Perform a synchronous request response exchange.

Methods inherited from class com.neeve.root.RootObject

getChecked, getThreaded, getTracer, setChecked, setTracer

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

create

public static LnkSender create(ILnkPeerEndpoint pep)
                        throws ELnkException

Create a link sender.

Parameters:

pep - The link using which the sender will perform all sends.

Returns:

Returns the created synchronous sender.

Throws:

ELnkException - Thrown in case an error is encountered during the creation of the sender.

Threading:

This method is safe for concurrent access by multiple threads.

createRequest

public final LnkRequest createRequest(PktPacket packet)

Create a new request context.

Parameters:

packet - The request packet to associated with the context.

Threading:

This method is safe for concurrent access by multiple threads.

open

public final void open()
                throws ELnkException

Open a link sender.

Throws:

ELnkSenderInvalidStateException - Thrown in case the link sender is already open.

ELnkNotJoinedException - Thrown in case the user has not joined the underlying link endpoint. The underlying link needs to be joined for a sender to be attached to it .

ELnkException

Threading:

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

This method opens the sender object. It needs to be invoked before any other method is this class is invoked. The method injects an event handler into the associated link's (link provided during construction) event handler chain.

sendSync

public final com.neeve.util.UtlList sendSync(LnkRequest request,
                                             int timeout)
                                      throws ELnkException

Perform a synchronous request response exchange.

Parameters:

request - A request context that contains the packet to send. Either a unique request context should be used for each send or the request object should be initialized (LnkRequest.init(com.neeve.pkt.PktPacket)) before each send.

timeout - The maximum amount of time (in millseconds) to wait for the exchange to complete (successfully or not). A value <= 0 indicates a request for infinite wait.

Returns:

Returns the list of packets that form the response to the request.

Throws:

ELnkSenderInvalidStateException - Thrown in case the sender is not open.

ELnkRequestInvalidStateException - Thrown in case the supplied request object is in any state other than LnkRequest.State.INITIALIZED state.

ELnkInvalidStateException - Thrown in case the supplied endpoint is in a state that does not permit a write to be posted on it or if the link is not contained in any container or if the request object has been used before for a send and was not initialized before this invocation.

ELnkReadNotOperationalException - Thrown in case the read is not operational on the endpoint's link tree.

ELnkFlushInProgressException - Thrown in case an asynchronous flush is pending completion on the endpoint.

ELnkOpTimeoutException - Thrown in case the timeout occurred before the reply was received.

ELnkOpRequestFailedException - Thrown in case a reply was received but it indicated a request processing failure. The error code for the failure can be obtained from the exception object.

ELnkOpFailedException - Thrown in case a failure occured during the packet exchange.

ELnkException

Threading:

This method is safe for concurrent access by multiple threads provided the underlying link peer endpoint is safe for concurrent access.

This method marks the request as LnkRequest.State.ACTIVE, enques the supplied packet in the underlying link endpoint, flushes the endpoint and then blocks until a reply is received, an error occurs or the specified timeout expires before returning to the caller. In case the request completes after the timeout expires, the request will just be dropped and no event dispatched to the user.

sendPipelined

public final void sendPipelined(LnkRequest request,
                                ILnkPeerEndpoint.FlushContext flushContext,
                                int flags)
                         throws ELnkException

Initiate a pipelined (non-blocking) request-response exchange.

Parameters:

request - A request context that contains the packet to send. The request context supplied here must not be altered until the request completes i.e. the user receives the LnkEvents.EVENT_REQUEST_COMPLETE event. Since the intent of pipelined delivery is to have multiple packets in flight, it is ost common to create a fresh request context for each packet.

flushContext - The flush context object that is passed unchanged to the underlying link endpoint during the enque operation.

flags - A set of flags to qualify the send operation. This set of flags is passed unchanged to the underlying link endpoint as part of the packet enque call.

Throws:

ELnkSenderInvalidStateException - Thrown in case the sender is not open.

ELnkRequestInvalidStateException - Thrown in case the supplied request object is in any state other than LnkRequest.State.INITIALIZED state.

ELnkInvalidStateException - Thrown in case the supplied endpoint is in a state that does not permit a write to be posted on it or if the link is not contained in any container.

ELnkNotJoinedException - Thrown in case the end user has not joined the peer endpint. It is required that an end user have joined the endpoint before any pipelined exchange performed through it.

ELnkFlushInProgressException - Thrown in case an asynchronous flush is pending completion on the endpoint.

ELnkOpFailedException - Thrown in case a failure occured during the packet exchange.

ELnkException

Threading:

This method is safe for concurrent access by multiple threads provided the underlying link peer endpoint is safe for concurrent access.

This method marks the request as LnkRequest.State.ACTIVE, enques the packet in the underlying link endpoint and returns immediately to the user. It is the responsibility of the user to continue to drive the link's read machinery upon return from this method. Upon receipt, the reply packet is dispatched to via an instance of the LnkEvents.EVENT_REQUEST_COMPLETE event. The user should not alter the request context until the request completion event has been dispatched to the user.

Note that this method does not flush the underlying link endpoint. The user is responsible for flushing the endpoint or supplying appropriate flags that will force a flush during the enque operation.

sendStreaming

public final void sendStreaming(PktPacket packet,
                                ILnkPeerEndpoint.FlushContext flushContext,
                                int flags)
                         throws ELnkException

Stream a packet through the underlying link.

Parameters:

packet - The packet to send.

flushContext - The flush context object that is passed unchanged to the underlying link endpoint during the enque operation.

flags - A set of flags to qualify the send operation. This set of flags is passed unchanged to the underlying link endpoint as part of the packet enque call.

Throws:

ELnkInvalidStateException - Thrown in case the supplied endpoint is in a state that does not permit a write to be posted on it or if the link is not contained in any container.

ELnkNotJoinedException - Thrown in case the end user has not joined the peer endpint. It is required that an end user have joined the endpoint before any pipelined exchange performed through it.

ELnkFlushInProgressException - Thrown in case an asynchronous flush is pending completion on the endpoint.

ELnkOpFailedException - Thrown in case a failure occured during the packet exchange.

ELnkException

Threading:

This method is safe for concurrent access by multiple threads provided the underlying link peer endpoint is safe for concurrent access.

This method enques the supplied packet in the underlying link endpoint and returns to the caller. Note that this method does not flush the underlying link endpoint. The user is responsible for flushing the endpoint or supplying appropriate flags to this method that will force a flush during the enque operation.

close

public final void close()

Close a link sender.

Threading:

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

This method opens the sender object. It needs to be invoked before any other method is this class is invoked. The method injects an event handler into the associated link's (link provided during construction) event handler chain.