com.neeve.link
Interface ILnkPeerEndpoint.EventHandlerChain

Enclosing interface:

ILnkPeerEndpoint

public static interface ILnkPeerEndpoint.EventHandlerChain

Interface to manage a link's peer endpoint event handler chain.

An event handler chain links events handlers. An implementation of this interface is maintained by the peer endpoint for the end user. When an event is to be dispatched to the end user of the endpoint, the event is dispatched to the root handler in maintained chain. The purpose of the chain is to enable the interception and filtering of events by intermediate event handlers.

When a user needs to intercept end user events emanating from the endpoint, the user invokes ILnkPeerEndpoint.getHandlerChain() to get an instance of this interface and then invoke push(java.lang.Object) to push the new handler before the existing one. This operation is guaranteed to be atomic and, once complete, the user events from the peer endpoint will start arriving at the new handler. It is the responsibility of a pushed handler to dispatch unfiltered events to the next handler in the chain. It does do by getting the next handler in the chain via next(java.lang.Object) and invoking the onEvent method in the obtained handler. Once done with the interception, the user should use pop(java.lang.Object) to remove the handler from the chain

Threading:

An event handler chain is safe for concurrent access by multiple threads.

Method Summary

int	count() Get number of handlers in the chain.
Object	get(ILnkEventHandler eventHandler) Wrap a chain handler object around an event handler.
ILnkEventHandler	next(Object handler) Get the next handler in the chain.
void	pop(Object handler) Remove an installed handler from the chain.
void	push(Object handler) Push a new handler in the chain.

Method Detail

get

Object get(ILnkEventHandler eventHandler)
           throws ELnkNotJoinedException

Wrap a chain handler object around an event handler.

Parameters:

eventHandler - The event handler to wrap.

Throws:

ELnkNotJoinedException - Thrown if the end user has not joined the endpoint. Methods in this class can only be invoked if the end user is joined to the endpoint.

Event handlers pushed into the handler chain are referenced by chain handler objects. Before the user can push(java.lang.Object) a handler onto the chain, it needs to obtain a chain handler object for the event handler using this method.

Threading:

This method is safe for concurrent access by multiple threads.

push

void push(Object handler)
          throws ELnkNotJoinedException

Push a new handler in the chain.

Parameters:

handler - The handler being pushed. This

Throws:

ELnkNotJoinedException - Thrown if the end user has not joined the endpoint. Methods in this class can only be invoked if the end user is joined to the endpoint.

This method pushes the specified handler under the endpoint's current handler i.e. it installs the specified handler with the peer endpoint and links it to the swapped handler. The installed handler is responsible for chaining unfiltered events to the old handler. It should get the old handler via the next(java.lang.Object) method. The newly installed handler may start receiving events before this method returns.

Threading:

This method is safe for concurrent access by multiple threads.

next

ILnkEventHandler next(Object handler)
                      throws ELnkNotJoinedException

Get the next handler in the chain.

Parameters:

handler - The handler relative to which the next handler is to be returned.

Returns:

Returns the handler next in the chain.

Throws:

ELnkNotJoinedException - Thrown if the end user has not joined the endpoint. Methods in this class can only be invoked if the end user is joined to the endpoint.

The user is designed for use by an installed handler to retrieve the next handler in the chain. The method should be called when an unfiltered event needs to be dispatched onwards in the chain.

Threading:

This method is safe for concurrent access by multiple threads.

pop

void pop(Object handler)
         throws ELnkNotJoinedException

Remove an installed handler from the chain.

Parameters:

handler - The handler to be removed.

Throws:

ELnkNotJoinedException - Thrown if the end user has not joined the endpoint. Methods in this class can only be invoked if the end user is joined to the endpoint.

This method should be invoked when the user wishes to uninstall an installed handler in the chain. In the event that the handler is the root handler in the chain i.e. the handler installed with the peer endpoint, the method will install the next handler in the chain onto the peer endpoint. Otherwise, the handler is just removed from the chain.

Threading:

This method is safe for concurrent access by multiple threads.

count

int count()

Get number of handlers in the chain.

Threading:

This method is safe for concurrent access by multiple threads.