Documentum cache

This chapter describes the caches maintained on a global and session level for sessions. It also describes the optional persistent client caching feature.

   I.        Object type caching

Content Server and DFC maintain caches of object type definitions. These caches help to ensure fast response times when users access objects. To ensure that the cached information about an object type is accurate, DFC and Content Server have mechanisms to verify the accuracy of a cached object type definition and update it if necessary. The mechanism varies depending on the object types.

1) For object types with names beginning with dm, dmr, and dmi

These object types are the types that are built‑in in a Content Server installation. Their type definitions are relatively static. There are few changes that can be made to the definition of a built‑in type. For these types, the mechanism is an internal process called Change Checker, that periodically checks all the object type definitions in the Content Server’s global cache. If any are found to be out‑of‑date, the process flushes the cache and reloads the type definitions into the global cache. Changes to these types are not visible to existing sessions because the DFC caches are not updated when the change checker refreshes the global cache.

Stopping and restarting a session makes any changes in the global cache visible. If the session was a web‑based client session, it is necessary to restart the web application server. The interval at which the Change Checker runs is configurable, by changing the setting of the database_refresh_interval in the server.ini file, which default value is 1 minute.

2) For custom object types and types with names beginning with dmc

These object types are installed with DAR files or scripts to support client applications.

Their type definitions typically change more often, and the changes may need to be visible to users immediately. For example, a Collaboration Services user can change the structure of a datatable often, and each change modifies the underlying type definition.

To meet that requirement, the mechanism that refreshes cached type definitions for these types is more dynamic than that for the built‑in types.

For these types, the DFC shared cache is updated regularly, at intervals defined by the dfc.cache.type.currency_check_interval key in the dfc.properties file. That key defaults to

300 seconds (5 minutes). It can be reset. Use Documentum Administrator to reset the key.

Additionally, when requested in a fetch method, DFC checks the currency of its cached version against the server’s global cache. If the versions in the caches are found to be mismatched, the object type definition is updated appropriately. If the server’s cache is more current, the DFC caches are updated. If the DFC has a more current version, the server’s cache is updated.

This mechanism ensures that a user who makes the change sees that change immediately and other users in other sessions see it shortly thereafter. Stopping and restarting a session or the web application server is not required to see changes made to these objects.

 

II.        Repository session caches

Repository session caches are caches that are created when a user or application opens a repository session. These caches exist only for the life of the repository session.

1) Object cache

An in‑memory object cache is maintained for each repository session for the duration of the repository session. If persistent caching is requested and enabled, the cache also contains a copy of every object fetched and persistently cached in previous sessions.

2) Query cache

Query results are only cached when persistent caching is requested and persistent caching is enabled. The results are cached in a file. They are not stored in memory. The file is stored with a randomly generated extension on the client application host disk

3) Data dictionary caches

In conjunction with the object cache, DFC maintains a data dictionary cache. The data dictionary cache is a shared cache, shared by all sessions in a multi‑threaded application.

When an object is fetched, the DFC also fetches and caches in memory the object’s associated data dictionary objects if they are not already in the cache.

 

III.        Persistent caching

This section describes persistent caching, a feature supported by the DFC and Content Server, that provides performance benefits during session start up and when users or applications access cached objects and query results.

1) What persistent caching is

Persistent caching is the ability to create, manage, and maintain persistent caches of query results, objects, and the type and data dictionary information associated with persistently cached objects. Persistent caches are maintained across client sessions for each user and repository combination. Persistent caches are implemented through DFC and supported by Content Server.

The ability to cache objects and query results is enabled by default for every repository and every client session. Documentum Webtop takes advantage of this feature.

Applications can take advantage of the feature through the DFC methods that support requests for persistent client caching.

Consistency between the repository and cached objects and query results is checked and maintained using a consistency check rule identified in the method call that references them. A consistency checking rule can be applied to individual objects or query results or a rule can be defined for a set of cached data.

2) Persistent object cache storage location

