Create containers in an Integration Adapter

You create a container in a DataSource application, typically in an Integration Adapter that interfaces to a bank system, or other external data feed. The DataSource application supplies the list of items that go in the container. For example, the external system could provide a list of Fixed Income instruments that can be traded.

The DataSource application that creates the container can be different to the one that supplies the data referenced by the container elements.

Overview

You use the DataSource API within your Adapter development kit (SDK) to set up and manipulate the container. For example, if you’re developing a Java-based Adapter using the Caplin Integration Suite, there are interfaces and classes to help you set up a container, such as ContainerMessage and ContainerOperation.

The APIs allow you to perform various operations on a container, such as:

  • Add an element to the end of the container.

  • Insert an element into the container at a specified position.

  • Remove an existing element from the container.

  • Remove ("clear down") all elements from the container that match a specified subject prefix.

The exact way in which your DataSource application should subscribe to and manipulate containers depends on which DataSource SDK you are using. For details, consult the API documentation for your particular DataSource SDK.

Design guidelines

Here are some design guidelines to help you when implementing containers in an Integration Adapter.

Responding to container subscription requests

When an Integration Adapter receives a subscription request, it normally sends back all the data relating to the subscribed subject as an initial image. However, if the subscription request is for for a container, it can be better to send the container elements back to Liberator / Transformer as an update, rather than as an initial image.

This is because when you have more than one Adapter supplying the container elements, the Adapters would normally be unaware of each other’s role. As a result, when the container is first subscribed to, if the Adapters were to send the container elements as an image ("image" flag set on the DataSource message), the later images would overwrite the earlier ones.

For example, referring to the example with multiple Integration Adapters in How can I…​ Obtain container data from several sources, the Adapter NYLists sends Liberator a container image with elements /FI/US/A, /FI/US/B, and /FI/US/C. Then the Adapter LONLists, which is unaware of NYLists, sends Liberator a container image with elements /FI/EU/A, /FI/EU/B, and /FI/EU/C. This second set of elements would overwrite the elements /FI/US/A, /FI/US/B and /FI/US/C in the container, because receipt of an image implicitly causes the container to be cleared down.

To avoid this problem, send the container elements as an update; Adapter LONLists then appends elements /FI/EU/A, /FI/EU/B, /FI/EU/C to the existing elements from NYLists (/FI/US/A, /FI/US/B, /FI/US/C).

Forcing container clear down

To recover properly from error situations (lost connections, and so on), an Integration Adapter may need to clear down (empty) any containers for which it supplies elements. The obvious way to do this is to just send the Liberator / Transformer an empty image of the container. However, this simple approach will not work when multiple Integration Adapters populate the same container.

Referring to the example with multiple Integration Adapters in How can I…​ Obtain container data from several sources, when the NYLists Adapter needs to clear down the container, rather than sending an empty image of the container, it should send the client a container "clear down" response for the subject /FI/US. This forces a clear down of just the container elements that particular Adapter is responsible for (/FI/US/A, /FI/US/B, /FI/US/C …​). Similarly, the LONLists Adapter should send a "clear down" response for /FI/EU, which forces a clear down of just the /FI/EU/A, /FI/EU/B, /FI/EU/C …​ elements in the container.

See also: