Administering Server-Based Caching

This section provides an overview of caching scope and discusses how to:

  • Implement target content caching.

  • Implement pagelet caching.

  • Implement metadata caching.

  • Implement proxied JavaScript caching.

You can define caching for server-based portal content with one of three levels of scope:

  • Private scope.

    This is also known as the user scope. The portal maintains the cached content independently for each user. This scope is useful when the content that is displayed, such as a 401K balance, is specific to the user who's signed in.

  • Role scope.

    Each user is assigned one or more roles. The portal maintains a single cache of the content for all users with a given combination of roles. This scope is useful when the content that is displayed, such as the menu structure, is specific to the role set of the user who’s signed in. If your user population has many unique role combinations, your caching memory requirements may be nearly the same as private scope caching.

  • Public scope.

    This is also known as the application scope. The portal maintains a single cache of the content for all users who are using a given application. This scope is useful when all users who have access to this content, such as company news articles, bulletins, or messages, see the same thing. Because only one cache object is managed in memory for your entire user population, this is the least memory-intensive scope option.

You can cache the content of an individual target by specifying several caching parameters in the HTML of each locally defined template that invokes the target. You must also enable target content caching for the portal.

Important! Target content is cached in memory on the web server. If you use this feature excessively, the cache could consume all available memory. Use target content caching only to cache content that is static or doesn't require constant updating and that is accessed frequently by many users.

Specifying Caching Parameters

You apply target content caching by inserting a Cache element inside a TargetContent element in the HTML of a locally defined template.

The Cache element has these attributes:

Attribute

Description

Scope

Use one of these values:

  • user: The portal maintains the cached target content independently for each user.

  • role: The portal maintains a single cache of the target content for all users in a role.

  • application: The portal maintains a single cache of the target content for all users who are using an application.

Interval

Specify the number of seconds that should pass before the portal refreshes the target content cache.

This example shows caching that is defined with the application scope and an interval of 1200 seconds:

<TargetContent Name="MyContent">
    <Cache Scope="application" Interval="1200">ANY</Cache>
</TargetContent>

Note: The Cache element must not be empty, but its content can be anything.

Enabling Target Content Caching

Any Cache elements that you insert in template HTML are ignored by the portal unless you enable target content caching globally for the portal. Select the Cache Target Content check box in the On the Web Server group box of the Web Profile Configuration - Caching page.

If you're developing a pagelet and you know that its content will remain static for all users, you can specify the application or public scope. If you know that the pagelet's content will remain static for all users with the same role, you can specify the role scope. However, if the pagelet content is static only for individual users, you must specify the user or private scope. If you're not the pagelet developer, you probably won't know when the pagelet content will change, so to be sure you must specify the user scope.

Important! Pagelet content is cached in memory on the web server. If you use this feature excessively, the cache could consume all available memory. Use pagelet caching only to cache content that is static or doesn't require constant updating, and is accessed frequently by many users.

You can cache the content of an individual pagelet by specifying caching parameters in one of these locations:

  • The HTML of any locally defined template that invokes the pagelet.

  • A content reference attribute in the pagelet definition.

Note: If you specify caching parameters for a pagelet in both locations, the caching parameters in the template take precedence, and the caching parameters in the content reference attribute are ignored.

The presence of the caching parameters is sufficient to enable caching for the associated pagelet; no additional setting is required. To disable pagelet caching, delete the caching parameters.

Specifying Pagelet Caching in the Template

You apply pagelet caching in a template by inserting a Cache element inside a Pagelet element or IClientComponent element in a locally defined template.

The Cache element has these attributes:

Attribute

Description

Scope

Use one of these values:

  • user: The portal maintains the cached pagelet independently for each user.

    Note: In a high-volume environment, caching pagelets with the user scope requires a separate web server cache of each pagelet for every user, which can result in significant memory problems. Because of this, caching pagelets with the role or application scope whenever possible is strongly recommended.

  • role: The portal maintains a single cache of the pagelet for all users in a role.

  • application: The portal maintains a single cached version of the pagelet for each user. The cache manager clones a copy of the meta pagelet and stores a copy for each user. For example, if 1000 users have signed in and they all have this pagelet on their homepage, 1000 copies of the pagelet will be stored in cache. Each of these pagelet copies has the associated time to live (TTL) variable. Each time the system builds the user's homepage, it reviews the TTL to determine whether the time has come to refresh the pagelet. When a TTL time expires, that copy of the meta pagelet is invalidated and refreshed from the application server. When each user's copy expires, his or her copy will be updated with the latest version.

Interval

Specify the number of seconds that should pass before the cache expires and is subject to an automatic refresh. This value depends on the frequency with which the data changes, and the need for data to be 100 percent accurate.

For example, a company news article rarely changes once it’s been published. You might want to set the refresh period for the article pagelet to be 86400 seconds so that it's cached for a 24-hour period.

This example shows caching that is defined in an IClientComponent element with the role scope and an interval of 1800 seconds:

<IClientComponent Name="Header">
    <Cache Scope="role" Interval="1800">ANY</Cache>
    <Source Product="Portal">ICType=Script...</Source>
</IClientComponent

Note: The Cache element must not be empty, but its content can be anything.

Specifying Pagelet Caching in the Content Reference