Persistently cached objects are written to a file on the client disk. For a desktop application, this is the user’s local disk. For a web‑based application, this is the web application server’s disk. The file is written after defined intervals during a user’s session and when the session terminates. The file is stored in the following directory:

root/object_caches/machine_name/repository_id/abbreviated_user_name

 root is the value of the dfc.data.local_dir key in the client’s dfc.properties file.

The next time the user starts a session with the repository on the same machine, the file is loaded back into memory.

3) Persistent object type and data dictionary storage location

For each persistently cached object, a persistent cache of its object type definition and data dictionary information is also maintained. These are stored in a file located in the following directory:

root/type_caches/machine_name/repository_id

 root is the value in the dfc.data.local_dir key in the client’s dfc.properties file.

4) Query cache storage location

The file that contains the cached query results is stored with a randomly generated extension on the client disk. For a desktop application, this is the user’s local disk. For a web‑based application, this is the web application server’s disk. The files are in the following directory:

On Windows:

\root\qrycache\machine_name\repository_id\user_name

On UNIX:

/root/qrycache/machine_name/repository_id/user_name

 root is the value in the dfc.data.local_dir key in the client’s dfc.properties file.

The query cache files for each user consist of a cache.map file and files with randomly generated extensions. The cache.map file maps each cached query to the file that contains

the results of the query (one of the files with the randomly generated extensions).

The queries are cached by user name because access permissions may generate different

results for different users.

Note: The cache.map file and the cached results files are stored in ASCII format. They are accessible and readable through the operating system. If security is an issue, make sure that the directory in which they are stored is truly local to each client, not on a shared disk.

5) Using persistent client caching in an application

Some Documentum clients use persistent client caching by default. If you want to use it in your applications, you must:

1>Ensure that persistent client caching is enabled

Persistent client caching is enabled at the repository and session levels by default.

At the client session level, this is controlled by the dfc.cache.enable_persistence key in dfc.properties.

2>Identify the objects or queries or both that you want to cache

You identify the data to cache in application methods that fetch the objects or execute the query.

3>Define the consistency check rule for cached data

A consistency check rule defines how often cached data is checked for consistency with the repository. The methods that support persistent client caching support a variety of rule options through a method argument.

 

 

 

 

Fetch

Query

 

 

 

 

   I.        Persistent caching and multiple sessions for one user

In federated environments or any distributed environment that has multiple repositories, users can work in multiple repositories through one primary client session. For the purposes of persistent caching, each connection to a different repository is treated as a separate session. For example, suppose JohnDoe opens a session with repository A and fetches a persistently cached document. Then, the user also fetches a persistently cached document from repository B. On termination, the DFC writes two persistent object caches:

root/object_caches/machine_name/repositoryA/JohnDoe

and

root/object_caches/machine_name/repositoryB/JohnDoe

Similarly, if the user queries either repository and caches the results, DFC creates a query cache file specific to the queried repository and user.

 

 

II.        Currency checking

Currency checking, the functionality that is used to ensure that objects in the persistent cache are not out of date.

Consistency checking

Consistency checking is the process that ensures that cached data accessed by a client is current and consistent with the data in the repository. How often the process is performed for any particular cached object or set of query results is determined by the consistency check rule defined in the method that references the data.

The consistency check rule can be a keyword, an integer value, or the name of a cache

config object. A keyword or integer value is an explicit directive to DFC that tells DFC

how often to conduct the check. A cache config object identifies the data to be cached as

part of a set of cached data managed by the consistency check rule defined in the cache config object. The data defined by a cache config object can be objects or queries or both.

Using a cache config object to group cached data has the following benefits:

• More efficient validation of cached data

It is more efficient to validate a group of data than it is to validate each object or set

of query results individually.

• Helps ensure that applications access current data

• Makes it easy to change the consistency check rule because the rule is defined in the cache config object rather than in application method calls

• Allows you to define a job to automatically validate cached data

Consistency checking is basically a two‑part process:

1. DFC determines whether a consistency check is necessary.

2. DFC conducts the consistency check if needed.

The consistency checking process described in this section is applied to all objects in the in‑memory cache, regardless of whether the object is persistently cached or not.

 

Determining if a consistency check is needed

To determine whether a check is needed, the DFC uses the consistency check rule defined

in the method that references the data. The rule may be expressed as either a keyword,

an integer value, or the name of a cache config object.

When a keyword or integer defines the rule

If the rule was specified as a keyword or an integer value, DFC interprets the rule as a

directive on when to perform a consistency check. The directive is one of the following:

• Perform a check every time the data is accessed

This option means that the data is always checked against the repository. If the cached data is an object, the object is always checked against the object in the repository. If the cached data is a set of query results, the results are always regenerated. The keyword check_always defines this option.

• Never perform a consistency check

This option directs the DFC to always use the cached data. The cached data is never checked against the repository if it is present in the cache. If the data is not present in the cache, the data is obtained from the server. The keyword check_never defines this option.

• Perform a consistency check on the first access only

This option directs the DFC to perform a consistency check the first time the cached data is accessed in a session. If the data is accessed again during the session, a consistency check is not conducted. The keyword check_first_access defines this option.

• Perform a consistency check after a specified time interval

This option directs the DFC to compare the specified interval to the timestamp on the cached data and perform a consistency check only if the interval has expired.

The timestamp on the cached data is set when the data is placed in the cache. The interval is expressed in seconds and can be any value greater than 0.

 

When a cache config object defines the rule

If a consistency check rule names a cache config object, the DFC uses information from the cache config object to determine whether to perform a consistency check on the cached data. The cache config information is obtained by invoking the CHECK_CACHE_CONFIG administration method and stored in memory with a timestamp that indicates when the information was obtained. The information includes the r_last_changed_date and the client_check_interval property values of the cache config object.

When a method defines a consistency check rule by naming a cache config object, DFC first checks whether it has information about the cache config object in its memory.

If not, it issues a CHECK_CACHE_CONFIG administration method to obtain the information. If it has information about the cache config object, DFC must determine whether the information is current before using that information to decide whether to perform a consistency check on the cached data.

To determine whether the cache config information is current, the DFC compares the stored client_check_interval value to the timestamp on the information. If the interval has expired, the information is considered out of date and DFC executes another CHECK_CACHE_CONFIG method to ask Content Server to provide current information about the cache config object. If the interval has not expired, DFC uses the information that it has in memory.

After the DFC has current information about the cache config object, it determines whether the cached data is valid. To determine that, the DFC compares the timestamp on the cached data against the r_last_changed_date property value in the cache config object. If the timestamp is later than the r_last_changed_date value, the cached data is considered usable and no consistency check is performed. If the timestamp is earlier than the r_last_changed_date value, a consistency check is performed on the data.

 

Conducting consistency checks

To perform a consistency check on a cached object, DFC uses the i_vstamp property value of the object. If the DFC has determined that a consistency check is needed, it compares the i_vstamp value of the cached object to the i_vstamp value of the object in the repository. If the i_vstamp values are different, DFC refetches the object and resets the time stamp. If they are the same, DFC uses the cached copy.

DFC does not perform consistency checks on cached query results. If the cached results are out of date, Content Server re‑executes the query and replaces the cached results with the newly generated results.

The default consistency check rule

If a fetch method does not include an explicit value for the argument defining a consistency check rule, the default is check_always. That means that DFC checks the i_vstamp value of the in‑memory object against the i_vstamp value of the object in the repository.

If a query method that requests persistent caching does not include an explicit value for the argument defining a consistency check rule, the default consistency rule is check_never. This means that DFC uses the cached query results.

 

The client_pcaching_change property

The client_pcaching_change property controls whether the persistent caches, including the object caches and all query caches, are flushed when a client session is started. When a client session is started, the DFC checks the cached value of the client_pcaching_change property against the repository value. If the values are different, the DFC flushes all the persistent caches, including the object caches and all query caches.

The client_pcaching_change value must be changed in the docbase config object manually, by a Superuser.