org.opends.server.extensions
Class DefaultEntryCache

java.lang.Object
  org.opends.server.api.EntryCache<EntryCacheCfg>
      org.opends.server.extensions.DefaultEntryCache

All Implemented Interfaces:

ConfigurationChangeListener<EntryCacheCfg>, BackendInitializationListener

public class DefaultEntryCache
extends EntryCache<EntryCacheCfg>
implements ConfigurationChangeListener<EntryCacheCfg>, BackendInitializationListener

This class defines the default entry cache which acts as an arbiter for every entry cache implementation configured and installed within the Directory Server or acts an an empty cache if no implementation specific entry cache is configured. It does not actually store any entries, so all calls to the entry cache public API are routed to underlying entry cache according to the current configuration order and preferences.

Field Summary

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

cacheHits, cacheMisses

Constructor Summary

DefaultEntryCache()
Creates a new instance of this default entry cache.

Method Summary

ConfigChangeResult	applyConfigurationChange(EntryCacheCfg configuration) Applies the configuration changes to this change listener.
void	clear() Removes all entries from the cache.
void	clearBackend(Backend backend) Removes all entries from the cache that are associated with the provided backend.
void	clearSubtree(DN baseDN) Removes all entries from the cache that are below the provided DN.
boolean	containsEntry(DN entryDN) Indicates whether the entry cache currently contains the entry with the specified DN.
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.
java.lang.Long	getCacheCount() Retrieves the current number of entries stored within the cache.
EntryCache<? extends EntryCacheCfg>[]	getCacheOrder() Retrieves the current cache order array.
Entry	getEntry(Backend backend, long entryID, LockType lockType, java.util.List<java.util.concurrent.locks.Lock> lockList) Retrieves the requested entry if it is present in the cache, obtaining a lock on the entry before it is returned.
Entry	getEntry(DN entryDN) Retrieves the entry with the specified DN from the cache.
Entry	getEntry(DN entryDN, LockType lockType, java.util.List<java.util.concurrent.locks.Lock> lockList) Retrieves the entry with the specified DN from the cache, obtaining a lock on the entry before it is returned.
DN	getEntryDN(Backend backend, long entryID) Retrieves the entry DN for the entry with the specified ID on the specific backend from the cache.
long	getEntryID(DN entryDN) Retrieves the entry ID for the entry with the specified DN from the cache.
java.util.ArrayList<Attribute>	getMonitorData() Retrieves a set of attributes containing monitor data that should be returned to the client if the corresponding monitor entry is requested.
void	handleLowMemory() Attempts to react to a scenario in which it is determined that the system is running low on available memory.
void	initializeEntryCache(EntryCacheCfg configEntry) Initializes this entry cache implementation so that it will be available for storing and retrieving entries.
boolean	isConfigurationChangeAcceptable(EntryCacheCfg configuration, java.util.List<Message> unacceptableReasons) Indicates whether the proposed change to the configuration is acceptable to this change listener.
void	performBackendFinalizationProcessing(Backend backend) Performs any processing that may be required whenever a backend is finalized.
void	performBackendInitializationProcessing(Backend backend) Performs any processing that may be required whenever a backend is initialized for use in the Directory Server.
void	putEntry(Entry entry, Backend backend, long entryID) Stores the provided entry in the cache.
boolean	putEntryIfAbsent(Entry entry, Backend backend, long entryID) Stores the provided entry in the cache only if it does not conflict with an entry that already exists.
void	removeEntry(DN entryDN) Removes the specified entry from the cache.
void	setCacheOrder(java.util.SortedMap<java.lang.Integer,EntryCache<? extends EntryCacheCfg>> cacheOrderMap) Sets the current cache order array.

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

filtersAllowCaching, getCacheHits, getCacheMisses, getEntryCacheMonitor, getExcludeFilters, getIncludeFilters, getLockTimeout, isConfigurationAcceptable, setEntryCacheMonitor, setExcludeFilters, setIncludeFilters, setLockTimeout

Methods inherited from class java.lang.Object

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

Constructor Detail

DefaultEntryCache

public DefaultEntryCache()

Creates a new instance of this default entry cache.

Method Detail

initializeEntryCache

public void initializeEntryCache(EntryCacheCfg configEntry)
                          throws ConfigException,
                                 InitializationException

Initializes this entry cache implementation so that it will be available for storing and retrieving entries.

Specified by:

initializeEntryCache in class EntryCache<EntryCacheCfg>

Parameters:

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

finalizeEntryCache

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

Specified by:

finalizeEntryCache in class EntryCache<EntryCacheCfg>

containsEntry

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

Specified by:

containsEntry in class EntryCache<EntryCacheCfg>

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 Entry getEntry(DN entryDN,
                      LockType lockType,
                      java.util.List<java.util.concurrent.locks.Lock> lockList)

Retrieves the entry with the specified DN from the cache, obtaining a lock on the entry before it is returned. If the entry is present in the cache, then a lock will be obtained for that entry and appended to the provided list before the entry is returned. If the entry is not present, then no lock will be obtained. Note that although this method is declared non-final it is not recommended for subclasses to implement this method.

Overrides:

getEntry in class EntryCache<EntryCacheCfg>

Parameters:

entryDN - The DN of the entry to retrieve.

lockType - The type of lock to obtain (it may be NONE).

