com.neeve.client.link
Class ClientLinkManager

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

All Implemented Interfaces:

ILnkRunnableContainer

Direct Known Subclasses:

ClientLinkTool

public class ClientLinkManager
extends LnkSTRRunnableContainer

Client link manager.

The X Platform client layer is comprised of a set of value added messaging modules and service clients. It is layered on top of the client link layer. The link layer is, in turn, comprised of a set of link managers. Each link manager supplies the read machinery to drive the set of links (actually a forest of link trees) that it maintains.

This class is implemented as an STR (single threaded reader) runnable link container with additional functionality to enable the class to serve as the foundation for X Platform clients. As an STR runnable link container, this class serves as a container for links and provides the mechanisms by which to drive the reader associated with the container. This class extends the STR runnable link container functionality by adding the semantics on how the reader thread for the container is selected. Essentially, it provides the mechanism by a use can elect to set a user-supplied or system created thread as the reader for the container. The former is called the attached mode of operation while the latter is called the detached mode of operation.

The user specifies the set of links to be managed via a set of link descriptors provided to the manager when created. These descriptors can describe root level or layered links. Each descriptor must contain the 'name' property that is used to identify the link described by the descriptor. The value of the 'name' property is a hierachical structured string of the form strN/.../str2/str1 where each element is an unstructured string. The name property taken collectively across all descriptors define a forest of link trees. For example, if three descriptors 'a', 'a/b' and 'a/c' are supplied to the manager, this class will interpret these as meaning that 'a' is a root link descriptors on which 'a/b' and 'a/c' depend. The descriptors are organized and stored in a forest of trees defined by the names to ensure that links are opened in the correct order. The trees defined by the link names mirror the link trees formed by link peer endpoints when the links have been all opened.

The user opens a managed link via open(). When requested to open a link, the link manager first creates a ILnkClientEndpoint using the link descriptor and then uses ILnkClientEndpoint.connectPost(com.neeve.emx.IEmxDispatcher, com.neeve.link.ILnkEventHandler, int, int) to synchronously establish the link connection. The link manager opens all unopened dependee links before opening a requested link. The open method modifies the descriptor of layered links to ensure that they are layered on links as defined by the tree formed by the link names.

Upon instantiation, the user can provide an event handler to the link manager through which link manager specific events are dispatched to the user. The user should listen for events it is interested in. Events dispatched by a link manager are defined in ClientLinkManagerEvent.

Once opened, the user is free to operate on the opened link without restriction. When done using the link, the user should leave or close the link if the link is not needed anymore. The user should be aware that 'leaving' a link can cause an implicit close unless the user chooses to suppress the implicit close. Furthermore, a close can cascade down the link tree closing links on the way in case they are not being used anymore.

When done using a link, the user must close the link. When done with the links, the user should close and shutdown the link manager. The shutdown part is only strictly needed for managers created in detached mode.

Threading:

This class is safe for concurrent access by multiple threads.

Nested Class Summary

static class

ClientLinkManager.Configuration A link manager configuration object.

Field Summary

static int

OPENFLG_ASYNC Specifies that an open should be executed asynchronously.

Fields inherited from class com.neeve.link.LnkContainer

RMFLG_ALLOW_READ_OPERATIONAL

Method Summary

void	close(String name) Close a link.
static ClientLinkManager	create(String name, ClientLinkManager.Configuration config, IClientLinkManagerEventHandler eventHandler) Create and initialise a link manager from a configuration object.
static ClientLinkManager	create(String name, IClientLinkManagerEventHandler eventHandler) Create and initialize a link manager from the default configuration repository.
static ClientLinkManager	create(String name, IClientLinkManagerEventHandler eventHandler, Set<String> descriptors, Properties props) Create and initialize a client link manager.
String	getDependee(String name) Get a link's dependee (i.e. the link this link directly depends on)
Set<String>	getDependents(String name, boolean immediate) Get a link's dependent's.
IClientLinkManagerEventHandler	getEventHandler() Get the link manager event handler.
Set<String>	getRoots() Get the roots of the link trees in the link tree forest.
ILnkRootEndpoint.ThreadingModel	getThreadingModel() Get the link manager I/O threading model.
boolean	isDetached() Get whether operating in detached or attached mode.
boolean	isManaged(String name) Get whether a link is managed by this link manager.
boolean	isOpenInProgress() Get whether an asynchronous open is currently in progress.
void	open(String name, int timeout, int flags) Open a link and all its dependee links.
IClientLinkManagerEventHandler	setEventHandler(IClientLinkManagerEventHandler eventHandler) Set the link manager event handler.
void	shutdown() Shut down the link manager.

