com.neeve.link
Class LnkContainer

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

Direct Known Subclasses:

LnkSTRContainer

public abstract class LnkContainer
extends LnkObject

Collection of link trees grouped by threading model and common read machinery.

Link containers serve as a collection of link trees that have the same read threading model and whose read machinery is powered by the same set of reader threads i.e. EMX event dispatchers. Link containers are identified by name and are stored in the link registry (LnkRegistry).

Links add and remove themselves from containers. The container to which a link adds itself is known by the user and communicated to the link during link creation time. In order to ensure that a link adds itself to a specific container, the user must invoke touch(java.lang.String) prior to creating the link. The touch method will modify the link descriptor to ensure that the link adds itself to the container that touched the descriptor. The link remains in the container until it is migrated to a new container or closed. The link removes itself from its container when closed.

Packet receipt through a link tree is accomplished by (1) identifying the set of threads (dispatchers) that will be driving the receipt of packets through the link tree (2) associating the threads with the link tree's read machinery and (3) driving the threads that will power the receipt of packets through the link tree. These steps are accomplished collaboratively between the link tree's container and root endpoint. The identification and management of the dispatchers that will be driving the packet receipt is handled by the container. The actual read machinery for a link tree (that pushes packets and events up the tree) is implemented by the tree's root endpoint. The container and root endpoint work together in starting (associating threads with the root endpoint's read machinery) and stopping reads (disassociating threads from the root endpoint's read machinery) through a link tree. The driving of the container threads (dispatchers) is specified by the container.

In order for step (2) above to work, a container and the root endpoints' of its link trees need to be compatible. Root endpoints expose their read machinery via derivatives of the ILnkRootEndpoint interface. Each interface embodies a specific read threading model. Each link container works with a specific read threading model i.e. it understands and works with a specific derivative of ILnkRootEndpoint. A link is considered compatible with a container if it implements the read threading model (derivative of ILnkRootEndpoint) that the container understands (see isCompatible(com.neeve.link.ILnkPeerEndpoint)).

A user should use startRead(com.neeve.link.ILnkPeerEndpoint) and stopRead(com.neeve.link.ILnkPeerEndpoint) to associate and disassociate a container's threads with the read machinery of a link tree. These methods implement step 2 described above i.e. contact the root endpoint of the link tree for which the read needs to be started or stopped and perform what is necessary to start or stop the receipt of packets through the link tree driven by the set of threads (dispatchers) managed by the container. It is recommended that these methods be used to manage the read machinery of links rather than contacting the root endpoints directly. This isolates the user from being aware of and of the intricacies of the various threading models at play.

A link container is not required to be 'runnable' i.e. it is not required to provide the machinery to drive its threads to power the read machinery of the link trees that it contains. The ILnkRunnableContainer interface and its derivatives defines the semantics of runnable containers.

A link container does not concerns itself with a link tree's write threading model.

Threading:

This class is safe for concurrent access by multiple threads.

Field Summary

static int

RMFLG_ALLOW_READ_OPERATIONAL Allow a link's tree's read to be operational when the link is removed from a container.

Method Summary

int	getCount() Get the number of links in the container.
abstract IEmxDispatcher	getCurrentReader() Check if the calling thread is a thread managed by the and, if so, return its associated dispatcher.
ILnkPeerEndpoint	getLink(String name) Get a link from the container.
cern.colt.list.ObjectArrayList	getLinks() Get the links in the container.
String	getName() Get the container name.
abstract boolean	isCompatible(ILnkPeerEndpoint pep) Test compatibility between a link and a container.
abstract void	startRead(ILnkPeerEndpoint pep) Associate a containers threads' with a link tree's read machinery.
abstract void	stopRead(ILnkPeerEndpoint pep) Disassociate the containers threads from a link tree's read machinery.
String	toString() Get a string representation of this link container
String	touch(String descriptor) Prepare a link descriptor to attach link to this container.
com.neeve.util.UtlAddressDescriptor	touch(com.neeve.util.UtlAddressDescriptor descriptor) Prepare a link descriptor to attach link to this container.

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, wait, wait, wait

Field Detail

RMFLG_ALLOW_READ_OPERATIONAL

public static final int RMFLG_ALLOW_READ_OPERATIONAL

Allow a link's tree's read to be operational when the link is removed from a container.

This flag is used with removeLink(java.lang.String, int). By default, a link cannot be removed from its container if the read is operational on the link's tree at the time of removal. This flag overrides that behaviour and allows for the link to be removed if the read is operational.

See Also:

Constant Field Values

Method Detail

getName

public final String getName()

Get the container name.

Threading:

This method is safe for concurrent access by multiple threads.

getLink

public final ILnkPeerEndpoint getLink(String name)

Get a link from the container.

Parameters:

name - The link name.

This method uses the supplied name to lookup a link in the container. A null value is returned in case the link with the specified name is not present in the container.

Threading:

This method is safe for concurrent access by multiple threads

getLinks

public final cern.colt.list.ObjectArrayList getLinks()

Get the links in the container.

Returns:

Returns the links in the container.

This method returns a copy of the list of links in the container. The user is free to modify the returned list. Modification of the returned list will not modify the contents of the container.

Threading:

This method is safe for concurrent access by multiple threads

getCount

public final int getCount()

Get the number of links in the container.

Returns:

Returns the number of links in the container

Threading:

This method is safe for concurrent access by multiple threads

touch

public final String touch(String descriptor)

Prepare a link descriptor to attach link to this container.

Parameters:

descriptor - The descriptor to touch.

Returns:

Returns the touched descriptor

Links are not created by the link container. They are created via the LnkFactory through the use of link descriptors. In order to ensure that established links are associated with the correct container, the descriptor must be 'touched' by that container. This method touches and returns the touched descriptor. It is guaranteed that any link created by an unmodified touched descriptor will be associated with this container.

Threading:

This method is safe for concurrent access by multiple threads.

touch

public final com.neeve.util.UtlAddressDescriptor touch(com.neeve.util.UtlAddressDescriptor descriptor)

Prepare a link descriptor to attach link to this container.

Parameters:

descriptor - The descriptor to touch.

Returns:

Returns the touched descriptor.

Links are not created by the link container. They are created via the LnkFactory through the use of link descriptors. In order to ensure that established links are associated with the correct container, the descriptor must be 'touched' by that container. This method touches and returns the touched descriptor. It is guaranteed that any link created by an unmodified touched descriptor will be associated with this container.

Threading:

This method is safe for concurrent access by multiple threads.

isCompatible

public abstract boolean isCompatible(ILnkPeerEndpoint pep)

Test compatibility between a link and a container.

Parameters:

pep - The link whose associated compatibility is to be tested.

Returns:

Return true in case the link is compatible with the container i.e. the container has determined that the root endpoint of the link's tree supports the interfaces (i.e. read threading models) that it understands and works with.

This method tests compatibility between a link and a container. A link is considered to be compatible with a container if the root endpoint of the link's tree supports the appropriate derivative of ILnkRootEndpoint that the container understands and works with.

Threading:

This method can be invoked concurrently by multiple threads.

startRead

public abstract void startRead(ILnkPeerEndpoint pep)
                        throws ELnkNotPresentException,
                               ELnkReadOperationalException,
                               ELnkNotCompatibleException,
                               ELnkException

Associate a containers threads' with a link tree's read machinery.

Parameters:

pep - The peer endpoint of a link in the link tree whose read machinery is to be started.

Throws:

ELnkNotPresentException - Thrown in case the link is associated with some container and that container is different from this one.

ELnkReadOperationalException - Thrown in case the read on the spcified link tree is already operational.

ELnkNotCompatibleException - Thrown in case the link on which the user is starting the read is incomptible with this container. This exception is never thrown in case the link in contained by this container.

ELnkException - Thrown in case an error was encountered while starting the read on the link.

This method associates the containers threads with the read machinery of the link tree of the specified link. A successful invocation of this method will cause the running of the container's threads' dispatchers to drive the receipt of packets and events through the specified link tree.

See Also:

stopRead(com.neeve.link.ILnkPeerEndpoint)

Threading:

This method can be invoked concurrently by multiple threads. The thread that invokes this method does not have to be one of the container's threads.

getCurrentReader

public abstract IEmxDispatcher getCurrentReader()

Check if the calling thread is a thread managed by the and, if so, return its associated dispatcher.

Returns:

Returns the dispatcher associated with the calling thread by the container. A return value of null indicates that the calling thread is not a thread managed by the container.

Threading:

This method can be invoked concurrently by multiple threads.

stopRead

public abstract void stopRead(ILnkPeerEndpoint pep)
                       throws ELnkNotPresentException,
                              ELnkNotCompatibleException,
                              ELnkException

Disassociate the containers threads from a link tree's read machinery.

Throws:

ELnkNotPresentException - Thrown in case the link is associated with some container and that container is different from this one.

ELnkNotCompatibleException - Thrown in case the link on which the user is stopping the read is incomptible with this container. This exception is never thrown in case the link in contained by this container.

ELnkException - Thrown in case an error was encountered while starting the read on the link.

This method disassociates the threads managed by the link container from the read machinery of the specified link tree. Once this method returns successfully, the running of the container's threads' dispatchers will have no effect on the receipt of packets and events through the link tree. This method can be safely invoked for a link tree whose read has not been started. In that case, the method will do nothing and just return.

See Also:

startRead(com.neeve.link.ILnkPeerEndpoint)

Threading:

This method can be invoked concurrently by multiple threads. The thread that invokes this method does not have to be one of the container's threads.

toString

public String toString()

Get a string representation of this link container

Overrides:

toString in class Object