Caching

Caching

Caching pages shared by multiple users
cookie.ignore.regex
Cache scope
Expiry time
Cache scope and expiry time settings
Default cache scope and expiry time settings
Factors affecting cache scope and expiry time
Limitations
Security Issues
Troubleshooting

Overview

WebSphere Portal configures cache scope and expiry by page, portlet, and theme, combining this information to produce a final cache scope and expiry time for each page it serves. You can configure these cache settings using...

XML configuration interface
Portlets: Manage Pages, Manage Portlets, and Properties

When caching JSR portlets, the cache scope is only for proxy server caching policies and requires the use of an edge server cache. Local display caching policies are not affected by this setting. The cache expiration setting is used for both local and remote caching policies.

cookie.ignore.regex

If a particular cookie is required for some custom code or feature to work but it is not designed to invalidate the cache, that cookie name should be matched by the regular expression in the list...
cookie.ignore.regex

This ensures that changes to the cookie value do not have any adverse impact on performance by prematurely invalidating cache entries.
To add cookie.ignore.regex to the resource environment provider from the WAS console go to...
Resources | Resource Environment | Resource Environment Providers | WP ConfigService | Additional Properties | Custom Properties | New

.and specify the name and value of the required property.
To specify cookies that are NOT included in the digest computation, specify...
cookie.ignore.regex = digest//.ignore.*|Item1|Item2|Item3|Item4

.where Item1, Item2, Item3, Item4 are the items you want to exclude from getting cached. The default value is...
digest//.ignore.*|LtpaToken|LtpaToken2|JSESSIONID

Click Apply, save, log out of the WAS console, and restart the WebSphere_Portal server.

Cache scope
The cache scope determines where the content will be cached. There are two types of caching:

Shared cache across users Provides biggest performance improvement. A proxy server caches content and serves requests for the content. This caching eases the load on the server because requests that are served by the proxy do not reach WebSphere Portal. If most requests are for customized content, this type of caching provides no performance improvement. The following default values exist for portlet definitions, themes, and compositions if nothing is provided:
This type of caching should be used only for pages that contain public content that is not personalized.

Remote cache scope is non-shared
Remote cache expiry is 0 seconds

Non-shared cache for a single user (Web browser cache) Provides a smaller performance improvement. Typically located in each user's Web browser. This type of caching can be used for all content, including content that is personalized. If the computer is shared among multiple users, a user may see personalized content from other users if served from the browser cache. To prevent this from happening, do not enable private caching, even for personalize content.

Expiry time
The expiry time determines how long the page is stored in a cache. WebSphere Portal allows three options for specifying expiry time:

Cache always expires The content will never be cached in either a shared or a private cache; set the remote cache expiry to 0
Cache never expires The content can be stored indefinitely in either a shared or a private cache; set the remote cache expiry to -1
Cache expires after this many seconds The content will be stored for the number of seconds specified in either a shared or a private cache; set the remote cache expiry to a positive integer up to 2^31 -1

Cache scope and expiry time settings
The following table lists the resources that contribute to the overall remote cache information on a Page:

Contributes Key Possible Values Set Via XML Access Set Via UI
remote cache scope com.ibm.portal.remote-cache-scope SHARED, NON_SHARED yes yes
remote cache expiry com.ibm.portal.remote-cache-expiry Time in seconds, given as an integer between -1 and the value ((2 to the power of 31)-1) Use the value -1 if you never want the cache to expire. yes yes
Ignore Access Control in Caches com.ibm.portal.IgnoreAccessControlInCaches True, False yes yes

Example for XML access:
    <parameter update="set" name="com.ibm.portal.remote-cache-scope" type="string">SHARED</parameter>
    <parameter update="set" name="com.ibm.portal.remote-cache-expiry" type="string">3000</parameter>
    <parameter update="set" name="com.ibm.portal.IgnoreAccessControlInCaches" type="string">true</parameter>
The following table lists the resources that contribute to the overall remote cache information for Themes:

Contributes Key Possible Values Set Via XML Access Set Via UI
remote cache scope com.ibm.portal.remote-cache-scope SHARED, NON_SHARED yes no
remote cache expiry com.ibm.portal.remote-cache-expiry Time in seconds, given as an integer between -1 and the value ((2 to the power of 31)-1) Use the value -1 if you never want the cache to expire. yes no

Example for XML access:
    <parameter update="set" name="com.ibm.portal.remote-cache-scope" type="string">SHARED</parameter>
    <parameter update="set" name="com.ibm.portal.remote-cache-expiry" type="string">3000</parameter>
The following table lists the resources that contribute to the overall remote cache information on a Portlet Definition:

Contributes Key Possible Values Set Via deployment descriptor or an extension to it Set Via UI
remote cache scope remote-cache-scope SHARED, NON_SHARED yes no
expiration cache EXPIRATION_CACHE Time in seconds, given as an integer between -1 and the value ((2 to the power of 31)-1) Use the value -1 if you never want the cache to expire. yes yes
remote cache dynamic remote-cache-dynamic True, False yes no

The Standard Portlet API specification defines the meaning of the EXPIRATION_CACHE value. WebSphere Portal uses this value to determine the lifetime of the portlet's output in a remote cache, just like the remote cache expiry for themes. The remote cache dynamic setting is an optimization to notify the container whether a portlet window can publish remote cache information at render time. The deployment descriptor specification shows how to deal with these settings.
The following table lists the resources that contribute to the overall remote cache information on a Portlet Window:

Contributes Key Possible Values Set Via deployment descriptor or an extension to it Set Via UI
remote cache scope remote-cache-scope SHARED, NON_SHARED no, only published during render time no
expiration cache EXPIRATION_CACHE Time in seconds, given as an integer between -1 and the value ((2 to the power of 31)-1) Use the value -1 if you never want the cache to expire. no, only published during render time no

The portlet definition describes the portlet at a deployment time level given in the portlet deployment descriptor. Thus, attributes specified in the deployment descriptor are valid on all occurrences on all pages of this portlet. The portlet window describes the runtime entity for a portlet. While in the rendering phase of a portlet, the portlet can publish values or attributes via an API. Thus, attributes specified while rendering the portlet is portlet instance specific.
Example code snippet for publishing the information at render time:
    String paramExpiry = "3000";
    String paramScope = "SHARED";
    renderResponse.setProperty( "portlet.remote-cache-scope", paramScope );
    renderResponse.setProperty( RenderResponse.EXPIRATION_CACHE, paramExpiry );
The following table lists the resources that contribute to the overall remote cache information on Portlet Wide Settings:

Contributes Key Possible Values Set Via XML Access Set Via UI
remote cache expiration remote.cache.expiration Time in seconds, given as an integer between -1 and the value ((2 to the power of 31)-1) Use the value -1 if you never want the cache to expire. no, property in WP NavigatorService no
vary vary List of HTTP header fields that can be put into the vary response header no, property in WP NavigatorService no

Default cache scope and expiry time settings
WP NavigatorService settings:

Key Meaning Default value
public.session Specifies whether an anonymous user always has a public session. This may be useful when a portlet requires a session for anonymous users. To enable public sessions for pages that anonymous users can view without logging in, set this parameter to true.
The setting of public.session influences the remote cache scope for public pages. If public.session is set to true, then the cache scope is set to non-shared (private). If public.session is set to false, then the cache scope is set to shared (public). Setting public.session to true might reduce performance. Setting public.session to true might reduce performance.
false
public.expires Specifies the cache expiration time (in seconds) for caches outside of WebSphere Portal and for unauthenticated pages only. These caches must adhere to the HTTP 1.1 specification (RFC 2616). The public.expires key specifies the time after which HTTP caches should drop the response. This can be further restricted by the remote.cache.expiration key (see below).
This value is used as a maximum value for the cache expiration time and as a global default value for unauthenticated pages. If the setting remote.cache.expiration is also set to a value greater than or equal to 0, the smaller one of the two values is used.
WebSphere Portal calculates and aggregates the remote cache information, that is the scope and expiration time, by a number of parameters contributed by themes, pages, and portlets besides the settings described here. Therefore WebSphere Portal can do any of the following internally while processing a request:

Reduce the cache lifetime

Reduce the cache scope, for example, from public (shared) to private (non-shared)

Switch off the overall cachability of pages.
Therefore this value might not be static for all responses resulting from requests to unauthenticated pages.
The response of WebSphere Portal sets the following header fields:

The Expires header with the expiration time added to the system date and time.

The Cache-Control : max-age = header with the expiration time as its parameter.
The default setting specified in this file is 60 seconds. If no value is specified, WebSphere Portal defaults the value to 60 seconds.
The response of WebSphere Portal sets the following header fields:

The Expires header with the expiration time added to the system date and time.

The Cache-Control : max-age = header with the expiration time as its parameter.
The default setting specified in this file is 60 seconds. If no value is specified, WebSphere Portal defaults the value to 60 seconds.
Therefore this value might not be static for all responses resulting from requests to unauthenticated pages.
The response of WebSphere Portal sets the following header fields:

The Expires header with the expiration time added to the system date and time.

The Cache-Control : max-age = header with the expiration time as its parameter.
The default setting specified in this file is 60 seconds. If no value is specified, WebSphere Portal defaults the value to 60 seconds.
The response of WebSphere Portal sets the following header fields:

The Expires header with the expiration time added to the system date and time.

The Cache-Control : max-age = header with the expiration time as its parameter.
The default setting specified in this file is 60 seconds. If no value is specified, WebSphere Portal defaults the value to 60 seconds. 60 (sec)
remote.cache.expiration Maximum cache lifetime (in seconds) of a page, both public and private. Use this setting to specify a global value for the expiration of pages in remote caches. Setting this value to 0 switches caching off in remote caches. If the legacy setting is not available, this setting is used for authenticated and unauthenticated pages. If the legacy setting is available, then the smaller of the two values is used for unauthenticated pages only. In this case the remote.cache.expiration setting is used for authenticated pages in general. If theme, composition, and portlets contribute remote cache information, then the global settings also contribute to the information. In this case the lowest of the values of all contributors is used, including the global settings.
The default setting specified in this file is 60 seconds. If no value is specified, WebSphere Portal defaults the value to zero (0 seconds).
0 (sec)
remoteCacheInfo.response.header.vary Specifies the HTTP headers that force a proxy to cache different variants of the same URL. Use this setting to specify a comma separated list of HTTP header fields to which WebSphere Portal should refer in its vary field of the generated HTTP response. This is required to ensure that proxy caches can invalidate entries in their cache if the specified header fields do not match from request to request. User-Agent
public.cache-control Value which is set for the cache-control HTTP header field when the portal generates a response in request for public pages. This header field controls the behavior of all caching mechanisms along the request/response chain. no-cache
private.cache-control Value which is set for the cache-control HTTP header field when the portal generates a response in request for private pages. This header field controls the behavior of all caching mechanisms along the request/response chain. no-cache

Factors affecting cache scope and expiry time
Multiple factors can affect the cache scope and expiry time for a page. The remote-cache-scope and remote-cache-expiration of a rendered page view is calculated as the minimum of the following factors:

Cache scope and expiry time specified for the page

Cache scope and expiry time of the portlets on the page
If any of the portlets on a page can only be cached in a private cache, then the entire page can only be cached in a private cache. A page cannot be stored in a shared cache unless all portlets on the page can also be stored in a shared cache. Make sure cache settings for portlets and pages are consistent.

Cache scope and expiry time of the theme

Global values as defined in the Navigator Service in the IBM WAS console.

Limitations

For best results, use WAS Edge Components version 6.0.0.1 (or later), version 5.1.0.7 (or later), version 5.0.2.30 (or later) for the proxy server. Previous versions do not serve multiple markup types from the same cache. If there are multiple requests for the same page, but with different markup, the cache is not used. These versions of WAS Edge Components correct this problem.

If WebSphere Portal serves only one markup, make sure the vary is set appropriately. If WebSphere Portal serves multiple markups, set the vary appropriately and use a larger cache size. Use remoteCacheInfo.response.header.vary = space separated list of other http header fields to appropriately set the vary.
Enter any HTTP header field names; use the HTTP 1.1 specification. The two most common HTTP headers to specify here are vary = accept-language user-agent. The Vary value indicates the set of request-header fields that force a proxy to cache different variants of the same URL.

If WebSphere Portal serves only one language, make sure the vary is set appropriately. If WebSphere Portal serves multiple languages, set the vary appropriately and use a larger cache size. Use remoteCacheInfo.response.header.vary = accept-language to appropriately set the vary.

Only JSR portlets can override the cache lifetime setting at runtime.
With the above settings, it is possible to generate an HTTP response header like Cache-Control: max-age=-1, which indicates an unlimited cache expiration when a page is rendered. This is beyond the HTTP 1.1 specification but if a proxy cache does not support an unlimited cache expiration, WebSphere Portal supports it. If the cache infrastructure does not properly work with this response header, set the remote.cache.expiration value in the WP NavigatorService to a large value. To set an unlimited cache expiration is not possible if the cache infrastructure does not support it.

Security Issues
Storing authenticated pages in a shared cache introduces security holes. If a malicious user discovered the URL for an authenticated page, that user could read pages containing private information. By default, WebSphere Portal does not permit shared caching for authenticated pages. You can use the Properties portlet or the XML configuration interface to override these default settings using the parameter...
com.ibm.portal.IgnoreAccessControlInCaches

.but in most cases this is not recommended. In some rare circumstances, it might be useful to store authenticated pages in a shared cache. For example, if all authenticated users receive identical content, then storing authenticated pages in a shared cache might be acceptable.

Troubleshooting
In general, you should monitor the cache hit rate on the proxy server and adjust the cache size appropriately. If the hit rate is lower than expected, increase the cache size. You can also check the following item:
Ensure that the cache settings for all portlets on the page are consistent with the cache settings for the page. For example, if one portlet on a page is set to only be cached in a private browser cache, then the entire page can only be cached in a private browser cache, and performance will not be optimal.

Parent
Configure portal behavior

Related tasks

Set service configuration properties
Portal configuration services

Portal farm considerations

+
Search Tips | Advanced Search

