Although achieving optimal Directory Server performance requires that the entire data set be fully cached, there may be deployments in which fully caching the data set is not possible due to hardware or financial constraints, or in which acceptable performance can be achieved by only caching a portion of the data. The Directory Server already provides support for controlling caching on a per-database basis (e.g., to cache only certain indexes and/or system databases), but these features may not provide sufficient control over how memory is used, particularly with regard to which entries are included in the cache, and they do not provide any degree of control over caching only a portion of attributes.
To better address the needs of environments that require partial caching, the Directory Server provides two new options: the ability to exclude certain entries
from the cache, and the ability to exclude certain attributes from the cache. The Directory Server uses an
uncached-id2entry database container, which is
similar to the
id2entry database that maps an entry's unique identifier and its
encoded representation. The
uncached-id2entry database contains either complete
and/or partial representations of entries that are intended to receive less memory for caching.
For example, if an entry has a particulary large attribute and the system has hardware
constraints on memory, then you can configure the system to not cache this particular attribute
or entry. This functionality is only available for the local DB backend, which uses the Berkeley
DB Java Edition database.
uncached-id2entry database can be included in the set of databases to
prime, but if priming is to be performed, it will only include internal nodes and not leaf nodes.
For example, the internal nodes of the
uncached-id2entry database will be
included in the preload if the
prime-all-indexes option is set to "true," or if
system-index-to-prime-internal-nodes-only option has a value of
Backup/Restore. There are no special considerations for backup and restore with regard to uncached entries and attributes. Backup will successfully save your database contents including uncached entries and attributes. Because of the way the server deals with changes to uncached entry and uncached attribute configuration, there is no problem with restoring a backup that was taken with a different uncached entry configuration than is currently in place for the server. Any entries encoded in a manner that is inconsistent with the current uncached entry or uncached attribute configuration will be properly re-encoded whenever they are updated, or whenever the re-encode entries task is invoked.
Replication. Replication does not propagate information about which portions of entries may have been cached or uncached, nor does it require that different replicas have the same uncached attribute or uncached entry configuration.
LDIF Import/Export. When LDIF content is imported into the server, the uncached
attribute and uncached entry configuration is used to determine on a per-entry basis whether some
or all of the content for that entry should be written into the
uncached-id2entry database. The determination is based on the current
configuration and is completely independent of and unaware of the configuration that may have
been in place when the LDIF data was initially exported. Neither the LDIF import nor export tools
provide any options that specifically target only cached or only uncached content, but these
tools do provide the ability to include or exclude entries using search filters, or to include or
exclude specific attributes.
Server Access Log. Server access log messages may include
uncachedDataAcessed=true in the result message for any operation in which it
was necessary to access uncached data in the course of processing the associated request. For
add, delete, modify, or modify DN result messages,
indicates that at least a portion of the new or updated entry was written into the
uncached-id2entry database, or that at least a portion of the updated entry was
formerly contained in the
uncached-id2entry database. For compare result
messages, it indicates that at least a portion of the target entry was contained in the
uncached-id2entry database and that data from the uncached portion of the entry
was required to evaluate the assertion. For search result messages, it indicates that one or more
of the entries evaluated as potential matches contained uncached data, and that data from the
uncached portion of at least one entry was needed in determining what data should be returned to
uncached-id2entry-cache-mode. Specifies the cache mode that is used when accessing
the records in the
uncached-id2entrydatabase. If the system has enough memory available to fully cache the internal nodes for this database, then
cache-keys-onlyis recommended, otherwise it is better to select
no-cachingto minimize the amount of memory required for interacting with the
uncached-id2entrydatabase. For more information, see the PingDirectory Server Configuration Reference.
uncached-attribute-criteria. Specifies the criteria used to identify attributes that
are written into the
uncached-id2entrydatabase, rather than the
id2entrydatabase. This property is only used for entries in which the associated
uncached-entry-criteriadoes not indicate that the entire entry should be uncached. The property applies to all entry writes, including add, soft delete, modify, and modify DN operations, as well as LDIF import and re-encode processing. Any changes to the property take effect immediately for writes occurring after the change is made. If no value is specified, then all attributes are written into the
uncached-entry-criteria. Specifies the criteria used to identify entries that are
written into the
uncached-id2entrydatabase, rather than the
id2entrydatabase. The property applies to all entry writes, including add, soft delete, modify, and modify DN operations, as well as LDIF import and re-encode processing. Any changes to the property take effect immediately for writes occurring after the change is made. If no value is specified, then all entries are written into the