Package org.opends.server.api

Class EntryCache<T extends EntryCacheCfg>

  • Type Parameters:
    T - The type of configuration handled by this entry cache.
    Direct Known Subclasses:
    DefaultEntryCache, FIFOEntryCache, SoftReferenceEntryCache
    @PublicAPI(stability=VOLATILE,
           mayInstantiate=false,
           mayExtend=true,
           mayInvoke=true,
           notes="Entry cache methods may only be invoked by backends")
public abstract class EntryCache<T extends EntryCacheCfg>
extends Object
    This class defines the set of methods that must be implemented by a Directory Server entry cache. Note that components accessing the entry cache must not depend on any particular behavior. For example, if a call is made to putEntry to store an entry in the cache, there is no guarantee that immediately calling getEntry will be able to retrieve it. There are several potential reasons for this, including:
    • The entry may have been deleted or replaced by another thread between the putEntry and getEntry calls.
    • The entry cache may implement a purging mechanism and the entry added may have been purged between the putEntry and getEntry calls.
    • The entry cache may implement some kind of filtering mechanism to determine which entries to store, and entries not matching the appropriate criteria may not be stored.
    • The entry cache may not actually store any entries (this is the behavior of the default cache if no implementation specific entry cache is available).

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected AtomicLong cacheHits
      Arbitrary number of cache hits for monitoring.
      protected AtomicLong cacheMisses
      Arbitrary number of cache misses for monitoring.

    • Constructor Summary

      Constructors 
      Constructor Description
      EntryCache()
      Default constructor which is implicitly called from all entry cache implementations.

    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      abstract void clear()
      Removes all entries from the cache.
      abstract void clearBackend​(String backendID)
      Removes all entries from the cache that are associated with the provided backend.
      abstract boolean containsEntry​(DN entryDN)
      Indicates whether the entry cache currently contains the entry with the specified DN.
      boolean filtersAllowCaching​(Entry entry)
      Indicates whether the current set of exclude and include filters allow caching of the specified entry.
      abstract void finalizeEntryCache()
      Performs any necessary cleanup work (e.g., flushing all cached entries and releasing any other held resources) that should be performed when the server is to be shut down or the entry cache destroyed or replaced.
      abstract Long getCacheCount()
      Retrieves the current number of entries stored within the cache.
      long getCacheHits()
      Retrieves the current number of cache hits for this cache.
      long getCacheMisses()
      Retrieves the current number of cache misses for this cache.
      Entry getEntry​(String backendID, long entryID)
      Retrieves the requested entry if it is present in the cache.
      abstract Entry getEntry​(DN entryDN)
      Retrieves the entry with the specified DN from the cache.
      EntryCacheMonitorProvider getEntryCacheMonitor()
      Retrieves the monitor that is associated with this entry cache.
      abstract DN getEntryDN​(String backendID, long entryID)
      Retrieves the entry DN for the entry with the specified ID on the specific backend from the cache.
      abstract long getEntryID​(DN entryDN)
      Retrieves the entry ID for the entry with the specified DN from the cache.
      Set<SearchFilter> getExcludeFilters()
      Retrieves the set of search filters that may be used to determine whether an entry should be excluded from the cache.
      Set<SearchFilter> getIncludeFilters()
      Retrieves the set of search filters that may be used to determine whether an entry should be included in the cache.
      abstract MonitorData getMonitorData()
      Retrieves a set of attributes containing monitor data that should be returned to the client if the corresponding monitor entry is requested.
      abstract void handleLowMemory()
      Attempts to react to a scenario in which it is determined that the system is running low on available memory.
      abstract void initializeEntryCache​(ServerContext serverContext, T configuration)
      Initializes this entry cache implementation so that it will be available for storing and retrieving entries.
      boolean isConfigurationAcceptable​(EntryCacheCfg configuration, List<org.forgerock.i18n.LocalizableMessage> unacceptableReasons)
      Indicates whether the provided configuration is acceptable for this entry cache.
      abstract void putEntry​(Entry entry, String backendID, long entryID)
      Stores the provided entry in the cache.
      abstract boolean putEntryIfAbsent​(Entry entry, String backendID, long entryID)
      Stores the provided entry in the cache only if it does not conflict with an entry that already exists.
      abstract void removeEntry​(DN entryDN)
      Removes the specified entry from the cache.
      void setEntryCacheMonitor​(EntryCacheMonitorProvider entryCacheMonitor)
      Sets the monitor for this entry cache.
      void setExcludeFilters​(Set<SearchFilter> excludeFilters)
      Specifies the set of search filters that may be used to determine whether an entry should be excluded from the cache.
      void setIncludeFilters​(Set<SearchFilter> includeFilters)
      Specifies the set of search filters that may be used to determine whether an entry should be included in the cache.
      abstract String toVerboseString()
      Return a verbose string representation of the current cache maps.

    • Field Detail

      • cacheHits

        protected AtomicLong cacheHits
        Arbitrary number of cache hits for monitoring.

      • cacheMisses

        protected AtomicLong cacheMisses
        Arbitrary number of cache misses for monitoring.

    • Constructor Detail

      • EntryCache

        public EntryCache()
        Default constructor which is implicitly called from all entry cache implementations.

    • Method Detail

      • initializeEntryCache

        public abstract void initializeEntryCache​(ServerContext serverContext,
                                          T configuration)
                                   throws ConfigException,
                                          InitializationException
        Initializes this entry cache implementation so that it will be available for storing and retrieving entries.
        Parameters:
        serverContext - The server context.
        configuration - The configuration to use to initialize the entry cache.
        Throws:
        ConfigException - If there is a problem with the provided configuration entry that would prevent this entry cache from being used.
        InitializationException - If a problem occurs during the initialization process that is not related to the configuration.

      • isConfigurationAcceptable

        public boolean isConfigurationAcceptable​(EntryCacheCfg configuration,
                                         List<org.forgerock.i18n.LocalizableMessage> unacceptableReasons)
        Indicates whether the provided configuration is acceptable for this entry cache. It should be possible to call this method on an uninitialized entry cache instance in order to determine whether the entry cache would be able to use the provided configuration.

        Note that implementations which use a subclass of the provided configuration class will likely need to cast the configuration to the appropriate subclass type.
        Parameters:
        configuration - The entry cache configuration for which to make the determination.
        unacceptableReasons - A list that may be used to hold the reasons that the provided configuration is not acceptable.
        Returns:
        true if the provided configuration is acceptable for this entry cache, or false if not.

      • finalizeEntryCache

        public abstract void finalizeEntryCache()
        Performs any necessary cleanup work (e.g., flushing all cached entries and releasing any other held resources) that should be performed when the server is to be shut down or the entry cache destroyed or replaced.

      • containsEntry

        public abstract boolean containsEntry​(DN entryDN)
        Indicates whether the entry cache currently contains the entry with the specified DN. This method may be called without holding any locks if a point-in-time check is all that is required. Note that this method is called from @see #getEntry(DN entryDN, LockType lockType, List lockList)
        Parameters:
        entryDN - The DN for which to make the determination.
        Returns:
        true if the entry cache currently contains the entry with the specified DN, or false if not.

      • getEntry

        public abstract Entry getEntry​(DN entryDN)
        Retrieves the entry with the specified DN from the cache.
        Parameters:
        entryDN - The DN of the entry to retrieve.
        Returns:
        The requested entry if it is present in the cache, or null if it is not present.

      • getEntry

        public Entry getEntry​(String backendID,
                      long entryID)
        Retrieves the requested entry if it is present in the cache.
        Parameters:
        backendID - ID of the backend associated with the entry to retrieve.
        entryID - The entry ID within the provided backend for the specified entry.
        Returns:
        The requested entry if it is present in the cache, or null if it is not present.

      • getEntryID

        public abstract long getEntryID​(DN entryDN)
        Retrieves the entry ID for the entry with the specified DN from the cache. The caller should have already acquired a read or write lock for the entry if such protection is needed.
        Parameters:
        entryDN - The DN of the entry for which to retrieve the entry ID.
        Returns:
        The entry ID for the requested entry, or -1 if it is not present in the cache.

      • getEntryDN

        public abstract DN getEntryDN​(String backendID,
                              long entryID)
        Retrieves the entry DN for the entry with the specified ID on the specific backend from the cache. The caller should have already acquired a read or write lock for the entry if such protection is needed. Note that this method is called from @see #getEntry(Backend backend, long entryID, LockType lockType, List lockList)
        Parameters:
        backendID - ID of the backend associated with the entry for which to retrieve the entry DN.
        entryID - The entry ID within the provided backend for which to retrieve the entry DN.
        Returns:
        The entry DN for the requested entry, or null if it is not present in the cache.

      • putEntry

        public abstract void putEntry​(Entry entry,
                              String backendID,
                              long entryID)
        Stores the provided entry in the cache. Note that the mechanism that it uses to achieve this is implementation-dependent, and it is acceptable for the entry to not actually be stored in any cache.
        Parameters:
        entry - The entry to store in the cache.
        backendID - ID of the backend with which the entry is associated.
        entryID - The entry ID within the provided backend that uniquely identifies the specified entry.

      • putEntryIfAbsent

        public abstract boolean putEntryIfAbsent​(Entry entry,
                                         String backendID,
                                         long entryID)
        Stores the provided entry in the cache only if it does not conflict with an entry that already exists. Note that the mechanism that it uses to achieve this is implementation-dependent, and it is acceptable for the entry to not actually be stored in any cache. However, this method must not overwrite an existing version of the entry.
        Parameters:
        entry - The entry to store in the cache.
        backendID - ID of the backend with which the entry is associated.
        entryID - The entry ID within the provided backend that uniquely identifies the specified entry.
        Returns:
        false if an existing entry or some other problem prevented the method from completing successfully, or true if there was no conflict and the entry was either stored or the cache determined that this entry should never be cached for some reason.

      • removeEntry

        public abstract void removeEntry​(DN entryDN)
        Removes the specified entry from the cache.
        Parameters:
        entryDN - The DN of the entry to remove from the cache.

      • clear

        public abstract void clear()
        Removes all entries from the cache. The cache should still be available for future use.

      • clearBackend

        public abstract void clearBackend​(String backendID)
        Removes all entries from the cache that are associated with the provided backend.
        Parameters:
        backendID - ID of the backend for which to flush the associated entries.

      • handleLowMemory

        public abstract void handleLowMemory()
        Attempts to react to a scenario in which it is determined that the system is running low on available memory. In this case, the entry cache should attempt to free some memory if possible to try to avoid out of memory errors.

      • getEntryCacheMonitor

        public final EntryCacheMonitorProvider getEntryCacheMonitor()
        Retrieves the monitor that is associated with this entry cache.
        Returns:
        The monitor that is associated with this entry cache, or null if none has been assigned.

      • setEntryCacheMonitor

        public final void setEntryCacheMonitor​(EntryCacheMonitorProvider entryCacheMonitor)
        Sets the monitor for this entry cache.
        Parameters:
        entryCacheMonitor - The monitor for this entry cache.

      • getMonitorData

        public abstract MonitorData getMonitorData()
        Retrieves a set of attributes containing monitor data that should be returned to the client if the corresponding monitor entry is requested.
        Returns:
        A list of attributes containing monitor data that should be returned to the client if the corresponding monitor entry is requested.

      • getCacheCount

        public abstract Long getCacheCount()
        Retrieves the current number of entries stored within the cache.
        Returns:
        The current number of entries stored within the cache.

      • getCacheHits

        public long getCacheHits()
        Retrieves the current number of cache hits for this cache.
        Returns:
        The current number of cache hits for this cache.

      • getCacheMisses

        public long getCacheMisses()
        Retrieves the current number of cache misses for this cache.
        Returns:
        The current number of cache misses for this cache.

      • getExcludeFilters

        public Set<SearchFilter> getExcludeFilters()
        Retrieves the set of search filters that may be used to determine whether an entry should be excluded from the cache.
        Returns:
        The set of search filters that may be used to determine whether an entry should be excluded from the cache.

      • setExcludeFilters

        public void setExcludeFilters​(Set<SearchFilter> excludeFilters)
        Specifies the set of search filters that may be used to determine whether an entry should be excluded from the cache.
        Parameters:
        excludeFilters - The set of search filters that may be used to determine whether an entry should be excluded from the cache.

      • getIncludeFilters

        public Set<SearchFilter> getIncludeFilters()
        Retrieves the set of search filters that may be used to determine whether an entry should be included in the cache.
        Returns:
        The set of search filters that may be used to determine whether an entry should be included in the cache.

      • setIncludeFilters

        public void setIncludeFilters​(Set<SearchFilter> includeFilters)
        Specifies the set of search filters that may be used to determine whether an entry should be included in the cache.
        Parameters:
        includeFilters - The set of search filters that may be used to determine whether an entry should be included in the cache.

      • filtersAllowCaching

        public boolean filtersAllowCaching​(Entry entry)
        Indicates whether the current set of exclude and include filters allow caching of the specified entry.
        Parameters:
        entry - The entry to evaluate against exclude and include filter sets.
        Returns:
        true if current set of filters allow caching the entry and false otherwise.

      • toVerboseString

        public abstract String toVerboseString()
        Return a verbose string representation of the current cache maps. This is useful primary for debugging and diagnostic purposes such as in the entry cache unit tests.

        This method is invoked by unit tests for debugging.

        Returns:
        String verbose string representation of the current cache maps in the following format: dn:id:backend one cache entry map representation per line or null if all maps are empty.