You apply pagelet caching in a template by defining a special content reference attribute on the pagelet definition.

To implement caching for a pagelet:

  1. Open the content reference administration page of the pagelet that you want to cache.

    Select the folder containing the pagelet, and edit its content reference.

    1. Select PeopleTools > Portal > Structure and Content.

    2. Click the Portal Object link.

    3. Click the Pagelets link.

    4. Click the link for the pagelet folder.

    5. Click the Edit link for the pagelet.

  2. Add a new content reference attribute.

  3. Specify the attribute name and label.

    • In the Name field, enter PSCACHECONTROL.

    • In the Label field, enter PSCache-Control.

  4. Specify the attribute value with this syntax:

    cache_scope,max-age=interval

    Parameter

    Description

    cache_scope

    Use one of these values:

    • private: The portal maintains the cached pagelet independently for each user.

      Note: In a high-volume environment, caching pagelets with the private scope requires a separate web server cache of each pagelet for each user, which can result in significant memory usage. Because of this, caching pagelets with the role or public scope wherever possible is strongly recommended.

    • role: The portal maintains a single cache of the pagelet for all users in a role.

    • public: The portal maintains a single cache of the pagelet for all users who are using an application.

    interval

    Specify the number of minutes that should pass before the cache expires and is subject to an automatic refresh.

    For example, consider a PeopleSoft Interaction Hub environment in which users can personalize their company news pagelet. The articles don't change frequently, and users don't need them to be current; therefore, you might specify private caching with a three-hour (180 minute) expiration:

    private,max-age=180

  5. Save the content reference.

    The next time a user signs in and displays the pagelet, the caching that you specified takes effect.

Managing the Caching of Pagelets

You can enable users to personalize their homepage pagelets. When a user personalizes a pagelet, the result should be visible only to that user, and therefore should be cached only for that user. To achieve this goal, as soon as the user attempts to personalize the pagelet, regardless of the caching scope that you originally specified, the portal automatically changes the caching scope to apply on a private basis and maintains the cached pagelet independently for that user.

Important! This automatic scope change applies only to the user who is personalizing the pagelet and to the portal on which the pagelet is personalized. On other portals, and for other users, the originally defined caching scope for that pagelet still applies. If the personalizations aren't stored as portal-specific data, then the personalizations for a pagelet that was originally defined with a wider caching scope can become visible to others who are accessing the same site through another portal.

Therefore, when developing personalizable pagelets, you need to ensure that stored pagelet personalization metadata is keyed by both user ID and portal name so that you can populate the pagelet independently for each portal. This prevents user personalizations on one portal from being cached and visible to a larger audience on another portal.

Disabling Manual Pagelet Refresh

When you implement pagelet caching, a refresh button appears by default in the pagelet header. You can prevent users from refreshing the pagelet manually by hiding the refresh button, which you do by selecting a check box on the pagelet's content reference administration page.

Metadata caching is governed by portal-wide properties that control caching for these portal metadata objects as a group:

  • The portal registry.

  • Node definitions.

  • Content references.

  • Locally defined templates.

Portal metadata is likely to change far less frequently than pagelets or target content, so caching it on the server is an easy way to improve portal performance. Caching improves system performance by decreasing service requests from the web server to the application server.

Note: Metadata caching always applies with the application scope—the portal maintains a single metadata cache for all users who are using an application.

You implement metadata caching for a portal by setting these properties in the On the Web Server group box of the Web Profile Configuration - Caching page:

Field or Control

Definition
Cache Portal Objects

Select to enable metadata caching.

Metadata caching is enabled by default. You must restart the web server or wait for the stale interval to expire when you change:

  • The default portal for a database.

  • The default local node for a database.

  • The remote node to local or a local node to remote.

  • Templates that are associated with a content reference, node, or portal.

  • HTML within a template.

Note: When you add or delete a content reference or folder, this change shows up in the menu structure immediately because it's rendered within the application server, not the portal servlet.
Cache Stale Interval

Specify the number of seconds that should pass before the portal refreshes the metadata cache.

The default value of this property is 86400 (24 hours). With this setting, if you change the default local node in the database, the change doesn't take effect until the following day.

Cache Purge All Hit Count

Set to the maximum total number of HTTP requests that the web server should receive for objects in the metadata caches of all portals. When the web server receives this number of hits, it purges all metadata caches, forcing the portals to refresh them.

This setting enables you to manage application server memory consumption. If the web server is consuming too much memory, you can lower this value. This causes the web server to reclaim the memory that is used for cached portal objects more often. The cost of this is increased CPU usage on both the web and the application server when the web server deletes the cached objects and then retrieves them again from the application server.

The default value of this property is 1000. Set to –1 to disable the feature.

Note: The timing properties—the cache stale interval and the cache purge all hit count—compete for effect. The first timing property to reach the specified interval or number of hits takes precedence. When the metadata cache on a portal is refreshed, the cache stale interval and cache purge all hit count counters for all portals on the same web server are reset.

In addition to target content, pagelets, and metadata, you can cache proxied JavaScript objects on the server. This is recommended for production systems; you might want to disable this caching during development.

You enable caching of proxied JavaScript for a portal by selecting the Cache Proxied JavaScripts check box in the On the Web Server group box of the Web Profile Configuration - Caching page.