T
- The type of configuration handled by this entry cache.@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
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:
putEntry
and getEntry
calls.putEntry
and getEntry
calls.registry
Constructor and Description |
---|
EntryCache()
Default constructor which is implicitly called from all entry cache implementations.
|
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.
|
configurationDnToMonitorDn, deregisterAll, getMonitorEntry, getMonitorInstanceDn, toString
public EntryCache()
public void initializeEntryCache(ServerContext serverContext, T configuration) throws ConfigException, InitializationException
serverContext
- The server context.configuration
- The configuration to use to initialize the entry cache.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.public boolean isConfigurationAcceptable(T configuration, List<LocalizableMessage> unacceptableReasons)
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.true
if the provided configuration is acceptable for this entry cache, or false
if not.public abstract void finalizeEntryCache()
public abstract boolean containsEntry(Dn entryDN)
entryDN
- The DN for which to make the determination.true
if the entry cache currently contains the entry with the specified DN, or false
if
not.public abstract Entry getEntry(Dn entryDN)
entryDN
- The DN of the entry to retrieve.null
if it is not present.public Entry getEntry(String backendID, long entryID)
backendID
- ID of the backend associated with the entry to retrieve.entryID
- The entry ID within the provided backend for the specified entry.null
if it is not present.public abstract long getEntryID(Dn entryDN)
entryDN
- The DN of the entry for which to retrieve the entry ID.public abstract Dn getEntryDN(String backendID, long entryID)
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.null
if it is not present in the cache.public abstract void putEntry(Entry entry, String backendID, long entryID)
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.public abstract boolean putEntryIfAbsent(Entry entry, String backendID, long entryID)
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.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.public abstract void removeEntry(Dn entryDN)
entryDN
- The DN of the entry to remove from the cache.public abstract void clear()
public abstract void clearBackend(String backendID)
backendID
- ID of the backend for which to flush the associated entries.public abstract void handleLowMemory()
protected Dn computeMonitorInstanceDn()
MonitorProvider
computeMonitorInstanceDn
in class MonitorProvider
protected void addMonitorObjectClassNames(Attribute objectClassAttribute)
MonitorProvider
addMonitorObjectClassNames
in class MonitorProvider
objectClassAttribute
- the objectClass attribute where to add the object class namesprotected MeterRegistryHolder newMeterRegistryHolder(MeterRegistry parent)
MeterRegistryHolder
with the appropriate name prefixes and tags.parent
- The meter registry to be decorated.public void bindTo(MeterRegistry parent)
MonitorProvider
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.
(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);
}
bindTo
in interface MeterBinder
bindTo
in class MonitorProvider
public abstract long getEntryCount()
protected void recordTry()
protected void recordMiss()
public void setIncludeExcludeFilters(Set<Filter> includeFilters, Set<Filter> excludeFilters)
includeFilters
- The search filters used for including entries in the cache.excludeFilters
- The search filters used for excluding entries from the cache.public boolean filtersAllowCaching(Entry entry)
entry
- The entry to evaluate against exclude and include filter sets.true
if current set of filters allow caching the entry and false
otherwise.public abstract String toVerboseString()
This method is invoked by unit tests for debugging.
null
if all maps are empty.Copyright 2010-2022 ForgeRock AS.