lockList - The list to which the obtained lock will be added (note that no lock will be added if the lock type was NONE).

Returns:

The requested entry if it is present in the cache, or null if it is not present.

getEntry

public Entry getEntry(Backend backend,
                      long entryID,
                      LockType lockType,
                      java.util.List<java.util.concurrent.locks.Lock> lockList)

Retrieves the requested entry if it is present in the cache, obtaining a lock on the entry before it is returned. If the entry is present in the cache, then a lock will be obtained for that entry and appended to the provided list before the entry is returned. If the entry is not present, then no lock will be obtained. Note that although this method is declared non-final it is not recommended for subclasses to implement this method.

Overrides:

getEntry in class EntryCache<EntryCacheCfg>

Parameters:

backend - The backend associated with the entry to retrieve.

entryID - The entry ID within the provided backend for the specified entry.

lockType - The type of lock to obtain (it may be NONE).

lockList - The list to which the obtained lock will be added (note that no lock will be added if the lock type was NONE).

Returns:

The requested entry if it is present in the cache, or null if it is not present.

getEntry

public Entry getEntry(DN entryDN)

Retrieves 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. Note that this method is called from @see #getEntry(DN entryDN, LockType lockType, List lockList)

Specified by:

getEntry in class EntryCache<EntryCacheCfg>

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.

getEntryID

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

Specified by:

getEntryID in class EntryCache<EntryCacheCfg>

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 DN getEntryDN(Backend backend,
                     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)

Specified by:

getEntryDN in class EntryCache<EntryCacheCfg>

Parameters:

backend - 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(Entry entry,
                     Backend backend,
                     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.

Specified by:

putEntry in class EntryCache<EntryCacheCfg>

Parameters:

entry - The entry to store in the cache.

backend - 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(Entry entry,
                                Backend backend,
                                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.

Specified by:

putEntryIfAbsent in class EntryCache<EntryCacheCfg>

Parameters:

entry - The entry to store in the cache.

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

Removes the specified entry from the cache.

Specified by:

removeEntry in class EntryCache<EntryCacheCfg>

Parameters:

entryDN - The DN of the entry to remove from the cache.

clear

public void clear()

Removes all entries from the cache. The cache should still be available for future use.

Specified by:

clear in class EntryCache<EntryCacheCfg>

clearBackend

public void clearBackend(Backend backend)

Removes all entries from the cache that are associated with the provided backend.

Specified by:

clearBackend in class EntryCache<EntryCacheCfg>

Parameters:

backend - The backend for which to flush the associated entries.

clearSubtree

public void clearSubtree(DN baseDN)

Removes all entries from the cache that are below the provided DN.

Specified by:

clearSubtree in class EntryCache<EntryCacheCfg>

Parameters:

baseDN - The base DN below which all entries should be flushed.

handleLowMemory

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

Specified by:

handleLowMemory in class EntryCache<EntryCacheCfg>

isConfigurationChangeAcceptable

public boolean isConfigurationChangeAcceptable(EntryCacheCfg configuration,
                                               java.util.List<Message> unacceptableReasons)

Indicates whether the proposed change to the configuration is acceptable to this change listener.

Specified by:

isConfigurationChangeAcceptable in interface ConfigurationChangeListener<EntryCacheCfg>

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.

applyConfigurationChange

public ConfigChangeResult applyConfigurationChange(EntryCacheCfg configuration)

Applies the configuration changes to this change listener.

Specified by:

applyConfigurationChange in interface ConfigurationChangeListener<EntryCacheCfg>

Parameters:

configuration - The new configuration containing the changes.

Returns:

Returns information about the result of changing the configuration.

getMonitorData

public java.util.ArrayList<Attribute> getMonitorData()

Retrieves a set of attributes containing monitor data that should be returned to the client if the corresponding monitor entry is requested.

Specified by:

getMonitorData in class EntryCache<EntryCacheCfg>

Returns:

A set of attributes containing monitor data that should be returned to the client if the corresponding monitor entry is requested.

getCacheCount

public java.lang.Long getCacheCount()

Retrieves the current number of entries stored within the cache.

Specified by:

getCacheCount in class EntryCache<EntryCacheCfg>

Returns:

The current number of entries stored within the cache.

getCacheOrder

public final EntryCache<? extends EntryCacheCfg>[] getCacheOrder()

Retrieves the current cache order array.

Returns:

The current cache order array.

setCacheOrder

public final void setCacheOrder(java.util.SortedMap<java.lang.Integer,EntryCache<? extends EntryCacheCfg>> cacheOrderMap)

Sets the current cache order array.

Parameters:

cacheOrderMap - The current cache order array.

performBackendInitializationProcessing

public void performBackendInitializationProcessing(Backend backend)

Performs any processing that may be required whenever a backend is initialized for use in the Directory Server. This method will be invoked after the backend has been initialized but before it has been put into service.

Specified by:

performBackendInitializationProcessing in interface BackendInitializationListener

Parameters:

backend - The backend that has been initialized and is about to be put into service.

performBackendFinalizationProcessing

public void performBackendFinalizationProcessing(Backend backend)

Performs any processing that may be required whenever a backend is finalized. This method will be invoked after the backend has been taken out of service but before it has been finalized.

Specified by:

performBackendFinalizationProcessing in interface BackendInitializationListener

Parameters:

backend - The backend that has been taken out of service and is about to be finalized.