Synchronization (scheduling 8.4.0 API)

All Superinterfaces:

Serializable

All Known Implementing Classes:

SynchronizationWrapper
```
@PublicAPI
public interface Synchronization
extends Serializable
```
Synchronization provides a persistent key/value store API, similar to the Map interface. The Synchronization service is automatically started with the ProActive Server.
The key/value store is organized in channels. Each channel corresponds to a private key/value HashMap. Synchronization provides an API to create or delete channel and decide if the channel should be persisted on disk (thus available on scheduler restart) or kept in memory only.

Each map operation is performed on a given channel, with the channel name provided as parameter.

The Synchronization API provides also additional map operations such as conditionalCompute to perform conditional operations based on the result of a BiPredicate, or wait operations such as waitUntil(String, String, String) to block the caller until a given predicate is met.

These wait operations allow the API to be used for synchronization and not only as a key/value store. The Synchronization API is notably used to synchronize parallel ProActive Tasks.

Each map operation can be performed remotely, for example from ProActive Workflow Tasks executed inside remote ProActive Nodes.

Each operation is as well synchronous and atomic, remote operations are received by the service and handled through a request queue.

Java 8 Map operations, based on lambdas, are allowed, but lambdas must be provided as String values containing Groovy Closures expressions which match the corresponding java lambda.

For example, to write a groovy closure which match a Java BiFunction:
```
 
 "{ k, x -> x + 1 }"
 
```
Since:

27/03/2018

See Also:

Map, Groovy Closures

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`boolean`	`channelExists(String name)` Check for channel existence
`void`	`clear(String channel)` Removes all of the mappings from this channel map (optional operation).
`Serializable`	`compute(String channel, String key, String remappingFunction)` Attempts to compute a mapping for the specified key and its current mapped value (or `null` if there is no current mapping).
`Serializable`	`computeIfAbsent(String channel, String key, String mappingFunction)` If the specified key is not already associated with a value (or is mapped to `null`), attempts to compute its value using the given mapping function and enters it into this map unless `null`.
`Serializable`	`computeIfPresent(String channel, String key, String remappingFunction)` If the value for the specified key is present and non-null, attempts to compute a new mapping given the key and its current mapped value.
`PredicateActionResult`	`conditionalCompute(String channel, String key, String predicate, String thenRemappingFunction)` Conditional execution on a key based on a predicate result and remapping function.
`PredicateActionResult`	`conditionalCompute(String channel, String key, String predicate, String thenRemappingFunction, String elseRemappingFunction)` Conditional execution on a key based on a predicate result and two remapping functions.
`void`	`conditionalReplaceAll(String channel, String predicate, String thenRemappingFunction)` Replaces each entry's value with the result of invoking the given function on that entry if the given predicate is satisfied.
`void`	`conditionalReplaceAll(String channel, String predicate, String thenRemappingFunction, String elseRemappingFunction)` Replaces each entry's value with the result of invoking the given function on that entry if the given predicate is satisfied.
`boolean`	`containsKey(String channel, String key)` Returns `true` if this channel map contains a mapping for the specified key.
`boolean`	`containsValue(String channel, Serializable value)` Returns `true` if this channel map maps one or more keys to the specified value.
`boolean`	`createChannel(String name, boolean isPersistent)` Create a channel, overwrite any already existing channel with the same name
`boolean`	`createChannelIfAbsent(String name, boolean isPersistent)` Create a channel, if no channel with the same name already exists
`boolean`	`deleteChannel(String name)` Delete a channel
`Set<Map.Entry<String,Serializable>>`	`entrySet(String channel)` Returns a `Set` view of the mappings contained in this map.
`void`	`forEach(String channel, String action)` Performs the given action for each entry in this channel map until all entries have been processed or the action throws an exception.
`Serializable`	`get(String channel, String key)` Returns the value to which the specified key is mapped, or `null` if this channel map contains no mapping for the key.
`Serializable`	`getOrDefault(String channel, String key, Serializable defaultValue)` Returns the value to which the specified key is mapped, or `defaultValue` if this channel map contains no mapping for the key.
`boolean`	`isEmpty(String channel)` Returns `true` if this channel map contains no key-value mappings.
`Set<String>`	`keySet(String channel)` Returns a `Set` view of the keys contained in this channel map.
`Serializable`	`merge(String channel, String key, Serializable value, String remappingFunction)` If the specified key is not already associated with a value or is associated with null, associates it with the given non-null value.
`Serializable`	`put(String channel, String key, Serializable value)` Associates the specified value with the specified key in this channel map (optional operation).
`void`	`putAll(String channel, Map<? extends String,? extends Serializable> m)` Copies all of the mappings from the specified map to this channel map (optional operation).
`Serializable`	`putIfAbsent(String channel, String key, Serializable value)` If the specified key is not already associated with a value (or is mapped to `null`) associates it with the given value and returns `null`, else returns the current value.
`Serializable`	`remove(String channel, String key)` Removes the mapping for a key from this channel map if it is present (optional operation).
`boolean`	`remove(String channel, String key, Serializable value)` Removes the entry for the specified key only if it is currently mapped to the specified value.
`Serializable`	`replace(String channel, String key, Serializable value)` Replaces the entry for the specified key only if it is currently mapped to some value.
`boolean`	`replace(String channel, String key, Serializable oldValue, Serializable newValue)` Replaces the entry for the specified key only if currently mapped to the specified value.
`void`	`replaceAll(String channel, String function)` Replaces each entry's value with the result of invoking the given function on that entry until all entries have been processed or the function throws an exception.
`int`	`size(String channel)` Returns the number of key-value mappings in this channel map.
`Collection<Serializable>`	`values(String channel)` Returns a `Collection` view of the values contained in this channel map.
`boolean`	`waitUntil(String channel, String key, String predicate)` Blocking call waiting for a predicate to be met.
`boolean`	`waitUntil(String channel, String key, String predicate, long timeout)` Blocking call waiting for a predicate to be met, with a timeout.
`PredicateActionResult`	`waitUntilThen(String channel, String key, String predicate, long timeout, String thenRemappingFunction)` Blocking call waiting with timeout for a predicate to be met before executing a remapping function.
`PredicateActionResult`	`waitUntilThen(String channel, String key, String predicate, String thenRemappingFunction)` Blocking call waiting for a predicate to be met before executing a remapping function.

- Method Detail
  - createChannel
```
boolean createChannel(String name,
                      boolean isPersistent)
               throws IOException
```
    Create a channel, overwrite any already existing channel with the same name
    
    Parameters:
    
    name - new channel name
    
    isPersistent - controls whether the channel should have a database backup (in case of crash or restart) or is kept in memory only
    
    Returns:
    
    true if the channel was created and no previous channel with the same name already existed
    
    Throws:
    
    IOException - if an error occurred while persisting the channel on disk
  - createChannelIfAbsent
```
boolean createChannelIfAbsent(String name,
                              boolean isPersistent)
                       throws IOException
```
    Create a channel, if no channel with the same name already exists
    
    Parameters:
    
    name - new or existing channel name
    
    isPersistent - controls whether the channel should have a database backup (in case of crash or restart) or is kept in memory only
    
    Returns:
    
    true if a new channel was created and no previous channel with the same name already existed
    
    Throws:
    
    IOException - if an error occurred while persisting the channel on disk
  - deleteChannel
```
boolean deleteChannel(String name)
               throws IOException
```
    Delete a channel
    
    Parameters:
    
    name - existing channel name
    
    Returns:
    
    true if a channel existed with the given name and was deleted by this operation
    
    Throws:
    
    IOException - if an error occurred while persisting the channel on disk
  - channelExists
```
boolean channelExists(String name)
```
    Check for channel existence
    
    Parameters:
    
    name - channel name
    
    Returns:
    
    true if the channel exists
  - size
```
int size(String channel)
  throws InvalidChannelException
```
    Returns the number of key-value mappings in this channel map. If the channel map contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.
    
    Parameters:
    
    channel - channel identifier
    
    Returns:
    
    the number of key-value mappings in this channel map
    
    Throws:
    
    InvalidChannelException - if the channel does not exist
  - isEmpty
```
boolean isEmpty(String channel)
         throws InvalidChannelException
```
    Returns true if this channel map contains no key-value mappings.
    
    Parameters:
    
    channel - channel identifier
    
    Returns:
    
    true if this channel map contains no key-value mappings
    
    Throws:
    
    InvalidChannelException - if the channel does not exist
  - containsKey
```
boolean containsKey(String channel,
                    String key)
             throws InvalidChannelException
```
    Returns true if this channel map contains a mapping for the specified key. More formally, returns true if and only if this channel map contains a mapping for a key k such that (key==null ? k==null : key.equals(k)). (There can be at most one such mapping.)
    
    Parameters:
    
    channel - channel identifier
    
    key - key whose presence in this channel map is to be tested
    
    Returns:
    
    true if this channel map contains a mapping for the specified key
    
    Throws:
    
    ClassCastException - if the key is of an inappropriate type for this channel map
    
    InvalidChannelException - if the channel does not exist
  - containsValue
```
boolean containsValue(String channel,
                      Serializable value)
               throws InvalidChannelException
```
    Returns true if this channel map maps one or more keys to the specified value. More formally, returns true if and only if this channel map contains at least one mapping to a value v such that (value==null ? v==null : value.equals(v)). This operation will probably require time linear in the channel map size for most implementations of the Map interface.
    
    Parameters:
    
    channel - channel identifier
    
    value - value whose presence in this channel map is to be tested
    
    Returns:
    
    true if this channel map maps one or more keys to the specified value
    
    Throws:
    
    ClassCastException - if the value is of an inappropriate type for this channel map (optional) (optional)
    
    InvalidChannelException - if the channel does not exist
  - get
```
Serializable get(String channel,
                 String key)
          throws InvalidChannelException
```
    Returns the value to which the specified key is mapped, or null if this channel map contains no mapping for the key.
    More formally, if this channel map contains a mapping from a key k to a value v such that (key==null ? k==null : key.equals(k)), then this method returns v; otherwise it returns null. (There can be at most one such mapping.)
    As this channel map permits null values, a return value of null does not necessarily indicate that the channel map contains no mapping for the key; it's also possible that the channel map explicitly maps the key to null. The containsKey operation may be used to distinguish these two cases.
    
    Parameters:
    
    channel - channel identifier
    
    key - the key whose associated value is to be returned
    
    Returns:
    
    the value to which the specified key is mapped, or null if this channel map contains no mapping for the key
    
    Throws:
    
    ClassCastException - if the key is of an inappropriate type for this channel map (optional)
    
    InvalidChannelException - if the channel does not exist
  - put
```
Serializable put(String channel,
                 String key,
                 Serializable value)
          throws InvalidChannelException,
                 IOException
```
    Associates the specified value with the specified key in this channel map (optional operation). If the channel map previously contained a mapping for the key, the old value is replaced by the specified value. (A channel map m is said to contain a mapping for a key k if and only if containsKey(String, String) m.containsKey(k)} would return true.)
    
    Parameters:
    
    channel - channel identifier
    
    key - key with which the specified value is to be associated
    
    value - value to be associated with the specified key
    
    Returns:
    
    the previous value associated with key, or null if there was no mapping for key. (A null return can also indicate that the channel map previously associated null with key, as this implementation supports null values.)
    
    Throws:
    
    UnsupportedOperationException - if the put operation is not supported by this channel map
    
    ClassCastException - if the class of the specified key or value prevents it from being stored in this channel map
    
    IllegalArgumentException - if some property of the specified key or value prevents it from being stored in this channel map
    
    InvalidChannelException - if the channel does not exist
    
    IOException - if an error occurred when persisting the modified channel on disk
  - remove
```
Serializable remove(String channel,
                    String key)
             throws InvalidChannelException,
                    IOException
```
    Removes the mapping for a key from this channel map if it is present (optional operation). More formally, if this channel map contains a mapping from key k to value v such that (key==null ? k==null : key.equals(k)), that mapping is removed. (The channel map can contain at most one such mapping.)
    Returns the value to which this channel map previously associated the key, or null if the channel map contained no mapping for the key.
    As this channel map permits null values, a return value of null does not necessarily indicate that the channel map contained no mapping for the key; it's also possible that the channel map explicitly mapped the key to null.
    The channel map will not contain a mapping for the specified key once the call returns.
    
    Parameters:
    
    channel - channel identifier
    
    key - key whose mapping is to be removed from the channel map
    
    Returns:
    
    the previous value associated with key, or null if there was no mapping for key.
    
    Throws:
    
    UnsupportedOperationException - if the remove operation is not supported by this channel map
    
    ClassCastException - if the key is of an inappropriate type for this channel map (optional)
    
    InvalidChannelException - if the channel does not exist
    
    IOException - if an error occurred when persisting the modified channel on disk
  - putAll
```
void putAll(String channel,
            Map<? extends String,? extends Serializable> m)
     throws InvalidChannelException,
            IOException
```
    Copies all of the mappings from the specified map to this channel map (optional operation). The effect of this call is equivalent to that of calling put(String, String, Serializable) put(k, v)} on this channel map once for each mapping from key k to value v in the specified map. The behavior of this operation is undefined if the specified map is modified while the operation is in progress.
    
    Parameters:
    
    channel - channel identifier
    
    m - mappings to be stored in this channel map
    
    Throws:
    
    UnsupportedOperationException - if the putAll operation is not supported by this channel map
    
    ClassCastException - if the class of a key or value in the specified channel map prevents it from being stored in this channel map
    
    NullPointerException - if the specified map is null
    
    IllegalArgumentException - if some property of a key or value in the specified channel map prevents it from being stored in this channel map
    
    InvalidChannelException - if the channel does not exist
    
    IOException - if an error occurred when persisting the modified channel on disk
  - clear
```
void clear(String channel)
    throws InvalidChannelException,
           IOException
```
    Removes all of the mappings from this channel map (optional operation). The channel map will be empty after this call returns.
    
    Parameters:
    
    channel - channel identifier
    
    Throws:
    
    UnsupportedOperationException - if the clear operation is not supported by this channel map
    
    InvalidChannelException - if the channel does not exist
    
    IOException - if an error occurred when persisting the modified channel on disk
  - keySet
```
Set<String> keySet(String channel)
            throws InvalidChannelException
```
    Returns a Set view of the keys contained in this channel map. As this operation is performed remotely, the returned set is a remote copy of the server-side channel content. Any operation on the reported set will not be reflected on the server and can be used only for informative purpose.
    
    Parameters:
    
    channel - channel identifier
    
    Returns:
    
    a set view of the keys contained in this map
    
    Throws:
    
    InvalidChannelException - if the channel does not exist
  - values
```
Collection<Serializable> values(String channel)
                         throws InvalidChannelException
```
    Returns a Collection view of the values contained in this channel map. As this operation is performed remotely, the returned collection is a remote copy of the server-side channel content. Any operation on the reported set will not be reflected on the server and can be used only for informative purpose.
    
    Parameters:
    
    channel - channel identifier
    
    Returns:
    
    a collection view of the values contained in this map
    
    Throws:
    
    InvalidChannelException - if the channel does not exist
  - entrySet
```
Set<Map.Entry<String,Serializable>> entrySet(String channel)
                                      throws InvalidChannelException
```
    Returns a Set view of the mappings contained in this map. As this operation is performed remotely, the returned collection is a remote copy of the server-side channel content. Any operation on the reported set will not be reflected on the server and can be used only for informative purpose.
    
    Parameters:
    
    channel - channel identifier
    
    Returns:
    
    a set view of the mappings contained in this map
    
    Throws:
    
    InvalidChannelException - if the channel does not exist
  - getOrDefault
```
Serializable getOrDefault(String channel,
                          String key,
                          Serializable defaultValue)
                   throws InvalidChannelException
```
    Returns the value to which the specified key is mapped, or defaultValue if this channel map contains no mapping for the key. This implementation guarantees that the operation is performed atomically on the map.
    
    Parameters:
    
    channel - channel identifier
    
    key - the key whose associated value is to be returned
    
    defaultValue - the default mapping of the key
    
    Returns:
    
    the value to which the specified key is mapped, or defaultValue if this channel map contains no mapping for the key
    
    Throws:
    
    ClassCastException - if the key is of an inappropriate type for this channel map (optional)
    
    InvalidChannelException - if the channel does not exist
    
    Since:
    
    1.8
  - forEach
```
void forEach(String channel,
             String action)
      throws InvalidChannelException,
             CompilationException
```
    Performs the given action for each entry in this channel map until all entries have been processed or the action throws an exception. Unless otherwise specified by the implementing class, actions are performed in the order of entry set iteration (if an iteration order is specified.) Exceptions thrown by the action are relayed to the caller as ClosureEvaluationException. The action is passed as a String containing a groovy closure definition which matches the BiConsumer specification. The first parameter receives the key, and the second parameter receives the binding associated with this key. For example:
```
 
 "{ k, x -> println(k + \":\" + x) }"
 
```
    This implementation guarantees that the operation is performed atomically on the channel map.
    Parameters:
    
    channel - channel identifier
    
    action - The action to be performed for each entry
    
    Throws:
    
    NullPointerException - if the specified action is null
    
    InvalidChannelException - if the channel does not exist
    
    CompilationException - if an error occurred during the compilation of the specified action
    
    ClosureEvaluationException - if an error occurred during the evaluation of the specified action
    
    Since:
    
    1.8
    
    See Also:
    
    Map.forEach(BiConsumer), BiConsumer, Groovy Closures
  - replaceAll
```
void replaceAll(String channel,
                String function)
         throws InvalidChannelException,
                CompilationException,
                IOException
```
    Replaces each entry's value with the result of invoking the given function on that entry until all entries have been processed or the function throws an exception. Exceptions thrown by the function are relayed to the caller as ClosureEvaluationException. The mapping function is passed as a String containing a groovy closure definition which matches the BiFunction specification. The first parameter receives the key, and the second parameter receives the binding associated with this key. For example:
