# Watchlist API interfaces and classes

This Watchlist API consists of four interfaces, and four implementation classes for the StreamLink.

## API Documentation

### Interfaces

* [caplin/watchlist/WatchlistService,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_WatchlistService)
* [caplin/watchlist/WatchlistServiceEvents,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_WatchlistServiceEvents)
* [caplin/watchlist/Watchlist,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_Watchlist)
* [caplin/watchlist/WatchlistEvents,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_WatchlistEvents)
* [caplin/watchlist/WatchlistContentsManager,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_WatchlistContentsManager)

### StreamLink implementation classes

* [caplin/sljsadapter/providers/StreamLinkWatchlistService,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_sljsadapter_providers_StreamLinkWatchlistService)
* [caplin/sljsadapter/watchlist/StreamLinkWatchlist,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_sljsadapter_watchlist_StreamLinkWatchlist)
* [caplin/sljsadapter/watchlist/StreamLinkWatchlistContentsManager,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_sljsadapter_watchlist_StreamLinkWatchlistContentsManager)
* [caplin/watchlist/sljs/WatchlistGridDataProvider,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_sljs_WatchlistGridDataProvider)

## Interface overview

### WatchlistService

The [WatchlistService,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_WatchlistService) object, retrieved from the Service Registry, is the object to use for:

* creating watchlists,
* disposing of watchlists,
* monitoring the status of the data connection to the Caplin Platform, via the event [WatchlistServiceEvents,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_WatchlistServiceEvents).STATUS_CHANGED.

Register listeners for the Watchlist Service events [WatchlistServiceEvents,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_WatchlistServiceEvents).ADDED and [WatchlistServiceEvents,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_WatchlistServiceEvents).REMOVED to maintain your own array of the user’s [Watchlist,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_Watchlist) objects.

### Watchlist

Watchlist objects are never constructed directly but are retrieved via five sources:

* Directly from the [WatchlistService.getById,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_WatchlistService#getById) method. This approach is used by the [Webcentric](../../3/webcentric/index.md) layout manager when de-serialising a GUI layout from XML.
* As the first function parameter of the event handler for the [WatchlistServiceEvents,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_WatchlistServiceEvents).ADDED event
* As the first function parameter of the event handler for the [WatchlistServiceEvents,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_WatchlistServiceEvents).REMOVED event
* As the first function parameter of the success callback for the [WatchlistService.create,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_WatchlistService#create) method
* As the first function parameter of the error callback for the [WatchlistService.dispose,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_WatchlistService#dispose) method

A Watchlist object allows direct access to its metadata, but working with its contents requires working, either directly or indirectly, with subscriptions:

* To retrieve the subjects monitored by a watchlist, subscribe to the RTTP subject name returned by [Watchlist.getSubject,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_Watchlist#getSubject)
* To insert, append or remove subjects from the watchlist, request a [WatchlistContentsManager,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_WatchlistContentsManager) instance for the watchlist using [Watchlist.getContentsManager,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_Watchlist#getContentsManager).

Register a listener for the Watchlist event [WatchlistEvents,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_WatchlistEvents).PROPERTY_CHANGED to respond to a change in a watchlist’s name.

### WatchlistContentsManager

An instance of the [WatchlistContentsManager,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_WatchlistContentsManager) class is used to manipulate the contents of a watchlist. You acquire an instance by calling [Watchlist.getContentsManager,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_Watchlist#getContentsManager). When you have finished manipulating the watchlist, call [WatchlistContentsManager.destroy,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_WatchlistContentsManager#destroy).

The [WatchlistContentsManager,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_WatchlistContentsManager) class exists as a means for [Watchlist,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_Watchlist) objects to manage the subscription to their container on Transformer. A watchlist object will keep its subscription open while at least one issued [WatchlistContentsManager,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_WatchlistContentsManager) remains active.

### WatchlistGridDataProvider

The [WatchlistGridDataProvider,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_sljs_WatchlistGridDataProvider) class links a grid component to an existing Transformer-hosted watchlist. This class provides data to the grid via a subscription to the watchlist’s container on Transformer, and translates local row addition and removal events into commands to Transformer’s Watchlist Service.

You will rarely need to instantiate this class explicitly; the Webcentric layout manager will instantiate the class in the course of deserialising the XML layout configuration for a watchlist grid.