com.neeve.link
Class LnkHandshaker

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

public abstract class LnkHandshaker
extends LnkObject

Provides the core machinery to perform a handshake on a link.

This class supplies the core machinery (the state machine implementation) to execute an asynchronous handshake on a link. The class is designed for use by client and server endpoints that need to perform handshakes as part of their initial connection establishment. The class implements the core handshake machinery and retrieves handshake specific information via abstract methods. Handshaker classes should extend this class and implement the abstract methods to complete the handshake implementation.

After creation, the user initiates the handshake using start(com.neeve.emx.IEmxDispatcher). This class conducts the handshake in the context of a single thread i.e. the thread that invoked start(com.neeve.emx.IEmxDispatcher). Before kicking off the handshake, the start method performs the following in the listed order:

1. Stop the read on the link's tree if started.
2. Join the link endpoint using the specified LTP.
3. Migrate the link tree to a temporary STR link container with the reader thread of the container being the thread that invoked start(com.neeve.emx.IEmxDispatcher). This is the context in which the handshake will be conducted.
4. Start the read on the link tree using the new container.

Note that the handshake will fail if an user with the specified LTP has already joined the link. This is deliberate since this class is designed for use for the first exchange of packets on a new link.

On creation, the user places the handshaker state machine in one of two initial states - State#CONNECTED or State#ACCEPTED. The former causes the handshaker state machine to kick off by sending a request packet to the peer and wait for the reply. The latter places the state machine in a wait state waiting for the request packet to arrive from the peer.

The user also supplies a maximum timeout for the handshake when creating the handshaker. This timeout (if not infinite) governs the maximum amount of time that the handshaker will wait for a request or reply from the peer before it deems the handshake to have failed.

Upon successful return from the start method, the handshake will continue in the background driven by the handshake dispatcher. The handshake is deemed complete when either one of the following conditions occur:

1. A request was sent and a valid reply received.
2. A valid request was received and a reply sent
3. A request or a reply was not received in a specific timeout.
4. The handshake was stopped by the user before it completed.
5. An error occured before the handshake completed e.g. link tree failed.

Upon completion, the handshaker performs the following:

1. Stop the read on the link's tree.
2. Leave the link using the specified LTP.
3. Migrate the link's tree back to its original container.
4. Restart read if originally started and handshake failed
5. Dispatch the handshake completion notification.

Note that the read on the link tree remains stopped if the handshake was successful. This is intentional since this class is designed for use by client and server endpoint implementations to perform the initial connection establishment handshake. Thus, a successful handshake would result in the creation of a peer endpoint. If we restart the read and the read is driven by threads different from the handshake thread, then there is a possibility of lost packets while the new peer endpoint is being created. So, in case the handshake is successful, we just mark whether the read was originally stopped in the handshake completion data and dispatch the completion notification. The caller can restart the read when appropriate. If the handshake failed, we restart the read.

The status of a completed handshake is communicate to the user via the onComplete(com.neeve.link.LnkHandshaker.CompletionData) method in a LnkHandshaker.CompletionData object. This object contains the state in which the handshake was kicked off, the request and reply packets exchanged during the handshake, the status of completion and the overflow packet list. The overflow packet list requires special mention. During the course of the handshake, since link trees can dispatch packet lists as a batch, it is possible that the handshaker receives some legitimate packets after the last handshake packet. The handshaker collects these packets and hands them to the user on completion. The user should process these packets before any other packets received through the link to ensure correct processing order.

The user can stop an ongoing handshake via the stop() method. The handshake can be stopped *only by the handshaker thread*. The stop method schedules a cancellation of the handshake. The cancellation event is subsequently dispatched to the user indicating completion of the handdshake.

Threading:

This class is not safe for concurrent access by multiple threads. This public and abstract methods and the handshaker state machine run exclusively in the context of the handshaker thread.

Nested Class Summary

class

LnkHandshaker.CompletionData Class contaning the handshake completion data

Method Summary

void	start(IEmxDispatcher dispatcher) Start the handshake.
void	stop() Stop the handshake.

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

start

public final void start(IEmxDispatcher dispatcher)

Start the handshake.

Parameters:

dispatcher - The dispatcher in whose context the handshake is to be conducted. The calling thread must be the owner of this dispatcher.

Throws:

ELnkNotOwnerException - Thrown in case the calling thread is not the owner of the specified dispatcher.

This method performs the following in the listed order:
1. Stop the read on the link's tree if started.
2. Join the link endpoint using the provided LTP.
3. Migrate the link tree to a temporary STR link container with the calling thread as the container reader thread. is the context in which the handshake will be conducted.
4. Start the read on the link tree using the new container.

In the event that a failure occurs in any of the above steps, user will be notified via a completion event (onComplete(com.neeve.link.LnkHandshaker.CompletionData)) before this method returns.

Threading:

This method is not safe for concurrent access by multiple threads and must be invoked only once by the owner of the specified dispatcher.

stop

public final void stop()

Stop the handshake.

This method schedules a cancellation of the handshake. Once the cancellation is complete, the completion handler will be invoked with ELnkOpCancelledException. It is guarateed that the completion event will not be invoked before this method returns. This method has to be invoked by the thread that started the handshake

Threading:

This method is not safe for concurrent access by multiple threads and has to be invoked by the same thread that started the handshake.