```
 
 "{ k, x -> x = x + 1 }"
 
```
    This implementation guarantees that the operation is performed atomically on the channel map.
    Parameters:
    
    channel - channel identifier
    
    function - the function to apply to each entry
    
    Throws:
    
    NullPointerException - if the specified function is null
    
    InvalidChannelException - if the channel does not exist
    
    CompilationException - if an error occurred during the compilation of the specified action
    
    ClosureEvaluationException - if an error occurred during the evaluation of the specified action
    
    IOException - if an error occurred when persisting the modified channel on disk
    
    Since:
    
    1.8
    
    See Also:
    
    Map.replaceAll(BiFunction), BiFunction, Groovy Closures
  - putIfAbsent
```
Serializable putIfAbsent(String channel,
                         String key,
                         Serializable value)
                  throws InvalidChannelException,
                         IOException
```
    If the specified key is not already associated with a value (or is mapped to null) associates it with the given value and returns null, else returns the current value. The default implementation is equivalent to, for this map:
```
 
 V v = map.get(key);
 if (v == null)
     v = map.put(key, value);

 return v;
 
```
    This implementation guarantees that the operation is performed atomically on the channel map.
    Parameters:
    
    channel - channel identifier
    
    key - key with which the specified value is to be associated
    
    value - value to be associated with the specified key
    
    Returns:
    
    the previous value associated with the specified key, or null if there was no mapping for the key. (A null return can also indicate that the map previously associated null with the key, as this implementation supports null values.)
    
    Throws:
    
    UnsupportedOperationException - if the put operation is not supported by this channel map (optional)
    
    ClassCastException - if the key or value is of an inappropriate type for this channel map (optional)
    
    IllegalArgumentException - if some property of the specified key or value prevents it from being stored in this channel map (optional)
    
    InvalidChannelException - if the channel does not exist
    
    IOException - if an error occurred when persisting the modified channel on disk
    
    Since:
    
    1.8
    
    See Also:
    
    Map.putIfAbsent(Object, Object)
  - remove
```
boolean remove(String channel,
               String key,
               Serializable value)
        throws InvalidChannelException,
               IOException
```
    Removes the entry for the specified key only if it is currently mapped to the specified value. The default implementation is equivalent to, for this map:
```
 
 if (map.containsKey(key) && Objects.equals(map.get(key), value)) {
     map.remove(key);
     return true;
 } else
     return false;
 
```
    This implementation guarantees that the operation is performed atomically on the channel map.
    Parameters:
    
    channel - channel identifier
    
    key - key with which the specified value is associated
    
    value - value expected to be associated with the specified key
    
    Returns:
    
    true if the value was removed
    
    Throws:
    
    UnsupportedOperationException - if the remove operation is not supported by this channel map (optional)
    
    ClassCastException - if the key or value is of an inappropriate type for this channel map (optional)
    
    InvalidChannelException - if the channel does not exist
    
    IOException - if an error occurred when persisting the modified channel on disk
    
    Since:
    
    1.8
    
    See Also:
    
    Map.remove(Object, Object)
  - replace
```
boolean replace(String channel,
                String key,
                Serializable oldValue,
                Serializable newValue)
         throws InvalidChannelException,
                IOException
```
    Replaces the entry for the specified key only if currently mapped to the specified value. The default implementation is equivalent to, for this map:
```
 
 if (map.containsKey(key) && Objects.equals(map.get(key), value)) {
     map.put(key, newValue);
     return true;
 } else
     return false;
 
```
    This implementation guarantees that the operation is performed atomically on the channel map.
    Parameters:
    
    channel - channel identifier
    
    key - key with which the specified value is associated
    
    oldValue - value expected to be associated with the specified key
    
    newValue - value to be associated with the specified key
    
    Returns:
    
    true if the value was replaced
    
    Throws:
    
    UnsupportedOperationException - if the put operation is not supported by this channel map (optional)
    
    ClassCastException - if the class of a specified key or value prevents it from being stored in this channel map
    
    IllegalArgumentException - if some property of a specified key or value prevents it from being stored in this channel map
    
    InvalidChannelException - if the channel does not exist
    
    IOException - if an error occurred when persisting the modified channel on disk
    
    Since:
    
    1.8
    
    See Also:
    
    Map.replace(Object, Object, Object)
  - replace
```
Serializable replace(String channel,
                     String key,
                     Serializable value)
              throws InvalidChannelException,
                     IOException
```
    Replaces the entry for the specified key only if it is currently mapped to some value. The default implementation is equivalent to, for this map:
```
 
 if (map.containsKey(key)) {
     return map.put(key, value);
 } else
     return null;
 
```
    This implementation guarantees that the operation is performed atomically on the channel map.
    Parameters:
    
    channel - channel identifier
    
    key - key with which the specified value is associated
    
    value - value to be associated with the specified key
    
    Returns:
    
    the previous value associated with the specified key, or null if there was no mapping for the key. (A null return can also indicate that the channel map previously associated null with the key, as this implementation supports null values.)
    
    Throws:
    
    UnsupportedOperationException - if the put operation is not supported by this channel map (optional)
    
    ClassCastException - if the class of the specified key or value prevents it from being stored in this channel map (optional)
    
    IllegalArgumentException - if some property of the specified key or value prevents it from being stored in this channel map
    
    InvalidChannelException - if the channel does not exist
    
    IOException - if an error occurred when persisting the modified channel on disk
    
    Since:
    
    1.8
    
    See Also:
    
    Map.replace(Object, Object)
  - computeIfAbsent
```
Serializable computeIfAbsent(String channel,
                             String key,
                             String mappingFunction)
                      throws InvalidChannelException,
                             CompilationException,
                             IOException
```
    If the specified key is not already associated with a value (or is mapped to null), attempts to compute its value using the given mapping function and enters it into this map unless null. The function is passed as a String containing a groovy closure definition which matches the Function specification. The parameter received contains the key. For example:
