API Reference

Aggregators

class coherence.Aggregators

Simple Aggregator DSL.

The methods in this class are for the most part simple factory methods for various coherence.aggregator.EntryAggregator classes, but in some cases provide additional type safety. They also tend to make the code more readable, especially if imported statically, so their use is strongly encouraged in lieu of direct construction of coherence.aggregator.EntryAggregator classes.

static average(extractor_or_property: ValueExtractor[T, E] | str) → EntryAggregator[Decimal]

Return an aggregator that calculates an average of the numeric values extracted from a set of entries in a Map.

Parameters:

extractor_or_property – the extractor or method/property name to provide values for aggregation

Returns:

an aggregator that calculates an average of the numeric values extracted from a set of entries in a Map.

static count() → EntryAggregator[int]

Return an aggregator that calculates a number of values in an entry set.

Returns:

an aggregator that calculates a number of values in an entry set.

static distinct(extractor_or_property: ValueExtractor[T, E] | str) → EntryAggregator[List[R]]

Return an aggregator that calculates the set of distinct values from the entries in a Map.

Parameters:

extractor_or_property – the extractor or method/property name to provide values for aggregation

Returns:

an aggregator that calculates the set of distinct values from the entries in a Map.

static group_by(extractor_or_property: ValueExtractor[T, E] | str, aggregator: EntryAggregator[Any], filter: Filter | None = None) → EntryAggregator[Dict[G, T]]

Return a coherence.aggregator.GroupAggregator based on a specified property or method name(s) and an coherence.aggregator.EntryAggregator.

Parameters:
Returns:

a coherence.aggregator.GroupAggregator based on a specified property or method name(s) and an coherence.aggregator.EntryAggregator.

static max(extractor_or_property: ValueExtractor[T, E] | str) → EntryAggregator[R]

Return an aggregator that calculates a maximum of the numeric values extracted from a set of entries in a Map.

Parameters:

extractor_or_property – the extractor or method/property name to provide values for aggregation

Returns:

an aggregator that calculates a maximum of the numeric values extracted from a set of entries in a Map

static min(extractor_or_property: ValueExtractor[T, E] | str) → EntryAggregator[R]

Return an aggregator that calculates a minimum of the numeric values extracted from a set of entries in a Map.

Parameters:

extractor_or_property – the extractor or method/property name to provide values for aggregation

Returns:

an aggregator that calculates a minimum of the numeric values extracted from a set of entries in a Map.

static priority(aggregator: EntryAggregator[R], execution_timeout: Timeout = Timeout.DEFAULT, request_timeout: Timeout = Timeout.DEFAULT, scheduling_priority: Schedule = Schedule.STANDARD) → EntryAggregator[R]

Return a new coherence.aggregator.PriorityAggregator to control scheduling priority of an aggregation operation.

Parameters:
Returns:

a new coherence.aggregator.PriorityAggregator to control scheduling priority of an aggregation operation.

static record(query_type: RecordType = RecordType.EXPLAIN) → EntryAggregator[Any]

Returns a new coherence.aggregator.QueryRecorder aggregator which may be used is used to produce an object that contains an estimated or actual cost of the query execution for a given coherence.filter.Filter.

Parameters:

query_type – the coherence.aggregator.RecordType

Returns:

a new coherence.aggregator.QueryRecorder aggregator which may be used is used to produce an object that contains an estimated or actual cost of the query execution for a given coherence.filter.Filter.

static reduce(extractor_or_property: ValueExtractor[T, E] | str) → EntryAggregator[Dict[K, Any | List[Any]]]

Return an aggregator that will return the extracted value for each entry in the map.

Parameters:

extractor_or_property – the extractor or method/property name to provide values for aggregation

Returns:

an aggregator that will return the extracted value for each entry in the map.

static script(language: str, script_name: str, characteristics: int = 0, *args: Any) → EntryAggregator[R]

Return an aggregator that is implemented in a script using the specified language.

Parameters:

  • language – The language with which the script is written in.

  • script_name – The name of the coherence.aggregator.EntryAggregator that needs to be evaluated.

  • characteristics – Present only for serialization purposes.

  • args – The arguments to be passed to the script for evaluation

Returns:

an aggregator that is implemented in a script using the specified language.

static sum(extractor_or_property: ValueExtractor[T, E] | str) → EntryAggregator[Decimal]

Return an aggregator that calculates a sum of the numeric values extracted from a set of entries in a Map.

Parameters:

extractor_or_property – the extractor or method/property name to provide values for aggregation

Returns:

an aggregator that calculates a sum of the numeric values extracted from a set of entries in a Map.

static top(count: int) → TopAggregator[Any, Any]

Return an aggregator that aggregates the top N extracted values into an array.

Parameters:

count – the maximum number of results to include in the aggregation result

Returns:

an aggregator that aggregates the top N extracted values into an array.

Comparator

class coherence.Comparator

Comparator is used to control the ordering for collections of objects

Extractors

class coherence.Extractors

A Utility class for creating extractors.

classmethod extract(expression: str, params: list[Any] | None = None) → ValueExtractor[T, E]
If providing only an expression, the following rules apply:

  • if the expression contains multiple values separated by a period, the expression will be treated as a chained expression. E.g., the expression ‘a.b.c’ would be treated as extract the ‘a’ property, from that result, extract the ‘b’ property, and finally from that result, extract the ‘c’ property.

  • if the expression contains multiple values separated by a comma, the expression will be treated as a multi expression. E.g., the expression ‘a,b,c’ would be treated as extract the ‘a’, ‘b’, and ‘c’ properties from the same object.

  • for either case, the params argument is ignored.

