73 Cache Management for Personalization

This chapter discusses cache management for Oracle WebCenter Personalization.

This chapter includes the following topics:

73.1 Introduction to Cache Management for Personalization

WebCenter Portal uses Oracle Coherence to manage server-side caching for personalization features. A local Coherence license is provided with all WebCenter installations. Personalization supports other more complex modes of Coherence use, although appropriate Coherence licenses must be purchased for those cases.

This chapter explains how to use caching with WebCenter Portal personalization features, like scenarios and data providers.

Note:

It is assumed that you have a basic understanding of caching concepts and techniques. In general, no attempt will be made in this chapter to explain these concepts. It is also assumed that you are familiar with Oracle Coherence. To learn about Coherence, see Getting Started with Oracle Coherence.

It is also assumed that you are familiar with the WebCenter Portal personalization concepts and features described in Chapter 66, "Personalizing Oracle WebCenter Portal Applications."

73.2 Locating and Updating Cache Configuration Files

WebCenter Portal provides two Coherence cache configuration files for use with personalization. The use of these files is described in this section.

Note:

All cache factories instantiated by WebCenter Personalization Server (WCPS) are specific to the WCPS classloader.

73.2.1 Where are the Cache Configuration Files Located?

Cache configuration files are located in:

$ORACLE_HOME/user_projects/applications/<domain>/conductor-extensions-library/WEB-INF/classes

If you create any custom cache configuration files, the best practice is to place them in this same directory. On the other hand, you can place them in any location that is in the WCPS web application classpath. You need to redeploy the WCPS web application or restart the server for the new class to be recognized. See also Section 73.2.2.3, "Creating Custom Cache Configuration Files."

73.2.2 Using the Cache Configuration Files

This section discusses each of the cache configuration files used by personalization features and the creation of custom cache configuration files.

73.2.2.1 Internal Cache Configuration File

The cache configuration file wcps-coherence-cache-config.xml supports internal integration components like the Property Service, Conductor, and the core data provider functionality.

Note:

Do not change the names of the caches in this configuration file. You can, however, change the cache configuration parameters in the file.

73.2.2.2 Data Provider Cache File

The cache configuration file wcps-dataprovider-cache-config.xml addresses caching associated with data providers. This file uses the wildcard pattern so that clients can have their specific caches, either by using a pattern like wcps-dp-small-content or my-custom-cache. For example, a wildcard pattern such as wcps-dp-medium-* will resolved when specifying cache names such as wcps-dp-small-content or wcps-dp-small-ebs.

The out-of-the-box data provider configurations may be modified to suit your needs, or you may add new entries to support your custom data providers. Please note that any changes to existing out-of-the-box configurations may affect other custom data providers deployed to your environment.

Default data provider cache configurations include the following:

  • Local cache implemented in memory

  • LRU eviction policy

  • Small: 100 entries, default TTL of 1 hour

  • Medium: 1000 entries, default TTL of 1 hour

  • Large: 10000 entries, default TTL of 1 hour

    Note:

    These configurations may be changed to support upgraded Coherence license features.

This cache configuration file takes advantage of Coherence parameter macros and can easily be modified to fit specific needs. Links to Coherence documentation specific to the parameters are provided in the configuration file itself.

Clients can configure additional entries in this configuration file. Those entries will be available to the personalization cache APIs. See Section 73.3, "Using Caching with Personalization Components."

73.2.2.3 Creating Custom Cache Configuration Files

You can create custom Coherence cache configuration files to address specific use cases. Oracle recommends that all Coherence cache configuration files adhere to these general rules:

Note:

In reality, cache configuration files can be placed wherever they are visible to the WCPS web application classloader; placing it in the above directory keeps it consistent with other WCPS cache configuration files. However, there may be times when you wish to define and package your cache configuration file differently.

You can package cache configuration files as part of the data provider's JAR file, or anywhere on the file system, because the CoherenceCacheFactory loads files using a URI. CoherenceCacheFactory is used programmatically by data providers or any other class deployed to the WCPS server. See Section 73.3.2, "Using CoherenceCacheFactory."

Note:

Data provider JAR files are located in:

$DOMAIN_HOME/conductor-extensions-library/WEB-INF/lib.

See Chapter 67, "Implementing Custom Data Providers: Introduction" for more information on packaging and deploying data providers.

You must redeploy the WCPS web application or restart the server for the new classes to be recognized.

73.3 Using Caching with Personalization Components

Personalization components like data and function providers, and custom data providers, interact with Coherence in one of two ways, depending on the context.

  • CacheFunctionProvider – Includes methods that can be used within the context of a scenario or used programmatically by any data provider. Function providers perform operations on data within the context of a scenario. See also Section 68.1, "Introduction to Function Providers."

  • CoherenceCacheFactory – Data providers and other classes deployed to the WCPS use this factory class to implement caching programmatically.

73.3.1 The Cache Function Provider

The CacheFunctionProvider provides methods for managing caches from within a scenario. This function provider delegates to the CoherenceCacheFactory class and includes several convenience methods.

The methods of the Cache Function Provider are described in "Cache Methods" in Chapter 69, "Function Provider Reference."

The prefix for the CacheFunctionProvider is cache (the name that appears in the Expression Builder dialogs in the scenario editor). Figure 73-1 shows the cache function provider in the Expression Builder dialog.

Figure 73-1 The Cache Function Provider

Description of Figure 73-1 follows
Description of ''Figure 73-1 The Cache Function Provider''

Example 73-1 lists the XML structure of a scenario that uses the Cache Function Provider method getMediumCache(). First, a cache is returned and stored in a variable. Then, that variable is used to return a specific value from the cache.

Example 73-1 Using the Cache Function Provider in a Scenario

<!-- Check cache first, using CacheFunctionProvider -->
        <assign-variable>
            <variable>userIdCache</variable>
            <expression>${cache:getMediumCache('userIdCache')}</expression>
        </assign-variable>
 
        <assign-variable>
            <variable>userId</variable>
            <expression>${cache:get(userIdCache,username)}</expression>
        </assign-variable>

Example 73-2 shows how the CacheFunctionProvider methods can be called programmatically. Be sure to import: oracle.wcps.dataprovider.base.CacheFunctionProvider.

Example 73-2 Using the Cache Function Provider Methods in a Java Class

NamedCache myCache = CacheFunctionProvider.getMediumCache("userIdCache");
String userId = (String)myCache.get("jpalmer");

Note:

Both examples Example 73-1 and Example 73-2 return a cache named wcps-cp-medium-userIdCache. If this cache does not already exist, it will be created.

Example 73-3 shows an example where a custom cache is used. In this case, the returned cache will not be the full cache name without a prefix.

Example 73-3 Using the Cache Function Provider Methods in a Java Class

NamedCache myCache = CacheFunctionProvider.getCustomCache("my-custom-cache");

73.3.2 Using CoherenceCacheFactory

Data providers and other classes deployed to the WCPS use this factory class to implement caching programmatically. This class is scoped to the web application with which it is deployed.

The CoherenceCacheFactory has a single method to call:

public static NamedCache getCache(String cacheConfigFile, String cacheName)

Example 73-4 shows how to call getCache() when the cache configuration file is in the WCPS classpath, according to the best practice described previously in Section 73.2.2.3, "Creating Custom Cache Configuration Files."

Example 73-4 Calling getCache() with Configuration File in the Classpath

NamedCache myCache = CoherenceCacheFactory.getCache("content-cache-config.xml", "userIdCache");
String userId = (String)myCache.get("jpalmer");

Example 73-5 shows how to call getCache() when the cache configuration file is located elsewhere on the file system.

Example 73-5 Calling getCache() with Configuration File on the Filesystem

NamedCache myCache = CoherenceCacheFactory.getCache("file:///myconfig/content-cache-config.xml", "userIdCache");
StringuserId = (String)myCache.get("jpalmer");

73.4 Configuring Caches for Personalization Components

This section explains how caches are configured in configuration files. Pre-configured and custom caches configured in wcps-datatprovider-cache-config.xml are discussed. Then, cases where a cache has it's own configuration file is explained.

73.4.1 Pre-configured Caches

The configuration file includes pre-configured caches (small, medium, and large). These caches are accessible through the Cache Function Provider (see Section 73.3.1, "The Cache Function Provider"). The access methods are described in "Cache Methods" in Chapter 69, "Function Provider Reference." They include:

  • getSmallCache(String cacheName)

  • getMediumCache(String cacheName)

  • getLargeCache(String cacheName)

Note:

The "cacheName" parameter is appended to an internal prefix to match patterns in the wcps-dataprovider-cache-config.xml. For example: wcps-dp-large-<cacheName>. For more details, see Section 73.2.2.2, "Data Provider Cache File."

73.4.2 Custom Caches

This assumes you have added a new entry in wcps-dataprovider-cache-config.xml. It returns a cache with that cacheName (no prefix), configured as the configuration file has specified it.

The Cache Function Provider method used to return a custom cache that is configured in wcps-dataprovider-cache-config.xml is:

getCustomCache(String cacheName)

For more details, see "Cache Methods" in Chapter 69, "Function Provider Reference."

73.4.3 When a Cache Has Its Own Configuration File

The configuration file, "configFile" must be available to the WCPS web application classloader. See also Section 73.2.2.3, "Creating Custom Cache Configuration Files."

The function provider method used to return a cache configured in a custom cache configuration file is:

getCache(String myConfigFile.xml, String cacheName)

Note:

The cache configuration file must be in the application classpath. Otherwise, it can be anywhere in the classpath of the caller.

For more details, see "Cache Methods" in Chapter 69, "Function Provider Reference."

73.5 Configuring a Cache on a Data Provider Connection

You can hard code a cache name into a data provider. Or, you can set the cache name as a parameter in the wcps-connections.xml provider configuration file. This file is explained in detail in Section 67.5.6, "Updating the WCPS Connections Configuration File."

Tip:

The advantage of setting the cache name as a connection parameter is that the cache name can be changed at runtime.

Example 73-6 illustrates how to configure a cache into wcps-connnections.xml. You need to add two properties to the <connection> element.

  • <cacheName> – Specifies a name for the cache. In the example, the name is demo-cache.

  • <configFileUri> – Specifies the location of the cache configuration file on the filesystem. In the example, the value is file:///mydir/demo-cache.xml.

In this example, the <connection> element is given a <cache-name> property with a value of demo-cache.

Example 73-6 Data Provider Connection Configuration

<connection>
        <connection-name>TestConnection</connection-name>
        <connection-type>my.test.connection</connection-type>
        <namespace>default</namespace>
        <properties>
            <property>
                <name>cacheName</name>
                <value>demo-cache</value>
            </property>
            <property>
                <name>configFileUri</name>
                <value>file:///Users/jpalmer/demo-cache.xml</value>
            </property>
        </properties>
    </connection>

73.6 Monitoring Oracle Coherence

Coherence provides an MBean console to monitor its caches. For information on how to set server properties to enable this feature, see Using JMX to Manage Oracle Coherence.

Figure 73-2 Coherence Monitoring Console

Description of Figure 73-2 follows
Description of ''Figure 73-2 Coherence Monitoring Console''