Package org.opends.server.api

Class EntryCache<T extends EntryCacheCfg>

  • Type Parameters:
    T - The type of configuration handled by this entry cache.
    All Implemented Interfaces:
    MeterBinder
    Direct Known Subclasses:
    DefaultEntryCache, FIFOEntryCache, NullEntryCache, 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 MonitorProvider
    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).

    • Constructor Detail

      • EntryCache

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

    • Method Detail

      • initializeEntryCache

        public 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.

      • getServerContext

        protected ServerContext getServerContext()
        Returns the server context.
        Returns:
        the server context

      • isConfigurationAcceptable

        public boolean isConfigurationAcceptable​(T configuration,
                                         List<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.
        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 SizedEntry getEntry​(Dn entryDN)
        Retrieves the entry with its size, with the specified DN from the cache.
        Parameters:
        entryDN - The DN of the entry to retrieve.
        Returns:
        The requested entry with its size if it is present in the cache, or null if it is not present.

      • getEntry

        public SizedEntry getEntry​(String backendID,
                           long entryID)
        Retrieves the requested entry with its size, 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.

      • 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​(SizedEntry 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​(SizedEntry 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.

      • addMonitorObjectClassNames

        protected void addMonitorObjectClassNames​(Attribute objectClassAttribute)
        Description copied from class: MonitorProvider
        Adds to the provided attribute the objectclass names that should be included in the monitor entry created from this monitor provider. This method should be implemented by child classes to make it easier to search for monitor entries of a specific type.
        Specified by:
        addMonitorObjectClassNames in class MonitorProvider
        Parameters:
        objectClassAttribute - the objectClass attribute where to add the object class names

      • newMeterRegistryHolder

        protected MeterRegistryHolder newMeterRegistryHolder​(MeterRegistry parent)
        Creates a MeterRegistryHolder with the appropriate name prefixes and tags.
        Parameters:
        parent - The meter registry to be decorated.
        Returns:
        The meter registry holder.

      • bindTo

        public void bindTo​(MeterRegistry parent)
        Description copied from class: MonitorProvider
        .

        Implementation considerations

        Implementations MUST set the MonitorProvider.registry field by creating a new MeterRegistryHolder, and specifying the appropriate prefix for the dimensional model and also the hierarchical model if they are different. This can be done using a parameter on the constructor, or the MeterRegistryHolder.hierarchicalNamePrefix(String) method. Tags common to all metrics for this monitor provider can also be set using the MeterRegistryHolder.tag(String, String) method.

        Attribute names are then registered by calling factory methods on the MonitorProvider.registry field.

        Sample dummy implementation

        (Please remove the comments when using this code as a template) 

         
 public void bindTo(final MeterRegistry parent) {
     // create the MeterRegistryHolder wrapping OpenDJ's MeterRegistry
     registry = new MeterRegistryHolder("dimensional-name-prefix", parent)
              .tag("label", "dimension")
              .hierarchicalNamePrefix("hierarchical-name-prefix.dimension");

     // register the metrics against the wrapper
     registry.numberGauge("gauge", numberSupplier); // use lambdas or method references here
     timer = registry.timer("requests-submitted");
     // set a different name for the metric in cn=monitor, dimensional model and hierarchical model
     Gauge.doubleGauge(dimensionalName, supplier)
          .hierarchicalName(hierarchicalName)
          .tag(MeterRegistryHolder.TAG_ATTRIBUTE_NAME, "cn-monitor-name") // drop the "ds-mon-" prefix here
          .register(registry);
     // this gauge will only output to cn=monitor based monitoring endpoints
     registry.monitoringGauge("only-visible-in-cn-monitor", supplier);
 }
        Specified by:
        bindTo in interface MeterBinder
        Specified by:
        bindTo in class MonitorProvider

      • getEntryCount

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

      • recordTry

        protected void recordTry()
        Records an attempt to retrieve an entry from this cache.

      • recordMiss

        protected void recordMiss()
        Records a failure to retrieve an entry from this cache.

      • setIncludeExcludeFilters

        public void setIncludeExcludeFilters​(Pair<Set<Filter>,​Set<Filter>> filters)
        Specifies the search filters used for including in / excluding entries from the cache.
        Parameters:
        filters - The include and exclude filters.

      • 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.