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.
// 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.
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.
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.
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);
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.
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 forinsertAfter(value, keyBefore).ifNext(keyBefore, keyAfter)
.
ListOperation
-
ifFirst(key)
The specifiedkey
must be the first in the list. -
ifLast(key)
The specifiedkey
must be the last in the list. -
ifPrev(key, keyPrev)
The specifiedkeyPrev
must be immediately beforekey
. -
ifNext(key, keyNext)
The specifiedkeyNext
must be immediately afterkey
. -
ifEmpty()
The list must have no entries. -
ifNotEmpty()
The list must have at least one entry.
// 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`