# Lists

The list data type is an alternative implementation of the [container](datasource-containers.md) model offering higher performance when serving collections of records intended to be displayed together, such as a trade blotter. It combines both index and records in a single compound object, while remaining compatible with StreamLink application code that subscribes to containers.

Available from Caplin Platform 8 (see [Product support](#product-support) for versions).

## Overview

A list object combines index and row data in a single object. It comprises two collections:

* **Elements:** an ordered set of row IDs. This collection is a list’s equivalent of a container subject.
* **Rows:** a map of records keyed by row ID. This collection is a list’s equivalent of a container’s constituent objects.

Lists are performance optimised for serving views of row-based data, such as trade blotters:

**FX execution blotter**

![list-datatype-example-blotter](../../images/list-datatype-example-blotter.png)

A list object built to serve the blotter above would look like this:

**Example blotter implemented as a list, using Trade IDs for row IDs (data abridged for clarity)**

![list-datatype-example](../../images/list-datatype-example.svg)

Compare the list object above with the equivalent implementation as a container, with the elements collection (the container) and each row (the container constituents) hosted under their own individual subjects:

**Example blotter implemented as a container, using Trade IDs for row IDs**

![list-datatype-example-container](../../images/list-datatype-example-container.svg)

A list object can be retrieved by Liberator from an adapter more efficiently than an equivalent container. For Liberator to retrieve a container from an adapter requires $n + 1$ requests, where $n$ is the number of container elements. To retrieve an equivalent list from an adapter, requires just one request.

A list object can be served to StreamLink clients more efficiently than an equivalent container. Optimisations in the transport of lists to clients reduces the amount of processing required by StreamLink.

## Compatibility with container subscription code

In versions of StreamLink that support lists (see [Product support](#product-support)), the handling of lists is identical to the handling of containers, making them interchangeable.

From Liberator 8.0.10, when setting a window size for a StreamLink subscription to a list object (see [Subscription.setContainerWindow](https://docs.caplin.com/developer/api/streamlinkjs/latest/classes/Subscription.html#setContainerWindow)), set the window size to a value less than the value of Liberator’s [`list-object-yield-size`](../liberator/liberator-tuning-configuration.md#list-object-yield-size) configuration item.

## Product support

The List data type is available in Caplin Platform 8 from the following versions:

**Component support for the list data type**

| Component | Minimum Version |
| --- | --- |
| Liberator | 8.0.5 |
| Transformer | 8.0.4 |
|    Refiner module | _Not supported yet_ |

**StreamLink support for the list data type**

| Library | Minimum Version |
| --- | --- |
| StreamLink Android | 8.0.4 |
| StreamLink Java | 8.0.4 |
| StreamLink JS | 8.0.4 |
| StreamLink TS | 8.0.4 |
| StreamLink .NET | 8.0.4 |
| StreamLink iOS | _Not supported yet_ |

**DataSource support for the list data type**

| Library | Minimum Version |
| --- | --- |
| C DataSource API | 8.0.6 |
| Java DataSource API | 8.0.6 |
| .NET DataSource API | _Not supported yet_ |

## Feature parity with containers

**DataSource: feature parity between lists and containers**

| Feature | Containers | Lists |
| --- | :-: | :-: |
| Add element | icon:check[] | icon:check[] |
| Insert element | icon:check[] | icon:check[] |
| Remove element | icon:check[] | icon:check[] |
| Add row | icon:check[] | icon:check[] |
| Update row fields | icon:check[] | icon:check[] |
| Add new fields to row | icon:check[] | icon:check[] |
| Remove row | icon:check[] | icon:check[] |

**Liberator: feature parity between lists and containers**

| Feature | Containers | Lists |
| --- | :-: | --- |
| Permission the element collection | icon:check[] | icon:check[] |
| Permission individual rows | icon:check[] | icon:close[] |
| StreamLink parameters: windowing | icon:check[] | Since SL 8.0.6 |
| Liberator server : windowing | icon:check[] | Since Liberator 8.0.10 |
| StreamLink parameters: field selection | icon:check[] | _Not supported yet_ |
| StreamLink parameters: row filtering | icon:check[] | _Not supported yet_ |

**Transformer Refiner: feature parity between lists and containers**

| Feature | Containers | Lists |
| --- | :-: | :-: |
| Server-side sorting | icon:check[] | _Not supported yet_ |
| Server-side filtering | icon:check[] | _Not supported yet_ |

## Reference documentation 
You subscribe to a List object from your StreamLink application in the exact same way as you do to a container. See the [Container Event](https://docs.caplin.com/developer/api/streamlinkjs/latest/classes/ContainerEvent.html) StreamLink API documentation for more information.

See the [DataSource for Java API documentation for List messages](https://docs.caplin.com/developer/api/datasource_java/latest/com/caplin/datasource/messaging/list/package-summary.html) for more information about creating, sending and updating List objects in a Java Adapter.

## List object how-to
See the [container to List object migration guide](datasource-list-migration.md) to see how to convert an existing container solution to use List objects.

---

**See also:**

* [Migrating from containers to lists](datasource-list-migration.md)
* DataSource for Java: [com.caplin.datasource.messaging.list](https://docs.caplin.com/developer/api/datasource_java/latest/com/caplin/datasource/messaging/list/package-summary.html) package