Using Caches

 

WebLogic Portal provides a single framework for configuring, accessing, monitoring, and maintaining caches. If configured properly, the caches can reduce the time needed to retrieve frequently used data.

Many WebLogic Portal services use preconfigured caches that you can tune to meet your performance needs. Some services use internally configured caches that you cannot configure or access. If you extend or create additional services, you can use the cache framework to define and use your own set of caches.

This topic contains the following sections:

• Overview of the Cache Framework

• Configuring Caches with MBeans

• Accessing Caches

• Reconfiguring Active Caches

• Monitoring and Managing Caches

• Recommended Settings

All of the recommendations in this document are in addition to the recommendations in the BEA WebLogic Server Performance and Tuning guide.

 

---

Overview of the Cache Framework

The most basic components of the cache framework are the com.bea.p13n.cache.CacheFactory and com.bea.p13n.cache.Cache classes. These classes provide facilities for creating, accessing, and managing caches.

In addition to these components, WebLogic Portal provides a set of MBeans (Java Beans for Management) that you can use to configure and administer the caches. (MBeans are part of the specification for Java Management Extensions, or JMX.) See Figure 4-1.

Figure 4-1 The Cache Framework

 

Comparison of Configuring Caches

Using MBeans to configure caches is optional. This section compares configuring caches with and without MBeans.

Using MBeans to configure caches provides the following advantages:

• A cache's configuration persists when you restart a server instance.

• You can use the WebLogic Server Administration Console (or an API) to dynamically modify a cache configuration.

• The configuration is available to all instances of the cache on all nodes of a cluster. Any changes that you make to this configuration via the WebLogic Server Administration Console are propagated to all instances of the cache on all cluster nodes.

Instead of using MBeans to configure caches, you can use a default configuration that is specified in com.bea.p13n.cache.CacheDefaults. You cannot use the WebLogic Server Administration Console to modify the configuration of caches that you create in this way. (Hence, any changes that you make to the configuration of such a cache are not propagated across a cluster.)

Caches in a Clustered Environment

In a clustered environment, entries within caches are not replicated across nodes.

If you use MBeans to configure a cache, the CacheMBean on the Administration Server propagates the cache configuration to all nodes in the cluster. If you modify the configuration, the CacheMBean propagates the changes to all instances of the cache throughout the cluster, thus maintaining a consistent view of the cache configuration parameters. (See Figure 4-2.)

Note: If you want to dynamically reconfigure an active, single instance of a cache without propagating the changes throughout a cluster, refer to Reconfiguring Active Caches.

Figure 4-2 Caches in a Cluster

 

In addition, for caches that are configured by MBeans, you can use the WebLogic Server Administration Console to do the following:

• Flush (remove) all items from all instances of the cache throughout a cluster.

• Invalidate a single item in a cache and propagate the invalidation to all instances of the cache throughout a cluster.

For example, a customer logs in to node A and receives a discount while shopping. The Discount Service on node A uses the discount cache to store data. A different customer logs in to node B and receives a discount while shopping. The Discount Service on node B creates its own instance of the discount cache to store its data. In the meantime, your supply of one of your discounted items unexpectedly runs low. You use the E-Business Control Center to deactivate the discount for the item, and to make sure that the discount is deactivated immediately (as opposed to waiting for the cache TTL to time out), you use the WebLogic Server Administration Console to flush the discount cache on all nodes in the cluster.

 

---

Configuring Caches with MBeans

Before you can access the cache MBeans, you must do the following:

• Assemble and deploy an enterprise application with a deployment descriptor that declares the default cache MBeans. For information on setting up a deployment descriptor for your enterprise application, refer to "Create Deployment Descriptors" under "Assembling and Deploying Enterprise Applications" in the Deployment Guide.

• Start the server instance onto which you deploy your enterprise application.

Configuring Default Caches

Many WebLogic Portal services use preconfigured caches that you can tune to meet your performance needs.