```
 
 "{ k -> new HashSet() }"
 
```
    If the function returns null no mapping is recorded. If the function itself throws an (unchecked) exception, the exception is rethrown as a ClosureEvaluationException, and no mapping is recorded. The most common usage is to construct a new object serving as an initial mapped value or memoized result, as in:
```
 
 store.computeIfAbsent(channel, key, "{k -> new Value(k)}");
 
```
    Or to implement a multi-value map, Map<K,Collection<V>>, supporting multiple values per key: The default implementation is equivalent to the following steps for this map, then returning the current value or null if now absent:
```
 
 if (map.get(key) == null) {
     V newValue = mappingFunction.apply(key);
     if (newValue != null)
         map.put(key, newValue);
 }
 
```
    This implementation guarantees that the operation is performed atomically on the channel map.
    Parameters:
    
    channel - channel identifier
    
    key - key with which the specified value is to be associated
    
    mappingFunction - the function to compute a value
    
    Returns:
    
    the current (existing or computed) value associated with the specified key, or null if the computed value is null
    
    Throws:
    
    CompilationException - if an error occurred during the compilation of the specified action
    
    ClosureEvaluationException - if an error occurred during the evaluation of the specified action
    
    InvalidChannelException - if the channel does not exist
    
    NullPointerException - if the mappingFunction is null
    
    IOException - if an error occurred when persisting the modified channel on disk
    
    Since:
    
    1.8
    
    See Also:
    
    Map.computeIfAbsent(Object, Function), Function, Groovy Closures
  - computeIfPresent
```
Serializable computeIfPresent(String channel,
                              String key,
                              String remappingFunction)
                       throws InvalidChannelException,
                              CompilationException,
                              IOException
```
    If the value for the specified key is present and non-null, attempts to compute a new mapping given the key and its current mapped value.
    If the function returns null, the mapping is removed. If the function itself throws an (unchecked) exception, the exception is rethrown, and the current mapping is left unchanged. The function is passed as a String containing a groovy closure definition which matches the BiFunction specification. The first parameter receives the key, and the second parameter receives the binding associated with this key. For example:
```
 
 "{ k, x -> x = x + 1 }"
 
```
    The default implementation is equivalent to performing the following steps for this map, then returning the current value or null if now absent:
```
 
 if (map.get(key) != null) {
     V oldValue = map.get(key);
     V newValue = remappingFunction.apply(key, oldValue);
     if (newValue != null)
         map.put(key, newValue);
     else
         map.remove(key);
 }
 
```
    This implementation guarantees that the operation is performed atomically on the channel map.
    Parameters:
    
    channel - channel identifier
    
    key - key with which the specified value is to be associated
    
    remappingFunction - the function to compute a value
    
    Returns:
    
    the new value associated with the specified key, or null if none
    
    Throws:
    
    NullPointerException - if the remappingFunction is null
    
    CompilationException - if an error occurred during the compilation of the specified action
    
    ClosureEvaluationException - if an error occurred during the evaluation of the specified action
    
    InvalidChannelException - if the channel does not exist
    
    IOException - if an error occurred when persisting the modified channel on disk
    
    Since:
    
    1.8
    
    See Also:
    
    Map.computeIfPresent(Object, BiFunction), BiFunction, Groovy Closures
  - compute
```
Serializable compute(String channel,
                     String key,
                     String remappingFunction)
              throws InvalidChannelException,
                     CompilationException,
                     IOException
```
    Attempts to compute a mapping for the specified key and its current mapped value (or null if there is no current mapping). The function is passed as a String containing a groovy closure definition which matches the BiFunction specification. The first parameter receives the key, and the second parameter receives the binding associated with this key. For example, to either create or append a String msg to a value mapping:
```
 
 store.compute(channel, key, "{ k, v -> (v == null) ? \"" + msg + "\" : v.concat(\"" + msg + "\")}")
```
    (Method merge() is often simpler to use for such purposes.)
    If the function returns null, the mapping is removed (or remains absent if initially absent). If the function itself throws an (unchecked) exception, the exception is rethrown as a ClosureEvaluationException, and the current mapping is left unchanged. The default implementation is equivalent to performing the following steps for this map, then returning the current value or null if absent:
```
 
 V oldValue = map.get(key);
 V newValue = remappingFunction.apply(key, oldValue);
 if (oldValue != null ) {
    if (newValue != null)
       map.put(key, newValue);
    else
       map.remove(key);
 } else {
    if (newValue != null)
       map.put(key, newValue);
    else
       return null;
 }
 
```
    This implementation guarantees that the operation is performed atomically on the channel map.
    Parameters:
    
    channel - channel identifier
    
    key - key with which the specified value is to be associated
    
    remappingFunction - the function to compute a value
    
    Returns:
    
    the new value associated with the specified key, or null if none
    
    Throws:
    
    NullPointerException - if the remappingFunction is null
    
    CompilationException - if an error occurred during the compilation of the specified action
    
    ClosureEvaluationException - if an error occurred during the evaluation of the specified action
    
    InvalidChannelException - if the channel does not exist
    
    IOException - if an error occurred when persisting the modified channel on disk
    
    Since:
    
    1.8
    
    See Also:
    
    Map.compute(Object, BiFunction), BiFunction, Groovy Closures
  - merge
```
Serializable merge(String channel,
                   String key,
                   Serializable value,
                   String remappingFunction)
            throws InvalidChannelException,
                   CompilationException,
                   IOException
```
    If the specified key is not already associated with a value or is associated with null, associates it with the given non-null value. Otherwise, replaces the associated value with the results of the given remapping function, or removes if the result is null. This method may be of use when combining multiple mapped values for a key. The function is passed as a String containing a groovy closure definition which matches the BiFunction specification. The first parameter receives the key, and the second parameter receives the binding associated with this key. For example, to either create or append a String msg to a value mapping:
```
 
 store.merge(channel, key, msg, "{k, x -> x.concat(\"" + msg + "\")}")
 
```
    If the function returns null the mapping is removed. If the function itself throws an (unchecked) exception, the exception is rethrown, and the current mapping is left unchanged. The default implementation is equivalent to performing the following steps for this map, then returning the current value or null if absent:
```
 
 V oldValue = map.get(key);
 V newValue = (oldValue == null) ? value :
              remappingFunction.apply(oldValue, value);
 if (newValue == null)
     map.remove(key);
 else
     map.put(key, newValue);
 
```
    This implementation guarantees that the operation is performed atomically on the channel map.
    Parameters:
    
    channel - channel identifier
    
    key - key with which the resulting value is to be associated
    
    value - the non-null value to be merged with the existing value associated with the key or, if no existing value or a null value is associated with the key, to be associated with the key
    
    remappingFunction - the function to recompute a value if present
    
    Returns:
    
    the new value associated with the specified key, or null if no value is associated with the key
    
    Throws:
    
    NullPointerException - if the remappingFunction is null
    
    CompilationException - if an error occurred during the compilation of the specified action
    
    ClosureEvaluationException - if an error occurred during the evaluation of the specified action
    
    InvalidChannelException - if the channel does not exist
    
    IOException - if an error occurred when persisting the modified channel on disk
    
    Since:
    
    1.8
    
    See Also:
    
    Map.merge(Object, Object, BiFunction), BiFunction, Groovy Closures
  - conditionalCompute
```
PredicateActionResult conditionalCompute(String channel,
                                         String key,
                                         String predicate,
                                         String thenRemappingFunction)
                                  throws InvalidChannelException,
                                         CompilationException,
                                         IOException
```
    Conditional execution on a key based on a predicate result and remapping function. Both predicate and function are passed as String containing a groovy closure definition which matches the BiPredicate and BiFunction specifications. The first parameter receives the key, and the second parameter receives the binding associated with this key. For example, to append a String msg to a value only if the value is already defined mapping:
```
 
 store.conditionalCompute(channel, key, "{ k, v -> v != null}", "{k, v -> v.concat(\"" + msg + "\")}")
```
    If the function returns null, the mapping is removed (or remains absent if initially absent). If the predicate or function itself throw an (unchecked) exception, the exception is rethrown as a ClosureEvaluationException, and the current mapping is left unchanged. The default implementation is equivalent to performing the following steps for this map, then returning PredicateActionResult object containing the current value or null if absent:
```
 
 V oldValue = map.get(key);
 if (predicate.test(key, oldValue)) {
  map.compute(key, thenRemappingFunction);
 }
 
```
    This implementation guarantees that the operation is performed atomically on the channel map.
    Parameters:
    
    channel - channel identifier
    
    key - key with which the specified value is to be associated
    
    predicate - closure used for conditional decision
    
    thenRemappingFunction - the function to compute a value if the predicate is true
    
    Returns:
    
    a PredicateActionResult object which contains the result of the predicate evaluation and either (true) the new value associated with the key after applying thenRemappingFunction, or (false) the unmodified value associated with the key.
    
    Throws:
    
    NullPointerException - if the predicate or remappingFunction is null
    
    CompilationException - if an error occurred during the compilation of the specified action
    
    ClosureEvaluationException - if an error occurred during the evaluation of the specified action
    
    InvalidChannelException - if the channel does not exist
    
    IOException - if an error occurred when persisting the modified channel on disk
    
    Since:
    
    1.8
    
    See Also:
    
    Map.compute(Object, BiFunction), BiPredicate, BiFunction, Groovy Closures, PredicateActionResult
  - conditionalCompute
```
PredicateActionResult conditionalCompute(String channel,
                                         String key,
                                         String predicate,
                                         String thenRemappingFunction,
                                         String elseRemappingFunction)
                                  throws InvalidChannelException,
                                         CompilationException,
                                         IOException
```
    Conditional execution on a key based on a predicate result and two remapping functions. Both predicate and functions are passed as String containing a groovy closure definition which matches the BiPredicate and BiFunction specifications. The first parameter receives the key, and the second parameter receives the binding associated with this key. For example, to append a String msg to a value if the value is already defined, and otherwise set msg as the new mapping mapping:
```
 
 store.conditionalCompute(channel, key, "{ k, v -> v != null}", "{k, v -> v.concat(\"" + msg + "\")}", "{k, v -> \"" + msg + "\""}")
```
    If either function returns null, the mapping is removed (or remains absent if initially absent). If the predicate or function itself throw an (unchecked) exception, the exception is rethrown as a ClosureEvaluationException, and the current mapping is left unchanged. The default implementation is equivalent to performing the following steps for this map, then returning a PredicateActionResult object containing the current value or null if absent:
```
 
 V oldValue = map.get(key);
 if (predicate.test(key, oldValue)) {
  map.compute(key, thenRemappingFunction);
 } else {
  map.compute(key, elseRemappingFunction);
 }
 
```
    This implementation guarantees that the operation is performed atomically on the channel map.
    Parameters:
    
    channel - channel identifier
    
    key - key with which the specified value is to be associated
    
    predicate - closure used for conditional decision
    
    thenRemappingFunction - the function to compute a value if the predicate is true
    
    elseRemappingFunction - the function to compute a value if the predicate is false
    
    Returns:
    
    a PredicateActionResult object which contains the result of the predicate evaluation and either (true) the new value associated with the key after applying thenRemappingFunction, or (false) the new value associated with the key after applying elseRemappingFunction.
    
    Throws:
    
    NullPointerException - if the predicate or any remappingFunction is null
    
    CompilationException - if an error occurred during the compilation of the specified action
    
    ClosureEvaluationException - if an error occurred during the evaluation of the specified action
    
    InvalidChannelException - if the channel does not exist
    
    IOException - if an error occurred when persisting the modified channel on disk
    
    Since:
    
    1.8
    
    See Also:
    
    Map.compute(Object, BiFunction), BiPredicate, BiFunction, Groovy Closures, PredicateActionResult
  - conditionalReplaceAll
```
void conditionalReplaceAll(String channel,
                           String predicate,
                           String thenRemappingFunction)
                    throws InvalidChannelException,
                           CompilationException,
                           IOException
```
    Replaces each entry's value with the result of invoking the given function on that entry if the given predicate is satisfied. The operation is performed until all entries have been processed or either the predicate or function throws an exception. Exceptions thrown by the function are relayed to the caller as ClosureEvaluationException. Both predicate and function are passed as String containing a groovy closure definition which matches the BiPredicate and BiFunction specifications. The first parameter receives the key, and the second parameter receives the binding associated with this key. For example, to increment a counter only on positive values
