DataSource configuration

DataSource applications are highly configurable.

Once you’ve built a DataSource application (such as an Integration Adapter) using the Caplin Integration Suite, the C DataSource API or the DataSource.NET API, you can configure it. You do this through settings supplied in one or more configuration files, or through settings that are stored in a database and supplied to the DataSource application by a configuration script. When you define the configuration in files, you’d normally make these files part of a Platform Blade that packages up the DataSource application (typically it would be an Adapter blade) - see Using blades to simplify configuration below.

Liberator and Transformer, being C-based DataSource applications, are also configured in the same way. They have their own, application specific, configuration settings too.

What do I need to configure in my DataSource application?

The configuration for a DataSource application includes:

  • Its name.

  • A label that is unique within the network of connected DataSource applications.

  • Connection details for each of the DataSource application’s peers.

Here’s an example of the DataSource configuration for an Integration Adapter that handles FX trades. The Adapter is called FXTradingAdapter and has a unique label FXTradingAdapter01. It talks to both a Liberator and a Transformer, and when it starts up it initiates the connection to each of them.

The Platform deployment would look like this:

Platform deplyment diagram for Liberator and Transformer talking to an FX Trading Adapter

The configuration for the FX Trading Adapter would look like this. The Adapter’s called FXTradingAdapter and it has a unique label (datasrc-local-label) of FXTradingAdapter01

#
# DataSource configuration for FX Trading Adapter
#

datasrc-name FXTradingAdapter

# Unique label identifying this Adapter:
datasrc-local-label FXTradingAdapter01

#
# Configuration defining this Integration Adapter's connection to LiberatorA.
#

add-peer
   remote-name            LiberatorA
   remote-label           LiberatorA
   addr                   <liberator host name or ip address>
   port                   15000
   local-type             active|contrib
   heartbeat-time         15
   heartbeat-slack-time   5
end-peer

#
# Configuration defining this Integration Adapter's connection to TransformerA.
#

add-peer
   remote-name            TransformerA
   remote-label           TransformerA
   addr                   <transformer host name or ip address>
   port                   15001
   local-type             active|contrib
   heartbeat-time         15
   heartbeat-slack-time   5
end-peer

This is what the add-peer …​ end-peer configuration that specifies each of the Trading Adapter’s peers means:

  • remote-name is the name by which the Adapter knows the peer.

  • remote-label is the unique label that identifies the peer.

  • addr is the host name or IP address of the peer.

  • port is the TCP port number to which the Adapter sends connection requests to the peer.

  • local-type active|contrib means that the FX Trading Adapter accepts active subscription requests from the peer, and it also accepts data (contributions) from the peer.

  • heartbeat-time and heartbeat-slack-time define the rate at which heartbeat messages are exchanged between the Adapter and its peers to ensure that the connection between them is kept open when no data is being exchanged.

And here’s the DataSource configuration for the Liberator that talks to both the Transformer and the FX Trading Adapter. The Liberator’s called LiberatorA and it has a unique label (datasrc-local-label) of LiberatorA.

#
# DataSource configuration for LiberatorA.
#
datasrc-name LiberatorA

# Unique label identifying this Liberator:
datasrc-local-label LiberatorA

datasrc-port 15000

#
# Configuration defining this Liberator's connection to TransformerA.
#
add-peer
   remote-name            TransformerA
   remote-label           TransformerA
   remote-type            active|contrib
   heartbeat-time         15
   heartbeat-slack-time   5
end-peer

#
# Configuration defining this Liberator's connection to the FX Trading.Adapter
#
add-peer
   remote-name            FXTradingAdapter
   remote-label           FXTradingAdapter01
   remote-type            active|contrib
   heartbeat-time         15
   heartbeat-slack-time   5
end-peer

Note that in the configuration for each peer connection the remote-label must match the datasrc-local-label in that peer’s configuration. The remote-type setting for each peer (in this case for Transformer and the Trading Adapter) tells the Liberator that the peers support active subscriptions, so the Liberator can send them subscription requests, and that they also accept data (contributions) from the Liberator.

Finally, here’s the DataSource configuration for the Transformer that talks to both the Liberator and the FX Trading Adapter. The Transformer’s called TransformerA and it has a unique label (datasrc-local-label) of TransformerA.

#
# DataSource configuration for TransformerA.
#
datasrc-name   TransformerA

# Unique label identifying this Transformer:
datasrc-local-label TransformerA

datasrc-port   15001

#
# Configuration defining this Tranformers's connection to LiberatorA.
#
add-peer
   addr                   <liberator host name or ip address>
   port                   15000
   remote-name            LiberatorA
   remote-label           LiberatorA
   local-type             active|contrib
   heartbeat-time         15
   heartbeat-slack-time   5
end-peer

add-peer
   remote-name            FXTradingAdapter
   remote-label           FXTradingAdapter01
   remote-type            active|contrib
   heartbeat-time         15
   heartbeat-slack-time   5
end-peer

This configuration is very similar to the Liberator’s. The main difference (apart from names) is that the Transformer initiates the connection to the Liberator (port 15000 in the add-peer …​ end-peer setup for the Liberator), but not to the Trading Adapter. In reality you would probably want to access the FXTradingAdapter from Liberator and Transformer through a configured data service.

The local-type active|contrib option in the add-peer configuration for the Liberator means that the Transformer will accept subscription requests and contributions from the Liberator peer. Conversely the remote-type active|contrib option in the add-peer for the Trading Adapter tells the Transformer that the Trading Adapter supports active subscriptions, so subscription requests can be sent to it, and the Adapter will accept contributions from the Transformer.

You might have noticed that whereas the add-peer items in the Integration Adapter and the Transformer configuration specify connection addresses (addr) and port numbers (port), the Liberator configuration doesn’t have this information in its add-peer items. These items aren’t needed in the Liberator’s peer configuration because the Integration Adapter and the Transformer connect in to the Liberator, rather than the Liberator initiating the connections. Similarly, the Transformer configuration for the Integration Adapter peer connection doesn’t need addr and port options because the Adapter connects in to the Transformer.

How do I create custom configuration items?

If you’re writing a C or C++ based DataSource application, such as an Integration Adapter, you can create new configuration items that are specific to your application. Just call the appropriate configuration functions in the C DataSource API. For more about this, see the "Configuration API" page in the C DataSource API Documentation.

Using blades to simplify configuration

When you use the Caplin Platform Deployment Framework, the availability of Caplin Platform blades makes it much easier to configure your Integration Adapters, Liberator and Transformer.

  • When you develop an Integration Adapter using the Caplin Integration Suite , the Adapter is generated as an Adapter blade, that includes all the configuration necessary for it to connect to a Liberator and/or Transformer.

  • Liberator and Transformer are also supplied with Config blades that implement specific features without you needing to write your own configuration; for example, see the list of Liberators blades that are supplied with the Deployment Framework.

See also: