netscape.ldap
Class LDAPCache

java.lang.Object
  extended by netscape.ldap.LDAPCache
All Implemented Interfaces:
java.io.Serializable

public class LDAPCache
extends java.lang.Object
implements java.io.Serializable

LDAPCache represents an in-memory cache that you can use to reduce the number of search requests sent to the LDAP server.

Each item in the cache represents a search request and its results. Each item is uniquely identified by the search criteria, which includes:

After a search request is cached, the results of any subsequent search requests using the same criteria are read from the cache. Note that if any part of the criteria differs (for example, if a different DN is used when binding to the server or if a different set of attributes to be returned is specified), the search request is sent to the server.

When you create the cache, you specify the maximum amount of time that an item can be kept in the cache. When an item's age exceeds that time limit, the item is removed from the cache.

The cache also has a maximum size that you specify when creating the cache. If adding a new item exceeds the maximum size of the cache, the first entries in the cache are removed to make enough space for the new item.

Finally, when creating the cache, you can specify a list of the base DNs in search requests that you want to cache. For example, if you specify o=Airius.com as a base DN to cache, your client caches search requests where the base DN is o=Airius.com.

To specify that you want to use a cache for a particular LDAP session, call the setCache method of the LDAPConnection object that you are working with.

All clones of an LDAPConnection object share the same LDAPCache object.

Note that LDAPCache does not maintain consistency with the directory, so that cached search results may no longer be valid after a directory update. If the same application is performing both cached searches and directory updates, then the application should flush the corresponding cache entries after an update. To do this use the flushEntries method.

Also, note that search requests that return referrals are not cached.

The LDAPCache class includes methods for getting statistics (such as hit rates) from the cache and for flushing entries from the cache.

See Also:
LDAPConnection.setCache(netscape.ldap.LDAPCache), LDAPConnection.getCache(), Serialized Form

Field Summary
static java.lang.String DELIM
          Delimiter used internally when creating keys for the cache.
(package private) static long serialVersionUID
           
 
Constructor Summary
LDAPCache(long ttl, long size)
          Constructs a new LDAPCache object, using the specified maximum size of the cache (in bytes) and the maximum age of cached items (in seconds).
LDAPCache(long ttl, long size, java.lang.String[] dns)
          Constructs a new LDAPCache object, using the specified maximum size of the cache (in bytes), and the maximum age of cached items (in seconds), and an array of the base DNs of searches that you want to cache.
 
Method Summary
(package private)  boolean addEntry(java.lang.Long key, java.lang.Object value)
          Add the entry to the hashtable cache and to the vector respectively.
(package private)  void addReference()
          Add a new reference to this cache.
(package private)  void cleanup()
          Cleans up
(package private)  java.lang.Long createKey(java.lang.String host, int port, java.lang.String baseDN, java.lang.String filter, int scope, java.lang.String[] attrs, java.lang.String bindDN, LDAPConstraints cons)
          Create a key for a cache entry by concatenating all input parameters
(package private)  void flushEntries()
          Flush entries which stay longer or equal to the time-to-live.
 boolean flushEntries(java.lang.String dn, int scope)
          Flush the entries identified by DN and scope from the cache.
 long getAvailableSize()
          Gets the amount of available space (in bytes) left in the cache.
 java.lang.String[] getBaseDNs()
          Gets the array of base DNs of searches to be cached.
(package private)  java.lang.Object getEntry(java.lang.Long key)
          Gets the cache entry based on the specified key.
 int getNumEntries()
          Gets the number of entries being cached.
 long getNumFlushes()
          Gets the total number of entries that are flushed when timer expires and flushEntries is called.
 long getNumHits()
          Gets the total number of requests which successfully found and retrieved an item from the cache.
 long getNumMisses()
          Gets the total number of requests which failed to find and retrieve an item from the cache.
(package private)  int getRefCount()
          Get number of LDAPConnections that share this cache
 long getSize()
          Gets the maximum size of the cache (in bytes).
 long getTimeToLive()
          Gets the maximum age allowed for cached items (in seconds).
 long getTotalOperations()
          Gets the total number of requests for retrieving items from the cache.
(package private)  void removeReference()
          Remove a reference to this cache.
(package private)  void scheduleTTLTimer()
          Flush entries which stayed longer or equal to the time-to-live, and Set up the TTLTimer for the next flush.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

serialVersionUID

static final long serialVersionUID
See Also:
Constant Field Values

DELIM

public static final java.lang.String DELIM
Delimiter used internally when creating keys for the cache.

See Also:
Constant Field Values
Constructor Detail

LDAPCache

public LDAPCache(long ttl,
                 long size)
