Package 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:
EntryCacheConfigManager.EntryCacheDispatcher
,FIFOEntryCache
,SoftReferenceEntryCache
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
andgetEntry
calls. - The entry cache may implement a purging mechanism and the entry added may have been purged between the
putEntry
andgetEntry
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
ConstructorDescriptionDefault constructor which is implicitly called from all entry cache implementations. -
Method Summary
Modifier and TypeMethodDescriptionprotected 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
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
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 SizedEntry
Retrieves the requested entry with its size, if it is present in the cache.abstract SizedEntry
Retrieves the entry with its size, with the specified DN from the cache.abstract long
Retrieves the current number of entries stored within the cache.abstract long
Retrieves the current amount of memory used by this cache in bytes.protected ServerContext
Returns the server context.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 aMeterRegistryHolder
with the appropriate name prefixes and tags.abstract void
putEntry
(SizedEntry entry, String backendID, long entryID) Stores the provided entry in the cache.abstract void
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.protected void
Records a failure to retrieve an entry from this cache.protected void
Records an attempt to retrieve an entry from this cache.abstract void
removeEntry
(Dn entryDN) Removes the specified entry from the cache.void
Specifies the search filters used for including in / excluding entries from the cache.abstract String
Return a verbose string representation of the current cache maps.Methods inherited from class org.opends.server.api.MonitorProvider
configurationDnToMonitorDn, deregisterAll, getMonitorEntry, getMonitorInstanceDn, toString
-
Constructor Details
-
EntryCache
public EntryCache()Default constructor which is implicitly called from all entry cache implementations.
-
-
Method Details
-
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
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, orfalse
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
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, orfalse
if not.
-
getEntry
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
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.
-
putEntry
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
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.
-
removeEntry
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
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.
-
computeMonitorInstanceDn
Description copied from class:MonitorProvider
Returns the monitor instance DN for this monitor provider.- Specified by:
computeMonitorInstanceDn
in classMonitorProvider
- Returns:
- the monitor instance DN.
-
addMonitorObjectClassNames
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 classMonitorProvider
- Parameters:
objectClassAttribute
- the objectClass attribute where to add the object class names
-
newMeterRegistryHolder
Creates aMeterRegistryHolder
with the appropriate name prefixes and tags.- Parameters:
parent
- The meter registry to be decorated.- Returns:
- The meter registry holder.
-
bindTo
Description copied from class:MonitorProvider
.Implementation considerations
Implementations MUST set the
MonitorProvider.registry
field by creating a newMeterRegistryHolder
, 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 theMeterRegistryHolder.hierarchicalNamePrefix(String)
method. Tags common to all metrics for this monitor provider can also be set using theMeterRegistryHolder.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 interfaceMeterBinder
- Specified by:
bindTo
in classMonitorProvider
-
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.
-
getMemoryUsage
public abstract long getMemoryUsage()Retrieves the current amount of memory used by this cache in bytes.- Returns:
- The current amount of memory used by this cache in bytes.
-
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
Specifies the search filters used for including in / excluding entries from the cache.- Parameters:
filters
- The include and exclude filters.
-
filtersAllowCaching
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 andfalse
otherwise.
-
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.
-