It is also possible to invoke, and pass arguments to, arbitrary methods. For example, if the target object of the extraction is a String, it’s possible to call the length() function by passing an expression of “length()”. If the target method accepts arguments, provide a list of one or more arguments to be passed.

Parameters:

  • expression – the extractor expression

  • params – the params to pass to the method invocation

Returns:

a ValueExtractor based on the provided inputs

classmethod identity() → IdentityExtractor[Any]

Returns an extractor that does not actually extract anything from the passed value, but returns the value itself.

Returns:

an extractor that does not actually extract anything from the passed value, but returns the value itself

Filters

class coherence.Filters
static all(filters: list[Filter]) → Filter

Return a composite filter representing logical AND of all specified filters.

Parameters:

filters – a variable number of filters

Returns:

a composite filter representing logical AND of all specified filters

static always() → Filter

Return a filter that always evaluates to true.

Returns:

a filter that always evaluates to true.

static any(filters: list[Filter]) → Filter

Return a composite filter representing logical OR of all specified filters.

Parameters:

filters – a variable number of filters

Returns:

a composite filter representing logical OR of all specified filters

static array_contains(extractor_or_method: ValueExtractor[T, E] | str, value: V) → Filter

Return a filter that tests if the extracted array contains the specified value.

Parameters:

  • extractor_or_method – the extractor.ValueExtractor used by this filter or the name of the method to invoke via reflection

  • value – the object that a Collection or Object array is tested to contain

Returns:

a filter that tests if the extracted array contains the specified value

static array_contains_all(extractor_or_method: ValueExtractor[T, E] | str, values: Set[Any]) → Filter

Return a filter that tests if the extracted array contains all of the specified values.

Parameters:

  • extractor_or_method – the extractor.ValueExtractor used by this filter or the name of the method to invoke via reflection

  • values – the set of objects that a Collection or Object array is tested to contain

Returns:

a filter that tests if the extracted array contains all of the specified values

static array_contains_any(extractor_or_method: ValueExtractor[T, E] | str, values: Set[Any]) → Filter

Return a filter that tests if the extracted array contains any of the specified values.

Parameters:

  • extractor_or_method – the extractor.ValueExtractor used by this filter or the name of the method to invoke via reflection

  • values – the set of objects that a Collection or Object array is tested to contain

Returns:

a filter that tests if the extracted array contains any of the specified values

static between(extractor_or_method: ValueExtractor[T, E] | str, from_range: int, to_range: int, include_lower_bound: bool = False, include_upper_bound: bool = False) → Filter

Return a filter that tests if the extracted value is between the specified values (inclusive).

Parameters:

  • extractor_or_method – the {@link extractor.ValueExtractor} used by this filter or the name of the method to invoke via reflection

  • from_range – the lower bound to compare the extracted value with

  • to_range – the upper bound to compare the extracted value with

  • include_lower_bound – a flag indicating whether values matching the lower bound evaluate to true

  • include_upper_bound – a flag indicating whether values matching the upper bound evaluate to true

Returns:

a filter that tests if the extracted value is between the specified values

static contains(extractor_or_method: ValueExtractor[T, E] | str, value: V) → Filter

Return a filter that tests if the extracted collection contains the specified value.

Parameters:

  • extractor_or_method – the extractor.ValueExtractor used by this filter or the name of the method to invoke via reflection

  • value – the object that a Collection or Object array is tested to contain

Returns:

a filter that tests if the extracted collection contains the specified value

static contains_all(extractor_or_method: ValueExtractor[T, E] | str, values: Set[Any]) → Filter

Return a filter that tests if the extracted collection contains all of the specified values.

Parameters:

  • extractor_or_method – the extractor.ValueExtractor used by this filter or the name of the method to invoke via reflection

  • values – the set of objects that a Collection or Object array is tested to contain

Returns:

a filter that tests if the extracted collection contains all of the specified values

static contains_any(extractor_or_method: ValueExtractor[T, E] | str, values: Set[Any]) → Filter

Return a filter that tests if the extracted collection contains any of the specified values.

Parameters:

  • extractor_or_method – the extractor.ValueExtractor used by this filter or the name of the method to invoke via reflection

  • values – the set of objects that a Collection or Object array is tested to contain

Returns:

a filter that tests if the extracted collection contains any of the specified values

static equals(extractor_or_method: ValueExtractor[T, E] | str, value: Any) → Filter

Return a filter that tests for equality against the extracted value.

Parameters:

  • extractor_or_method – the extractor.ValueExtractor used by this filter or the name of the method to invoke via reflection

  • value – the value to compare the extracted value with

Returns:

a filter that tests for equality

static event(filter: Filter, mask: int = 29) → Filter

Returns a filter that may be passed to a event.MapListener to restrict the events sent to the listener to a subset of the notifications emitted by the map.

Parameters:

  • filter – the filter used to evaluate event values

  • mask – the event mask

Returns:

a filter that may be passed to a event.MapListener to restrict the events sent to the listener to a subset of the notifications emitted by the map

static greater(extractor_or_method: ValueExtractor[T, E] | str, value: Any) → Filter

Returns instance of coherence.filter.GreaterFilter to test Greater condition

Parameters:
Returns:

an instance of coherence.filter.GreaterFilter

static greater_equals(extractor_or_method: ValueExtractor[T, E] | str, value: Any) → Filter

Returns instance of coherence.filter.GreaterEqualsFilter to test Greater or Equal condition

Parameters:
Returns:

an instance of coherence.filter.GreaterEqualsFilter

