org.opends.server.extensions
Class FileSystemEntryCache

java.lang.Object
  extended by org.opends.server.api.EntryCache<FileSystemEntryCacheCfg>
      extended by org.opends.server.extensions.FileSystemEntryCache
All Implemented Interfaces:
ConfigurationChangeListener<FileSystemEntryCacheCfg>

public class FileSystemEntryCache
extends EntryCache<FileSystemEntryCacheCfg>
implements ConfigurationChangeListener<FileSystemEntryCacheCfg>

This class defines a Directory Server entry cache that uses JE database to keep track of the entries. Intended use is when JE database resides in the memory based file system which has obvious performance benefits, although any file system will do for this cache to function. Entries are maintained either by FIFO (default) or LRU (configurable) based list implementation.

Cache sizing is based on the size of free space available in the file system, such that if enough memory is free, then adding an entry to the cache will not require purging, but if more than a specified size of the file system available space 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.

JE environment cache size can also be configured either as percentage of the free memory available in the JVM or as explicit size in bytes.

This cache has a persistence property which, if enabled, allows for the contents of the cache to stay persistent across server or cache restarts.


Field Summary
 
Fields inherited from class org.opends.server.api.EntryCache
cacheHits, cacheMisses
 
Constructor Summary
FileSystemEntryCache()
          Creates a new instance of this entry cache.
 
Method Summary
 ConfigChangeResult applyConfigurationChange(FileSystemEntryCacheCfg 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.
 Entry getEntry(DN entryDN)
          Retrieves the entry with the specified DN from the cache.
 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(FileSystemEntryCacheCfg configuration)
          Initializes this entry cache implementation so that it will be available for storing and retrieving entries.
 boolean isConfigurationAcceptable(EntryCacheCfg configuration, java.util.List<Message> unacceptableReasons)
          Indicates whether the provided configuration is acceptable for this entry cache.
 boolean isConfigurationChangeAcceptable(FileSystemEntryCacheCfg configuration, java.util.List<Message> unacceptableReasons)
          Indicates whether the proposed change to the configuration is acceptable to this change listener.
 boolean processEntryCacheConfig(FileSystemEntryCacheCfg configuration, boolean applyChanges, EntryCacheCommon.ConfigErrorHandler errorHandler)
          Parses the provided configuration and configure the entry cache.
 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.
protected  boolean removeEldestEntry(java.util.Map.Entry eldest)
          This method is called each time we add a new key/value pair to the map.
 void removeEntry(DN entryDN)
          Removes the specified entry from the cache.
 
Methods inherited from class org.opends.server.api.EntryCache
filtersAllowCaching, getCacheHits, getCacheMisses, getEntry, getEntry, getEntryCacheMonitor, getExcludeFilters, getIncludeFilters, getLockTimeout, setEntryCacheMonitor, setExcludeFilters, setIncludeFilters, setLockTimeout
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

FileSystemEntryCache

public FileSystemEntryCache()
Creates a new instance of this entry cache.

Method Detail

initializeEntryCache

public void initializeEntryCache(FileSystemEntryCacheCfg configuration)
                          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<FileSystemEntryCacheCfg>
Parameters:
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.

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

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

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

isConfigurationAcceptable

public boolean isConfigurationAcceptable(EntryCacheCfg configuration,
                                         java.util.List<Message> 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.

Note that implementations which use a subclass of the provided configuration class will likely need to cast the configuration to the appropriate subclass type.

Overrides:
isConfigurationAcceptable in class EntryCache<FileSystemEntryCacheCfg>
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(FileSystemEntryCacheCfg 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<FileSystemEntryCacheCfg>
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(FileSystemEntryCacheCfg configuration)
Applies the configuration changes to this change listener.

Specified by:
applyConfigurationChange in interface ConfigurationChangeListener<FileSystemEntryCacheCfg>
Parameters:
configuration - The new configuration containing the changes.
Returns:
Returns information about the result of changing the configuration.

processEntryCacheConfig

public boolean processEntryCacheConfig(FileSystemEntryCacheCfg configuration,
                                       boolean applyChanges,
                                       EntryCacheCommon.ConfigErrorHandler errorHandler)
Parses the provided configuration and configure the entry cache.

Parameters:
configuration - The new configuration containing the changes.
applyChanges - If true then take into account the new configuration.
errorHandler - An handler used to report errors.
Returns:
true if configuration is acceptable, or false otherwise.

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<FileSystemEntryCacheCfg>
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<FileSystemEntryCacheCfg>
Returns:
The current number of entries stored within the cache.

removeEldestEntry

protected boolean removeEldestEntry(java.util.Map.Entry eldest)
This method is called each time we add a new key/value pair to the map. The eldest entry is selected by the LinkedHashMap implementation based on the access order configured.

Parameters:
eldest - The least recently inserted entry in the map, or if this is an access-ordered map, the least recently accessed entry. This is the entry that will be removed it this method returns true. If the map was empty prior to the put or putAll invocation resulting in this invocation, this will be the entry that was just inserted; in other words, if the map contains a single entry, the eldest entry is also the newest.
Returns:
boolean true if the eldest entry should be removed from the map; false if it should be retained.