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:
- the host name and port number of the LDAP server
- the base DN of the search
- the search filter
- the scope of the search
- the attributes to be returned in the search results
- the DN used to authenticate the client when binding
to the server
- the LDAP v3 controls specified in the search request
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.
flushEntries
public boolean flushEntries(String dn,
int scope)
Flush the entries identified by DN and scope from the cache.
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)
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.
- the available space (in bytes) in the cache.
getBaseDNs
public String[] getBaseDNs()
Gets the array of base DNs of searches to be cached.
(Search requests with these base DNs are cached.)
getNumEntries
public int getNumEntries()
Gets the number of entries being cached.
- the number of entries being cached.
getNumFlushes
public long getNumFlushes()
Gets the total number of entries that are flushed when timer expires
and
flushEntries
is called.
- the total number of entries that are flushed when timer
expires.
getNumHits
public long getNumHits()
Gets the total number of requests which successfully found and
retrieved an item from the cache.
- the number of requests that successfully found and
retrieved an item from the cache.
getNumMisses
public long getNumMisses()
Gets the total number of requests which failed to find and
retrieve an item from the cache.
- the number of requests that did not find and retrieve
an item in the cache.
getSize
public long getSize()
Gets the maximum size of the cache (in bytes).
- 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.)
- the maximum age of items in the cache (in
seconds).
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.
- the total number of requests for retrieving items from
the cache.