4 Managing the Cache

Oracle Identity Manager uses two types of caching: global and ThreadLocal.

The global cache stores information globally. Any part of the system can access information that is stored in this cache. The global cache uses OSCache from OpenSymphony. One advantage of using OSCache is its support for cluster environments. Database queries are usually stored in the global cache so that repeated queries are not run against the database again.

The ThreadLocal cache stores information that is used multiple times in a single transaction. For example, a query that is issued many times during a transaction uses data from the ThreadLocal cache. The data used for this query does not change for the transaction.

Oracle Identity Manager allows caching by category. You can enable and disable caching for specific entities and configure separate expiration times.

This chapter discusses the following topics:

Sample Cache Configuration
General Cache Configuration Properties
Category-Based Cache Configuration Properties
Class Reloading
Purging the Cache
Optimal Cache Configuration for a Production Environment

Sample Cache Configuration

Example 4-1 is a snippet from the Cache section in the xlconfig.xml file:

Example 4-1 xlconfig.xml Snippet

<Cache>
  <Enable>false</Enable>
  <ThreadLocalCacheEnabled>false</ThreadLocalCacheEnabled>
  <ExpireTime>14400</ExpireTime>

  <CacheProvider>com.thortech.xl.cache.OSCacheProvider</CacheProvider>
  <XLCacheProvider>
    <Size>5000</Size>
    <MultiCastAddress>231.121.212.133</MultiCastAddress>
  </XLCacheProvider>

  <!-- Individual cache categories -->

  <!-- Adapters and event handlers to be executed on update/insert/delete -->
  <DataObjectEventHandlers>
    <Enable>false</Enable>
    <ExpireTime>14400</ExpireTime>
  </DataObjectEventHandlers>
 
...
...
...
</Cache>

Note:

Oracle recommends that you disable caching in development environments. Data in development environments changes frequently. If cached data is not refreshed in time, it can cause problems for developers working with the product.

General Cache Configuration Properties

The Cache tag refers to the cache configuration and what is contained between the beginning and the end Cache tag. Table 4-1 describes the entries in the Cache section:

Table 4-1 Cache Configuration Parameters

Property	Description
`Enable`	This property enables components in the cache configuration for categories that are not explicitly defined in the configuration file. If the configuration file does not contain a particular category, the cache uses this entry to enable or disable the category.
`ThreadLocalCacheEnabled`	This property enables or disables ThreadLocal caching.
`ExpireTime`	This property specifies a default expiration time for components in the cache configuration.
`CacheProvider`	This is the complete class path of the provider used for caching. Do not change this property.
`XLCacheProvider`	This section specifies cache provider properties. In Example 4-1, the `Size` and `Multicast Address` properties are specified.
`XLCacheProvider - Size`	This property specifies the size of the cache. This number reflects the number of items that the cache stores. If the size is reached, new items are stored in the cache while the least used are pushed out of the cache.
`XLCacheProvider` - `MultiCastAddress`	The IP address used for multicast communication among all of Oracle Identity Manager components.

Note:

The same MultiCast Address must be used for all Oracle Identity Manager installations in an environment, for example, for all the nodes in a cluster. Cache flushes are propagated to all installations using MultiCast IP. If multicasting is disabled, cache flush is not possible.

Category-Based Cache Configuration Properties

After you preform general cache configuration, each component or category is shown with its own tag name. The tag name reflects a category name that is used in the code to store information in the cache. You can enable or disable each category independently of other categories, and you can set the expiration time for each component or category.

Table 4-2 lists the categories in the cache configuration file. By default, all the categories are disabled in the cache configuration file unless otherwise mentioned in Table 4-2.

Table 4-2 Category Based Cache Configuration Parameters

Category Name	Description
`DataObjectEventHandlers`	List of event handlers to be run when data object changes occur. This is the location where custom event handler and entity adapters are attached to a data object.
`ProcessDefinition`	Process definition information, for example process attributes, tasks, task mappings, and so on.
`RuleDefinition`	Rule definition information.
`FormDefinition`	Form definition information.
`ColumnMap`	DB column name from a column code. This is enabled by default.
`UserDefinedColumns`	User Defined Form and column definitions
`ObjectDefinition`	Object definition information.
`StoredProcAPI`	Used to stored total counts when calling APIs with paging capability. Because information changes frequently, the default expiration time for this category is 10 minutes.
`NoNeedToFlush`	This category defines data that does not need to be flushed and does not fall into a particular category. This category does not have an expiration time. This information is typically populated during initial database setup and never changes in an installation.
`MetaData`	DB field metadata information. This is category is enabled by default.
`AdapterInformation`	Adapter variables, compilation status and so on.
`OrgnizationName`	Cache organization names.
`Reconciliation`	Reconciliation rules.
`SystemProperties`	Caches system properties.
`LookupDefinition`	Caches the conversions between lookup names and fields.
`UserGroups`	Caches user groups.
`LookupValues`	Caches the lookup values for a given lookup name.
`ITResourceKey`	IT Resources DB key cache.
`ServerProperties`	Caches what data is to be encrypted along with System Properties
`ColumnMetaData`	Database metadata information for common queries.
`CustomResourceBundle`	Caches custom resource bundle.
`CustomDefaultBundle`	Caches custom default bundle.
`ConnectorResourceBundle`	Caches connector resource bundles

Class Reloading

Class reloading refers to automatically reloading classes without restarting the server. Class reloading settings are useful for scheduled tasks and adapter-related files. Oracle recommends that you enable reloading in development environments. You must restart the Oracle Identity Manager server if cache reloading is disabled and any new adapters are imported, existing adapters are changed, or any .jar files are modified.

Note:

Oracle recommends that you disable class reloading in production environments to improve performance.

The class reloading configuration information is included in the xlconfig.xml file as follows:

<ClassLoading>
  <ReloadEnabled>true</ReloadEnabled>
  <ReloadInterval>15</ReloadInterval>
  <LoadingStyle>ParentFirst</LoadingStyle>
</ClassLoading>

ReloadEnabled enables class reloading on regular basis.
ReloadInterval specifies the time to reload (in seconds).
LoadingStyle specifies the type of loading used.

The following are the different types of loading:
- ParentFirst looks for the classes in the parent before loading them from the jar files in ADPClassLoader classpath.
- ParentLast overrides the classes from the parent. Using ParentLast may cause ClassCastExceptions.
- ParentLoader is the ThreadContext Class Loader.

Purging the Cache

If you want to purge the cache before the allocated amount of time, use the PurgeCache utility in the XL_HOME/bin directory. This utility purges all elements in the cache.

Depending on the platform, the PurgeCache utility is a batch file or a shell script. After you edit the XEL_HOME and JAVA_HOME environment variables to point to the correct location, you can run the PurgeCache from the command line.

To use the PurgeCache utility, run PurgeCache.bat category name on Windows systems or PurgeCache.sh category name on UNIX/Linux systems. The category name argument represents the name of the category that needs to be purged. For example, the following commands purge all FormDefinition entries from a system and its clusters:

PurgeCache.bat FormDefinition
PurgeCache.sh FormDefinition

To purge all Oracle Identity Manager categories, pass a value of "ALL" to the PurgeCache utility.

Note:

The category name argument of the PurgeCache utility is case sensitive.
A java.lang.NullPointerException is thrown after running this script. However, this exception does not prevent data from being purged.

Optimal Cache Configuration for a Production Environment

Post-deployment changes to the cache configuration may affect performance and usage. Configure your cache using utmost caution.

The following are guidelines for configuring the Oracle Identity Manager cache for a production environment:

Set all properties to true, except for the <StoredProcAPI> setting.

Increase the <XLCacheProvider> size to 15000 (default value is 5000).

Example 4-2 shows the recommended values for the Oracle Identity Manager cache configuration file (xlconfig.xml) in a production environment.

Example 4-2 Recommended Cache Values for xlconfig.xml in a Production Environment