static is_in(extractor_or_method: ValueExtractor[T, E] | str, values: Set[Any]) → Filter
Returns instance of coherence.filter.InFilter to check whether

the result of a method invocation belongs to a predefined set of values.

Parameters:
Returns:

an instance of coherence.filter.InFilter

static is_none(extractor_or_method: ValueExtractor[T, E] | str) → Filter

Returns instance of coherence.filter.IsNoneFilter for testing equality to None.

Parameters:

extractor_or_method – the coherence.extractor.ValueExtractor to use by this coherence.filter.Filter or the name of the method to invoke via reflection

Returns:

an instance of coherence.filter.IsNoneFilter

static is_not_none(extractor_or_method: ValueExtractor[T, E] | str) → Filter

Returns instance of coherence.filter.IsNotNoneFilter for testing inequality to None.

Parameters:

extractor_or_method – the coherence.extractor.ValueExtractor to use by this coherence.filter.Filter or the name of the method to invoke via reflection

Returns:

an instance of coherence.filter.IsNotNoneFilter

static less(extractor_or_method: ValueExtractor[T, E] | str, value: Any) → Filter

Returns instance of coherence.filter.LessFilter for testing Less condition.

Parameters:
Returns:

an instance of coherence.filter.LessFilter

static less_equals(extractor_or_method: ValueExtractor[T, E] | str, value: Any) → Filter

Returns instance of coherence.filter.LessEqualsFilter for testing Less or Equals condition.

Parameters:
Returns:

an instance of coherence.filter.LessEqualsFilter

static like(extractor_or_method: ValueExtractor[T, E] | str, pattern: str, escape: str = '0', ignore_case: bool = False) → Filter

Returns instance of coherence.filter.LikeFilter for for pattern match

Parameters:

  • extractor_or_method – the coherence.extractor.ValueExtractor to use by this coherence.filter.Filter or the name of the method to invoke via reflection

  • pattern – the string pattern to compare the result with

  • escape – the escape character for escaping % and _

  • ignore_case – true to be case-insensitive

Returns:

an instance of coherence.filter.LikeFilter

static negate(filter: Filter) → Filter
Returns instance of coherence.filter.NotFilter which negates

the results of another filter.

Parameters:

filter – The Filter whose results are negated by this filter.

Returns:

an instance of coherence.filter.NotFilter

static never() → Filter

Returns instance of coherence.filter.NeverFilter which always evaluates to false.

Returns:

an instance of coherence.filter.NeverFilter

static not_equals(extractor_or_method: ValueExtractor[T, E] | str, value: Any) → Filter
Returns instance of coherence.filter.NotEqualsFilter for testing

inequality.

Parameters:
Returns:

an instance of coherence.filter.NotEqualsFilter

static present() → Filter
Returns instance of coherence.filter.PresentFilter which

returns true for entries that currently exist in a map.

Returns:

an instance of coherence.filter.PresentFilter

static regex(extractor_or_method: ValueExtractor[T, E] | str, regex: str) → Filter
Returns instance of coherence.filter.RegexFilter which uses

the regular expression pattern match defined by the Java’s String.matches contract.

Parameters:
Returns:

an instance of coherence.filter.RegexFilter

MapEntry

class coherence.MapEntry(key: K, value: V)

Bases: Generic[K, V]

A map entry (key-value pair).

MapEvent

class coherence.event.MapEvent(source: NamedMap[K, V], response: MapEventResponse, serializer: Serializer)

Bases: Generic[K, V]

An event which indicates that the content of a map has changed:

  • an entry has been added

  • an entry has been removed

  • an entry has been changed

property description: str

Returns the event’s description. :return: the event’s description

property key: K

Return the key for the entry generating the event. :return: the key for the entry generating the event

property name: str

The name of the cache from which the event originated. :return: the cache name from which the event originated

property new: V | None

Return the new value for the entry generating the event. :return: the new value, if any, for the entry generating the event

property old: V | None

Return the old value for the entry generating the event. :return:the old value, if any, for the entry generating the event

property source: NamedMap[K, V]

The source of the event. :return: the event source

property type: MapEventType

The MapEventType. This may be one of: * MapEventType.ENTRY_INSERTED * MapEventType.ENTRY_UPDATED * MapEventType.ENTRY_DELETED :return: the event type

MapListener

class coherence.event.MapListener

Bases: Generic[K, V]

A listener interface for receiving MapEvents.

__init__() → None

Constructs a new MapListener.

on_any(callback: Callable[[MapEvent[K, V]], None]) → MapListener[K, V]

Defines the callback that should be invoked when any entry event has occurred.

Parameters:

callback – the callback that will be invoked when a deletion event has occurred

on_deleted(callback: Callable[[MapEvent[K, V]], None]) → MapListener[K, V]

Defines the callback that should be invoked when a deletion event has occurred.

Parameters:

callback – the callback that will be invoked when a deletion event has occurred

on_inserted(callback: Callable[[MapEvent[K, V]], None]) → MapListener[K, V]

Defines the callback that should be invoked when an insertion event has occurred.

Parameters:

callback – the callback that will be invoked when an insertion event has occurred

on_updated(callback: Callable[[MapEvent[K, V]], None]) → MapListener[K, V]

Defines the callback that should be invoked when an update event has occurred.

Parameters:

callback – the callback that will be invoked when an update event has occurred

NamedCache

class coherence.NamedCache(*args, **kwds)

Bases: NamedMap[K, V]

A Map-based data-structure that manages entries across one or more processes. Entries are typically managed in memory, and are often comprised of data that is also stored in an external system, for example, a database, or data that has been assembled or calculated at some significant cost. Such entries are referred to as being cached.

