Package com.vaadin.collaborationengine
Interface CollaborationList
-
- All Superinterfaces:
HasExpirationTimeout
public interface CollaborationList extends HasExpirationTimeout
A list that is shared between multiple users. List instances can be retrieved through aTopicConnection
. Changes performed by one user will be delivered as events to subscribers defined by other users.- Since:
- 3.1
- Author:
- Vaadin Ltd
-
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods Modifier and Type Method Description default CompletableFuture<Void>
append(Object item)
Deprecated, for removal: This API element is subject to removal in a future version.Useapply(ListOperation)
withListOperation.insertLast(Object)
default CompletableFuture<Void>
append(Object item, EntryScope scope)
Deprecated, for removal: This API element is subject to removal in a future version.Useapply(ListOperation)
withListOperation.insertLast(Object).withScope(EntryScope)
ListOperationResult<Boolean>
apply(ListOperation operation)
Performs the given list operation.TopicConnection
getConnection()
Gets the topic connection which is used to propagate changes to this list.Optional<Duration>
getExpirationTimeout()
Gets the optional expiration timeout of this list.<T> T
getItem(ListKey key, com.fasterxml.jackson.core.type.TypeReference<T> type)
Gets the list item identifier by the given key as instance of the given type reference.<T> T
getItem(ListKey key, Class<T> type)
Gets the list item identifier by the given key as instance of the given class.<T> List<T>
getItems(com.fasterxml.jackson.core.type.TypeReference<T> type)
Gets the list items as instances of the given type reference.<T> List<T>
getItems(Class<T> type)
Gets the list items as instances of the given class.Stream<ListKey>
getKeys()
Gets the keys for all the items on the list.default ListOperationResult<Boolean>
insertAfter(ListKey key, Object item)
Inserts the given item just after the given key location.default ListOperationResult<Boolean>
insertAfter(ListKey key, Object item, EntryScope scope)
Deprecated, for removal: This API element is subject to removal in a future version.Useapply(ListOperation)
withListOperation.insertAfter(ListKey, Object).withScope (EntryScope)
.default ListOperationResult<Boolean>
insertBefore(ListKey key, Object item)
Inserts the given item just before the given key location.default ListOperationResult<Boolean>
insertBefore(ListKey key, Object item, EntryScope scope)
Deprecated, for removal: This API element is subject to removal in a future version.Useapply(ListOperation)
withListOperation.insertBefore(ListKey, Object).withScope (EntryScope)
.default ListOperationResult<Void>
insertFirst(Object item)
Inserts the given item as the first item of the list.default ListOperationResult<Void>
insertFirst(Object item, EntryScope scope)
Deprecated, for removal: This API element is subject to removal in a future version.Useapply(ListOperation)
withListOperation.insertFirst(Object).withScope(EntryScope)
.default ListOperationResult<Void>
insertLast(Object item)
Inserts the given item as the last item of the list.default ListOperationResult<Void>
insertLast(Object item, EntryScope scope)
Deprecated, for removal: This API element is subject to removal in a future version.Useapply(ListOperation)
withListOperation.insertLast(Object).withScope(EntryScope)
.default CompletableFuture<Boolean>
moveAfter(ListKey key, ListKey keyToMove)
Moves the second given key just after the first given key location.default CompletableFuture<Boolean>
moveBefore(ListKey key, ListKey keyToMove)
Moves the second given key just before the first given key location.default CompletableFuture<Boolean>
remove(ListKey key)
Removes the value for the item identified by the given key.default CompletableFuture<Boolean>
set(ListKey key, Object value)
Sets a new value for the item identified by the given key.default CompletableFuture<Boolean>
set(ListKey key, Object value, EntryScope scope)
Deprecated, for removal: This API element is subject to removal in a future version.Useapply(ListOperation)
withListOperation.set(ListKey, Object).withScope(EntryScope)
.void
setExpirationTimeout(Duration expirationTimeout)
Sets the expiration timeout of this list.Registration
subscribe(ListSubscriber subscriber)
Subscribes to changes to this list.
-
-
-
Method Detail
-
getItems
<T> List<T> getItems(Class<T> type)
Gets the list items as instances of the given class.- Type Parameters:
T
- the type of the class given as the argument- Parameters:
type
- the expected type of the items- Returns:
- a list of the items
- Throws:
JsonConversionException
- if one or more values in the list cannot be converted to an instance of the given class
-
getItems
<T> List<T> getItems(com.fasterxml.jackson.core.type.TypeReference<T> type)
Gets the list items as instances of the given type reference.- Type Parameters:
T
- the type of the reference given as the argument- Parameters:
type
- the reference of the expected type of the items- Returns:
- a list of the items
- Throws:
JsonConversionException
- if one or more values in the list cannot be converted to an instance of the given type reference
-
getItem
<T> T getItem(ListKey key, Class<T> type)
Gets the list item identifier by the given key as instance of the given class.- Type Parameters:
T
- the type of the value fromtype
parameter, e.g.String
- Parameters:
key
- the key of the requested item, notnull
type
- the expected type of the item, notnull
- Returns:
- the requested item
- Throws:
JsonConversionException
- if the value in the list cannot be converted to an instance of the given class- Since:
- 4.1
-
getItem
<T> T getItem(ListKey key, com.fasterxml.jackson.core.type.TypeReference<T> type)
Gets the list item identifier by the given key as instance of the given type reference.- Type Parameters:
T
- the type reference of the value fromtype
parameter, e.g.List
- Parameters:
key
- the key of the requested item, notnull
type
- the expected type reference of the item, notnull
- Returns:
- the requested item
- Throws:
JsonConversionException
- if the value in the list cannot be converted to an instance of the given class- Since:
- 4.1
-
getKeys
Stream<ListKey> getKeys()
Gets the keys for all the items on the list.- Returns:
- the keys
- Since:
- 4.1
-
apply
ListOperationResult<Boolean> apply(ListOperation operation)
Performs the given list operation. The operation contains the value, its position and other requirements. If any of the conditions are not met, the operation may fail (seeListOperationResult
).- Parameters:
operation
- the list operation, notnull
- Returns:
- the result of the operation, not
null
-
insertFirst
default ListOperationResult<Void> insertFirst(Object item)
Inserts the given item as the first item of the list.- Parameters:
item
- the item, notnull
- Returns:
- the result of the operation, not
null
-
insertFirst
@Deprecated(since="5.1", forRemoval=true) default ListOperationResult<Void> insertFirst(Object item, EntryScope scope)
Deprecated, for removal: This API element is subject to removal in a future version.Useapply(ListOperation)
withListOperation.insertFirst(Object).withScope(EntryScope)
.Inserts the given item as the first item of the list, with the given scope.- Parameters:
item
- the item, notnull
scope
- the scope of the entry, notnull
- Returns:
- the result of the operation, not
null
-
insertLast
default ListOperationResult<Void> insertLast(Object item)
Inserts the given item as the last item of the list.- Parameters:
item
- the item, notnull
- Returns:
- the result of the operation, not
null
- Since:
- 4.1
-
insertLast
@Deprecated(since="5.1", forRemoval=true) default ListOperationResult<Void> insertLast(Object item, EntryScope scope)
Deprecated, for removal: This API element is subject to removal in a future version.Useapply(ListOperation)
withListOperation.insertLast(Object).withScope(EntryScope)
.Inserts the given item as the last item of the list, with the given scope.- Parameters:
item
- the item, notnull
scope
- the scope of the entry, notnull
- Returns:
- the result of the operation, not
null
- Since:
- 4.1
-
insertBefore
default ListOperationResult<Boolean> insertBefore(ListKey key, Object item)
Inserts the given item just before the given key location.- Parameters:
key
- the position key, notnull
item
- the item, notnull
- Returns:
- the result of the operation, not
null
-
insertBefore
@Deprecated(since="5.1", forRemoval=true) default ListOperationResult<Boolean> insertBefore(ListKey key, Object item, EntryScope scope)
Deprecated, for removal: This API element is subject to removal in a future version.Useapply(ListOperation)
withListOperation.insertBefore(ListKey, Object).withScope (EntryScope)
.Inserts the given item just before the given key location, with the given scope.- Parameters:
key
- the position key, notnull
item
- the item, notnull
scope
- the scope of the entry, notnull
- Returns:
- the result of the operation, not
null
-
insertAfter
default ListOperationResult<Boolean> insertAfter(ListKey key, Object item)
Inserts the given item just after the given key location.- Parameters:
key
- the position key, notnull
item
- the item, notnull
- Returns:
- the result of the operation, not
null
-
insertAfter
@Deprecated(since="5.1", forRemoval=true) default ListOperationResult<Boolean> insertAfter(ListKey key, Object item, EntryScope scope)
Deprecated, for removal: This API element is subject to removal in a future version.Useapply(ListOperation)
withListOperation.insertAfter(ListKey, Object).withScope (EntryScope)
.Inserts the given item just after the given key location, with the given scope.- Parameters:
key
- the position key, notnull
item
- the item, notnull
scope
- the scope of the entry, notnull
- Returns:
- the result of the operation, not
null
-
moveBefore
default CompletableFuture<Boolean> moveBefore(ListKey key, ListKey keyToMove)
Moves the second given key just before the first given key location.- Parameters:
key
- the position key, notnull
keyToMove
- the key to move, notnull
- Returns:
- a completable future that is resolved when the operation has
completed, not
null
-
moveAfter
default CompletableFuture<Boolean> moveAfter(ListKey key, ListKey keyToMove)
Moves the second given key just after the first given key location.- Parameters:
key
- the position key, notnull
keyToMove
- the key to move, notnull
- Returns:
- a completable future that is resolved when the operation has
completed, not
null
-
set
default CompletableFuture<Boolean> set(ListKey key, Object value)
Sets a new value for the item identified by the given key.- Parameters:
key
- the item key, notnull
value
- the new value of the item- Returns:
- the result of the operation, not
null
- Since:
- 4.1
-
set
@Deprecated(since="5.2", forRemoval=true) default CompletableFuture<Boolean> set(ListKey key, Object value, EntryScope scope)
Deprecated, for removal: This API element is subject to removal in a future version.Useapply(ListOperation)
withListOperation.set(ListKey, Object).withScope(EntryScope)
.Sets a new value for the item identified by the given key, with the given scope.- Parameters:
key
- the item key, notnull
value
- the new value of the itemscope
- the scope of the entry, notnull
- Returns:
- the result of the operation, not
null
- Since:
- 4.1
-
remove
default CompletableFuture<Boolean> remove(ListKey key)
Removes the value for the item identified by the given key.- Parameters:
key
- the item key, notnull
- Returns:
- the result of the operation, not
null
-
append
@Deprecated(since="4.0", forRemoval=true) default CompletableFuture<Void> append(Object item)
Deprecated, for removal: This API element is subject to removal in a future version.Useapply(ListOperation)
withListOperation.insertLast(Object)
Appends the given item to the list.The given item must be JSON-serializable so it can be sent over the network when Collaboration Engine is hosted in a standalone server.
- Parameters:
item
- the item to append, notnull
- Returns:
- a completable future that is resolved when the item has been appended to the list
- Throws:
JsonConversionException
- if the given item isn't serializable as JSON string
-
append
@Deprecated(since="4.0", forRemoval=true) default CompletableFuture<Void> append(Object item, EntryScope scope)
Deprecated, for removal: This API element is subject to removal in a future version.Useapply(ListOperation)
withListOperation.insertLast(Object).withScope(EntryScope)
Appends the given item to the list with the given scope.The given item must be JSON-serializable so it can be sent over the network when Collaboration Engine is hosted in a standalone server.
The
scope
parameter specifies the scope of the entry, which is either one ofEntryScope.TOPIC
to keep the entry in the list until explicitly removed, orEntryScope.CONNECTION
to automatically remove the entry when the connection which put the entry is deactivated.- Parameters:
item
- the item to append, notnull
scope
- the scope of the entry, notnull
- Returns:
- a completable future that is resolved when the item has been appended to the list
- Throws:
JsonConversionException
- if the given item isn't serializable as JSON string
-
subscribe
Registration subscribe(ListSubscriber subscriber)
Subscribes to changes to this list. When subscribing, the subscriber will receive an event for each item already in the list.- Parameters:
subscriber
- the subscriber to use, notnull
- Returns:
- a handle that can be used for removing the subscription, not
null
-
getConnection
TopicConnection getConnection()
Gets the topic connection which is used to propagate changes to this list.- Returns:
- the topic connection used by this list, not
null
-
getExpirationTimeout
Optional<Duration> getExpirationTimeout()
Gets the optional expiration timeout of this list. An emptyOptional
is returned if no timeout is set, which means the list is not cleared when there are no connected users to the related topic (this is the default).- Specified by:
getExpirationTimeout
in interfaceHasExpirationTimeout
- Returns:
- the expiration timeout
-
setExpirationTimeout
void setExpirationTimeout(Duration expirationTimeout)
Sets the expiration timeout of this list. If set, the list content is cleared whenexpirationTimeout
has passed after the last connection to the topic this list belongs to is closed. If set tonull
, the timeout is cancelled.- Specified by:
setExpirationTimeout
in interfaceHasExpirationTimeout
- Parameters:
expirationTimeout
- the expiration timeout
-
-