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 Detail

      • getCacheName

        String getCacheName()
        Return the name of the cache that this BackingMapContext is associated with.
        Returns:
        the corresponding cache name

      • 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