Parameters:

  • K – the type of the map entry keys

  • V – the type of the map entry values

abstract async put(key: K, value: V, ttl: int = -1) → V

Associates the specified value with the specified key in this map. If the map previously contained a mapping for this key, the old value is replaced.

Parameters:

  • key – the key with which the specified value is to be associated

  • value – the value to be associated with the specified key

  • ttl – the expiry time in millis (optional)

Returns:

resolving to the previous value associated with specified key, or None if there was no mapping for key. A None return can also indicate that the map previously associated None with the specified key if the implementation supports None values

abstract async put_if_absent(key: K, value: V, ttl: int = -1) → V

If the specified key is not already associated with a value (or is mapped to null) associates it with the given value and returns None, else returns the current value.

Parameters:

  • key – the key with which the specified value is to be associated

  • value – the value to be associated with the specified key

  • ttl – the expiry time in millis (optional)

Returns:

resolving to the previous value associated with specified key, or None if there was no mapping for key. A None return can also indicate that the map previously associated None with the specified key if the implementation supports None values

NamedMap

class coherence.NamedMap(*args, **kwds)

Bases: ABC, Generic[K, V]

A Map-based data-structure that manages entries across one or more processes. Entries are typically managed in memory, and are often comprised of data that is also stored persistently, on disk.

Parameters:

  • K – the type of the map entry keys

  • V – the type of the map entry values

abstract add_index(extractor: ValueExtractor[T, E], ordered: bool = False, comparator: Comparator | None = None) → None

Add an index to this map.

Parameters:

  • extractor – The coherence.extractor.ValueExtractor object that is used to extract an indexable Object from a value stored in the indexed Map. Must not be ‘None’.

  • ordered – true if the contents of the indexed information should be ordered false otherwise.

  • comparator – The coherence.comparator.Comparator object which imposes an ordering on entries in the indexed map or None if the entries’ values natural ordering should be used.

abstract async add_map_listener(listener: MapListener[K, V], listener_for: K | Filter | None = None, lite: bool = False) → None

Add a MapListener that will receive events (inserts, updates, deletes) that occur against the map, with the key, old-value and new-value included.

Parameters:

  • listener – the MapListener to register

  • listener_for – the optional key that identifies the entry for which to raise events or a Filter that will be passed MapEvent objects to select from; a MapEvent will be delivered to the listener only if the filter evaluates to True for that MapEvent. None is equivalent to a Filter that always returns True

  • lite – optionally pass True to indicate that the MapEvent objects do not have to include the old or new values in order to allow optimizations

Raises:

ValueError – if listener is None

abstract async aggregate(aggregator: EntryAggregator[R], keys: set[K] | None = None, filter: Filter | None = None) → R

Perform an aggregating operation against the entries specified by the passed keys.

Parameters:

  • aggregator – the EntryAggregator that is used to aggregate across the specified entries of this Map

  • keys – the Iterable of keys that specify the entries within this Map to aggregate across

  • filter – the Filter that is used to select entries within this Map to aggregate across

Returns:

the result of the invocation as returned from the EntryProcessor

abstract async clear() → None

Clears all the mappings in the ‘NamedMap’.

abstract async contains_key(key: K) → bool

Returns true if the specified key is mapped a value within the cache.

Parameters:

key – the key whose presence in this cache is to be tested

Returns:

resolving to true if the key is mapped to a value, or false if it does not

abstract async contains_value(value: V) → bool

Returns true if the specified value is mapped to some key.

Parameters:

value – the value expected to be associated with some key

Returns:

resolving to true if a mapping exists, or false if it does not

abstract async destroy() → None

Release and destroy this cache.

Warning: This method is used to completely destroy the specified cache across the cluster. All references in the entire cluster to this cache will be invalidated, the cached data will be cleared, and all resources will be released.

abstract entries(filter: Filter | None = None, comparator: Comparator | None = None, by_page: bool = False) → AsyncIterator[MapEntry[K, V]]

Return a set view of the entries contained in this map that satisfy the criteria expressed by the filter. Each element in the returned set is a coherence.client.MapEntry.

Parameters:

  • filter – the Filter object representing the criteria that the entries of this map should satisfy

  • comparator – the Comparator object which imposes an ordering on entries in the resulting set; or None if the entries’ values natural ordering should be used

  • by_page – returns the keys in pages (transparently to the caller). This option is only valid if no filter or comparator is provided.

Returns:

an AsyncIterator of MapEntry instances that satisfy the specified criteria

abstract async get(key: K) → V | None

Returns the value to which this cache maps the specified key.

Parameters:

key – the key whose associated value is to be returned

Example:
>>> import asyncio
>>> from typing import Any, AsyncGenerator, Optional, TypeVar
>>> from coherence import NamedCache, Session
>>> K = TypeVar("K")
>>> V = TypeVar("V")
>>> R = TypeVar("R")
>>> session: Session = Session(None)
>>> cache: NamedCache[Any, Any] = await session.get_cache("test")
>>> k: str = "one"
>>> v: str = "only-one"
>>> await cache.put(k, v)
>>> r = await cache.get(k)
>>> print(r)
only-one
abstract get_all(keys: set[K]) → AsyncIterator[MapEntry[K, V]]

Get all the specified keys if they are in the map. For each key that is in the map, that key and its corresponding value will be placed in the map that is returned by this method. The absence of a key in the returned map indicates that it was not in the cache, which may imply (for caches that can load behind the scenes) that the requested data could not be loaded.

Parameters:

keys – an Iterable of keys that may be in this map

Returns:

an AsyncIterator of MapEntry instances for the specified keys passed in keys