If you want to re-configure these default caches, do the following:

1. Start the WebLogic Server Administration Console by entering the following URL in a Web browser:

   http://hostname:port-number/console

   For example, you started a server on a host named bonnie and it uses port 7001 as a listen-on port. Enter the following URL:

   http://bonnie:7001/console

2. The WebLogic Server Administration Console prompts you to log in with a user account that has administrator privileges.

3. After you log in, in the left pane, click Deployments -> Applications -> MyApplication -> Service Configuration -> Caches.

4. Click the cache that you want to configure. (See Figure 4-3.)

   Figure 4-3 Configuring a Cache MBean

   
    

5. On the Cache Service page, click the Configuration tab and modify any of the following items:

   Name	Description
   Enabled	Determines whether the cache can be instantiated and accessed. Clearing this check box also flushes the cache and causes the fetch, add, and remove methods to do nothing.
   Time to Live	Determines the number of milliseconds that items in the cache remain valid. For information on setting TTL values for individual items in a cache, refer to Putting and Getting Items in a Cache.
   Maximum Number of Entries	Determines the maximum number of items that the cache maintains. If a cache already contains the maximum number of entries and a service tries to add an item, the cache does one of the following: If the item already exists, the cache replaces the entry. If the item does not already exist, it is added to the cache and the least recently used element is removed to accommodate the new element. Caches remove items to accommodate new ones only if the cache is at capacity.

6. Click Apply. Your modifications take effect immediately.

The WebLogic Server Administration Console saves these values to the application-config.xml file, which is located in the META-INF directory of your enterprise application.

Configuring Custom Caches

If you create a cache to support one of your extensions or additional services, you can use MBeans to configure the cache. To use MBeans to configure a custom cache, do the following:

1. In a text editor, open myApplication/META-INF/application-config.xml.

   Note: Do not use the WebLogic Server Administration Console for your domain while you are editing application-config.xml in the text editor. The WebLogic Server Administration Console writes its changes to application-config.xml.

2. In application-config.xml, within the <CacheManager> element, add the following subelement:

   <Cache
   Name="cache-name"
   TimeToLive="time-in-milliseconds"
   MaxEntries="numerical value">
   </Cache>

   For example,

   <Cache
   Name="MyCache"
   TimeToLive="360000"
   MaxEntries="100">
   </Cache>

3. Restart the server or redeploy your application.

To access this cache, use CacheFactory.getCache(cache-name).

 

---

Accessing Caches

To access (instantiate and retrieve) a cache, you use CacheFactory.getCache(). This section contains the following subsections:

• Accessing a Cache

• Putting and Getting Items in a Cache

For information about the advantages of each configuration method, refer to Comparison of Configuring Caches. For more information about com.bea.p13n.cache.CacheFactory.getCache(), refer to the WebLogic Portal Javadoc.

Accessing a Cache

Use the following syntax to access a cache:

CacheFactory.getCache(String cacheName)

With this command, getCache() does the following:

• Determines whether a cache identified by the cacheName value has already been instantiated. If it has, then it retrieves the existing cache.

• If it has not, then CacheFactory looks for an instance of a CacheMBean with a name attribute that matches cacheName. If it finds such an MBean, then it creates a cache using the MBean configuration parameters.

• If CacheFactory does not find an CacheMBean that matches cacheName, then getCache() configures the cache with default parameters from com.bea.p13n.cache.CacheDefaults:
  MaxEntries=100
  TimeToLive=360000
  Enabled=true

For example, the following command returns a cache named MyCache:

Cache cache = CacheFactory.getCache("MyCache");

Putting and Getting Items in a Cache

After you retrieve a cache, you use the following methods to put and get items:

• Cache.put(Object key, Object value) to add items.

• Cache.put (Object key, Object value, long ttl) to add and specify a time-to-live (in milliseconds) for an item. This item-specific TTL does not persist and does not propagate to other instances of the cache in a cluster. The TTL for other items in the cache is determined by the cache-wide TTL, which you specify when you create the cache.

