org.opends.server.api
Class EntryCache<T extends EntryCacheCfg>

java.lang.Object
  extended by org.opends.server.api.EntryCache<T>
Type Parameters:
T - The type of configuration handled by this entry cache.
Direct Known Subclasses:
DefaultEntryCache, FIFOEntryCache, FileSystemEntryCache, 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 java.lang.Object

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:


Field Summary
protected  java.util.concurrent.atomic.AtomicLong cacheHits
          Arbitrary number of cache hits for monitoring.
protected  java.util.concurrent.atomic.AtomicLong cacheMisses
          Arbitrary number of cache misses for monitoring.
 
Constructor Summary
EntryCache()
          Default constructor which is implicitly called from all entry cache implementations.
 
Method Summary
abstract  void clear()
          Removes all entries from the cache.
abstract  void clearBackend(Backend backend)
          Removes all entries from the cache that are associated with the provided backend.
abstract  void clearSubtree(DN baseDN)
          Removes all entries from the cache that are below the provided DN.
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  java.lang.Long getCacheCount()
          Retrieves the current number of entries stored within the cache.
 java.lang.Long getCacheHits()
          Retrieves the current number of cache hits for this cache.
 java.lang.Long getCacheMisses()
          Retrieves the current number of cache misses for this cache.
 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.
abstract  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.
 EntryCacheMonitorProvider getEntryCacheMonitor()
          Retrieves the monitor that is associated with this entry cache.
abstract  DN getEntryDN(Backend backend, 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.
 java.util.Set<SearchFilter> getExcludeFilters()
          Retrieves the set of search filters that may be used to determine whether an entry should be excluded from the cache.
 java.util.Set<SearchFilter> getIncludeFilters()
          Retrieves the set of search filters that may be used to determine whether an entry should be included in the cache.
 long getLockTimeout()
          Retrieves the maximum length of time in milliseconds to wait for a lock before giving up.
abstract  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.
abstract  void handleLowMemory()
          Attempts to react to a scenario in which it is determined that the system is running low on available memory.
abstract  void initializeEntryCache(T 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.
abstract  void putEntry(Entry entry, Backend backend, long entryID)
          Stores the provided entry in the cache.
abstract  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.
abstract  void removeEntry(DN entryDN)
          Removes the specified entry from the cache.
 void setEntryCacheMonitor(EntryCacheMonitorProvider entryCacheMonitor)
          Sets the monitor for this entry cache.
 void setExcludeFilters(java.util.Set<SearchFilter> excludeFilters)
          Specifies the set of search filters that may be used to determine whether an entry should be excluded from the cache.
 void setIncludeFilters(java.util.Set<SearchFilter> includeFilters)
          Specifies the set of search filters that may be used to determine whether an entry should be included in the cache.
 void setLockTimeout(long lockTimeout)
          Specifies the maximum length of time in milliseconds to wait for a lock before giving up.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

cacheHits

protected java.util.concurrent.atomic.AtomicLong cacheHits
Arbitrary number of cache hits for monitoring.


cacheMisses

protected java.util.concurrent.atomic.AtomicLong cacheMisses
Arbitrary number of cache misses for monitoring.

Constructor Detail

EntryCache

public EntryCache()
Default constructor which is implicitly called from all entry cache implementations.

Method Detail

initializeEntryCache

public abstract void initializeEntryCache(T configuration)
                                   throws ConfigException,
                                          InitializationException
Initializes this entry cache implementation so that it will be available for storing and retrieving entries.

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.

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.

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

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

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.

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.

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

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

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

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 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(Backend backend)
Removes all entries from the cache that are associated with the provided backend.

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

clearSubtree

public abstract void clearSubtree(DN baseDN)
Removes all entries from the cache that are below the provided DN.

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

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.


getEntryCacheMonitor

public final EntryCacheMonitorProvider getEntryCacheMonitor()
Retrieves the monitor that is associated with this entry cache.

Returns:
The monitor that is associated with this entry cache, or null if none has been assigned.

setEntryCacheMonitor

public final void setEntryCacheMonitor(EntryCacheMonitorProvider entryCacheMonitor)
Sets the monitor for this entry cache.

Parameters:
entryCacheMonitor - The monitor for this entry cache.

getMonitorData

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

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

getCacheCount

public abstract java.lang.Long getCacheCount()
Retrieves the current number of entries stored within the cache.

Returns:
The current number of entries stored within the cache.

getCacheHits

public java.lang.Long getCacheHits()
Retrieves the current number of cache hits for this cache.

Returns:
The current number of cache hits for this cache.

getCacheMisses

public java.lang.Long getCacheMisses()
Retrieves the current number of cache misses for this cache.

Returns:
The current number of cache misses for this cache.

getLockTimeout

public long getLockTimeout()
Retrieves the maximum length of time in milliseconds to wait for a lock before giving up.

Returns:
The maximum length of time in milliseconds to wait for a lock before giving up.

setLockTimeout

public void setLockTimeout(long lockTimeout)
Specifies the maximum length of time in milliseconds to wait for a lock before giving up.

Parameters:
lockTimeout - The maximum length of time in milliseconds to wait for a lock before giving up.

getExcludeFilters

public java.util.Set<SearchFilter> getExcludeFilters()
Retrieves the set of search filters that may be used to determine whether an entry should be excluded from the cache.

Returns:
The set of search filters that may be used to determine whether an entry should be excluded from the cache.

setExcludeFilters

public void setExcludeFilters(java.util.Set<SearchFilter> excludeFilters)
Specifies the set of search filters that may be used to determine whether an entry should be excluded from the cache.

Parameters:
excludeFilters - The set of search filters that may be used to determine whether an entry should be excluded from the cache.

getIncludeFilters

public java.util.Set<SearchFilter> getIncludeFilters()
Retrieves the set of search filters that may be used to determine whether an entry should be included in the cache.

Returns:
The set of search filters that may be used to determine whether an entry should be included in the cache.

setIncludeFilters

public void setIncludeFilters(java.util.Set<SearchFilter> includeFilters)
Specifies the set of search filters that may be used to determine whether an entry should be included in the cache.

Parameters:
includeFilters - The set of search filters that may be used to determine whether an entry should be included in 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.