abstract async get_or_default(key: K, default_value: V | None = None) → V | None

Returns the value to which the specified key is mapped, or the specified defaultValue if this map contains no mapping for the key.

Parameters:

  • key – the key whose associated value is to be returned

  • default_value – defaultValue if this map contains no mapping for the key.

Returns:

value for the key in the map or the defaultValue

abstract async invoke(key: K, processor: EntryProcessor[R]) → R

Invoke the passed EntryProcessor against the Entry specified by the passed key, returning the result of the invocation.

Parameters:

  • key – the key to process - it is not required to exist within the Map

  • processor – the EntryProcessor to use to process the specified key

Returns:

the result of the invocation as returned from the EntryProcessor

abstract invoke_all(processor: EntryProcessor[R], keys: set[K] | None = None, filter: Filter | None = None) → AsyncIterator[MapEntry[K, R]]

Invoke the passed EntryProcessor against the set of entries that are selected by the given Filter, returning the result of the invocation for each.

Unless specified otherwise, implementations will perform this operation in two steps:

  1. use the filter to retrieve a matching entry set

  2. apply the agent to every filtered entry.

This algorithm assumes that the agent’s processing does not affect the result of the specified filter evaluation, since the filtering and processing could be performed in parallel on different threads. If this assumption does not hold, the processor logic has to be idempotent, or at least re-evaluate the filter. This could be easily accomplished by wrapping the processor with the ConditionalProcessor.

Parameters:

  • processor – the EntryProcessor to use to process the specified keys

  • keys – the keys to process these keys are not required to exist within the Map

  • filter – a Filter that results in the set of keys to be processed

Returns:

an AsyncIterator of MapEntry instances containing the results of invoking the EntryProcessor against each of the specified keys

abstract async is_empty() → bool

Returns true if this map contains no key-value mappings.

Returns:

true if this map contains no key-value mappings.

abstract keys(filter: Filter | None = None, by_page: bool = False) → AsyncIterator[K]

Return a set view of the keys contained in this map for entries that satisfy the criteria expressed by the filter.

Parameters:

  • filter – the Filter object representing the criteria that the entries of this map should satisfy

  • by_page – returns the keys in pages (transparently to the caller). This option is only valid if no filter is provided.

Returns:

an AsyncIterator of keys for entries that satisfy the specified criteria

abstract property name: str

documentation

abstract on(event: MapLifecycleEvent, callback: Callable[[str], None]) → None

Add a callback that will be invoked when the specified MapLifecycleEvent is raised. :param event: the MapLifecycleEvent to listen for :param callback: the callback that will be invoked when the event occurs

abstract async put(key: K, value: V) → V

Associates the specified value with the specified key in this map. If the map previously contained a mapping for this key, the old value is replaced.

Parameters:

  • key – the key with which the specified value is to be associated

  • value – the value to be associated with the specified key

Returns:

the previous value associated with the specified key, or None if there was no mapping for key. A None return can also indicate that the map previously associated None with the specified key if the implementation supports None values

abstract async put_all(map: dict[K, V]) → None

Copies all mappings from the specified map to this map

Parameters:

map – the map to copy from

abstract async put_if_absent(key: K, value: V) → V

If the specified key is not already associated with a value (or is mapped to None) associates it with the given value and returns None, else returns the current value.

Parameters:

  • key – the key with which the specified value is to be associated

  • value – the value to be associated with the specified key

Returns:

the previous value associated with the specified key, or None if there was no mapping for key. A None return can also indicate that the map previously associated None with the specified key if the implementation supports None values

abstract release() → None

Release local resources associated with instance.

abstract async remove(key: K) → V

Removes the mapping for a key from this map if it is present.

Parameters:

key – key whose mapping is to be removed from the map

Returns:

the previous value associated with key, or None if there was no mapping for key

abstract remove_index(extractor: ValueExtractor[T, E]) → None

Removes an index on this NamedMap.

Parameters:

extractor – The coherence.extractor.ValueExtractor object that is used to extract an indexable Object from a value stored in the indexed Map. Must not be ‘None’.

abstract async remove_map_listener(listener: MapListener[K, V], listener_for: K | Filter | None = None) → None

Remove a standard map listener that previously registered to receive events. :param listener: the MapListener to be removed :param listener_for: the key or filter, if any, passed to a previous addMapListener invocation :raises ValueError: if listener is None

abstract async remove_mapping(key: K, value: V) → bool

Removes the entry for the specified key only if it is currently mapped to the specified value.

Parameters:

  • key – key with which the specified value is associated

  • value – expected to be associated with the specified key

Returns:

resolving to true if the value was removed

abstract async replace(key: K, value: V) → V

Replaces the entry for the specified key only if currently mapped to the specified value.

Parameters:

  • key – key whose associated value is to be replaced

  • value – value expected to be associated with the specified key

Returns:

resolving to the previous value associated with the specified key, or None if there was no mapping for the key. (A None return can also indicate that the map previously associated None with the key if the implementation supports None values.)

abstract async replace_mapping(key: K, old_value: V, new_value: V) → bool

Replaces the entry for the specified key only if currently mapped to the specified value.

Parameters:

  • key – key whose associated value is to be removed

  • old_value – value expected to be associated with the specified key

  • new_value – value to be associated with the specified key

Returns:

resolving to true if the value was replaced

abstract async size() → int

Signifies the number of key-value mappings in this map.

Returns:

the number of key-value mappings in this map

abstract async truncate() → None

Truncates the cache. Unlike coherence.client.NamedMap.clear(), this function does not generate an event for each removed entry.