Methods inherited from class com.neeve.link.LnkSTRRunnableContainer

run, run

Methods inherited from class com.neeve.link.LnkSTRContainer

createTemporary, getCurrentReader, getReader, isCompatible, startRead, stopRead, toString

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

Field Detail

OPENFLG_ASYNC

public static final int OPENFLG_ASYNC

Specifies that an open should be executed asynchronously.

This flag is used with the open() method to indicate that the open should be performed asynchronously. An asynchronous open will traverse the link trees attempting to open unopened links as with the synchronous open. However, the opening thread will not block waiting for an open to complete. If the open for a link does not complete immediately, the open process schedules the open to complete in the background and returns to the caller. The open is always executed in the context of the link manager reader thread and will continue in the background driven by the reader thread. Since the open process is always bracketed by the dispatch of ClientLinkManagerEvent.OPEN_BEGIN and ClientLinkManagerEvent.OPEN_END events (irrespective of whether the open executes synchronously or asynchronously), the user can detect when the open process has completed. The isOpenInProgress() method can also be used to detect an asynchronous open in progress. Methods that modify the link trees will throw an exception in case invoked while an async open is in progress.

See Also:

Constant Field Values

Method Detail

create

public static ClientLinkManager create(String name,
                                       IClientLinkManagerEventHandler eventHandler,
                                       Set<String> descriptors,
                                       Properties props)
                                throws EClientLinkAlreadyPresentException,
                                       EClientLinkInvalidThreadingModelException

Create and initialize a client link manager.

Parameters:

name - The name of the link manager. This will be the name of the link container created in the link registry for this link manager. This value cannot be null.

eventHandler - The event handler through which events pertaining to the operation of the link manager will be dispatched to the user. This parameter can be null in which case no events will be dispatched to the user.

descriptors - See ClientLinkManager.Configuration.descriptors

props - See ClientLinkManager.Configuration.props

Returns:

Returns the created link manager.

Throws:

EClientLinkAlreadyPresentException - Thrown in case a link manager (or, more specifically, a link container) of the specified name is already present in the link registry (there is one registry per application).

EClientLinkInvalidThreadingModelException - Indicates that the threading model specified in the properties table cannot be used with links managed by this link manager.

This method creates a new link manager, sets the event handler and initializes the link manager using init(com.neeve.emx.IEmxDispatcher, java.util.Set, java.util.Properties)

Threading:

This method is safe for concurrent access by multiple threads.

create

public static ClientLinkManager create(String name,
                                       IClientLinkManagerEventHandler eventHandler)
                                throws EClientLinkNotPresentException,
                                       EClientLinkAlreadyPresentException,
                                       EClientLinkInvalidThreadingModelException,
                                       EClientLinkException

Create and initialize a link manager from the default configuration repository.

Parameters:

name - The name used to identify the link manager in the repository.

eventHandler - The event handler through which events pertaining to the operation of the link manager will be dispatched to the user. This parameter can be null in which case no events will be dispatched to the user.

Returns:

Returns the created link manager.

Throws:

EClientLinkNotPresentException - Thrown in case a configured link manager object with the specified name could not be found.

EClientLinkAlreadyPresentException - Thrown in case a link manager (or, more specifically, a link container) of the specified name already exists in the link registry (there is one registry per application).

EClientLinkInvalidThreadingModelException - Thrown in case the threading model specified in the properties is invalid.

EClientLinkException - Thrown in case some other error occured whie loading the link manager from the configuration repository.

This method creates a new link manager, sets the event handler and initializes the link manager using initFromRepository(com.neeve.emx.IEmxDispatcher)

Threading:

This method is safe for concurrent access by multiple threads.

create

public static ClientLinkManager create(String name,
                                       ClientLinkManager.Configuration config,
                                       IClientLinkManagerEventHandler eventHandler)
                                throws EClientLinkAlreadyPresentException,
                                       EClientLinkInvalidThreadingModelException,
                                       EClientLinkException

Create and initialise a link manager from a configuration object.

Parameters:

name - The name used to identify the link manager.

config - The configuration object to use.

