com.neeve.link
Class LnkSTRContainer

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

Direct Known Subclasses:

LinkTool, LnkSTRRunnableContainer

public class LnkSTRContainer
extends LnkContainer

Collection of link trees grouped by the STR threading model.

An STR link container serves as a collection of link trees that support the STR (single threaded read) read threading model and whose read machinery are powered by a single reader thread. The container maintains knowledge of the reader thread (in the form of an EMX dispatcher) but does not provide the machinery by which the thread (dispatcher) is run. It interacts with root endpoints of the contained link trees using ILnkSTRRootEndpoint through which it starts and stops the read of the contained link trees.

This link container is compatible with link trees whose root endpoints implement the ILnkSTRRootEndpoint interface.

Threading:

This class is safe for concurrent access by multiple threads.

Field Summary

Fields inherited from class com.neeve.link.LnkContainer

RMFLG_ALLOW_READ_OPERATIONAL

Method Summary

static LnkSTRContainer	createTemporary(RootConfig.ObjectConfig config, IEmxDispatcher reader) Create a temporary STR container.
IEmxDispatcher	getCurrentReader() Implementation of LnkContainer.getCurrentReader()
IEmxDispatcher	getReader() Get the reader thread.
boolean	isCompatible(ILnkPeerEndpoint pep) Implementation of LnkContainer.isCompatible(com.neeve.link.ILnkPeerEndpoint).
void	startRead(ILnkPeerEndpoint pep) Implementation of LnkContainer.startRead(com.neeve.link.ILnkPeerEndpoint)
void	stopRead(ILnkPeerEndpoint pep) Implementation of LnkContainer.stopRead(com.neeve.link.ILnkPeerEndpoint)
String	toString() Get a string representation of this link container

Methods inherited from class com.neeve.link.LnkContainer

getCount, getLink, getLinks, getName, touch, touch

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

Method Detail

createTemporary

public static LnkSTRContainer createTemporary(RootConfig.ObjectConfig config,
                                              IEmxDispatcher reader)

Create a temporary STR container.

Parameters:

config - The package configuration object to use in the creation of this container. The allows the parameters used to configure the package that is using this class to be automatically applied to this object too. A null value will cause the container to use its default config object.

reader - The thread (the owner of the specified EMX dispatcher) to be associated with the temporary container as the reader thread. A value of null indicates that no reader thread is to be associated with the temporary container at this time. In that case, the reader thread should be set at a later point via setReader(com.neeve.emx.IEmxDispatcher) before any of the other methods are invoked.

This is a utility method that creates an STR link container for temporary use. The method uses a UUID to obtain the name of the container. It creates the container using the specified dispatcher as the container reader.

Threading:

This method is safe for concurrent access by multiple threads.

getReader

public final IEmxDispatcher getReader()

Get the reader thread.

Threading:

This method is safe for concurrent access by multiple threads.

isCompatible

public final boolean isCompatible(ILnkPeerEndpoint pep)

Implementation of LnkContainer.isCompatible(com.neeve.link.ILnkPeerEndpoint).

This method validate that the root endpoint of the link tree of the specified link implements ILnkSTRRootEndpoint.

Specified by:

isCompatible in class LnkContainer

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.

startRead

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

Implementation of LnkContainer.startRead(com.neeve.link.ILnkPeerEndpoint)

Specified by:

startRead in class LnkContainer

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:

LnkContainer.stopRead(com.neeve.link.ILnkPeerEndpoint)

getCurrentReader

public final IEmxDispatcher getCurrentReader()

Implementation of LnkContainer.getCurrentReader()

Specified by:

getCurrentReader in class LnkContainer

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.

stopRead

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

Implementation of LnkContainer.stopRead(com.neeve.link.ILnkPeerEndpoint)

Specified by:

stopRead in class LnkContainer

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:

LnkContainer.startRead(com.neeve.link.ILnkPeerEndpoint)

toString

public String toString()

Get a string representation of this link container

Overrides:

toString in class LnkContainer