Creating dynamic chains from a chain manager plug-in
If a transport has an associated chain manager, the chain manager is responsible for creating all chains involving that transport. Note that this is the only way to create chains involving such a transport, they cannot be created using startChains or from EPL's ConnectivityPlugin.createDynamicChain action.
Chain managers may create chains at any time after
start() has been called and before
shutdown(), and for any reason. However, most managers create chains in response to a notification that a channel has been created, which means it is in use for the first time. See
Requirements of a transport chain manager plug-in class for more information about how to do this.
When a chain manager is ready to create a new chain, it does so by calling ChainManagerHost.createChain(), usually making use of the host field on AbstractChainManager. The following information must be supplied when creating a chain:
chainInstanceIdSuffix - A string identifier which will be suffixed onto "
managerName-" to uniquely identify the new chain instance.
Caution: A small amount of memory is allocated for each unique chain instance identifier. This memory is not freed when the chain is destroyed. Therefore, if you are creating many chains, consider reusing old chain instance identifiers. If you create more than 1000 unique identifiers, a warning is written to the correlator log file to notify you of this. You cannot have two active chains with the same chain instance identifier, so only reuse identifiers which are no longer in use.
dynamicChainDefinition - Specifies which of the chain definitions that contain this transport should be used. The
AbstractChainManager provides
getChainDefinition() helper methods to select a chain definition based on its identifier or by assuming that only one definition will be configured. For more complex cases, a collection of all the chain definitions for this transport is provided in the
chainDefinitions field which a manger can iterate over to find the one with the desired transport plug-in configuration. There are various possible approaches to selecting which chain definition to use to create a chain:
For some managers, it may not make sense to support multiple chain definitions and can be written to just use a singleton chain definition.
Some managers may allow the user to specify a chain definition by providing a chain definition identifier as a configuration option for the manager in
managerConfig.
Another approach is for the manager to search through the available chain definitions and use the transport plug-in's configuration of each one to decide which to use, for example, by providing a channel prefix or regular expression pattern as part of the transport configuration.
substitutions - The chain manager can provide zero or more
@{varname} variable replacement values. This provides a way to use information from the manager or transport to configure the host or codec plug-ins, for example, by having the Mapper codec set a field with details about the manager's connection.
defaultChannelTowardsHost and
subscribeChannels - Used to specify the channel or channels that this chain will send to (unless overridden in individual messages) or subscribe to. You can either use a single chain to send messages in both directions, or have a separate chain for each direction, that is, each transport instance will only be responsible for sending or receiving, but not both.
The transport from the chain definition should match the transport that contains the chain manager making the call. To create the transport object, the chain host will call createTransport rather than the transport's constructor (for Java), or the transports constructor, passing through any extra parameters passed to createChain (for C++). Once the chain has been created, it needs to be started by calling the start() method on the returned Chain object (a Chain pointer for C++).
For more detailed information about the classes and interfaces involved in creating a chain manager, see the
API Reference for Java (Javadoc) on the
com.softwareag.connectivity.chainmanagers package, or see the
API Reference for C++ (Doxygen) on the
com::softwareag::connectivity::chainmanagers namespace.