Package 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 Details

    • 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 all partitions of 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 for all partitions of the cache

    • getIndexMap

      Map<ValueExtractor,MapIndex> getIndexMap(PartitionSet partitions)
      Return a map of indexes defined for the specified partitions of the cache that this BackingMapContext is associated with. The returned map must be treated in the read-only manner.
      Parameters:
      partitions - the partitions to get the index map for
      Returns:
      the map of indexes defined for the specified partitions of the cache

    • getIndexMap

      default Map<ValueExtractor,MapIndex> getIndexMap(int nPartition)
      Return a map of indexes defined for the specified partition of the cache that this BackingMapContext is associated with. The returned map must be treated in the read-only manner.
      Parameters:
      nPartition - the partition to get the index map for
      Returns:
      the map of indexes defined for the specified partition of 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 a 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