Overview of using connectivity plug-ins

Connectivity plug-ins can be written in Java or C++, and run inside the correlator process to allow messages to be sent and received to/from external systems. Individual plug-ins are combined together to form chains that define the path of a message, with the correlator host process at one end and an external system or library at the other, and with an optional sequence of message mapping transformations between them.

You can configure connectivity plug-ins and also develop applications that use them with Software AG Designer. To do so, you have to add an instance of the User Connectivity connectivity bundle to your project. See Adding connectivity and adapter bundles to projects or Creating and managing an Apama project from the command line for more information.

A configuration file describes both the chains and the plug-ins making up each chain. The configuration file is written using the YAML markup language, and can express structured configuration (maps, lists and simple values) for plug-ins. The default text encoding of the configuration file is UTF-8.

connectivityPlugins:
stringCodec:
libraryName: connectivity-string-codec
class: StringCodec
mapperCodec:
libraryName: MapperCodec
class: MapperCodec
jsonCodec:
libraryName: connectivity-json-codec
class: JSONCodec
HTTPClientTransport:
libraryName: connectivity-http-client
class: HTTPClient
startChains:
weatherService:
- apama.eventMap:
defaultEventType: com.apamax.Weather
- mapperCodec:
"*":
towardsTransport:
mapFrom:
- metadata.requestId: payload.id
defaultValue:
- metadata.http.path: /data/2.5/weather?q=Cambridge,uk
- metadata.http.method: GET
- jsonCodec
- stringCodec
- HTTPClientTransport:
host: api.openweathermap.org

Codec plug-in. Optionally, one or more codec plug-ins are responsible for applying transformations to the messages (for example, the JSON codec in the above example) to prepare them for the next plug-in in the chain.

Transport plug-in. One transport plug-in is responsible for sending/receiving messages to/from an external system (for example, HTTPClientTransport in the above example).

Host plug-in. One built-in host plug-in is responsible for sending/receiving messages to/from the correlator process that is hosting the chain. These are built-in plug-ins (which do not need to be specified in the connectivityPlugins stanza) which the correlator supports. Host plug-ins determine in which format events are passed in and out of the correlator. Thus, a chain should specify a host plug-in that is compatible with the next codec or transport element in the chain. Host plug-ins can also specify on which channel the chain receives events from the correlator, and can specify a default channel to send events in to the correlator (for example, apama.eventMap in the above example).

Each transport plug-in and codec plug-in used in the chain must also be described in the connectivityPlugins stanza. All of the plug-ins in a chain can optionally take configuration that is specified in the configuration file nested below them.

Plug-ins can pass messages in a number of different forms (strings, maps, plug-in-specific objects). Codecs can be used to translate from one form into another. For example, the JSON codec in the above example would convert the map objects from the host plug-in to strings in JSON format. Transport plug-ins and codec plug-ins written in Java and C++ may be used together in the same chain regardless of language, using strings or maps of values to represent messages passed across the language boundary.

An Apama application can send events to a connectivity chain in the same way as it would send them to any other receiver connected to the correlator, that is, using the send or emit keywords. Events from the EPL application are translated into the form specified by the host plug-in (the first in the chain configuration). They are then passed through each codec in turn, and then delivered to the transport. The host plug-in (apama.eventMap in the above example) by default listens for events from the application using the chain's name as a channel name. The host plug-in can be configured to listen on a specific set of channels with the subscribeChannels configuration property.

Events from a connectivity chain's transport are passed through the codecs in the reverse order and are translated by the host plug-in to Apama events which are enqueued to the Apama application on the desired channel. The channel can be specified per event, or a default channel can be configured in the host plug-in using the defaultChannel configuration property.