ShowTable of Contents
Note: The following information is provided "as-is" and without any guarantees whatsoever. In particular, the publication of this information does not constitute a (de facto) public API and therefore may be subject to change at any point in time and without prior notice.
The digest is computed based on a selection of request headers and the user identity. We distinguish between the "request digest" and the "data source digest". The request digest is always based on all relevant headers and the user identity, whereas the data source digest is optionally based on a subset of this information (depending on data source settings).
The resolver framework uses the following information to compute digests:
- Accept-Language (L)
identifies the localization settings of the browser. In most cases a REST response will dependon these headers.
- User-Agent (A)
- Cookie (C)
identifies the cookies sent by the browser. Typically REST responses only depend on a subset of these cookies, not on the complete cookie header. So for the digest computation you can configure which cookies to to ignore from this header field and, thus, to exclude from the digest computation. This server-wide configuration can be set in the WAS Admin Console, “Resource Environment Providers → “WP ConfigService” → custom properties” with the following syntax:
cookie.ignore.regex = digest\\.ignore.*||
where cookie1, cookie2, etc. are the cookies you want to exclude from digest computation. The regular expression is evaluated by an instance of the Java Pattern class. Per default the configuration excludes the LTPA tokens and the session cookie. ( cookie.ignore.regex = digest\\.ignore.*|LtpaToken|LtpaToken2|JSESSIONID).
- User identity (U)
is the identification of the user that is currently logged in. Most REST responses depend on this information because they serve access control restricted information.
- Accept-Encoding (E)
identifies the encodings that the browser can accept. REST services typically don't depend on this header directly, but the cacheable HTTP response does.
- Range (R)
used by download managers to address a byte range of a large response. REST services typically don't depend on this header directly, but the cacheable HTTP response does.
- Virtual Portal (V)
the ObjectID of the virtual portal
- Hostname (H)
identifies the host of WebSphere Portal. This information is important to generate different cache hits for proxy servers vs. direct access to the portal.
The request digest is based on all information above. Data sources however might depend on less information, so the request digest would be too strong and result in fewer cache hits than theoretically possible. As a consequence data sources can indicate their via optional interfaces, notably the com.ibm.portal.resolver.data.UserContextDataSource and the com.ibm.portal.resolver.data.VaryDataSource. Per default - if a data source does not specify anything special - we assume that the data source depends on all information mentioned above.
The fewer information however a data source depends on, the better is its cacheability. We call a digest that is based on fewer information than another digest "weak".
The digest is carried in the URL to allow caches to cache variations of a resource for different headers via different URLs. The following situations can occur:
- The URL does not contain digest information. In this case we redirect to a URL that contains the data source digest.
- The URL contains a digest, but the digest in the URL is based on a different set of request headers compared to the current request. In this case we redirect to a URL that contains the data source digest based on the current request.
- The URL contains a digest and the digest is based on the same header as the current request. However the digest is computed based on a smaller subset of these headers compared to the subset required by the data source. In this case we redirect to a URL that contains the datasource digest based on the current request.
- The URL contains a digest and the digest is based on the same header as the current request. However the digest is computed based on a larger subset of these headers compared to the subset required by the data source. In this case we do not redirect but accept the request. It is done to minimize the number of redirects at the price of fewer cache hits. If the goal was to optimize cache hits we would have to redirect to a URL that contains the data source digest.
- The URL contains a digest and the digest is based on the same header as the current request.
The digest also matches the data source digest for the addressed resource. This is the ideal case and we accept the request without sending a redirect.
Since the Cookie header field is a mixed bag of information that may or may not affect the response, the cachability of a response can be improved by ignoring certain cookies within the Cookie header
field and thus exclude them from the digest computation. This is done with the cookie.ignore.regex configuration property.
The cookie.ignore.regex parameter
Perform the following steps to add the
parameter to the portal resource environment provider:
- If necessary, start the WebSphere_Portal server.
- Log in to the WebSphere Application Server Administrative Console.
- Navigate to Resources -> Resource Environment -> Resource Environment Providers.
- Select WP ConfigService.
- Under Additional Properties, select Custom Properties.
- Click New.
- Specify the name of the required property and set the value of the property to the appropriate value as required.
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
Important: Any cookie that is set or modified by any component will cause the digests in the URLs to change, directly affecting the cache of those resources. 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 included in the cookie.ignore.regex list or at least matched successfully by the regular expression in that property. This will ensure that changes to that cookie's value will not have any adverse impact on performance by prematurely invalidating cache entries.
- Click Apply and save your changes.
- Log out of the WebSphere Application Server Administrative Console.
- Restart the WebSphere_Portal server.
Consider a data source that only depends on cookies (C) and the current user (U), but not on the accept language header (L) nor the user agent header (A). Let's denote this resource as CU. The power set picture shows the relationship of the digest of this resource to digests computed on the basis of other headers. Digests "down" the hierarchy are "weaker" digests and if encountered in the URL that addresses the CU data source would lead to a redirect. Digests "up" the hierarchy are "stronger" and can be accepted to serve the resource.
A URL with LCU e.g. would serve the CU without a redirect, whereas a URL with only C would not. The blue elements in the power set graph show all acceptable digests for resource CU.
So, how can it happen that a URL contains none or just an incompatible digest?
• The URL might use "early binding". In this mode the actual resource is resolved only after the URL has been accessed, not at URL generation time. The digest in the URL will therefore be the request digest LACU even if the addressed resource is CU. No redirect in this case, but non-optimal cache hits.
• The URL might have been generated "manually" without adding a digest at all. In this case we need to send a redirect.
• The URL might have been computed via relative URL semantics. Consider the following example. A CSS file is served via a URL with a digest A, it only depends on the user agent. This CSS references images using relative URLs, and these images depend also on the locale LA.
The URL to the CSS file could look like http://server/wps/mycontenthandler/digest!A/dav/file-store/default.css (note the digest A in the URL). Since the images are referenced via relative URL references, the image would be served via the URL
http://server/wps/mycontenthandler/digest!A/dav/file-store/info.gif. This URL also contains the digest A although the resource requires LA. This scenario would therefore lead to a redirect when serving the image.
• The headers (or cookies) or the user identity changed between URL generation and URL serving time. If these headers are part of the required digest, we send a redirect.