Constructs a new LDAPCache object, using the specified maximum size of the cache (in bytes) and the maximum age of cached items (in seconds). When items in the cache exceed this age, they are removed from the cache.

Parameters:
ttl - the maximum amount of time that an item can be cached (in seconds)
size - the maximum size of the cache (in bytes)

LDAPCache

public LDAPCache(long ttl,
                 long size,
                 java.lang.String[] dns)
Constructs a new LDAPCache object, using the specified maximum size of the cache (in bytes), and the maximum age of cached items (in seconds), and an array of the base DNs of searches that you want to cache. (For example, if the array of base DNs includes o=Airius.com, the cache stores search results if the base DN in the search request is o=Airius.com.)

Parameters:
ttl - the maximum amount of time that an item can be cached (in seconds)
size - the maximum size of the cache (in bytes)
dns - the list of base DNs of searches that you want to cache.
Method Detail

getSize

public long getSize()
Gets the maximum size of the cache (in bytes).

Returns:
the maximum size of the cache (in bytes).

getTimeToLive

public long getTimeToLive()
Gets the maximum age allowed for cached items (in seconds). (Items that exceed this age are removed from the cache.)

Returns:
the maximum age of items in the cache (in seconds).

getBaseDNs

public java.lang.String[] getBaseDNs()
Gets the array of base DNs of searches to be cached. (Search requests with these base DNs are cached.)

Returns:
the array of base DNs.

flushEntries

public boolean flushEntries(java.lang.String dn,
                            int scope)
Flush the entries identified by DN and scope from the cache.

Parameters:
dn - the distinguished name (or base DN) of the entries to be removed from the cache. Use this parameter in conjunction with scope to identify the entries that you want removed from the cache. If this parameter is null, the entire cache is flushed.
scope - the scope identifying the entries that you want removed from the cache. The value of this parameter can be one of the following:
  • LDAPv2.SCOPE_BASE (to remove the entry identified by dn)
  • LDAPv2.SCOPE_ONE (to remove the entries that have dn as their parent entry)
  • LDAPv2.SCOPE_SUB (to remove the entries in the subtree under dn in the directory)

Returns:
true if the entry is removed from the cache; false if the entry is not removed.

getAvailableSize

public long getAvailableSize()
Gets the amount of available space (in bytes) left in the cache.

Returns:
the available space (in bytes) in the cache.

getTotalOperations

public long getTotalOperations()
Gets the total number of requests for retrieving items from the cache. This includes both items successfully found in the cache and items not found in the cache.

Returns:
the total number of requests for retrieving items from the cache.

getNumMisses

public long getNumMisses()
Gets the total number of requests which failed to find and retrieve an item from the cache.

Returns:
the number of requests that did not find and retrieve an item in the cache.

getNumHits

public long getNumHits()
Gets the total number of requests which successfully found and retrieved an item from the cache.

Returns:
the number of requests that successfully found and retrieved an item from the cache.

getNumFlushes

public long getNumFlushes()
Gets the total number of entries that are flushed when timer expires and flushEntries is called.

Returns:
the total number of entries that are flushed when timer expires.

createKey

java.lang.Long createKey(java.lang.String host,
                         int port,
                         java.lang.String baseDN,
                         java.lang.String filter,
                         int scope,
                         java.lang.String[] attrs,
                         java.lang.String bindDN,
                         LDAPConstraints cons)
                   throws LDAPException
Create a key for a cache entry by concatenating all input parameters

Returns:
the key for a cache entry
Throws:
LDAPException - Thrown when failed to create key.

getEntry

java.lang.Object getEntry(java.lang.Long key)
Gets the cache entry based on the specified key.

Parameters:
key - the key for the cache entry
Returns:
the cache entry.

flushEntries

void flushEntries()
Flush entries which stay longer or equal to the time-to-live.


addEntry

boolean addEntry(java.lang.Long key,
                 java.lang.Object value)
Add the entry to the hashtable cache and to the vector respectively. The vector is used to keep track of the order of the entries being added.

Parameters:
key - the key for the cache entry
value - the cache entry being added to the cache for the specified key
Returns:
a flag indicating whether the entry was added.

scheduleTTLTimer

void scheduleTTLTimer()
Flush entries which stayed longer or equal to the time-to-live, and Set up the TTLTimer for the next flush. Called when first entry is added to the cache and when the TTLTimer expires.


getNumEntries

public int getNumEntries()
Gets the number of entries being cached.

Returns:
the number of entries being cached.

getRefCount

int getRefCount()
Get number of LDAPConnections that share this cache

Returns:
Reference Count

addReference

void addReference()
Add a new reference to this cache.


removeReference

void removeReference()
Remove a reference to this cache. If the reference count is 0, cleaup the cache.


cleanup

void cleanup()
Cleans up