• Cache.get(Object key) to retrieve items.

For example, the following commands retrieve a cache named MyCache, add three items that are identified as Element 1, Element 2, and Element 3, and then retrieves the value for Element 2.

Cache cache = CacheFactory.getCache("MyCache");
cache.put("Element 1", "stream");
cache.put("Element 2", "mountain");
cache.put("Element 3", "stars");
String s = (String)cache.get("Element 2");

The following command specifies a TTL of 6000 milliseconds for the Element 2 item,

cache.put ("Element 2", "mountain", 6000);

For a description of all Cache API methods, refer to the WebLogic Portal Javadoc. for com.bea.p13n.cache.Cache.

 

---

Reconfiguring Active Caches

If you configured a cache with MBeans, you can use the WebLogic Server Administration Console to reconfigure the cache and all of its instances across a cluster. For more information, refer to Configuring Caches with MBeans.

If you want to reconfigure a single instance of any currently active cache, invoke Cache.set methods. These configuration changes do not use MBeans and are not propagated to other instances the cache in a cluster.

For more information, refer to the WebLogic Portal Javadoc. for com.bea.p13n.cache.CacheFactory.Cache.

 

---

Monitoring and Managing Caches

You can use the APIs to monitor cache activity and the WebLogic Server Administration Console or APIs to perform management tasks such as removing items.

This section contains the following subsections:

• Monitoring a Cache

• Flush or Invalidate Items in a Cache That Is Configured with MBeans

• Clear or Remove Items from a Cache

Monitoring a Cache

Each cache object maintains and reports information about itself. The following sections describe how to monitor an individual instance of a cache:

• Viewing the Number of Items in a Cache

• Viewing the Hit Count

• Viewing the Hit Rate

• Viewing the Miss Count

• Example of Monitoring Caches

Note: Cache statistics, such as hit count and hit rate, describe activity for individual instances of the cache. You cannot view them from the WebLogic Server Administration Console. Compare this to cache attributes, such as enabled, which apply to all instances of a named cache in a cluster and are available to view or modify from the WebLogic Server Administration Console.

Viewing the Number of Items in a Cache

To view the number of items in a cache, use the following API:

com.bea.p13n.cache.Cache.size()

For information about this method, refer to the documentation for com.bea.p13n.cache.Cache in the WebLogic Portal Javadoc.

Viewing the Hit Count

To view the hit count, which is the number of Cache.get() calls that successfully returned data, use the following API:

com.bea.p13n.cache.getHitCount()

For information about this method, refer to the documentation for com.bea.p13n.cache.CacheStats in the WebLogic Portal Javadoc.

Viewing the Hit Rate

To view the hit rate, which is the percentage of Cache.get() calls that successfully returned data, use the following API:

com.bea.p13n.cache.getHitRate()

For information about this method, refer to the documentation for com.bea.p13n.cache.CacheStats in the WebLogic Portal Javadoc.

Viewing the Miss Count

To view the miss count, which is the number of Cache.get() calls that did not return data, either because an entry has expired or was not in the cache, use the following API:

com.bea.p13n.cache.getMissCount()

For information about this method, refer to the documentation for com.bea.p13n.cache.CacheStats in the WebLogic Portal Javadoc.

Example of Monitoring Caches

The following commands retrieve a cache named FooCache and return the statistics that the cache object keeps. The final line resets the statistics:

Cache cache = CacheFactory.getCache("FooCache");
//do stuff; put, get items
int hitRate = cache.getHitRate();
int hitCount = cache.getHitCount();
int missCount = cache.getMissCount();

com.bea.p13n.cache.resetStats();

Disable a Cache

If you want to make a cache unavailable for putting and getting items, you can disable it. Disabling also flushes a cache and causes the fetch, add, and remove methods to do nothing.