abstract values(filter: Filter | None = None, comparator: Comparator | None = None, by_page: bool = False) → AsyncIterator[V]

Return a Set of the values contained in this map that satisfy the criteria expressed by the filter. If no filter or comparator is specified, it returns a Set view of the values contained in this map.The collection is backed by the map, so changes to the map are reflected in the collection, and vice-versa. If the map is modified while an iteration over the collection is in progress (except through the iterator’s own remove operation), the results of the iteration are undefined.

Parameters:

  • filter – the Filter object representing the criteria that the entries of this map should satisfy

  • comparator – the Comparator object which imposes an ordering on entries in the resulting set; or null if the entries’ natural ordering should be used

  • by_page – returns the keys in pages (transparently to the caller). This option is only valid if no filter or comparator is provided.

Returns:

an AsyncIterator of MapEntry instances resolving to the values that satisfy the specified criteria

Options

class coherence.Options(address: str = 'localhost:1408', scope: str = '', request_timeout_seconds: float = 30.0, ready_timeout_seconds: float = 0, session_disconnect_seconds: float = 30.0, ser_format: str = 'json', channel_options: Sequence[Tuple[str, Any]] | None = None, tls_options: TlsOptions | None = None)

Bases: object

Supported coherence.client.Session() options.

__init__(address: str = 'localhost:1408', scope: str = '', request_timeout_seconds: float = 30.0, ready_timeout_seconds: float = 0, session_disconnect_seconds: float = 30.0, ser_format: str = 'json', channel_options: Sequence[Tuple[str, Any]] | None = None, tls_options: TlsOptions | None = None) → None

Construct a new coherence.client.Options()

Parameters:

  • address – Address of the target Coherence cluster. If not explicitly set, this defaults to coherence.client.Options.DEFAULT_ADDRESS(). See also coherence.client.Options.ENV_SERVER_ADDRESS()

  • scope – scope name used to link this coherence.client.Options() to the corresponding ConfigurableCacheFactory on the server.

  • request_timeout_seconds – Defines the request timeout, in seconds, that will be applied to each remote call. If not explicitly set, this defaults to coherence.client.Options.DEFAULT_REQUEST_TIMEOUT(). See also coherence.client.Options.ENV_REQUEST_TIMEOUT()

  • ready_timeout_seconds –

    Defines the ready timeout, in seconds. If this is a positive float value, remote calls will not fail immediately if no connection is available. If this is a value of zero or less, then remote calls will fail-fast. If not explicitly configured, the default of 0 is assumed.

    See also coherence.client.Options.ENV_READY_TIMEOUT

  • session_disconnect_seconds – Defines the maximum time, in seconds, that a session may remain in a disconnected state without successfully reconnecting.

  • ser_format – The serialization format. Currently, this is always json

  • channel_options – The gRPC ChannelOptions. See https://grpc.github.io/grpc/python/glossary.html#term-channel_arguments and https://github.com/grpc/grpc/blob/master/include/grpc/impl/grpc_types.h

  • tls_options – Optional TLS configuration.

DEFAULT_ADDRESS: Final[str] = 'localhost:1408'

The default target address to connect to Coherence gRPC server.

DEFAULT_FORMAT: Final[str] = 'json'

The default serialization format

DEFAULT_READY_TIMEOUT: Final[float] = 0

The default ready timeout is 0 which disables the feature by default. Explicitly configure the ready timeout session option or use the environment variable to specify a positive value indicating how many seconds an RPC will wait for the underlying channel to be ready before failing.

DEFAULT_REQUEST_TIMEOUT: Final[float] = 30.0

The default request timeout.

DEFAULT_SCOPE: Final[str] = ''

The default scope.

DEFAULT_SESSION_DISCONNECT_TIMEOUT: Final[float] = 30.0

The default maximum time a session may be in a disconnected state without having successfully reconnected.

ENV_READY_TIMEOUT = 'COHERENCE_READY_TIMEOUT'

Environment variable to specify the maximum amount of time an NamedMap or NamedCache operations may wait for the underlying gRPC channel to be ready. This is independent of the request timeout which sets a deadline on how long the call may take after being dispatched.

ENV_REQUEST_TIMEOUT = 'COHERENCE_CLIENT_REQUEST_TIMEOUT'

Environment variable to specify the request timeout for each remote call. The environment variable is used if request timeout is not passed as an argument in the constructor. If the environment variable is not set and request timeout is not passed as an argument then DEFAULT_REQUEST_TIMEOUT of 30 seconds is used

ENV_SERVER_ADDRESS = 'COHERENCE_SERVER_ADDRESS'

Environment variable to specify the Coherence gRPC server address for the client to connect to. The environment variable is used if address is not passed as an argument in the constructor. If the environment variable is not set and address is not passed as an argument then DEFAULT_ADDRESS is used

ENV_SESSION_DISCONNECT_TIMEOUT = 'COHERENCE_SESSION_DISCONNECT_TIMEOUT'

Environment variable to specify the maximum amount of time, in seconds, a Session may remain in a disconnected state without successfully reconnecting.

property address: str

Return the IPv4 host address and port in the format of [host]:[port].

Returns:

the IPv4 host address and port in the format of [host]:[port].

property channel_options: Sequence[Tuple[str, Any]] | None

Return the gRPC ChannelOptions.

Returns:

the gRPC ChannelOptions.

property format: str

The serialization format used by this session. This library currently supports JSON serialization only, thus this always returns ‘json’.

Returns:

the serialization format used by this session.

property ready_timeout_seconds: float

Returns the ready timeout in seconds.

Returns:

the ready timeout in seconds

