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 a TopicConnection. Changes performed by one user will be delivered as events to subscribers defined by other users.

Since:

3.1

Author:

Vaadin Ltd

Method Summary

Modifier and Type	Method and Description
default CompletableFuture<Void>	append(Object item) Appends the given item to the list.
CompletableFuture<Void>	append(Object item, EntryScope scope) Appends the given item to the list with the given scope.
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> List<T>	getItems(Class<T> type) Gets the list items as instances 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.
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

append

default CompletableFuture<Void> append(Object item)

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, not null

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

CompletableFuture<Void> append(Object item,
                               EntryScope scope)

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 of EntryScope.TOPIC to keep the entry in the list until explicitly removed, or EntryScope.CONNECTION to automatically remove the entry when the connection which put the entry is deactivated.

Parameters:

item - the item to append, not null

scope - the scope of the entry, not null

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, not null

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 empty Optional 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 interface HasExpirationTimeout

Returns:

the expiration timeout

setExpirationTimeout

void setExpirationTimeout(Duration expirationTimeout)

Sets the expiration timeout of this list. If set, the list content is cleared when expirationTimeout has passed after the last connection to the topic this list belongs to is closed. If set to null, the timeout is cancelled.

Specified by:

setExpirationTimeout in interface HasExpirationTimeout

Parameters:

expirationTimeout - the expiration timeout