If you use the WebLogic Server Administration Console to configure a cache, do the following to disable the cache:

1. Start the WebLogic Server Administration Console by entering the following URL in a Web browser:

   http://hostname:port-number/console

   For example, you started a server on a host named bonnie and it uses port 7001 as a listen-on port. Enter the following URL:

   http://bonnie:7001/console

2. The WebLogic Server Administration Console prompts you to log in with a user account that has administrator privileges.

3. After you log in, in the left pane, click Deployments -> Applications -> MyApplication -> Service Configuration -> Caches.

4. Click the cache that you want to disable. (See Figure 4-3.)

5. On the Cache Service page, click the Configuration tab.

6. Clear the Enabled check box and click Apply.

Note: The Cache.disable() API also disables caches, but we recommend that you do not use this method for caches that are configured with MBeans.

If you do not use the WebLogic Server Administration Console and MBeans to configure a cache, use Cache.setEnabled(false) to disable a cache.

Flush or Invalidate Items in a Cache That Is Configured with MBeans

For any cache that is configured with MBeans, you can flush or invalidate items cluster-wide. Flushing removes all items from all instances of the cache throughout a cluster. Invalidating removes a single item from all instances of the cache throughout a cluster.

Flushing or Invalidating From the WebLogic Server Administration Console

To flush or invalidate from the WebLogic Server Administration Console, do the following:

1. Start the WebLogic Server Administration Console by entering the following URL in a Web browser:

   http://hostname:port-number/console

   For example, you started a server on a host named bonnie and it uses port 7001 as a listen-on port. Enter the following URL:

   http://bonnie:7001/console

2. The WebLogic Server Administration Console prompts you to log in with a user account that has administrator privileges.

3. After you log in, in the left pane, click Deployments -> Applications -> MyApplication -> Service Configuration -> Caches.

4. Click the cache that you want to flush or invalidate.

5. On the Cache Service page, click the Administration tab. (See Figure 4-4.)

   Figure 4-4 Cache Administration

   
    

6. To flush all items from a cache, select the Flush the Entire Cache check box. Then click Flush.

   To invalidate an item, enter the item's key in the Invalidate a Specific Key box. Then click Flush.

Clear or Remove Items from a Cache

For any cache that is currently active, you can clear or remove items. Clearing removes all items from a cache; removing destroys only the items that you specify. Both of these operations apply only to the current instance of a cache. They do not affect other instances on other nodes of a cluster.

To clear all items from a cache, retrieve the cache and then use the cache.clear method:

CacheFactory.getCache(String name);
cache.clear()

For example, the following two commands retrieve a cache named MyCache and clear all items from it:

CacheFactory.getCache("MyCache");
cache.clear()

To remove items from a cache, retrieve the cache and then use the cache.remove method:

CacheFactory.getCache(String name);
cache.remove(Object key)

For example, the following two commands retrieve a cache named MyCache and remove an entry named Element 2:

Cache cache = CacheFactory.getCache("MyCache");
cache.remove("Element 2")

 

---

Recommended Settings

To adjust caching for production Web site, complete the following tasks:

• Adjust Caching for Content Management

• Property Caching in a Clustered Environment

• Adjust Group Membership TTL in the Caching Realm

• Adjust Caching for the Discount Service

Adjust Caching for Content Management

To optimize content-management performance for your production Web site, the Content Manager uses the caching framework to configure and manage the following caches:

• documentContentCache

• documentMetadataCache

• documentIdCache

The content management JSP tags provide an additional set of caches, which you can access by doing the following:

• For the cm:select, cm:selectById, pz:contentQuery, and pz:contentSelector JSP tags, use the useCache attribute whenever possible. Doing so avoids a call to DocumentManager and, in the case of pz:ContentSelector, to the Rules Manager.

  For information on using the useCache attribute, refer to "JSP Tag Library Reference" in the Guide to Building Personalized Applications.

  To clear cached content when user and/or document attributes change, use the remove method of com.bea.p13n.content.ContentCache. For more information, see the WebLogic Portal Javadoc. for com.bea.p13n.content.ContentCache.

