Watchlist API design

A key influence on the design of the Watchlist API is the requirement that watchlist configurations synchronise across devices in real time. To reduce the possibility of conflicts between devices, changes to watchlists are made on Transformer first and then replicated, via StreamLink subscription, to all the user’s connected devices. The Watchlist API only changes its own (local) model in response to watchlist-related events received from Transformer.

In the Watchlist API, commands to create, modify and delete watchlists are sent to Transformer’s Watchlist Service by contributing new records to a 'control object', unique and private to each user. Transformer’s Watchlist Service subscribes to changes to the control object and thus receives the commands as subscription updates.

Watchlists are hosted on Transformer as a collection of containers, private to each user. These containers persist across restarts of Transformer. The Watchlist API insulates you from needing to manage subscriptions to these containers directly, and if you use the WatchlistGridDataProvider to populate the Caplin Grid component, you need never know the details of how watchlists are hosted. However, the Watchlist API does expose one container you can subscribe to directly should you need it: the container of subject names monitored by a watchlist (see Watchlist.getSubject).

The Watchlist API manages subscriptions efficiently. While the WatchlistService maintains a constant subscription to the list of the user’s watchlists, the Watchlist object maintains only a temporary subscription to its own content container, active only when you need to manipulate the watchlist’s content. Methods for manipulation of a watchlist’s content are only available on the WatchlistContentsManager interface. Requesting a WatchlistContentsManager for a watchlist activates the watchlist’s subscription, and the subscription remains active until all WatchlistContentsManager instances for the watchlist have been destroyed (see WatchlistContentsManager.destroy). The Watchlist object uses its temporary subscription to monitor the success of the WatchlistContentsManager.insert, WatchlistContentsManager.append and WatchlistContentsManager.remove methods.

The diagram below illustrates the relationship between the main classes in Caplin Trader’s Watchlist API, and the Caplin Platform components hosted in Transformer. Commands to manipulate watchlists are shown as blue arrows, and signify the publication of records to the user’s private control object. Subscriptions to watchlist containers are shown as bold green arrows. Not shown in the diagram, but described above, is the temporary nature of the Watchlist object’s subscription to its own content.

The Watchlist API’s events are an important part of its interface. While the API maintains a private model of watchlist data held on Transformer, the API provides limited direct access to this model through method calls on it. There are two use cases that are implemented through the event model rather than by method calls:

The API does not trigger events for the addition and removal of a watchlist’s subjects. As described above, the Watchlist API avoids subscribing to watchlist content unless actual operations need to be performed upon it. Instead, you should subscribe directly to the watchlist’s subject container on Transformer. The method Watchlist.getSubject returns the subject name of this container.

See also: