Class LDAPCache
- All Implemented Interfaces:
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:
- 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.
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final String
Delimiter used internally when creating keys for the cache.A hashtable of search results.private static boolean
private String[]
private long
private long
private long
A list of cached entries ordered by time (augments m_cache).private int
private long
private TTLTimer
private long
private long
(package private) static final long
-
Constructor Summary
ConstructorsConstructorDescriptionLDAPCache
(long ttl, long size) Constructs a newLDAPCache
object, using the specified maximum size of the cache (in bytes) and the maximum age of cached items (in seconds).Constructs a newLDAPCache
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
Modifier and TypeMethodDescription(package private) boolean
Add the entry to the hashtable cache and to the vector respectively.(package private) void
Add a new reference to this cache.private String
appendString
(int num) Concatenates the specified integer with the delimiter.private String
appendString
(String str) Concatenates the specified integer with the delimiter.private String
appendString
(String[] str) Concatenate the specified string array with the delimiter.(package private) void
cleanup()
Cleans up(package private) Long
createKey
(String host, int port, String baseDN, String filter, int scope, String[] attrs, String bindDN, LDAPConstraints cons) Create a key for a cache entry by concatenating all input parameters(package private) void
Flush entries which stay longer or equal to the time-to-live.boolean
flushEntries
(String dn, int scope) Flush the entries identified by DN and scope from the cache.long
Gets the amount of available space (in bytes) left in the cache.String[]
Gets the array of base DNs of searches to be cached.private long
getCRC32
(byte[] barray) Create a 32 bits CRC from the given byte array.(package private) Object
Gets the cache entry based on the specified key.int
Gets the number of entries being cached.long
Gets the total number of entries that are flushed when timer expires andflushEntries
is called.long
Gets the total number of requests which successfully found and retrieved an item from the cache.long
Gets the total number of requests which failed to find and retrieve an item from the cache.(package private) int
Get number of LDAPConnections that share this cachelong
getSize()
Gets the maximum size of the cache (in bytes).long
Gets the maximum age allowed for cached items (in seconds).long
Gets the total number of requests for retrieving items from the cache.private void
init
(long ttl, long size) Initialize the instance variables.(package private) void
Remove a reference to this cache.(package private) void
Flush entries which stayed longer or equal to the time-to-live, and Set up the TTLTimer for the next flush.private void
sortStrings
(String[] str) Sorts the array of strings using bubble sort.
-
Field Details
-
serialVersionUID
static final long serialVersionUID- See Also:
-
m_cache
A hashtable of search results. The key is created from the search request parameters (see createKey() method). The value is a Vector where the first element is a Long integer representing the size of all entries, followed by the actual search result entries (of type LDAPEntry). -
m_orderedStruct
A list of cached entries ordered by time (augments m_cache). Each element in the list is a 2 element Vector where the element at index 0 is the key in the m_cache table, and the element at index 1 is the time when the entry was created. The list is used to track the time-to-live limit and to implement the FIFO algorithm when adding new entries; if the size of the new entry exceeds the cache available space, the extra space is made by removing existing cached results in the order of their entry in the cache. -
m_timeToLive
private long m_timeToLive -
m_maxSize
private long m_maxSize -
m_dns
-
m_remainingSize
private long m_remainingSize -
m_refCnt
private int m_refCnt -
DELIM
Delimiter used internally when creating keys for the cache.- See Also:
-
m_timer
-
m_totalOpers
private long m_totalOpers -
m_hits
private long m_hits -
m_flushes
private long m_flushes -
m_debug
private static boolean m_debug
-
-
Constructor Details
-
LDAPCache
public LDAPCache(long ttl, long size) Constructs a newLDAPCache
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
Constructs a newLDAPCache
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 includeso=Airius.com
, the cache stores search results if the base DN in the search request iso=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 Details
-
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
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
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 withscope
to identify the entries that you want removed from the cache. If this parameter isnull
, 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 bydn
)LDAPv2.SCOPE_ONE
(to remove the entries that havedn
as their parent entry)LDAPv2.SCOPE_SUB
(to remove the entries in the subtree underdn
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 andflushEntries
is called.- Returns:
- the total number of entries that are flushed when timer expires.
-
createKey
Long createKey(String host, int port, String baseDN, String filter, int scope, String[] attrs, 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
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
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 entryvalue
- 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 -
init
private void init(long ttl, long size) Initialize the instance variables. -
appendString
Concatenates the specified integer with the delimiter.- Parameters:
str
- the String to concatenate with the delimiter- Returns:
- the concatenated string.
-
appendString
Concatenates the specified integer with the delimiter.- Parameters:
num
- the integer to concatenate with the delimiter- Returns:
- the concatenated string.
-
appendString
Concatenate the specified string array with the delimiter.- Parameters:
str
- a string array- Returns:
- the concatenated string.
-
sortStrings
Sorts the array of strings using bubble sort.- Parameters:
str
- the array of strings to sort. The str parameter contains the sorted result.
-
getCRC32
private long getCRC32(byte[] barray) Create a 32 bits CRC from the given byte array.
-