Apama 10.15.0 | Connecting Apama Applications to External Components | Working with Connectivity Plug-ins | Using Connectivity Plug-ins | Configuration file for connectivity plug-ins
 
Configuration file for connectivity plug-ins
A configuration file for the connectivity plug-ins is specified using the --config option when starting the correlator with the correlator executable. It is possible to specify multiple configuration files. See the description of the --config option in Starting the correlator.
A configuration file for the connectivity plug-ins is written in YAML. See also Using YAML configuration files.
A configuration file should contain a map at the top level which has keys for connectivityPlugins and some of startChains, dynamicChains and dynamicChainManagers.
*The value of connectivityPlugins is a map which specifies how each plug-in is to be loaded. The keys name the plug-ins, and the values specify how the host loads the plug-ins. Plug-ins may be written in:
*Java. In this case, a class key and a classpath key should exist.
The class is name of the plug-in class, which must include the package. The plug-in's documentation specifies the class name to be used. The class is a transport, a codec or dynamic transport chain manager. See also Requirements of a plug-in class.
The classpath can be either a single string or a list of strings. For example:
*Single string:
classpath: one.jar
*List of strings where each string is written on a new line with a preceding dash and space:
classpath:
- one.jar
- two.jar
- three.jar
*List of strings where the strings are delimited by semicolons (;). For example:
classpath: one.jar;two.jar;three.jar
Each string can name an absolute or relative jar file or directory.
An optional directory key specifies a directory which is where the jar files will be found (unless an absolute path is specified for a classpath element).
*C++. In this case, a class key and a libraryName key should exist.
The class is the base name of the class, without a package. The plug-in's documentation specifies the class name to be used. The class is a transport, a codec or dynamic transport chain manager. See also Requirements of a plug-in class.
The libraryName is the base filename name of the library, excluding the operating system-specific prefixes and suffixes (that is, excluding the lib prefix and .so suffix for UNIX, and the .dll" suffix for Windows).
An optional directory key specifies a directory which is where the library will be found (see Deploying plug-in libraries).
globalConfig is an optional map providing default configuration options for this plug-in, which are used by all chains/chain definitions using this plug-in that do not provide their own value for them. The globalConfig configuration can be overridden by configuration per chain.
*Chains under startChains are created at startup. The value of startChains is a map where each key is a string that names a chain. Each value should be a list, naming the plug-ins that make up the chain. Each chain must contain one host plug-in, which is one of the built-in supported host plug-ins, optionally followed by a number of codecs, and end with a plug-in that is the transport. Configuration can optionally be specified for each plug-in, by following the plug-in name with a colon and space, and providing the configuration below it. Note that in YAML terms, the chain entry is a map rather than a string.
*The dynamicChains map is used to provide chain definitions that are used by chain manager plug-ins or EPL code that dynamically create chain instances after the correlator has started. Each key in the map is a chain definition identifier, which is the string that will be used by the chain manager or from EPL to identify what kind of chain it wants to create. Each value should be a list, naming the plug-ins that make up the chain, similar to what you would specify in startChains. Each chain must contain one host plug-in, which is one of the built-in supported host plug-ins, optionally followed by a number of codecs, and end with a plug-in that is the transport. Configuration can optionally be specified for each plug-in, by following the plug-in name with a colon and space, and providing the configuration below it as a map value. One difference between dynamicChains and startChains is that the plug-in configurations used in dynamicChains can specify @{varname} variable placeholders which get replaced when a chain instance is created from the chain definition, with values provided dynamically by the chain manager plug-in or the EPL createDynamicChain call. If you are using a chain manager plug-in, see the plug-in's documentation for information about any @{varname} substitutions that it supports. Note that this is unrelated to the ${varname} replacements that are performed statically when YAML files are loaded at startup.
*The value of dynamicChainManagers is a map where each key is a manager name, that is, a string naming an instance of a dynamic chain manager plug-in class. Each value is a map providing the configuration for the chain manager instance (such as details for connecting to a specific external system) and the name of the transport plug-in it is associated with. The manager should have the following keys:
*transport: Specifies the transport plug-in associated with this dynamic chain manager. This must match the key used in connectivityPlugins to load this chain manager, and also the name used in the dynamicChains definition to identify the transport plug-in at the end of each chain. This is the name used for the plug-in in the configuration file, not the name of the class that implements the plug-in.
*managerConfig: Specifies the configuration map that will be passed to the chain manager constructor when it is created at startup. The available configuration options are defined by the plug-in author, therefore, see the plug-in's documentation for details. If the managerConfig is invalid and the chain manager throws an exception, the correlator logs an error message and fails to start. The managerConfig usually includes details for connecting to a specific external server or system. Some chain managers may also provide some options that are set in the transport plug-in's configuration section under dynamicChains, for example, options specific to the protocol or message format described by that chain definition.
Note that there can be more than one manager instance configured for a given transport, for example, if you need to connect to several different servers of the same type. Each manager can make use of more than one chain definition, for example, if different message formats (such as XML and JSON) are being used with the same server or chain manager. In simple configurations where a transport only ever had a single manager instance and a single chain definition, it is common to use the same string for the transport name, dynamic chain definition identifier and manager name. However, there is no requirement for them to be the same.
You can use .properties files to specify values for ${varname} substitution variables in configuration files. See Using properties files for further information.
There are a few values which can be written into the configuration file which will be substituted at runtime. This is to aid portability of configuration files between different deployments. Specifically the following variables may be used:
Variable
Description
${PARENT_DIR}
The absolute normalized path of the directory containing the properties file or YAML file currently being processed.
${APAMA_HOME}
The path to the Apama installation.
${APAMA_WORK}
The path to the Apama work directory.
${$}
The literal $ sign.
Example:
connectivityPlugins:
myTransport:
directory: ${APAMA_WORK}/build
classpath:
- myTransport.jar
class: org.my.Transport

startChains:
service:
- apama.eventMap
- myTransport:
apamaInstall: ${APAMA_HOME}
The following example shows a more complex configuration for a transport plug-in that uses two dynamic chain manager instances and also two different chain definitions:
connectivityPlugins:
# a transport plug-in that uses a chain manager to instantiate
# its chains and transport instances dynamically
myTransport:
directory: ${APAMA_WORK}/build
classpath:
- myTransport.jar
class: org.my.MyTransportChainManager

# ... codecs defined here too
 
dynamicChainManagers:
# example of multiple chain managers for the same transport;
# an instance is created during correlator startup for each
# manager listed here
myTransportManager1:
# must match transport plug-in name specified under connectivityPlugins
transport: myTransport
 
managerConfig:
myManagerConfigOption: ${myTransport.foo}
myTransportManager2:
# must match transport plug-in name specified under connectivityPlugins
transport: myTransport
 
managerConfig:
# some managers specify which chain definition
# to use in their configuration (others decide it at runtime)
myStaticallyConfiguredChainId: myJSONChainDefinition
 
dynamicChains:
myJSONChainDefinition:
- apama.eventMap
- jsonCodec
# must match transport plug-in name specified under connectivityPlugins
- myTransport:
myTransportChainDefOption1: @{bar}
myTransportChainDefOption2: ${myTransport.baz}
 
myXMLChainDefinition:
- apama.eventMap
- myXMLCodec
- myTransport
To see a fully working example of using a dynamic chain manager plug-in, try adding the Universal Messaging connectivity plug-in to your project (see Adding the Universal Messaging connectivity plug-in to a project).
In a configuration file, you can also specify the following:
*Additional YAML configuration files that are to be processed. For more details, see Including YAML configuration files inside another YAML configuration file.
*JVM options which the correlator is to pass to the embedded JVM. For more details, see Specifying JVM options.