• For the cm:select, cm:selectById, pz:contentQuery, and pz:contentSelector JSP tags, set the cacheScope attribute to application whenever possible. This application scope applies to the Web application, not to the enterprise application.

  For example:

  <cm:select id="myDocs" query="riskFactor = 'Low'"
  useCache="true" cacheId="myDocs"
  cacheScope="application"
  max="10" cacheTimeout="300000" />

  The application cache type is global instead of per-user and should speed up queries by avoiding a call to the DocumentManager EJB.

Note: For pz:contentSelector, set the cacheScope attribute to application only when you want to select shared content. For example, you create an application that uses an application-scoped cache to select content for non-authenticated users. Because it uses the application scope, all non-authenticated users see the same content. For authenticated users, your application provides personalized content by switching to a session scoped cache.

• Whenever you can predict the next document that users will view based on the document that they are currently viewing, load the next document into the cache before users request it. This "forward caching" will greatly improve the speed at which WebLogic Portal responds to user requests (assuming that your prediction is correct; forward caching a document that no one requests will only degrade performance and scalability).

  The following JSP fragment is an example of forward caching a document:

  <%-- Get the first set of content --%>

  <cm:select id="myDocs" query="riskFactor = 'Low'"
  useCache="true" cacheId="myDocs"
  cacheScope="application"
  max="10" cacheTimeout="300000" />

  <%-- Generate a query from each content's relatedDocId --%>

  <% String query = null; %>
  <es:forEachInArray array="<%=myDocs%>" id="myDoc" type="com.bea.p13n.content.Content">

  <% String relId = (String)myDoc.getProperty("relatedDocId", null); %>
  <es:notNull item="<%=relId%>">

  <%
  if (query != null)
  query += " || ";
  else
  query = "";
  query += "identifier = '" +
  ExpressionHelper.toStringLiteral(relId) + "'";

  %>

  </es:notNull>
  </es:forEachInArray>

  <%-- Load the related content into the cache via cm:select --%>

  <es:notNull item="<%=query%>">

  <cm:select query="<%=query%>" id="foo" useCache="true" cacheId="relatedDocs"
  cacheScope="session" max="10" cacheTimeout="300000" />

  </es:notNull>

For More Information

For more information about content management, see "Creating and Managing Content" in the Guide to Building Personalized Applications.

For more information about JSP tags for content management, see "JSP Tag Library Reference" in the Guide to Building Personalized Applications.

Property Caching in a Clustered Environment

To decrease the amount of time needed to access user, group, and other properties data, the WebLogic Server Configurable Entity and Entity Property Manager use the cache framework to configure and manage the following caches:

• ldapGroupCache

• ldapUserCache

• entityPropertyCache

• entityIdCache

• unifiedProfiletypeCache

• propertyKeyIdCache

By default, these property caches are enabled.

With property caching enabled in a clustered environment, each server in a cluster maintains its own cache; the cache is not replicated on other servers. In this environment, when properties that are stored in the caches change on one server, they may not change on another server in a timely fashion. In most cases, immediate or quick access to properties on another server is not necessary: user sessions are pinned to a single server, and even with caching enabled, users immediately see changes they make to their own settings on the server.

If a user and an administrator are pinned to different servers in the cluster and the administrator changes a user's properties, the user may not see the changes during the current session. You can mitigate this situation by specifying a small Time-To-Live (TTL) setting. For information on adjusting the TTL setting for a cache, refer to Configuring Caches with MBeans.

If you require multiple servers in a cluster to have immediate access to modified properties, disable property caching. For information on disabling a cache, refer to Disable a Cache.

For More Information

For more information about property sets, see "Creating and Managing Property Sets" in the Guide to Building Personalized Applications.