```
 
 store.conditionalCompute(channel, key, "{ k, v -> v >= 0}", "{k, v -> v + 1}")
 
```
    If the function returns null, the mapping is removed (or remains absent if initially absent). If the predicate or function itself throw an (unchecked) exception, the exception is rethrown as a ClosureEvaluationException, and the current mapping is left unchanged. The default implementation is equivalent to performing the following steps for this map, then returning PredicateActionResult object containing the current value or null if absent:
```
 
 for (Map.Entry<String, V> entry : map.entries()) {

  if (predicate.test(entry.getKey(), entry.getValue())) {
      map.compute(entry.getKey(), thenRemappingFunction);
  }
 }
 
```
    This implementation guarantees that the operation is performed atomically on the channel map.
    Parameters:
    
    channel - channel identifier
    
    predicate - closure used for conditional decision
    
    thenRemappingFunction - the function to compute a value if the predicate is true
    
    Throws:
    
    NullPointerException - if the predicate or remappingFunction is null
    
    CompilationException - if an error occurred during the compilation of the specified action
    
    ClosureEvaluationException - if an error occurred during the evaluation of the specified action
    
    InvalidChannelException - if the channel does not exist
    
    IOException - if an error occurred when persisting the modified channel on disk
    
    Since:
    
    1.8
    
    See Also:
    
    Map.compute(Object, BiFunction), BiPredicate, BiFunction, Groovy Closures
  - conditionalReplaceAll
```
void conditionalReplaceAll(String channel,
                           String predicate,
                           String thenRemappingFunction,
                           String elseRemappingFunction)
                    throws InvalidChannelException,
                           CompilationException,
                           IOException
```
    Replaces each entry's value with the result of invoking the given function on that entry if the given predicate is satisfied. The operation is performed until all entries have been processed or either the predicate or function throws an exception. Exceptions thrown by the function are relayed to the caller as ClosureEvaluationException. Both predicate and function are passed as String containing a groovy closure definition which matches the BiPredicate and BiFunction specifications. The first parameter receives the key, and the second parameter receives the binding associated with this key. For example, to increment a counter only on positive values
```
 
 store.conditionalCompute(channel, key, "{ k, v -> v >= 0}", "{k, v -> v + 1}")
 
```
    If the function returns null, the mapping is removed (or remains absent if initially absent). If the predicate or function itself throw an (unchecked) exception, the exception is rethrown as a ClosureEvaluationException, and the current mapping is left unchanged. The default implementation is equivalent to performing the following steps for this map, then returning PredicateActionResult object containing the current value or null if absent:
```
 
 for (Map.Entry<String, V> entry : map.entries()) {

  if (predicate.test(entry.getKey(), entry.getValue())) {
      map.compute(entry.getKey(), thenRemappingFunction);
  } else {
      map.compute(entry.getKey(), elseRemappingFunction);
  }
 }
 
```
    This implementation guarantees that the operation is performed atomically on the channel map.
    Parameters:
    
    channel - channel identifier
    
    predicate - closure used for conditional decision
    
    thenRemappingFunction - the function to compute a value if the predicate is true
    
    elseRemappingFunction - the function to compute a value if the predicate is false
    
    Throws:
    
    NullPointerException - if the predicate or remappingFunction is null
    
    CompilationException - if an error occurred during the compilation of the specified action
    
    ClosureEvaluationException - if an error occurred during the evaluation of the specified action
    
    InvalidChannelException - if the channel does not exist
    
    IOException - if an error occurred when persisting the modified channel on disk
    
    Since:
    
    1.8
    
    See Also:
    
    Map.compute(Object, BiFunction), BiPredicate, BiFunction, Groovy Closures
  - waitUntil
```
boolean waitUntil(String channel,
                  String key,
                  String predicate)
           throws InvalidChannelException,
                  CompilationException
```
    Blocking call waiting for a predicate to be met. The predicate is passed as String containing a groovy closure definition which matches the BiPredicate specification. For example, to wait until a mapping is defined:
```
 
 store.waitUntil(channel, key, "{ k, v -> v != null}")
```
    The default implementation is equivalent to performing the following steps for this map, then returning the result of the predicate, which will always be true;
```
 
 V oldValue = map.get(key);
 while (!predicate.test(key, oldValue)) {
  oldValue = map.get(key);
 }
 
```
    This implementation guarantees that the operation is performed atomically on the channel map, which means that as soon as another operation modifies the underlying structure to meet the predicate, the waitUntil will be unblocked. Subsequent operations based on this condition wait may still be interleaved by other operations performed on the map. This is why it is generally preferable to use waitUntilThen() to guaranty both predicate and action.
    Parameters:
    
    channel - channel identifier
    
    key - key with which the specified value is to be associated
    
    predicate - closure used for conditional decision
    
    Throws:
    
    NullPointerException - if the predicate is null
    
    CompilationException - if an error occurred during the compilation of the specified actions
    
    ClosureEvaluationException - if an error occurred during the evaluation of the specified actions
    
    InvalidChannelException - if the channel does not exist
    
    Since:
    
    1.8
    
    See Also:
    
    Map.compute(Object, BiFunction), BiPredicate, Groovy Closures
  - waitUntil
```
boolean waitUntil(String channel,
                  String key,
                  String predicate,
                  long timeout)
           throws InvalidChannelException,
                  CompilationException,
                  TimeoutException
```
    Blocking call waiting for a predicate to be met, with a timeout. The predicate is passed as String containing a groovy closure definition which matches the BiPredicate specification. For example, to wait for at most one minute until a mapping is defined:
