Package org.opends.server.extensions

Class FIFOEntryCache

  • All Implemented Interfaces:
    MeterBinder, ConfigurationChangeListener<FifoEntryCacheCfg>
    public final class FIFOEntryCache
extends EntryCache<FifoEntryCacheCfg>
implements ConfigurationChangeListener<FifoEntryCacheCfg>
    This class defines a Directory Server entry cache that uses a FIFO to keep track of the entries. Entries that have been in the cache the longest are the most likely candidates for purging if space is needed. In contrast to other cache structures, the selection of entries to purge is not based on how frequently or recently the entries have been accessed. This requires significantly less locking (it will only be required when an entry is added or removed from the cache, rather than each time an entry is accessed).

    Cache sizing is based on the percentage of free memory within the JVM, such that if enough memory is free, then adding an entry to the cache will not require purging, but if more than a specified percentage of the available memory within the JVM is already consumed, then one or more entries will need to be removed in order to make room for a new entry. It is also possible to configure a maximum number of entries for the cache. If this is specified, then the number of entries will not be allowed to exceed this value, but it may not be possible to hold this many entries if the available memory fills up first.

    Other configurable parameters for this cache include the maximum length of time to block while waiting to acquire a lock, and a set of filters that may be used to define criteria for determining which entries are stored in the cache. If a filter list is provided, then only entries matching at least one of the given filters will be stored in the cache.

    • Constructor Detail

      • FIFOEntryCache

        public FIFOEntryCache()

    • Method Detail

      • finalizeEntryCache

        public void finalizeEntryCache()
        Description copied from class: EntryCache
        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.
        Specified by:
        finalizeEntryCache in class EntryCache<FifoEntryCacheCfg>

      • containsEntry

        public boolean containsEntry​(Dn entryDN)
        Description copied from class: EntryCache
        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)
        Specified by:
        containsEntry in class EntryCache<FifoEntryCacheCfg>
        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 SizedEntry getEntry​(Dn entryDN)
        Description copied from class: EntryCache
        Retrieves the entry with its size, with the specified DN from the cache.
        Specified by:
        getEntry in class EntryCache<FifoEntryCacheCfg>
        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.

      • getEntryDN

        public Dn getEntryDN​(String backendID,
                     long entryID)
        Description copied from class: EntryCache
        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)
        Specified by:
        getEntryDN in class EntryCache<FifoEntryCacheCfg>
        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 void putEntry​(SizedEntry entry,
                     String backendID,
                     long entryID)
        Description copied from class: EntryCache
        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.
        Specified by:
        putEntry in class EntryCache<FifoEntryCacheCfg>
        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 boolean putEntryIfAbsent​(SizedEntry entry,
                                String backendID,
                                long entryID)
        Description copied from class: EntryCache
        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.
        Specified by:
        putEntryIfAbsent in class EntryCache<FifoEntryCacheCfg>
        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 void removeEntry​(Dn entryDN)
        Description copied from class: EntryCache
        Removes the specified entry from the cache.
        Specified by:
        removeEntry in class EntryCache<FifoEntryCacheCfg>
        Parameters:
        entryDN - The DN of the entry to remove from the cache.

      • clear

        public void clear()
        Description copied from class: EntryCache
        Removes all entries from the cache. The cache should still be available for future use.
        Specified by:
        clear in class EntryCache<FifoEntryCacheCfg>

      • clearBackend

        public void clearBackend​(String backendID)
        Description copied from class: EntryCache
        Removes all entries from the cache that are associated with the provided backend.
        Specified by:
        clearBackend in class EntryCache<FifoEntryCacheCfg>
        Parameters:
        backendID - ID of the backend for which to flush the associated entries.

      • handleLowMemory

        public void handleLowMemory()
        Description copied from class: EntryCache
        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.
        Specified by:
        handleLowMemory in class EntryCache<FifoEntryCacheCfg>

      • isConfigurationAcceptable

        public boolean isConfigurationAcceptable​(FifoEntryCacheCfg configuration,
                                         List<LocalizableMessage> unacceptableReasons)
        Description copied from class: EntryCache
        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.
        Overrides:
        isConfigurationAcceptable in class EntryCache<FifoEntryCacheCfg>
        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.

      • isConfigurationChangeAcceptable

        public boolean isConfigurationChangeAcceptable​(FifoEntryCacheCfg configuration,
                                               List<LocalizableMessage> unacceptableReasons)
        Description copied from interface: ConfigurationChangeListener
        Indicates whether the proposed change to the configuration is acceptable to this change listener.
        Specified by:
        isConfigurationChangeAcceptable in interface ConfigurationChangeListener<FifoEntryCacheCfg>
        Parameters:
        configuration - The new configuration containing the changes.
        unacceptableReasons - A list that can be used to hold messages about why the provided configuration is not acceptable.
        Returns:
        Returns true if the proposed change is acceptable, or false if it is not.

      • 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
        Overrides:
        bindTo in class EntryCache<FifoEntryCacheCfg>

      • getEntryCount

        public long getEntryCount()
        Description copied from class: EntryCache
        Retrieves the current number of entries stored within the cache.
        Specified by:
        getEntryCount in class EntryCache<FifoEntryCacheCfg>
        Returns:
        The current number of entries stored within the cache.

      • toVerboseString

        public String toVerboseString()
        Description copied from class: EntryCache
        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.

        Specified by:
        toVerboseString in class EntryCache<FifoEntryCacheCfg>
        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.