property request_timeout_seconds: float

Returns the request timeout in seconds

Returns:

the request timeout in seconds

property scope: str

Return the scope name used to link this Session with to the corresponding ConfigurableCacheFactory on the server.

Returns:

the scope name used to link this Session with to the corresponding ConfigurableCacheFactory on the server.

property session_disconnect_timeout_seconds: float

Returns the ready timeout in seconds.

Returns:

the ready timeout in seconds

property tls_options: TlsOptions | None

Returns the TLS-specific configuration options.

Returns:

the TLS-specific configuration options.

Processors

class coherence.Processors

The Processors class provides a set of static methods for creating standard Coherence coherence.processor.EntryProcessor’s.

static conditional_put(filter: Filter, value: V, return_value: bool = False) → EntryProcessor[V]

Construct a coherence.processor.ConditionalPut that updates an entry with a new value if and only if the coherence.filter.Filter applied to the entry evaluates to True.

param filter:

the coherence.filter.Filter to evaluate an entry

param value:

a value to update an entry with

param return_value:

specifies whether the processor should return the current value in case it has not been updated

return:

a processor that updates an entry with a new value if and only if the filter applied to the entry evaluates to True.

static conditional_put_all(filter: Filter, values: dict[K, V]) → EntryProcessor[V]

Construct a coherence.processor.ConditionalRemove processor that updates an entry with a new value if and only if the coherence.filter.Filter applied to the entry evaluates to True. The new value is extracted from the specified map based on the entry’s key.

Parameters:

  • filter – the coherence.filter.Filter to evaluate all supplied entries

  • values – a dict of values to update entries with

Returns:

a processor that updates one or more entries with the provided values if and only if the filter applied to the entry evaluates to True

static conditional_remove(filter: Filter, return_value: bool = False) → EntryProcessor[V]

Constructs a coherence.processor.ConditionalRemove processor that removes an coherence.client.NamedMap entry if and only if the coherence.filter.Filter applied to the entry evaluates to True.

This processor may optionally return the current value as a result of the invocation if it has not been removed (the coherence.filter.Filter evaluated to False).

Parameters:

  • filter – the coherence.filter.Filter to evaluate an entry

  • return_value – specifies whether the processor should return the current value if it has not been removed

static extract(extractor: ValueExtractor[T, E] | str | None = None) → EntryProcessor[E]

Construct an coherence.processor.ExtractorProcessor using the given coherence.extractor.ValueExtractor or string expression to extract a value from an object cached within a coherence.client.NamedMap.

For clustered caches using the coherence.processor.ExtractorProcessor could significantly reduce the amount of network traffic.

Parameters:

extractor – the coherence.extractor.ValueExtractor or string expression to use by this processor or the name of the method to invoke via java reflection. If None, an coherence.extractor.IdentityExtractor will be used.

static increment(name_or_manipulator: ValueManipulator[T, E] | str, increment: int | float | Decimal, post_increment: bool = False) → EntryProcessor[int | float | Decimal]

Construct an coherence.processor.NumberIncrementor processor that will increment a property value by a specified amount, returning either the old or the new value as specified.

Parameters:

  • name_or_manipulator – the coherence.extractor.ValueManipulator or string expression

  • increment – the numeric value representing the magnitude and sign of the increment

  • post_increment – pass True to return the value as it was before it was incremented, or pass False to return the value as it is after it is incremented

Returns:

static invoke_accessor(method_name: str, *args: Any) → EntryProcessor[R]
Constructs a coherence.processor.MethodInvocationProcessor that invokes the specified method on

a value of a cache entry.

Parameters:

  • method_name – the name of the method to invoke

  • args – the method arguments

Returns:

a coherence.processor.MethodInvocationProcessor that invokes the specified method on a value of a cache entry and optionally updates the entry with a modified value

static invoke_mutator(method_name: str, *args: Any) → EntryProcessor[R]

Constructs a coherence.processor.MethodInvocationProcessor that invokes the specified method on a value of a cache entry updating the entry with a modified value.

Parameters:

  • method_name – the name of the method to invoke

  • args – the method arguments

Returns:

a coherence.processor.MethodInvocationProcessor that invokes the specified method on a value of a cache entry and optionally updates the entry with a modified value

static multiply(name_or_manipulator: ValueManipulator[T, E] | str, multiplier: int | float | Decimal, post_multiplication: bool = False) → EntryProcessor[int | float | Decimal]

Construct an NumberMultiplier processor that will multiply a property value by a specified factor, returning either the old or the new value as specified.

Parameters:

  • name_or_manipulator – the ValueManipulator or the property name

  • multiplier – the Number representing the magnitude and sign of the multiplier

  • post_multiplication – pass True to return the value as it was before it was multiplied, or pass False to return the value as it is after it is multiplied

static nop() → EntryProcessor[bool]

Construct an coherence.processor.EntryProcessor that does nothing and returns True as a result of execution :return: an coherence.processor.EntryProcessor that does nothing and returns True as a result of execution

static preload() → EntryProcessor[None]

coherence.processor.PreloadRequest is a simple coherence.processor.EntryProcessor that performs a get call. No results are reported back to the caller.

The coherence.processor.PreloadRequest process provides a means to “preload” an entry or a collection of entries into the cache using the cache loader without incurring the cost of sending the value(s) over the network. If the corresponding entry (or entries) already exists in the cache, or if the cache does not have a loader, then invoking this coherence.processor.PreloadRequest has no effect. :return:

static script(name: str, language: str, *args: Any) → EntryProcessor[Any]

