../E63259-01.epub /> ../E63259-01.mobi />
This chapter discusses cache management for personalization
This chapter includes the following topics:
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."
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.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."
This section discusses each of the cache configuration files used by personalization features and the creation of custom cache configuration files.
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.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."
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:
Place cache configuration files in:
$ORACLE_HOME/user_projects/applications/<domain>/conductor-extensions-library/WEB-INF/classes
Only refer to caches that are used by server-side personalization components, like data and function providers. For details on these components, see Chapter 67, "Implementing Custom Data Providers: Introduction" and Chapter 68, "Implementing Custom Function Providers: Introduction."
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.
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, "What are Function Providers?."
CoherenceCacheFactory – Data providers and other classes deployed to the WCPS use this factory class to implement caching programmatically.
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.
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 namedwcps-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.
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.
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.
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 thewcps-dataprovider-cache-config.xml
. For example: wcps-dp-large-<cacheName>
. For more details, see Section 73.2.2.2, "Data Provider Cache File."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."
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."
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>
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.