For more information about JSP tags for managing property sets, see "JSP Tag Library Reference" in the Guide to Building Personalized Applications.

Adjust Caching for the Discount Service

To reduce the amount of time the Order and Shopping Cart services need to calculate order and price information that include discounts, the Discount Service uses the caching framework to create and manage the following caches:

• discountCache, which contains data for campaign discounts. Campaign discounts are targeted to specific customers or customer segments, and are available only in the context of a campaign.

• globalDiscountCache, which contains data for global discounts. Global discounts apply to all customers, regardless of customer properties or customer segments.

When a customer adds an item to the shopping cart, removes an item from the shopping cart, checks out, or confirms an order, the Pricing Service is responsible for determining the price of the items in the cart. To calculate the effect of discounts on the shopping cart, the Pricing Service requests the Discount Service to retrieve information about all global discounts and about any campaign discounts that apply to the current customer.

The first request for information about discounts requires a separate call to the database for each discount that applies. For example, if you have defined one global discount and if a customer is eligible for two campaign-related discounts, the Discount Service makes three calls to the database. To decrease the response time for any subsequent requests, the Discount Service uses the caches.

This section contains the following subsections:

• Adjusting the discountCache

• Adjusting the globalDiscountCache

• Discount-Service Caches in Clustered and Non-Clustered Environments

Adjusting the discountCache

The discountCache contains data for campaign discounts. For maximum performance, set the capacity to the number of campaign discounts that are currently deployed. A larger capacity will potentially use more memory than a smaller capacity.

The Time-To-Live (TTL) property determines the number of milliseconds that the Discount Service keeps the information in the cache. After the cache value times out, the next request for the value requires the Discount Service to call the database to retrieve the information and then cache the value. A longer TTL decreases the number of database calls made over time when requesting cached objects. In a clustered environment, the TTL is the maximum time required to guarantee that any changes to global discounts are available on all servers.

Adjusting the globalDiscountCache

The Maximum Number of Entries property for global caches does not need to be modified.

The time-to-live property determines the number of milliseconds that the Discount Service keeps information in the global-discount cache. After the Time-To-Live (TTL) expires, the next request for global discount information requires the Discount Service to call the database to retrieve the information and then cache the value. A longer TTL decreases the number of database calls made over time when requesting cached objects. In a clustered environment, the TTL is the maximum time required to guarantee that any changes to campaign discounts are available on all servers.

Discount-Service Caches in Clustered and Non-Clustered Environments

In either environment (clustered or non-clustered), when you change a discount priority, end date, or its active/inactive state, WebLogic Portal flushes the discount from the appropriate cache. Changes to a campaign discount flush only the specific discount from the campaign-discount cache. Changes to a global discount flush all discounts from the global-discount cache.

For example, you log in to a WebLogic Portal host named bread and deactivate a campaign discount named CampaignDiscount1. WebLogic Portal flushes the CampaignDiscount1 from the campaign-discount cache on bread.

In a clustered environment, other machines in the cluster continue to use their cached copy of the discount until the TTL for that discount expires.

Adjust Group Membership TTL in the Caching Realm

The WebLogic Server Caching realm stores the results of both successful and unsuccessful realm lookups. It does not use the WebLogic Portal caching framework.

The Caching realm manages separate caches for Users, Groups, permissions, ACLs, and authentication requests. It improves the performance of WebLogic Server by caching lookups, thereby reducing the number of calls into other security realms.

WebLogic Portal enables the Caching realm by default. While all of the caches in the Caching realm can improve performance, the Time-To-Live (TTL) value for the Group Membership Cache in particular can affect the performance of WebLogic Portal.

In addition, note that if you delete a user from the system without first removing the user from a group, then the system continues to recognize the user until the TTL for the Group Membership Cache expires.

For information on adjusting the Group Membership TTL, refer to "Configuring the Caching Realm" under "Managing Security" in the WebLogic Server Administration Guide.