Create a coherence.processor.ScriptProcessor that wraps a script written in the specified language and identified by the specified name. The specified args will be passed during execution of the script.

Parameters:
static touch() → EntryProcessor[None]

Creates an coherence.processor.EntryProcessor that touches an entry (if present) in order to trigger interceptor re-evaluation and possibly increment expiry time. :return:

static update(updater_or_property_name: ValueUpdater[V, bool] | str, value: V) → EntryProcessor[bool]

Construct an coherence.processor.UpdaterProcessor based on the specified ValueUpdater.

While it’s possible to update a value via standard Map API, using the updater allows for clustered caches using the UpdaterProcessor allows avoiding explicit concurrency control and could significantly reduce the amount of network traffic.

Parameters:

  • updater_or_property_name – a ValueUpdater object or the method name; passing null will simpy replace the entry’s value with the specified one instead of updating it

  • value – the value to update the target entry with

static versioned_put(value: V, allow_insert: bool = False, return_current: bool = False) → EntryProcessor[V]

Construct a coherence.processor.VersionedPut that updates an entry with a new value if and only if the version of the new value matches to the version of the current entry’s value. This processor optionally returns the current value as a result of the invocation if it has not been updated (the versions did not match).

Parameters:

  • value – a value to update an entry with

  • allow_insert – specifies whether an insert should be allowed (no currently existing value)

  • return_current – specifies whether the processor should return the current value in case it has not been updated

static versioned_put_all(values: dict[K, V], allow_insert: bool = False, return_current: bool = False) → EntryProcessor[V]

Construct a coherence.processor.VersionedPut processor that updates an entry with a new value if and only if the version of the new value matches to the version of the current entry’s value (which must exist). This processor optionally returns a map of entries that have not been updated (the versions did not match).

Parameters:

  • values – a dict of values to update entries with

  • allow_insert – specifies whether an insert should be allowed (no currently existing value)

  • return_current – specifies whether the processor should return the current value in case it has not been updated

Session

class coherence.Session(session_options: Options | None = None)

Bases: object

Session represents a logical connection to an endpoint. It also acts as a factory for creating caches.

This class emits the following events:

  1. coherence.event.MapLifecycleEvent.DESTROYED: when the underlying cache is destroyed

  2. coherence.event.MapLifecycleEvent.TRUNCATED: When the underlying cache is truncated

  3. coherence.event.MapLifecycleEvent.RELEASED: When the underlying cache is released

  4. coherence.event.SessionLifecycleEvent.CONNECT: when the Session detects the underlying gRPC

    channel has connected.

  5. coherence.event.SessionLifecycleEvent.DISCONNECT: when the Session detects the underlying gRPC

    channel has disconnected

  6. coherence.event.SessionLifecycleEvent.RECONNECTED: when the Session detects the underlying gRPC

    channel has re-connected

  7. coherence.event.SessionLifecycleEvent.CLOSED: when the Session has been closed

__init__(session_options: Options | None = None)

Construct a new Session based on the provided coherence.client.Options()

Parameters:

session_options – the provided coherence.client.Options()

DEFAULT_FORMAT: Final[str] = 'json'

The default serialization format

property channel: Channel

Return the underlying gRPC Channel used by this session.

Returns:

the underlying gRPC Channel used by this session.

async close() → None

Close the Session

property closed: bool

Returns True if Session is closed else False.

Returns:

True if Session is closed else False

property format: str

Returns the default serialization format used by the Session

Returns:

the default serialization format used by the Session

is_ready() → bool

Returns :return:

property options: Options

Return the coherence.client.Options() (read-only) used to configure this session.

Returns:

the coherence.client.Options() (read-only) used to configure this session.

property scope: str

Return the scope name used to link this Session with to the corresponding ConfigurableCacheFactory on the server.

Returns:

the scope name used to link this Session with to the corresponding ConfigurableCacheFactory on the server.

property session_id: str

Returns this Session’s ID.

Returns:

this Session’s ID

TlsOptions

class coherence.TlsOptions(locked: bool = False, enabled: bool = False, ca_cert_path: str | None = None, client_cert_path: str | None = None, client_key_path: str | None = None)

Bases: object

Options specific to the configuration of TLS.

__init__(locked: bool = False, enabled: bool = False, ca_cert_path: str | None = None, client_cert_path: str | None = None, client_key_path: str | None = None) → None

Construct a new coherence.client.TlsOptions()

Parameters:

  • locked – If true, prevents further mutations to the options.

  • enabled – Enable/disable TLS support.

  • ca_cert_path – the path to the CA certificate. If not specified then its configured using the environment variable COHERENCE_TLS_CERTS_PATH

  • client_cert_path – the path to the client certificate. If not specified then its configured using the environment variable COHERENCE_TLS_CLIENT_CERT

  • client_key_path – the path to the client certificate key. If not specified then its configured using the environment variable COHERENCE_TLS_CLIENT_KEY

ENV_CA_CERT = 'COHERENCE_TLS_CERTS_PATH'

Environment variable to configure the path to CA certificates

ENV_CLIENT_CERT = 'COHERENCE_TLS_CLIENT_CERT'

Environment variable to configure the path to client certificates

ENV_CLIENT_KEY = 'COHERENCE_TLS_CLIENT_KEY'

Environment variable to configure the path to client key

property ca_cert_path: str | None

Property to set/get the path to the CA certificate

property client_cert_path: str | None

Property to set/get the path to the client certificate.

property client_key_path: str | None

Property to set/get the path to the client certificate key.

property enabled: bool

Property to set/get the boolean state if TLS is enabled(true) or disabled(false)

locked() → None

Once called, no further mutations can be made.

Modules