Method Details

• 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

• remove

  default CompletableFuture<Void> remove(String key)

  Removes the value with the given key. Subscribers are notified if there exists a non-null value.

  Parameters:

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

  Returns:

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

• remove

  default CompletableFuture<Boolean> remove(String key, Object expectedValue)

  Removes the value with the given key only if and only if the current value is as expected. Subscribers are notified if the current value is non-null.

  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 remove the value, or null to expect that no value is present.

  Returns:

  a boolean completable future that is resolved when the removal 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

• 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