com.tangosol.net

Interface BackingMapContext

public interface BackingMapContext

The BackingMapContext provides an execution context to server side agents such as EntryProcessors and EntryAggregators. As of Coherence 3.7, this context is also used to initialize pluggable indexes to provide contextual knowledge about the backing map and cache for which the index is created.

Since:

Coherence 3.7

Author:

coh 2010.12.04

Method Summary

Modifier and Type	Method and Description
ObservableMap	getBackingMap() Deprecated. As of Coherence 12.1.3, replaced with getBackingMapEntry(java.lang.Object)
InvocableMap.Entry	getBackingMapEntry(Object oKey) Return an InvocableMap.Entry for the specified key (in its internal format) from the associated cache, obtaining exclusive access to that cache entry.
String	getCacheName() Return the name of the cache that this BackingMapContext is associated with.
Map<ValueExtractor,MapIndex>	getIndexMap() Return a map of indexes defined for the cache that this BackingMapContext is associated with.
BackingMapManagerContext	getManagerContext() Return the "parent" BackingMapManagerContext for this context.
InvocableMap.Entry	getReadOnlyEntry(Object oKey) Return an read-only InvocableMap.Entry for the specified key (in its internal format) from the associated cache.

Method Detail

getManagerContext

BackingMapManagerContext getManagerContext()

Return the "parent" BackingMapManagerContext for this context. Inversely, this context could be retrieved using the getBackingMapContext API.

Returns:

the enclosing BackingMapManagerContext

getCacheName

String getCacheName()

Return the name of the cache that this BackingMapContext is associated with.

Returns:

the corresponding cache name

getBackingMap

ObservableMap getBackingMap()

Deprecated. As of Coherence 12.1.3, replaced with getBackingMapEntry(java.lang.Object)

Return the backing map that this BackingMapContext is associated with. Most commonly it is the same map that is created by the instantiateBackingMap call. In the case the returned map is not observable, it will be wrapped by the WrapperObservableMap.

Returns:

the corresponding backing map

getIndexMap

Map<ValueExtractor,MapIndex> getIndexMap()

Return a map of indexes defined for the cache that this BackingMapContext is associated with. The returned map must be treated in the read-only manner.

Returns:

the map of indexes defined on the cache

getBackingMapEntry

InvocableMap.Entry getBackingMapEntry(Object oKey)

Return an InvocableMap.Entry for the specified key (in its internal format) from the associated cache, obtaining exclusive access to that cache entry.

This method may only be called within the context of an EntryProcessor invocation. Any changes made to the entry will be persisted with the same lifecycle as those made by the enclosing invocation. The returned entry is only valid for the duration of the enclosing invocation and multiple calls to this method within the same invocation context will return the same entry object.

Because this method implicitly locks the specified cache entry, callers may use it to access, insert, update, modify, or remove cache entries from within the context of an EntryProcessor invocation. Operating on the entries returned by this method differs from operating directly against the backing map, as the returned entries provide an isolated, read-consistent view. The implicit lock acquisition attempted by this method could create a deadlock if entries are locked in conflicting orders on different threads. It is the caller's responsibility to ensure that cache entries are accessed (locked) in a deadlock-free manner.

The usage of this method is highly encouraged instead of direct operations against the backing map retrieved by (now deprecated) BackingMapManagerContext.getBackingMap(String) method.

Parameters:

oKey - the key (in internal format) to obtain an entry for; must not be null

Returns:

an InvocableMap.Entry for the specified key, or null if the specified key is not owned by this service member

Throws:

IllegalStateException - if called from outside of an EntryProcessor invocation context

IllegalMonitorStateException - if a deadlock is detected while attempting to obtain exclusive access to the entry

IllegalArgumentException - if attempting to access an entry that does not belong to partition(s) associated with the caller's context

getReadOnlyEntry

InvocableMap.Entry getReadOnlyEntry(Object oKey)

Return an read-only InvocableMap.Entry for the specified key (in its internal format) from the associated cache.

This method may be called within the context of an EntryProcessor or Aggregator invocation, and may result in a load.

Note: to infer whether the InvocableMap.Entry exists in the cache use InvocableMap.Entry#isPresent()

Parameters:

oKey - the key (in internal format) to obtain an entry for; must not be null

Returns:

an InvocableMap.Entry for the specified key, or null if the specified key is not owned by this service member

Throws:

IllegalStateException - if called from an inactive invocation context