<Cache>
  <Enable>true</Enable>
  <ThreadLocalCacheEnabled>true</ThreadLocalCacheEnabled>
  <ExpireTime>14400</ExpireTime>
  <CacheProvider>com.thortech.xl.cache.OSCacheProvider</CacheProvider>
  <XLCacheProvider>
    <Size>15000</Size>
    <MultiCastAddress>231.172.169.176</MultiCastAddress>
  </XLCacheProvider>
 
<!-- Individual cache categories -->
<!-- Adapters and event handlers to be executed on update/insert/delete -->
  <DataObjectEventHandlers>
    <Enable>true</Enable>
    <ExpireTime>14400</ExpireTime>
  </DataObjectEventHandlers>
  <ProcessDefinition>
    <Enable>true</Enable>
    <ExpireTime>14400</ExpireTime>
  </ProcessDefinition>
  <RuleDefinition>
    <Enable>true</Enable>
    <ExpireTime>14400</ExpireTime>
  </RuleDefinition>
  <FormDefinition>
    <Enable>true</Enable>
    <ExpireTime>14400</ExpireTime>
  </FormDefinition>
  <ColumnMap>
    <Enable>true</Enable>
    <ExpireTime>14400</ExpireTime>
  </ColumnMap>
  <UserDefinedColumns>
    <Enable>true</Enable>
    <ExpireTime>14400</ExpireTime>
  </UserDefinedColumns>
  <ObjectDefinition>
    <Enable>true</Enable>
    <ExpireTime>14400</ExpireTime>
  </ObjectDefinition>
  <StoredProcAPI>
    <Enable>false</Enable>
    <ExpireTime>600</ExpireTime>
  </StoredProcAPI>
 
<!-- This information never needs to flushed out. For example, key for requests organization and so on. -->
 
  <NoNeedToFlush>
    <Enable>true</Enable>
    <ExpireTime>-1</ExpireTime>
  </NoNeedToFlush>
 
<!-- Metadata Information -->
  <MetaData>
    <Enable>true</Enable>
    <ExpireTime>14400</ExpireTime>
  </MetaData>
 
<!-- Adapter Mapping Information -->
  <AdapterInformation>
    <Enable>true</Enable>
    <ExpireTime>14400</ExpireTime>
  </AdapterInformation>
 
<!-- Name of the organization for a given key and vice versa -->
  <OrgnizationName>
    <Enable>true</Enable>
    <ExpireTime>14400</ExpireTime>
  </OrgnizationName>
 
<!-- Reconciliation rules -->
  <Reconciliation>
    <Enable>true</Enable>
    <ExpireTime>14400</ExpireTime>
  </Reconciliation>
 
<!-- System Properties -->
  <SystemProperties>
    <Enable>true</Enable>
    <ExpireTime>14400</ExpireTime>
  </SystemProperties>
  <LookupDefinition>
    <Enable>true</Enable>
    <ExpireTime>14400</ExpireTime>
  </LookupDefinition>
  <UserGroups>
    <Enable>true</Enable>
    <ExpireTime>14400</ExpireTime>
  </UserGroups>
  <LookupValues>
    <Enable>true</Enable>
    <ExpireTime>14400</ExpireTime>
  </LookupValues>
  <ITResourceKey>
    <Enable>true</Enable>
    <ExpireTime>14400</ExpireTime>
  </ITResourceKey>
  <RecordExists>
    <Enable>true</Enable>
    <ExpireTime>14400</ExpireTime>
  </RecordExists>
  <ServerProperties>
    <Enable>true</Enable>
    <ExpireTime>14400</ExpireTime>
  </ServerProperties>
 
<!-- Column Meta Data -->
  <ColumnMetaData>
    <Enable>true</Enable>
    <ExpireTime>14400</ExpireTime>
  </ColumnMetaData>
  <CustomResourceBundle>
    <Enable>true</Enable>
    <ExpireTime>-1</ExpireTime>
  </CustomResourceBundle>
  <CustomDefaultBundle>
    <Enable>true</Enable>
    <ExpireTime>-1</ExpireTime>
  </CustomDefaultBundle>  
  <ConnectorResourceBundle>
    <Enable>true</Enable>
    <ExpireTime>-1</ExpireTime>
  </ConnectorResourceBundle>  
</Cache>