> Markdown version of [Collaboration List](https://vaadin.com/docs/v23/tools/collaboration/advanced/collaboration-list). Section index: [llms.txt](https://vaadin.com/docs/v23/tools/llms.txt)

# <a id="ce.collaboration-list"></a>Store Ordered Values in Topics

The Topic API provides the `CollaborationList` data structure to store ordered values and subscribe to their changes.

You can get a `CollaborationList` by its name in the Topic connection activation callback.

`CollaborationListExample.java`

```java
// NOTE: In a real application, use the user id of the logged in user
// instead
String userId = System.identityHashCode(UI.getCurrent()) + "";
UserInfo localUser = new UserInfo(userId, "User " + userId);
CollaborationEngine.getInstance().openTopicConnection(this, "my-topic",
        localUser, connection -> {
            CollaborationList list = connection.getNamedList("my-list");
            return null;
        });
```

When you have gotten the list instance, you can insert values at the end of the list with the `insertLast()` method.

`CollaborationListExample.java`

```java
ListOperationResult<Void> result = list.insertLast("foo");
```

Since the insertion is asynchronous, the method returns a result object from which you can get a `CompletableFuture` that you can use to determine when the insertion has been done.

`CollaborationListExample.java`

```java
ListOperationResult<Void> result = list.insertLast("foo");
result.getCompletableFuture().thenAccept(v -> {
    // do something when the insertion completes
});
```

The result object also provides the `ListKey` of the inserted item, which you can use to replace the item itself, get its current value or remove it from the list.

`CollaborationListExample.java`

```java
ListOperationResult<Void> result = list.insertLast("foo");
ListKey key = result.getKey();

// Replace an item using its key
list.set(key, "bar");

// Get an item value using its key
String bar = list.getItem(key, String.class);


// Remove an item using its key
list.remove(key);
```

## <a id="advanced-list-operations"></a>Advanced List Operations

The `ListOperation` class allows you to prepare a list operation that can then be applied to the list using the `CollaborationList::apply` method.

The reason you may want to use this class is to define certain conditions that must be met when the operation is attempted. If a condition isn’t met, the operation isn’t be completed. This is useful to protect against duplicate operations.

Static methods of `ListOperation`

- `insertFirst()` Value is inserted at the beginning of the list.

- `insertLast()` Value is inserted at the end of the list.

- `insertBefore()` Value is inserted immediately before a specified key.

- `insertAfter()` Value is inserted immediately after a specified key.

- `insertBetween()` Shorthand for `insertAfter(value, keyBefore).ifNext(keyBefore, keyAfter)`.

Conditional methods of `ListOperation`

- `ifFirst(key)` The specified `key` must be the first in the list.

- `ifLast(key)` The specified `key` must be the last in the list.

- `ifPrev(key, keyPrev)` The specified `keyPrev` must be immediately before `key`.

- `ifNext(key, keyNext)` The specified `keyNext` must be immediately after `key`.

- `ifEmpty()` The list must have no entries.

- `ifNotEmpty()` The list must have at least one entry.

`CollaborationListExample.java`

```java
// Insert an item at the end of the list
// Only succeeds if key is currently last
ListOperation operation1 = ListOperation.insertLast("baz")
        .ifLast(key);
ListOperationResult<Boolean> result1 = list
        .apply(operation1);
ListKey key1 = result1.getKey();

// Insert an item before key1
// Only succeeds if key1 is currently last
ListOperation operation2 = ListOperation
        .insertBefore(key1, "qux").ifLast(key1);
ListOperationResult<Boolean> result2 = list
        .apply(operation2);
ListKey key2 = result2.getKey();

// Insert an item between two keys
// Only succeeds if the keys are consecutive
ListOperation operation3 = ListOperation.insertBetween(key2,
        key1, "xyz");
ListOperationResult<Boolean> result3 = list
        .apply(operation3);
```

`` 106C5E39-A7E3-48D9-AF74-2E9A9A6576DF` ``
