com.neeve.link
Class LnkRequest

java.lang.Object
  com.neeve.link.LnkRequest

public final class LnkRequest
extends Object

A request context.

A request object is used to represent a request in a request-reply message exchange pattern. Each request object is associated with a LnkSender. The user creates a request object using the LnkSender.createRequest(com.neeve.pkt.PktPacket) method. This method creates the request object and associates it with the LnkSender. The created request object can be used only with it's associated sender object.

A request object exists in one of many states. A freshly created request (created using LnkSender.createRequest(com.neeve.pkt.PktPacket)) starts of in the LnkRequest.State.CREATED state. A request in this state is associated with a sender object but is not yet associated with any underlying request packet. Before using the request with any of the LnkSender methods, the user needs to initialize the request. This is done using init(com.neeve.pkt.PktPacket) which transitions the request to the LnkRequest.State.INITIALIZED state. The user can then use the request object with any of the LnkSender methods that accept a request object. The act of sending a request transitions a request to the LnkRequest.State.ACTIVE state. The request stays in the this state until the request completes (either successfully or with failure). The user cannot perform modify the internal state of the request object while it is in this state except for detaching the packet object from the request (using detachPacket(). This is permissible since the packet object is not used by the request object or associated sender object once the request object's state transitions to LnkRequest.State.ACTIVE state. Other than this, only the associated sender object can modify the request object's internal state while it is active. However, getter methods can still be invoked to read the request state as it changes while active.

A request object internally contains a LnkRequest.Result object that is updated with inbound replies as and when then arrive. Once the request is complete, the user can obtain all received responses from the result object as well if any error was encountered.

Threading:

A request object is not safe for concurrent access by multiple threads. Furthermore, a request object should not be concurrently accessed with any of the LnkSender object's send methods that accept a request.

This class stores the context of a request.

Nested Class Summary

class	LnkRequest.Result Contains the result for the request.
static class	LnkRequest.State Enumerates the different request states

Method Summary

void	detachPacket() Detach the packet from the request object.
long	getCorrelationId() Get the request correlation id
PktPacket	getPacket() Get the request packet
LnkRequest.Result	getResult() Get the result object.
LnkRequest.State	getState() Get the request state.
LnkRequest	init(PktPacket packet) Initialize a request object for use

Methods inherited from class java.lang.Object

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

Method Detail

init

public final LnkRequest init(PktPacket packet)
                      throws ELnkRequestInvalidStateException

Initialize a request object for use

Parameters:

packet - The request packet to initialize the request object with.

Throws:

ELnkRequestInvalidStateException - Thrown if this method is invoked in the LnkRequest.State.ACTIVE state.

This method prepares a request object for use with the link sender's LnkSender.sendSync(com.neeve.link.LnkRequest, int) and LnkSender.sendPipelined(com.neeve.link.LnkRequest, com.neeve.link.ILnkPeerEndpoint.FlushContext, int) methods. The user should always call this method on a request object before supplying it to any of the above methods.

getCorrelationId

public final long getCorrelationId()

Get the request correlation id

getPacket

public final PktPacket getPacket()

Get the request packet

detachPacket

public final void detachPacket()

Detach the packet from the request object.

This method detaches the underlying request packet from a request object. This method can only be invoked on a request object in any state other than the LnkRequest.State.INITIALIZED state. The request object does not reference the underlying packet once the packet has been sent i.e. after the request state has been switched to LnkRequest.State.ACTIVE and therefore can be detached from the request object if the user chooses.

getResult

public final LnkRequest.Result getResult()

Get the result object.

getState

public final LnkRequest.State getState()

Get the request state.