eventHandler - The event handler through which events pertaining to the operation of the link manager will be dispatched to the user. This parameter can be null in which case no events will be dispatched to the user.

Returns:

Returns the created link manager.

Throws:

EClientLinkAlreadyPresentException - Thrown in case a link manager (or, more specifically, a link container) of the specified name already exists in the link registry (there is one registry per application).

EClientLinkInvalidThreadingModelException - Thrown in case the threading model specified in the properties is invalid.

EClientLinkException - Thrown in case some other error occured whie creating the link manager.

This method creates a new link manager, sets the event handler and initializes the link manager using the specified configuration object.

Threading:

This method is safe for concurrent access by multiple threads.

isDetached

public final boolean isDetached()

Get whether operating in detached or attached mode.

Threading:

This method is safe for concurrent access by multiple threads.

getThreadingModel

public final ILnkRootEndpoint.ThreadingModel getThreadingModel()

Get the link manager I/O threading model.

This method returns the link manager's I/O threading model. This is the threading model applied to each of the links managed by the client.

Threading:

This method is safe for concurrent access by multiple threads.

setEventHandler

public final IClientLinkManagerEventHandler setEventHandler(IClientLinkManagerEventHandler eventHandler)

Set the link manager event handler.

Returns:

Return the previously installed event handler.

Threading:

This method is safe for concurrent access by multiple threads.

getEventHandler

public final IClientLinkManagerEventHandler getEventHandler()

Get the link manager event handler.

Threading:

This method is safe for concurrent access by multiple threads.

open

public final void open(String name,
                       int timeout,
                       int flags)
                throws EClientLinkNotManagedException,
                       EClientLinkOpenInProgressException

Open a link and all its dependee links.

Parameters:

name - The name of the link to open. If this value is null, then the method will attempt to open all unopened links.

timeout - The maximum time (in seconds) that the link manager should attempt to open the link. A non-positive value indicates an infinite timeout. In case the user has requested for all unopened links to be opened, this value will be used in the opening of each of the unopened links.

flags - Flags used to qualify the open operation. The following flags are valid for use with this method:
- OPENFLG_ASYNC

Throws:

EClientLinkNotManagedException - Thrown if a link of the specified name is not managed by this link manager.

EClientLinkOpenInProgressException - Thrown if an asynchronous open is currently in progress. See OPENFLG_ASYNC for details on asynchronous opens.

This method opens a link managed by a link manager. The method opens all unopened links that the specified link depends on (dependees) before opening the link. For each link that is opened, the open process first creates the ILnkClientEndpoint object for the link and then establishes the link connection. The open process begins with the dispatch of the ClientLinkManagerEvent.OPEN_BEGIN event to indicate the start of the open process. Then, for each link being opened, the open process dispatches the ClientLinkManagerEvent.LINK_OPEN_SUCCESS or the ClientLinkManagerEvent.LINK_OPEN_FAIL event to communicate the result of the opening of the link. The ClientLinkManagerEvent.OPEN_END event is dispatched when the open process completes. This sequence of execution applies to synchronous as well as asynchronous opens.

A successful open of the specified link causes any read that was previously started on the link's tree to be stopped i.e. on successful open of a link, the user is responsible for restarting the read on the link's tree. The restart can be done on return from this method or from the event handler on receipt of the open event that indicates the successful open. The state of the read on the link is restored to the read state prior to the open attempt in case the open failed. It is recommended that the read be restarted on the dispatch of the ClientLinkManagerEvent.OPEN_END event since the successful opening of each link will cause the read to be stopped and so it only makes sense, in the interest of efficiency, to restart the read when the open process has completed. The user should note that the read will remain stopped even if a single link was opened successfully even if subsequent link opens fail.

Note that this method reports the open completion status for each of the links opened exclusively via events whether the open is a sync or an async one.

This method can be invoked multiple times. Each invocation will only open unopened links.

Threading:

This method is safe for concurrent access by multiple threads and can be invoked by any thread including the reader thread independent of the I/O threading model associated with this link manager. The open process is always executed by the client reader thread irrespective of which thread invokes this method.

getRoots

public final Set<String> getRoots()

Get the roots of the link trees in the link tree forest.

Returns:

Returns the list of root links.

This method returns a list with each node specifying the name of root link i.e. root of a tree in the forest of link trees maintained by the link manager.

Threading:

