com.vaadin.collaborationengine

Interface CollaborationMap

All Superinterfaces:

HasExpirationTimeout

public interface CollaborationMap
extends HasExpirationTimeout

A map that is shared between multiple users. Map instances can be retrieved through a TopicConnection. Changes performed by one user will be delivered as events to subscribers defined by other users.

Since:

1.0

Author:

Vaadin Ltd

Method Summary

Modifier and Type	Method and Description
<T> T	get(String key, Class<T> type) Gets the map value for the given key as an instance of the given class.
<T> T	get(String key, com.fasterxml.jackson.core.type.TypeReference<T> type) Gets the map value for the given key as an instance corresponding to the given type reference.
TopicConnection	getConnection() Gets the topic connection which is used to propagate changes to this map.
Optional<Duration>	getExpirationTimeout() Gets the optional expiration timeout of this map.
Stream<String>	getKeys() Gets a stream of the currently available keys.
default CompletableFuture<Void>	put(String key, Object value) Associates the given value with the given key.
CompletableFuture<Void>	put(String key, Object value, EntryScope scope) Associates the given value with the given key and scope.
CompletableFuture<Boolean>	replace(String key, Object expectedValue, Object newValue) Atomically replaces the value for a key if and only if the current value is as expected.
void	setExpirationTimeout(Duration expirationTimeout) Sets the expiration timeout of this map.
Registration	subscribe(MapSubscriber subscriber) Subscribes to changes to this map.

Method Detail

get

<T> T get(String key,
          Class<T> type)

Gets the map value for the given key as an instance of the given class.

Parameters:

key - the string key for which to get a value, not null

type - the expected type

Returns:

the value associated with the key, or null if no value is present

Throws:

JsonConversionException - if the value in the map cannot be converted to an instance of the given class

Since:

1.0

get

<T> T get(String key,
          com.fasterxml.jackson.core.type.TypeReference<T> type)

Gets the map value for the given key as an instance corresponding to the given type reference.

Parameters:

key - the string key for which to get a value, not null

type - the type reference of the expected type to get

Returns:

the value associated with the key, or null if no value is present

Throws:

JsonConversionException - if the value in the map cannot be converted to an instance of the given type reference

Since:

1.0

put

default CompletableFuture<Void> put(String key,
                                    Object value)

Associates the given value with the given key. This method can also be used to remove an association by passing null as the value. Subscribers are notified if the new value isn't equals() with the old value.

The given value must be JSON-serializable so it can be sent over the network when Collaboration Engine is hosted in a standalone server.

Parameters:

key - the string key for which to make an association, not null

value - the value to set, or null to remove the association

Returns:

a completable future that is resolved when the data update is completed.

Throws:

JsonConversionException - if the given value isn't serializable as JSON string

Since:

1.0

put

CompletableFuture<Void> put(String key,
                            Object value,
                            EntryScope scope)

Associates the given value with the given key and scope. This method can also be used to remove an association by passing null as the value. Subscribers are notified if the new value isn't equals() with the old value.

The given value 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 map until explicitly removed, or EntryScope.CONNECTION to automatically remove the entry when the connection which put the entry is deactivated. Putting the same value will update the ownership and the scope of the entry, but listeners won't be invoked.

Parameters:

key - the string key for which to make an association, not null

value - the value to set, or null to remove the association

scope - the scope of the entry, not null

Returns:

a completable future that is resolved when the data update is completed.

Throws:

JsonConversionException - if the given value isn't serializable as JSON string

Since:

4.0

replace

CompletableFuture<Boolean> replace(String key,
                                   Object expectedValue,
                                   Object newValue)

Atomically replaces the value for a key if and only if the current value is as expected. Subscribers are notified if the new value isn't equals() with the old value. equals() is also used to compare the current value with the expected value.

The given value must be JSON-serializable so it can be sent over the network when Collaboration Engine is hosted in a standalone server.

Parameters:

key - the string key for which to make an association, not null

expectedValue - the value to compare with the current value to determine whether to make an update, or null to expect that no value is present

newValue - the new value to set, or null to remove the association

Returns:

a boolean completable future that is resolved when the data update is completed. The resolved value is true if the expected value was present so that the operation could proceed; false if the expected value was not present

Throws:

JsonConversionException - if the given value isn't serializable as JSON string

Since:

1.0

getKeys

Stream<String> getKeys()

Gets a stream of the currently available keys. The stream is backed by a current snapshot of the available keys and will thus not update even if keys are added or removed before the stream is processed.

Returns:

the stream of keys, not null

Since:

1.0

subscribe

Registration subscribe(MapSubscriber subscriber)

Subscribes to changes to this map. When subscribing, the subscriber will receive an event for each current value association.

Parameters:

subscriber - the subscriber to use, not null

Returns:

a handle that can be used for removing the subscription, not null

Since:

1.0

getConnection

TopicConnection getConnection()

Gets the topic connection which is used to propagate changes to this map.

Returns:

the topic connection used by this map, not null

Since:

1.0

getExpirationTimeout

Optional<Duration> getExpirationTimeout()

Gets the optional expiration timeout of this map. An empty Optional is returned if no timeout is set, which means the map 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 map. If set, this map data is cleared when expirationTimeout has passed after the last connection to the topic this map belongs to is closed. If set to null, the timeout is cancelled.

Specified by:

setExpirationTimeout in interface HasExpirationTimeout

Parameters:

expirationTimeout - the expiration timeout