5 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

5.1 Sample Cache Configuration

This section contains a sample code block from the Cache section in the xlconfig.xml file, as shown in Example 5-1. The code contains the general configuration properties available in the xlconfig.xml file.

Example 5-1 Cache Section in the xlconfig.xml File

<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.

5.2 General Cache Configuration Properties

The Cache tag in the xlconfig.xml file refers to the cache configuration and what is contained between the beginning and the end Cache tags. Table 5-1 describes the general cache configuration properties listed in Example 5-1.

Table 5-1 Cache Configuration Properties

Property	Description
`Enable`	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, then the cache uses this entry to enable or disable the category.
`ThreadLocalCacheEnabled`	Enables or disables ThreadLocal caching.
`ExpireTime`	Specifies a default expiration time (in seconds) for components in the cache configuration.
`CacheProvider`	Identifies the complete class path of the provider used for caching. Do not change this property.
`XLCacheProvider`	Specifies cache provider properties. In Example 5-1, the `Size` and `Multicast Address` properties are specified.
`XLCacheProvider - Size`	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`	Used for multicast communication among all of the 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 nodes in a cluster. Cache flushes are propagated to all installations by using the MultiCast IP. If multicasting is disabled, then cache flush is not possible.

5.3 Category-Based Cache Configuration Properties

After you perform 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 5-2 lists the categories in the cache configuration file. By default, all categories are disabled in the cache configuration file unless otherwise mentioned in Table 5-2.

Table 5-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 handlers and entity adapters are attached to a data object.
`ProcessDefinition`	Process definition information, for example process attributes, tasks, and task mappings.
`RuleDefinition`	Rule definition information.
`FormDefinition`	Form definition information.
`ColumnMap`	DB column name from a column code. This is enabled by default. Note: This category is enabled by default.
`UserDefinedColumns`	User-defined form and column definitions
`ObjectDefinition`	Object definition information.
`StoredProcAPI`	Used to stored total counts when calling Apes with paging capability. Because information changes frequently, the default expiration time for this category is 600 seconds.
`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. Note: This 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 the custom resource bundle.
`CustomDefaultBundle`	Caches the custom default bundle.
`ConnectorResourceBundle`	Caches connector resource bundles
`EmailDefinition`	Caches e-mail definition information
`LinguisticSort`	Caches database sort parameters
`RecordExists`	Caches user keys
`GenericConnector`	Caches pertinent data about a particular Generic Technology Connector instance
`GenericConnectorProviders`	Caches the provider parameter values associated with a particular Generic Technology Connector instance

5.4 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 disable class reloading in production environments for better performance. 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.

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, when set to true, 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:
- With parentFirst mode , first preference is given to classes placed in System Classpath, Oracle Identity Manager Application Classpath, and then the ADP Classpath. This is the Oracle recommended option.
- With ParentLast mode, first preference is given to classes placed in ADP Classpath, System classpath, and then Oracle Identity Manager Application Classpath. This is deprecated option and must not be used because it might cause ClassCastExceptions.
Note:
ADP Classpath = JavaTasks, ScheduleTasks, EventHandlers and ThirdParty directories are in the OIM_HOME directory.

5.5 Purging the Cache

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

To use the PurgeCache utility, run PurgeCache.bat category name on Microsoft Windows systems or PurgeCache.sh category name on Linux and UNIX systems. The category name argument represents the name of the category that must 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 this script is run. However, this exception does not prevent data from being purged.

5.6 Optimal Cache Configuration for a Production Environment

Postdeployment changes to the cache configuration may affect performance and usage. Configure your cache with 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 5-2 shows the recommended values for the Oracle Identity Manager cache configuration file (xlconfig.xml) in a production environment.

Example 5-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 must not be flushed out. For example, key for requests organization. -->
 
  <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>  
  <LinguisticSort>
      <Enable>true</Enable>
      <ExpireTime>-1</ExpireTime>
  </LinguisticSort>
  <GenericConnector>
      <Enable>true</Enable>
      <ExpireTime>-1</ExpireTime>
  </GenericConnector>
  <GenericConnectorProviders>
      <Enable>true</Enable>
      <ExpireTime>-1</ExpireTime>
  </GenericConnectorProviders>
</Cache>