This method is safe for concurrent access by multiple threads and can be invoked by any thread including the reader thread independent of the I/O threading model associated with this link manager.

isManaged

public final boolean isManaged(String name)

Get whether a link is managed by this link manager.

Parameters:

name - The link to check for.

This method checks whether a particular link is managed by this link manager.

Threading:

This method is safe for concurrent access by multiple threads and can be invoked by any thread including the reader thread independent of the I/O threading model associated with this link manager.

isOpenInProgress

public final boolean isOpenInProgress()

Get whether an asynchronous open is currently in progress.

This method returns whether an asynchronous open is currently in progress and pending completion. See OPENFLG_ASYNC for details on asynchronous opens.

Threading:

This method is safe for concurrent access by multiple threads and can be invoked by any thread including the reader thread independent of the I/O threading model associated with this link manager.

getDependee

public final String getDependee(String name)
                         throws EClientLinkNotManagedException

Get a link's dependee (i.e. the link this link directly depends on)

Parameters:

name - The link whose dependee is to be returned.

Returns:

Returns the link that the specified link is dependent on.

Throws:

EClientLinkNotManagedException - Thrown if a link of the specified name is not managed by this link manager.

This method returns the link that the specified link is dependent on. A value of null is returned if the specified link is a root link.

Threading:

This method is safe for concurrent access by multiple threads and can be invoked by any thread including the reader thread independent of the I/O threading model associated with this link manager.

getDependents

public final Set<String> getDependents(String name,
                                       boolean immediate)
                                throws EClientLinkNotManagedException

Get a link's dependent's.

Parameters:

name - The link on which the returned set depends.

immediate - Setting this value to true will cause this method to return only the immediate dependents of the specified link. A value of false will cause all dependents including indirect ones to be returned.

Returns:

Returns the set of links that depend on the specified link. A value of null is returned in case there are no links that depend of the specified link.

Throws:

EClientLinkNotManagedException - Thrown if a link of the specified name is not managed by this link manager.

This method returns the set of links that directly depend on the specified link. The returned list is in no specified order.

Threading:

This method is safe for concurrent access by multiple threads and can be invoked by any thread including the reader thread independent of the I/O threading model associated with this link manager.

close

public final void close(String name)
                 throws EClientLinkNotManagedException,
                        EClientLinkOpenInProgressException,
                        EClientLinkException

Close a link.

Parameters:

name - The link to close. In case this parameter is null, this method closes all managed links.

Throws:

EClientLinkNotManagedException - Thrown if a link of the specified name is not managed by this link manager.

EClientLinkOpenInProgressException - Thrown if an asynchronous open is currently in progress. See OPENFLG_ASYNC for details on asynchronous opens.

EClientLinkException - Thrown in case the close operation encountered an error.

This method closes a connected link managed by this link manager. It does do by invoking ILnkPeerEndpoint.close(short) on the link. The close method is invoked as an end user i.e. with -1 as parameter value. It should be noted that closing a link does not imply that the link will shut down. A link will shut down when all links that depend on it are also closed.

The most common usage is for the user to ILnkPeerEndpoint.leave(short, int) a link without suppressing the implicit close when it is done with it. Then, when the user is done with a link manager, it should close all clients and messaging modules and then invoke this method with a null parameter. That will ensure that all links shut down.

In case the link manager was created using 'detached' mode, then the link manager should be shut down using shutdown() after all links have been closed.

Threading:

This method is safe for concurrent access by multiple threads and can be invoked by any thread including the reader thread independent of the I/O threading model associated with this link manager. The close process is always executed by the client reader thread irrespective of which thread invokes this method.

shutdown

public final void shutdown()
                    throws EClientLinkLinksOpenException,
                           EClientLinkException

Shut down the link manager.

Throws:

EClientLinkLinksOpenException - Thrown if there are some managed links that are still open.

EClientLinkOpenInProgressException - Thrown if an asynchronous open is currently in progress. See OPENFLG_ASYNC for details on asynchronous opens.

EClientLinkException - Thrown in case the shutdown operation encountered an error.

This method shuts down the reader thread if the link manager is operating in detached mode. The method first checks if there are any links open. If so, the method returns with an exception.

Threading:

This method is safe for concurrent access by multiple threads and can be invoked by any thread including the reader thread independent of the I/O threading model associated with this link manager. The close process is always executed by the client reader thread irrespective of which thread invokes this method.