Cache always expires	The content will never be cached in either a shared or a private cache; set the remote cache expiry to 0
Cache never expires	The content can be stored indefinitely in either a shared or a private cache; set the remote cache expiry to -1
Cache expires after this many seconds	The content will be stored for the number of seconds specified in either a shared or a private cache; set the remote cache expiry to a positive integer up to 2^31 -1

Contributes	Key	Possible Values	Set Via XML Access	Set Via UI
remote cache scope	com.ibm.portal.remote-cache-scope	SHARED, NON_SHARED	yes	yes
remote cache expiry	com.ibm.portal.remote-cache-expiry	Time in seconds, given as an integer between -1 and the value ((2 to the power of 31)-1) Use the value -1 if you never want the cache to expire.	yes	yes
Ignore Access Control in Caches	com.ibm.portal.IgnoreAccessControlInCaches	True, False	yes	yes

Key	Meaning	Default value
public.session	Specifies whether an anonymous user always has a public session. This may be useful when a portlet requires a session for anonymous users. To enable public sessions for pages that anonymous users can view without logging in, set this parameter to true. The setting of public.session influences the remote cache scope for public pages. If public.session is set to true, then the cache scope is set to non-shared (private). If public.session is set to false, then the cache scope is set to shared (public). Setting public.session to true might reduce performance. Setting public.session to true might reduce performance.	false
public.expires	Specifies the cache expiration time (in seconds) for caches outside of WebSphere Portal and for unauthenticated pages only. These caches must adhere to the HTTP 1.1 specification (RFC 2616). The public.expires key specifies the time after which HTTP caches should drop the response. This can be further restricted by the remote.cache.expiration key (see below). This value is used as a maximum value for the cache expiration time and as a global default value for unauthenticated pages. If the setting remote.cache.expiration is also set to a value greater than or equal to 0, the smaller one of the two values is used. WebSphere Portal calculates and aggregates the remote cache information, that is the scope and expiration time, by a number of parameters contributed by themes, pages, and portlets besides the settings described here. Therefore WebSphere Portal can do any of the following internally while processing a request: Reduce the cache lifetime Reduce the cache scope, for example, from public (shared) to private (non-shared) Switch off the overall cachability of pages. Therefore this value might not be static for all responses resulting from requests to unauthenticated pages. The response of WebSphere Portal sets the following header fields: The Expires header with the expiration time added to the system date and time. The Cache-Control : max-age = header with the expiration time as its parameter. The default setting specified in this file is 60 seconds. If no value is specified, WebSphere Portal defaults the value to 60 seconds. The response of WebSphere Portal sets the following header fields: The Expires header with the expiration time added to the system date and time. The Cache-Control : max-age = header with the expiration time as its parameter. The default setting specified in this file is 60 seconds. If no value is specified, WebSphere Portal defaults the value to 60 seconds. Therefore this value might not be static for all responses resulting from requests to unauthenticated pages. The response of WebSphere Portal sets the following header fields: The Expires header with the expiration time added to the system date and time. The Cache-Control : max-age = header with the expiration time as its parameter. The default setting specified in this file is 60 seconds. If no value is specified, WebSphere Portal defaults the value to 60 seconds. The response of WebSphere Portal sets the following header fields: The Expires header with the expiration time added to the system date and time. The Cache-Control : max-age = header with the expiration time as its parameter. The default setting specified in this file is 60 seconds. If no value is specified, WebSphere Portal defaults the value to 60 seconds.	60 (sec)
remote.cache.expiration	Maximum cache lifetime (in seconds) of a page, both public and private. Use this setting to specify a global value for the expiration of pages in remote caches. Setting this value to 0 switches caching off in remote caches. If the legacy setting is not available, this setting is used for authenticated and unauthenticated pages. If the legacy setting is available, then the smaller of the two values is used for unauthenticated pages only. In this case the remote.cache.expiration setting is used for authenticated pages in general. If theme, composition, and portlets contribute remote cache information, then the global settings also contribute to the information. In this case the lowest of the values of all contributors is used, including the global settings. The default setting specified in this file is 60 seconds. If no value is specified, WebSphere Portal defaults the value to zero (0 seconds).	0 (sec)
remoteCacheInfo.response.header.vary	Specifies the HTTP headers that force a proxy to cache different variants of the same URL. Use this setting to specify a comma separated list of HTTP header fields to which WebSphere Portal should refer in its vary field of the generated HTTP response. This is required to ensure that proxy caches can invalidate entries in their cache if the specified header fields do not match from request to request.	User-Agent
public.cache-control	Value which is set for the cache-control HTTP header field when the portal generates a response in request for public pages. This header field controls the behavior of all caching mechanisms along the request/response chain.	no-cache
private.cache-control	Value which is set for the cache-control HTTP header field when the portal generates a response in request for private pages. This header field controls the behavior of all caching mechanisms along the request/response chain.	no-cache