org.opends.server.api

Class EntryCache<T extends EntryCacheCfg>

java.lang.Object

org.opends.server.api.MonitorProvider

org.opends.server.api.EntryCache<T>

Type Parameters:

T - The type of configuration handled by this entry cache.

All Implemented Interfaces:

MeterBinder

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

Field Summary

Fields inherited from class org.opends.server.api.MonitorProvider

registry

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
protected void	addMonitorObjectClassNames(Attribute objectClassAttribute) Adds to the provided attribute the objectclass names that should be included in the monitor entry created from this monitor provider.
void	bindTo(MeterRegistry parent) .
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.
protected Dn	computeMonitorInstanceDn() Returns the monitor instance DN for this monitor provider.
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 Entry	getEntry(Dn entryDN) Retrieves the entry with the specified DN from the cache.
Entry	getEntry(String backendID, long entryID) Retrieves the requested entry if it is present in the cache.
abstract long	getEntryCount() Retrieves the current number of entries stored within the 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.
abstract void	handleLowMemory() Attempts to react to a scenario in which it is determined that the system is running low on available memory.
void	initializeEntryCache(ServerContext serverContext, T configuration) Initializes this entry cache implementation so that it will be available for storing and retrieving entries.
boolean	isConfigurationAcceptable(T configuration, List<LocalizableMessage> unacceptableReasons) Indicates whether the provided configuration is acceptable for this entry cache.
protected MeterRegistryHolder	newMeterRegistryHolder(MeterRegistry parent) Creates a MeterRegistryHolder with the appropriate name prefixes and tags.
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.
protected void	recordMiss() Records a failure to retrieve an entry from this cache.
protected void	recordTry() Records an attempt to retrieve an entry from this cache.
abstract void	removeEntry(Dn entryDN) Removes the specified entry from the cache.
void	setIncludeExcludeFilters(Set<Filter> includeFilters, Set<Filter> excludeFilters) Specifies the search filters used for including in / excluding entries from the cache.
abstract String	toVerboseString() Return a verbose string representation of the current cache maps.

Methods inherited from class org.opends.server.api.MonitorProvider

configurationDnToMonitorDn, deregisterAll, getMonitorEntry, getMonitorInstanceDn, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

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.

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

computeMonitorInstanceDn

protected Dn computeMonitorInstanceDn()

Description copied from class: MonitorProvider

Returns the monitor instance DN for this monitor provider.

Specified by:

computeMonitorInstanceDn in class MonitorProvider

Returns:

the monitor instance DN.

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(Set<Filter> includeFilters,
                                     Set<Filter> excludeFilters)

Specifies the search filters used for including in / excluding entries from the cache.

Parameters:

includeFilters - The search filters used for including entries in the cache.

excludeFilters - The search filters used for excluding entries from 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.