```
 
 store.waitUntil(channel, key, "{ k, v -> v != null}", 60000)
```
    This implementation guarantees that the operation is performed atomically on the channel map, which means that as soon as another operation modifies the underlying structure to meet the predicate, the waitUntil will be unblocked. Subsequent operations based on this condition wait may still be interleaved by other operations performed on the map. This is why it is generally preferable to use waitUntilThen() to guaranty both predicate and action.
    Parameters:
    
    channel - channel identifier
    
    key - key with which the specified value is to be associated
    
    predicate - closure used for conditional decision
    
    timeout - maximum time in milliseconds to wait
    
    Throws:
    
    NullPointerException - if the predicate is null
    
    CompilationException - if an error occurred during the compilation of the specified actions
    
    ClosureEvaluationException - if an error occurred during the evaluation of the specified actions
    
    InvalidChannelException - if the channel does not exist
    
    TimeoutException - if the predicate is not met before the timeout is reached
    
    Since:
    
    1.8
    
    See Also:
    
    Map.compute(Object, BiFunction), BiPredicate, Groovy Closures
  - waitUntilThen
```
PredicateActionResult waitUntilThen(String channel,
                                    String key,
                                    String predicate,
                                    String thenRemappingFunction)
                             throws InvalidChannelException,
                                    CompilationException,
                                    IOException
```
    Blocking call waiting for a predicate to be met before executing a remapping function. Attempts to compute a mapping for the specified key and its current mapped value (or null if there is no current mapping), if the given predicate is met. If the predicate is not yet met, block the operation until it is satisfied Both predicate and function are passed as String containing a groovy closure definition which matches the BiPredicate and BiFunction specifications. The first parameter receives the key, and the second parameter receives the binding associated with this key. For example, to append a String msg to a value when the value will be defined mapping:
```
 
 store.waitUntilThen(channel, key, "{ k, v -> v != null}", "{k, v -> v.concat(\"" + msg + "\")}")
```
    If the function returns null, the mapping is removed (or remains absent if initially absent). If the predicate or function itself throw an (unchecked) exception, the exception is rethrown as a ClosureEvaluationException, and the current mapping is left unchanged. The default implementation is equivalent to performing the following steps for this map, then returning the current value or null if absent:
```
 
 V oldValue = map.get(key);
 while (!predicate.test(key, oldValue)) {
  oldValue = map.get(key)
 }
 map.compute(key, thenRemappingFunction);
 
```
    This implementation guarantees that the operation is performed atomically on the channel map, which means that as soon as another operation modifies the underlying structure to meet the predicate, the remappingFunction will be executed at once and atomically, without letting another operation to interfere.
    Parameters:
    
    channel - channel identifier
    
    key - key with which the specified value is to be associated
    
    predicate - closure used for conditional decision
    
    thenRemappingFunction - the function to compute a value
    
    Returns:
    
    a PredicateActionResult object which contains the result of the predicate evaluation and the new value associated with the key after applying thenRemappingFunction
    
    Throws:
    
    NullPointerException - if the predicate or remappingFunction is null
    
    CompilationException - if an error occurred during the compilation of the specified action
    
    ClosureEvaluationException - if an error occurred during the evaluation of the specified action
    
    InvalidChannelException - if the channel does not exist
    
    IOException - if an error occurred when persisting the modified channel on disk
    
    Since:
    
    1.8
    
    See Also:
    
    Map.compute(Object, BiFunction), BiPredicate, BiFunction, Groovy Closures
  - waitUntilThen
```
PredicateActionResult waitUntilThen(String channel,
                                    String key,
                                    String predicate,
                                    long timeout,
                                    String thenRemappingFunction)
                             throws InvalidChannelException,
                                    CompilationException,
                                    IOException,
                                    TimeoutException
```
    Blocking call waiting with timeout for a predicate to be met before executing a remapping function. Attempts to compute a mapping for the specified key and its current mapped value (or null if there is no current mapping), if the given predicate is met. If the predicate is not yet met, block the operation until it is satisfied or until the specified timeout is reached. Both predicate and function are passed as String containing a groovy closure definition which matches the BiPredicate and BiFunction specifications. The first parameter receives the key, and the second parameter receives the binding associated with this key. For example, to append a String msg to a value when the value will be defined mapping:
```
 
 store.waitUntilThen(channel, key, "{ k, v -> v != null}", "{k, v -> v.concat(\"" + msg + "\")}")
```
    If the function returns null, the mapping is removed (or remains absent if initially absent). If the predicate or function itself throw an (unchecked) exception, the exception is rethrown as a ClosureEvaluationException, and the current mapping is left unchanged.
    This implementation guarantees that the operation is performed atomically on the channel map, which means that as soon as another operation modifies the underlying structure to meet the predicate, the remappingFunction will be executed at once and atomically, without letting another operation to interfere.
    Parameters:
    
    channel - channel identifier
    
    key - key with which the specified value is to be associated
    
    predicate - closure used for conditional decision
    
    timeout - maximum time in milliseconds to wait
    
    thenRemappingFunction - the function to compute a value
    
    Returns:
    
    a PredicateActionResult object which contains the result of the predicate evaluation and the new value associated with the key after applying thenRemappingFunction
    
    Throws:
    
    NullPointerException - if the predicate or remappingFunction is null
    
    CompilationException - if an error occurred during the compilation of the specified action
    
    ClosureEvaluationException - if an error occurred during the evaluation of the specified action
    
    InvalidChannelException - if the channel does not exist
    
    IOException - if an error occurred when persisting the modified channel on disk
    
    TimeoutException - if the predicate is not met before the timeout is reached
    
    Since:
    
    1.8
    
    See Also:
    
    Map.compute(Object, BiFunction), BiPredicate, BiFunction, Groovy Closures

Interface Synchronization

Method Summary

Method Detail

createChannel

createChannelIfAbsent

deleteChannel

channelExists

size

isEmpty

containsKey

containsValue

get

put

remove

putAll

clear

keySet

values

entrySet

getOrDefault

forEach

replaceAll

putIfAbsent

remove

replace

replace

computeIfAbsent

computeIfPresent

compute

merge

conditionalCompute

conditionalCompute

conditionalReplaceAll

conditionalReplaceAll

waitUntil

waitUntil

waitUntilThen

waitUntilThen