6 Caching and Compressing Content

This chapter introduces techniques to cache and compress content using Oracle Web Cache. It discusses cache population, consistency, and rules. The chapter describes the properties for configuring caching rules and expiration policies.

This chapter includes the following topics:

Section 6.1, "About Cache Population"
Section 6.2, "About Cache Consistency"
Section 6.3, "About Caching Decisions"
Section 6.5, "Introduction to Configuring Advanced Settings"
Section 6.4, "Introduction to Creating Caching Rules"
Section 6.6, "Basic Tasks for Configuring and Monitoring Caching Rules"
Section 6.7, "Configuring Expiration Policies"
Section 6.8, "Configuring and Monitoring Caching Rules"
Section 6.9, "Monitoring Summary Settings for Caching Rules"
Section 6.10, "Using the Surrogate-Control Response Header as an Alternative to Caching Rules"

6.1 About Cache Population

You define caching rules to determine which objects to cache. When you establish a caching rule, objects matching the rule are not cached until there is a client request for them. When a client first requests an object, Oracle Web Cache sends the request to the origin server. This request is a cache miss. Because this URL has an associated caching rule, Oracle Web Cache caches the object for subsequent requests. When Oracle Web Cache receives a second request for the same object, Oracle Web Cache serves the object from its cache to the client. This request is a cache hit.

When you stop Oracle Web Cache, the cache clears all objects. In addition, Oracle Web Cache clears and resets statistics.

See Section 6.3 for a description of how Oracle Web Cache determines cache population through caching rules.

6.2 About Cache Consistency

Consistency is crucial for the reliability of Oracle Web Cache. The following features ensure consistency between the cache and origin servers:

Section 6.2.1, "Expiration"
Section 6.2.2, "HTTP Cache Validation"
Section 6.2.3, "Invalidation"

6.2.1 Expiration

With expiration, Oracle Web Cache marks objects as invalid after a certain amount of time in the cache. Expirations are useful if you can accurately predict when content changes on an origin server or database. To prevent objects from remaining in the cache indefinitely, Oracle recommends creating expiration policies for all cached objects.

For instructions on creating expiration policies, see Section 6.7.

6.2.2 HTTP Cache Validation

Oracle Web Cache uses HTTP/1.1 validation models to determine how to best serve a response to clients. Validation works by the comparing two validators to determine if they represent the same or different entities. Specifically, Oracle Web Cache uses the If-Modified-Since and If-None-Match headers to determine the following validity:

Browser header is valid as compared with the cached copy's header
Cached copy's header is valid as compared with the origin server's header

Note:

Oracle Web Cache does not support weak validators for the If-None-Match validator. Oracle Web Cache supports all other If-None-Match request-header field formatting.

For further information about validation, see:

Section 13.3 Validation Model of the HTTP/1.1 specification available at http://www.ietf.org/rfc/rfc2616.txt for further information about the validation caching
Section 6.2.3 for instructions on invalidating content
Section 6.7 for instructions on configuring expiration policies

6.2.3 Invalidation

You use invalidation for content that does not have predictable expiration times. With invalidation , Oracle Web Cache marks objects as invalid. When objects are marked as invalid and a client requests them, they are removed and then refreshed with new content from the origin servers. You can choose to remove and refresh invalid objects immediately, or base the removal and refresh on the current load of the origin servers.

For further information about invalidation, see Chapter 7, "Invalidating Content."

6.3 About Caching Decisions

You can choose to cache or not to cache content for static objects, multiple-version objects, personalized pages, pages that support a session cookie, embedded URL parameter, or POST body parameter, and dynamic pages with caching rules.

You configure a caching rule by specifying caching attributes based on the URL or the Content-Type response header with Fusion Middleware Control, or you set the caching attributes for a specific object within a Surrogate-Control response-header field. Those objects matching the rule are not cached until there is a client request for them.

Oracle Web Cache uses the following priority to determine object cacheability:

Surrogate-Control response header
Caching rule configured with Fusion Middleware Control
Other HTTP headers:
- Authorization request header
- Proxy-Authorization request header
- Pragma: no-cache response header
- Warning response header
If any of these headers are present, then Oracle Web Cache does not cache the object.
Cookie values from Cookie request header and Set-Cookie response header
Cache-Control response header
Expires response header

The Surrogate-Control response-header field enables the origin server to override the caching rules configured through Fusion Middleware Control. When both a Surrogate-Control response header and a caching rule for the same object are present, Oracle Web Cache merges the two. For example, if there is a caching rule for an non-cacheable object set in Fusion Middleware Control with compression enabled, and the response header contains Surrogate-Control: max-age=30+60, then Oracle Web Cache respects both settings. Oracle Web Cache uses the max-age control directive from the Surrogate-Control response-header to cache the object and the compression setting from the caching rule. If there is a conflict between the Surrogate-Control response header and a caching rule, then Oracle Web Cache uses the settings from the Surrogate-Control response header.

If no caching rules or the Surrogate-Control response header are specified, then Oracle Web Cache behaves just as HTTP proxy cache does, that is, it relies on HTTP header information to determine what is cacheable. Generally, HTTP proxy caches store only pages with static content.

Notes:

You can pre-populate the cache using Web crawler freeware such as WGET to warm up the cache on restart or after bulk invalidation operations. See http://www.gnu.org/software/wget/wget.html for further information about WGET.
When you stop Oracle Web Cache, all objects are cleared from the cache. In addition, all statistics are cleared.

For a description of how Oracle Web Cache determines cache population, see Section 6.1.

6.4 Introduction to Creating Caching Rules

When you decide to create a caching rule for an object, determine first whether the rule for the object is for a specific site or global to all sites. Oracle Web Cache gives site-specific caching rules a higher priority than the global rules. After you determine that choice, you configure general attributes for the rule:

Information about the rule, such as its name, description, site, and whether or not to enable the rule
Actions for Oracle Web Cache to take when an incoming request matches a rule
Match criteria for Oracle Web Cache to locate the matching rule for incoming requests.

Select to base the match evaluation on the request URL expression, the response MIME type, or both criteria. If you do not select a match criteria, Oracle Web Cache matches the rule to all URLs and all MIME types.

Matching the evaluation on the MIME type makes sense when entering URL expressions becomes cumbersome. For example, the following shows a complicated URL expression for various image types:

\.(gif|jpe?g|png|bmp)$

Instead, you can select the MIME Type option, select Starts with, and enter the following string in the expression field:

image/

For most match evaluations, select the Starts with option, because the Content-Type response header typically has additional content parameter values.

You can also enter a list in the expression field, separated by commas. Continuing with the same example, if you want to match only GIF or JPEG responses, enter the following string in the expression field:

image/gif, image/jpeg

After you create caching rules, you order the priority of caching rules. Higher priority rules are matched first. Oracle Web Cache gives site-specific caching rules a higher priority than the global caching rules. When ordering caching rules for cacheable and non-cacheable objects, give the non-cacheable objects a higher priority than the cacheable objects.

In the rules shown in Table 6-1, rule 2 caches objects of the URL that use the GET and GET with query string methods, and rule 3 caches objects of the URL that use the POST method and a POST body matching action=search. If the order were reversed, all objects starting with /cec/cstage?ecaction=ecpassthru would be cached, including /cec/cstage?ecaction=ecpassthru2.

Table 6-1 Example of Priority for Different HTTP Methods

Priority	Match Criteria	HTTP Methods	POST Body Expression	Action
1	URL Expression: Regular Expression: `^/cec/cstage\?ecaction=ecpassthru2` Path Prefix: `/cec/cstage\?ecaction=ecpassthru2`	GET and GET with query string	N/A	Don't Cache
2	URL Expression: Regular Expression: `^/cec/cstage\?ecaction=ecpassthru.*` Path Prefix: `/cec/cstage\?ecaction=ecpassthru`	GET and GET with query string	N/A	Cache
3	URL Expression: Regular Expression: `^/cec/cstage\?ecaction=ecpassthru.*` Path Prefix: `/cec/cstage\?ecaction=ecpassthru`	POST Body Expression	`action=search`	Cache
4	MIME Type: `/image`	GET and GET with query string	N/A	Cache

For more information about specifying general attributes for caching rules and specifying priority, see Section 6.8.1

6.5 Introduction to Configuring Advanced Settings

In addition to general attributes, you can configure advanced settings, as described in the following topics:

Section 6.5.1, "Caching for Objects with Multiple Versions"
Section 6.5.2, "Caching for Objects with Embedded URL and POST Body Parameters"
Section 6.5.3, "Caching Error Responses"
Section 6.5.4, "Caching for Objects with Sessions"
Section 6.5.5, "Caching for Objects with Session-Encoded URLs"

6.5.1 Caching for Objects with Multiple Versions

Some pages have multiple versions, enabling categorization. Figure 6-1 shows the same object, https://oraclestore.oracle.com/OA_HTML/ibeCCtpItmDspRte.jsp?item=293017&section=11538, with different prices for customers and internal Oracle employees. While customers pass a cookie name and value of ec-400-id-acctcat=WALKIN, employees pass a cookie name and value of ec-400-id-acctcat=INTERNAL.

Figure 6-1 Multiple-Version Object

Description of "Figure 6-1 Multiple-Version Object"

You can configure Oracle Web Cache to recognize and cache multiple-version pages by using the:

Values of the cookie for the page
HTTP request headers for the page

For those objects that use a cookie (sometimes referred to as a category cookie), configure caching rules that specify the cookie name and whether to cache versions of the object that do not use the cookie.

When a client sends an initial request for a multiple-version object, Oracle Web Cache passes the request to the origin server. In its response, the origin server includes a Set-Cookie response-header with the category cookie and its value:

Set-Cookie:cookie=value

Oracle Web Cache does not cache this initial response. Upon receiving the Set-Cookie response-header field, the client stores the cookie in memory. With its next request to the same origin server, the client includes the Cookie request-header field with the category cookie name and value that was received in the last response:

Cookie:cookie=value

Oracle Web Cache still forwards the request to the origin server, which responds with or without the Set-Cookie header. Oracle Web Cache then evaluates whether the cookie and its value set in the Set-Cookie response-header matches the cookie and its value set in the Cookie request-header. If the cookie and value match, then the response is cached. Oracle Web Cache consider the absence of the Set-Cookie header a match. If cookie and its value do not match, then the response is not cached. After versions of the object are cached, Oracle Web Cache uses the value of the cookie in the client's request to serve the appropriate version of the object to the client browser.

Note:

Oracle Web Cache does not cache the Set-Cookie response header field.

Table 6-2 shows four different versions of same URL, http://www.dot.com/page1.htm. The URL uses a cookie named user_type, which supports client requests that contain cookie values of Customer, Internal, and Promotional. You can configure Oracle Web Cache to recognize the user_type cookie, enabling Oracle Web Cache to cache three different objects. In addition, you can configure Oracle Web Cache to cache a fourth object for those requests that do not use a cookie.

Table 6-2 Multiple-Version Object with Different Cookie Values

Version	URL	Cookie Name/Value
1	`http://www.dot.com/page1.htm`	`user_type=Customer`
2	`http://www.dot.com/page1.htm`	`user_type=Internal`
3	`http://www.dot.com/page1.htm`	`user_type=Promotional`
4	`http://www.dot.com/page1.htm`	No cookie

For those objects that have different versions based on HTTP request headers, configure caching rules that specify the HTTP request header. HTTP request headers enable clients to pass additional information about the request and about themselves. Oracle Web Cache uses the header to serve the appropriate version of the URL to clients.

Oracle Web Cache supports all valid HTTP request headers. Table 6-3 lists the HTTP request-header fields supported by Fusion Middleware Control. You can specify any of the standard or other HTTP request-header fields with the Surrogate-Control response-header field.

Table 6-3 HTTP Request-Header Field

Header Field	Description
`Accept`	Specifies which media types are acceptable for the response Example: `Accept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, image/png, /`
`Accept-Charset`	Specifies which character sets are acceptable for the response Example: `Accept-Charset: iso-8859-1,*,utf-8`
`Accept-Encoding`	Restricts the content-encodings that are acceptable in the response Example: `Accept-Encoding: gzip`
`Accept-Language`	Specifies the set of languages that are preferred as a response Example: `Accept-Language: en`
`User-Agent`	Contains information about the client that initiated the request Example: `User-Agent: Mozilla/4.61 [en] (WinNT; U)`

Note:

By default, Oracle Web Cache does not interpret the values of these HTTP request headers. If the values for two pages are different, Oracle Web Cache caches both pages separately.

This issue is especially problematic with the User-Agent request header, whereby the browser type, version, and operating system can result in too many duplicate cache entries. For example, if one request sends an HTTP request-header field of User-Agent: Mozilla/4.0 (compatible; MSIE 5.5; Windows) and another request sends an HTTP request-header field of User-Agent: Mozilla/4.0 (compatible; MSIE 5.0; Windows; DigExt) for different versions of Internet Explorer, Oracle Web Cache serves two pages for the two requests.

You can override this behavior for the User-Agent request header by configuring Oracle Web Cache to cache and serve the same page for the same browser type, as described in Section 6.8.4.

For configuration details, see Section 6.8.2.

6.5.2 Caching for Objects with Embedded URL and POST Body Parameters

By default, Oracle Web Cache distinguishes origin server responses by the request URLs. However, if the request contains an embedded URL or POST body parameter, the request URL to the same page content is distinct for each session. Therefore, Oracle Web Cache caches responses for each of the distinct URLs. This can result in low cache hit rates and redundantly cached objects.

By configuring Oracle Web Cache to ignore the value of embedded URL or POST body parameters, you enable Oracle Web Cache to serve one cached object to multiple sessions requesting the same page. Oracle Web Cache caches the response to the first request and serves subsequent requests for the page from its cache.

Consider user Jane Doe accessing a page with a request URL of:

https://oraclestore.oracle.com/OA_HTML/ibeCCtpSctDspRte.jsp?section=10103&session_ID=33436

User John Doe accesses the same page with a request URL of:

https://oraclestore.oracle.com/OA_HTML/ibeCCtpSctDspRte.jsp?section=10103&session_ID=33437

In addition, this page contains the following POST body for Jane Doe and John Doe, respectively:

section=1013
&session_ID=3346

section=1013
&session_ID=3347

The only distinct part to the request URL and the POST body is the value of the session_ID parameter. Rather than caching and serving two versions of the same object, you can configure Oracle Web Cache to ignore the value of session_ID so that one cached object can be served to both users.

To configure parameters to ignore, establish global parameters to be applied to all caching rules or site-specific parameters to be applied to caching rules for a specific site. See Section 6.8.3.

6.5.3 Caching Error Responses

If there is a problem on the origin server that does not result in a 200 OK HTTP response status for a request that matches this rule, then Oracle Web Cache does not attempt to send the request to the origin server again. Instead, it serves the cached HTTP error, saving origin server resources for known bad responses.

By default, Oracle Web Cache does not cache any non-200 OK HTTP responses. If you want these errors to be cached, then you must configure caching rules to specifically cache error responses. Oracle Web Cache caches the error pages according to the expiration policy of the rule. After the problem is resolved, invalidate the HTTP error responses.

For configuration details, see Section 6.8.5.

6.5.4 Caching for Objects with Sessions

You can specify how Oracle Web Cache serves requests with the existence or nonexistence of session cookies, embedded URL parameters, or POST body parameters. You can choose to:

Serve or not serve cached objects to requests that have a session cookie, embedded URL parameter, or POST body parameter
Serve or not serve cached objects to requests that do not have a session cookie, embedded URL parameter, or POST body parameter

For example, if you want the first request of a new user to establish a session from the origin server, then choose to serve cached objects to requests that have the session cookie or parameter, but do not serve cached objects to requests that do not have the session cookie or parameter.

When you choose to serve for both, you can then specify if requests with or without the session cookie or parameter can share the same cached object. Oracle Web Cache uses a default string for those requests without the cookie or parameter.

For configuration details, see Section 6.8.6.

6.5.5 Caching for Objects with Session-Encoded URLs

The section Section 6.5.2 describes how you can ignore the value of embedded URL or POST body parameters for objects with identical content for all sessions. However, in some cases, the HTML content of objects is programmed with hyperlink tags, such as <A HREF=...>, that contain embedded session information to distinguish users. These links are called session-encoded URLs. The use of session-encoded URLs results in responses that vary slightly from session to session.

You can configure Oracle Web Cache to substitute sessions within HTML hyperlink tags with the session values obtained from a session cookie, embedded URL parameter, or POST body parameter. By configuring session value substitution in combination with ignoring the value of embedded URL parameters, you can configure Oracle Web Cache to cache one object for multiple sessions, even if the session parameter values in session-encoded URLs vary.

Note:

Oracle Web Cache does not cache the Set-Cookie response header field.

Continuing with the example from Section 6.5.2, assume that Jane Doe and John Doe are again assigned an embedded URL parameters of session_ID=33436 and session_ID=33437 by the origin server. The page shown in Figure 6-2 has several <A HREF=...> links that include the session_ID parameter. The Oracle Database Standard Edition link under the Oracle Database heading for Jane Doe uses the following HTML code:

<A HREF="http://oraclestore.oracle.com/OA_HTML/ibeCCtpSctDspRte.jsp?section=10166&session_ID=334326">Oracle Database Standard Edition</A>

The same link for John Doe uses the following HTML code:

<A HREF="http://oraclestore.oracle.com/OA_HTML/ibeCCtpSctDspRte.jsp?section=10166&session_ID=334327">Oracle Database Standard Edition</A>

By using the value of the session_ID embedded URL parameter, Oracle Web Cache substitutes the correct session information for Jane Doe and John Doe.

Figure 6-2 Session-Encoded URLs

Description of "Figure 6-2 Session-Encoded URLs"

After the cache is populated with a page that contains session-encoded URLs, other requests for the page are served from the cache, regardless of whether the request has a session cookie, embedded URL parameter, or POST body parameter. If the request does not contain a session cookie or embedded URL parameter, you can configure Oracle Web Cache to substitute the session information in the session-encoded URLs with a configurable default string.

For configuration details, see Section 6.8.7.

6.6 Basic Tasks for Configuring and Monitoring Caching Rules

The following provides a summary of the steps required to cache and monitor objects:

Configure expiration policies. See Section 6.7.
Create sites for which Oracle Web Cache manages requests. See Section 2.11.3 and Section 2.11.4.
Configure general settings for a caching rule. See Section 6.8.1.
Configure advanced settings for a caching rule:
- Configure cookie and HTTP request-header fields for rules supporting multiple-version objects. Section 6.8.2.
- Configure Oracle Web Cache to ignore the value of embedded URL or POST body parameters. See Section 6.8.3.
- Configure error responses for rules. See Section 6.8.5.
- Configure session settings for rules. See Section 6.8.6.
- Configure support for session-encoded URLs. See Section 6.8.7.
Restart Oracle Web Cache to apply caching rule. See Section 2.13.
Monitor statistics for caching rules. See Section 6.9.
View popular requests. See Section 8.2.

6.7 Configuring Expiration Policies

Prior to creating a caching rule, you create expiration policies. Later, when you create caching rules, you specify an expiration policy to apply with the caching rule.

You can create expiration policies that specify when to expire objects in the cache. In addition, you can specify how long objects can reside in the cache after they have expired. When an object expires, Oracle Web Cache removes it either immediately or as permitted by origin server capacity up to a maximum time limit.

To create an expiration policy:

Navigate to the Web Cache Home page in Fusion Middleware Control. See Section 2.6.2.
From the Web Cache menu, select Administration and then Expiration.

The Expiration Policies page displays.
Click Create.

The Create Expiration Policy dialog displays.
In the Objects Expire section, specify when to expire objects by selecting an option:
- As per HTTP Expires Header: Select this option to respect the HTTP Cache-Control or Expires response-header fields. This is the default.
- After Cache Entry: Select this option to base expiration on when the objects entered the cache. Enter the time to expire the objects in the Time Limit field.
- After Creation: Select this option to base expiration on when the objects were created, as indicated by the origin server. Enter the time to expire the objects in the Time Limit field.
In the Action On Expired Objects section, specify how you want Oracle Web Cache to process objects after they have expired:
- Remove Immediately: Oracle Web Cache marks objects as invalid and then removes them immediately. An object is refreshed from the origin server when the cache receives the next request for it.
- Refresh on Demand as Origin Server Permits: Oracle Web Cache marks objects as stale and then refreshes them based on origin server capacity. Oracle Web Cache may serve the stale content when the origin server is heavily loaded. Enter the maximum time in which the objects can reside in the cache and be served stale in the Time Limit field.
Click OK to apply changes.
Restart Oracle Web Cache. See Section 2.13.

6.8 Configuring and Monitoring Caching Rules

This section describes how to configure caching rules for Oracle Web Cache. It includes the following topics:

Section 6.8.1, "Configuring General Rule Settings"
Section 6.8.2, "Configuring Settings for Rules with Multiple Versions of the Same Object"
Section 6.8.3, "Excluding the Value of Embedded URL or POST Body Parameters"
Section 6.8.4, "Recognizing Similar Browser Types for Multiple-Version Objects Containing HTTP Request Headers"
Section 6.8.5, "Configuring Error Responses for Rules"
Section 6.8.6, "Configuring Session Caching Rules"
Section 6.8.7, "Configuring Support for Session-Encoded URLs"
Section 6.8.8, "Configuring Rules for Popular Pages with Session Establishment"

6.8.1 Configuring General Rule Settings

Before you create a caching rule, determine first whether the rule for the object is for a specific site or global to all sites. Oracle Web Cache gives site-specific caching rules a higher priority than the global rules.

For more information about caching decisions, see Section 6.3.

To create a caching rule:

Navigate to the Web Cache Home page in Fusion Middleware Control. See Section 2.6.2.
From the Web Cache menu, select Administration and then Caching Rules.

The Caching Rules page displays.
Create a new rule.
1. From Site Specific Caching Rules or Global Caching Rules section, click Create.
  
  The Create Caching Rule page displays with the General tab in view.
2. Complete the elements using the descriptions in Table 6-4.
  
  When completing the elements, in the Match Criteria section, select to base match evaluation on the request URL expression, the response MIME type, or both criteria. If you do not select a match criteria, Oracle Web Cache matches the rule to all URLs and all MIME types.
  
  If you find entering URL expressions is cumbersome for your rules, select the MIME Type option in the Match Criteria section. See Section 6.4 for further information about using the MIME Type option in place of complicated URL expressions.
3. Click OK to create the caching rule.
4. Click the Caching Rules breadcrumb at the top of the page, or from the Web Cache menu, select Administration and then Caching Rules to navigate back to the Caching Rules page.
Repeat Step 3 for each additional rule.
Use the Move Up and Move Down icons to change the order in which the rules are matched against requests.

The order of the rules is important. Oracle Web Cache matches higher priority rules first.
In the Caching Rules page, click Enable to enable rules.

If you do not click Enable, Oracle Web Cache ignores any the settings for the rule.
Click Apply to save the configuration for the request filter.
Restart Oracle Web Cache. See Section 2.13.

Table 6-4 Caching Rules - General Page

Element	Description
Name	Enter a string that uniquely identifies the caching rule.
Description	Enter a descriptive comment about the caching rule.
Enabled	Select to enable the caching rule; deselect to disable the caching rule temporarily without losing the rule definition.
Site	Displays the site for which to apply this rule. If you do not see the site required, create one, following the procedure in Section 2.11.3.
Cache	Select this option to instruct Oracle Web Cache to cache content; deslect this option to instruct Oracle Web Cache to forward requests to the origin server and to not cache the content.
Expiration	From the list, select an expiration policy to apply to the objects. If you do not see an expiration policy suitable for the objects, click the Expiration Policies link.
Compress	S elect this option to instruct Oracle Web Cache to serve compressed cacheable and non-cacheable objects to browsers. To enable compression for this rule, you must also enable compression for the site. To set the compression property for a site, see Section 2.11.3. Oracle Web Cache automatically disables compression for some common file types which are known to be already compressed. Oracle recommends not compressing content for these file type, including GIF, JPEG, and PNG images, or files that are already compressed with utilities like WinZip or GZIP. Compressing these files incurs additional overhead without gaining any compression benefit. See Section 1.2.5 to better understand when Oracle Web Cache automatically disables compression.
Match URL By	Select to base the match evaluation on the URL expression: Select the expression type: - File Extension: Select to apply the caching rule to objects ending in a particular file extension, such as `.gif`. In the accompanying field, enter the file extension. Because Oracle Web Cache internally starts the file extension with a period (`.`), it is not necessary to enter it. - Path Prefix: Select to apply the caching rule to objects matching a path prefix. In the accompanying field, enter the path prefix of the objects. Start the path with `/`; do not start the path with `http://host_name:port/`. The prefix is interpreted literally, including reserved regular expression characters. These characters include periods (`.`), question marks (`?`), asterisks (`*`), brackets (`[]`), curly braces (`{}`), carets (`^`), dollar signs (`$`), and backslashes (`\`). - Regular Expression: Select to apply the caching rule to objects matching regular expression syntax. In the accompanying field, enter the regular expression of the objects. Remember to use "`^`" to denote the start of the URL and "`$`" to denote the end of the URL. Click the Case Insensitive Match check box to match requests regardless of the case. If you do not select this check box, the rule bases the match on the case.
MIME Type	Select to base the match evaluation on the `Content-Type` response header: Select an operation value to determine where Oracle Web Cache searches for the expression value in the response's `MIME` type: -Equals: Select to instruct Oracle Web Cache to match the `MIME` type if it equals the expression. -Starts With: Select to instruct Oracle Web Cache to match the `MIME` type if it starts with the expression. -Contains: Select to instruct Oracle Web Cache to match the `MIME` type if it contains the expression. For most match evaluations, select the Starts with option, because the `Content-Type` response header typically has additional content parameter values. If you select Equals, then the match may not work as you expect. In the accompanying field, enter the string value that you want Oracle Web Cache to compare against the response's `MIME` type. You can enter a list in the expression field, separated by commas.
HTTP Methods	Select one or more of the following HTTP request methods: GET: An HTTP request method used for simple requests for Web pages. A GET method is made up of a URL. Requests for pages that use the GET methods are typically cached. GET with query string: An HTTP request method made up of a URL and a query string containing parameters and values. POST Body Expression: An HTTP request method used for requests that modify the contents of the data store on the application Web server, such as posting a message to a mailing list, submitting forms for registration purposes, or adding entries to the database. Note: If your Web site's GET with query string or POST methods are used for forms that make changes to the origin server or database, do not select GET with query string or POST Body Expression. Select these options only if the forms are used in search forms.
Required Request Parameters	Click Add to enter an embedded URL parameter or POST body parameter and its value in the corresponding Parameter Name and optional Value fields. Notes: If you selected Regular Expression from the Match URL By list, you either use the Required Request Parameters section or manually enter the embedded URL parameters alphabetically in the accompanying Match URL By field. When you use the Required Request Parameters section, the embedded URL parameters are automatically sorted. See Section 6.8.1.1 for information about how to specify parameters in the accompanying Match URL By field. If you selected POST in the HTTP Methods section and do not specify POST body parameters in this section, specify the HTTP POST body in the accompanying POST Body Expression field. To apply this rule to any POST request body, enter `.*`" in the field.

6.8.1.1 Regular Expression Parameters

The request URL that client browsers send to Oracle Web Cache and the internal URL expression that Oracle Web Cache uses for that request are different. When Oracle Web Cache serves a page request, it alphabetically sorts any embedded URL parameters of the URL. However, the caching rules are matched against only the internal representation of the URL in which any embedded URL parameters are sorted. To ensure caching rules are matched correctly, you either use the Required Request Parameters section or manually enter the embedded URL parameters alphabetically in regular expression syntax in the Match URL By field. When you use the Required Request Parameters section, the Oracle Web Cache automatically sorts the embedded URL parameters.

For example, consider the following URL:

http://my.oracle.com/servlet/page?_pageid=53&_dad=moc&_schema=MOC

If you enter the regular expression without manually sorting the embedded URL parameters in the Match URL By expression field, ^/servlet/page\?_pageid=53&_dad=moc&_schema=MOC$, then the caching rule does not match the internal representation of the URL used by Oracle Web Cache. To ensure matching, you must enter the regular expression in the URL Expression field as:

^/servlet/page\?_dad=moc&_pageid=53&_schema=MOC$

6.8.2 Configuring Settings for Rules with Multiple Versions of the Same Object

For more information about caching multiple-version objects, see Section 6.5.1.

To specify a caching rule for multiple-version objects:

For sites with category cookies that affect caching, specify which category cookies whose values Oracle Web Cache uses to cache and identify multiple-version objects:
1. Navigate to the Web Cache Home page in Fusion Middleware Control. See Section 2.6.2.
2. From the Web Cache menu, select Administration and then Multi-Version Cookies.
  
  The Multi-Version Cookie page displays.
3. Click Create.
4. In the Cookie Name field, enter the name of the cookie.
5. Click the Cache If Absent check box to cache versions of the object that do not contain this cookie. This option enables Oracle Web Cache to serve objects from the cache for client requests that do not contain this cookie. Keep this option unchecked to not cache versions of objects that do not contain this cookie.
6. Click Apply.
Create a caching rule. See Section 6.8.1.
From Site Specific Caching Rules or Global Caching Rules section of the Caching Rules page, select the rule you created and click Edit.

The Create Caching Rule page displays.
Click the Multi Versioning tab.
For multiple-version objects that rely on a cookie or HTTP request header, specify the cookies or HTTP request headers to enable Oracle Web Cache to cache multiple versions of an object and serve the appropriate version to requests.

For multiple-version objects with cookies, select the cookie you created in Step 1.

For multiple-version objects with HTTP headers, from the By HTTP Request Headers section, select one or more of the headers from the Available Headers and click Move or Move All to move them to the Selected Headers list.
Click OK to apply changes.
Restart Oracle Web Cache. See Section 2.13.

6.8.3 Excluding the Value of Embedded URL or POST Body Parameters

For more information about configuring Oracle Web Cache to ignore the value of parameters can enable Oracle Web Cache to serve one cached object to multiple sessions, see Section 6.5.2.

You have two configuration options for specifying parameters to ignore. You can:

Establish global parameters to be automatically applied to all global caching rules and site-specific caching rules.
Specify site-specific parameters to be automatically applied to caching rules for that site.

To establish global parameters:

From Oracle Web Cache Manager, in the navigator frame, select Origin Servers, Sites, and Load Balancing > Site Definitions. See Section 2.7.2.

The Site Definitions page displays.
Click Edit Global URL Parameters to Ignore to specify global parameters for all sites.

The Global URL Parameters to Ignore dialog displays.
In the Parameters to Ignore field, specify the global parameters. Separate multiple parameters by commas or blank spaces.
Click Submit.
Click Apply Changes.
Restart Oracle Web Cache. See Section 2.13.
Create a site-specific caching rule. See Section 6.8.1

To establish site-specific parameters:

From Oracle Web Cache Manager, in the navigator frame, select Origin Servers, Sites, and Load Balancing > Site Definitions. See Section 2.7.2.

The Site Definitions page displays.
Select a site, and then click Show/Edit Selected.

The Show/Edit Site Definition dialog displays.
In the URL Parameters to Ignore field, specify the site-specific parameters. Separate multiple parameters by commas or blank spaces.
Click Submit.
Click Apply Changes.
Restart Oracle Web Cache. See Section 2.13.
Create a site-specific caching rule. See Section 6.8.1

6.8.4 Recognizing Similar Browser Types for Multiple-Version Objects Containing HTTP Request Headers

By default, Oracle Web Cache does not interpret the values of the HTTP request headers. When the Multiple Objects with the Same Selector by Other Headers for the User-Agent request-header field is selected in Fusion Middleware Control and the value of the User-Agent request header of the same URL differ, then Oracle Web Cache caches both pages separately. For example, if one request sends an HTTP request header of User-Agent: Mozilla/4.0 (compatible; MSIE 5.5; Windows) and another request sends an HTTP request header of User-Agent: Mozilla/4.0 (compatible; MSIE 5.0; Windows; DigExt) for different versions of Internet Explorer, Oracle Web Cache caches two separate pages.

You can override this default behavior by configuring Oracle Web Cache with a User-Agent pattern string for a particular client. For the affected multiple-version objects, Oracle Web Cache adds an x-Oracle-Mapped-User request-header field, and uses the value of the string rather than the entire User-Agent value:

x-Oracle-Mapped-User: MAPPEDUSERAGENT_String

To configure Oracle Web Cache to cache and serve the same page for each browser type:

Create a caching rule for the pages that support the User-Agent request header, as described in Section 6.8.2, ensuring you select the User-Agent header.

Use a text editor to open webcache.xml, located in:

(UNIX) ORACLE_INSTANCE/<instance_name>/config/WebCache/<webcache_name>
(Windows) ORACLE_INSTANCE\<instance_name>\config\WebCache\<webcache_name>

Locate the GLOBALCACHINGRULES element.

For each browser type, add the following subelements in the next line after the GLOBALCACHINGRULES element:

<USERAGENTREMAPRULE MATCHSTRING="browser" MAPPEDUSERAGENT="x-Oracle-Mapped-User-Agent_value" MAPTYPE="USERAGENT"/>

If you enter multiple entries, order them according to how you want Oracle Web Cache to match. The order of these rules work in the same fashion as priority works for caching rules.

Table 6-5 describes how to enter values for the subelements.

Table 6-5 GLOBAL CACHINGRULES Subelements

Subelement Description

Subelement	Description
`MATCHSTRING`	Enter the pattern that used to match the incoming request header. Note: You can use the wildcard `` to pattern match for multiple browser type variants. For example, `Mozilla` can be used to match all variations of Mozilla.
`MAPPEDUSERAGENT`	Enter a unique value of the `User-Agent` pattern that to be added to the `x-Oracle-Mapped-User-Agent` request header by Oracle Web Cache.
`MAPTYPE`	Enter `USERAGENT` to pattern match on the `User-Agen`t request header.

MATCHSTRING

Enter the pattern that used to match the incoming request header.

Note: You can use the wildcard * to pattern match for multiple browser type variants. For example, Mozilla* can be used to match all variations of Mozilla.

MAPPEDUSERAGENT

Enter a unique value of the User-Agent pattern that to be added to the x-Oracle-Mapped-User-Agent request header by Oracle Web Cache.

MAPTYPE

Enter USERAGENT to pattern match on the User-Agent request header.

The following webcache.xml fragment shows the User-Agent remapping:

<USERAGENTREMAPRULE MATCHSTRING="MSIE *" MAPPEDUSERAGENT="MSIE" MAPTYPE="USERAGENT"/>
<USERAGENTREMAPRULE MATCHSTRING="Mozilla*" MAPPEDUSERAGENT="MOZ" MAPTYPE="USERAGENT"/>

If an incoming request does not match any of the rules, Oracle Web Cache appends a default mapping to the request. The default value of the x-Oracle-Mapped-User-Agent header is DEFAULT_USER_AGENT.

These mapping rules are executed for every incoming request. If you create several mapping rules, you may experience a performance degradation.

Locate the <MULTIVERSIONHEADERSRULE> subelement of CACHEABILITYRULE for the caching rule created in Step 0.
```
<MULTIVERSIONHEADERSRULE>
     <HTTPHEADER NAME="User-Agent"/>
</MULTIVERSIONHEADERSRULE>
```
To match on the value of the MAPPEDUSERAGENT string rather than the entire User-Agent value, change the User-Agent header to x-Oracle-Mapped-User-Agent in the HTTPHEADER attribute of the rule:
```
<MULTIVERSIONHEADERSRULE>
     <HTTPHEADER NAME="x-Oracle-Mapped-User-Agent"/>
</MULTIVERSIONHEADERSRULE>
```
Save webcache.xml.
Restart Oracle Web Cache using opmnctl. See Section 2.13.1.

6.8.5 Configuring Error Responses for Rules

To understand how you can cache HTTP error responses to save origin server resources, see Section 6.5.3.

To create a caching rule for an error response:

Create a caching rule. See Section 6.8.1.
From the Site Specific Caching Rules or the Global Caching Rules section of the Caching Rules page, select the rule you created and click Edit.

The Create Caching Rule page displays.
Click the Error Responses tab.
Select the HTTP error codes you want Oracle Web Cache to cache and serve for this rule.

Ensure the origin server generates the HTTP error itself.
Click OK to apply changes.
Restart Oracle Web Cache. See Section 2.13.

6.8.6 Configuring Session Caching Rules

To understand how Oracle Web Cache serves requests with the existence or nonexistence of session cookies, embedded URL parameters, or POST body parameters, see Section 6.5.4.

To specify how session-related pages are served by Oracle Web Cache:

From the Web Cache menu, select Administration and then select Session Configuration.

The Session Definitions page displays.
Create a session definition in the Session Definitions table. See Section 2.12.
Specify session policy settings:
1. In the Session Policy Configuration section, click Create.
  
  A new row in the table appears.
2. From the Session Name list, select the session you created in Step 2.
3. In the Cache column, select the Without Session check box for Oracle Web Cache to cache versions of objects that do not use the cookie or parameter; select No for Oracle Web Cache not to serve objects from the cache for requests without the session information.
4. In the Cache column, select the With Session check box for Oracle Web Cache to cache versions of objects that use the cookie or parameter.
5. In the Substitute Default Value column, select the check box to instruct Oracle Web Cache to cache one version of the object. For those requests without a cookie or parameter, a default value is used. Do not select the check box to instruct Oracle Web Cache to cache two different versions of the object. Oracle Web Cache serves one version to those requests that support the cookie or parameter and serves the other version to those requests that do not support the cookie or parameter.
Create a caching rule. See Section 6.8.1.
Associate session policies with a caching rule:
1. From the Site-Specific Caching Rules or the Global Caching Rules section of the Create Caching Rule page, select the rule you created and click Edit.
  
  The Edit Caching Rules page displays.
2. Click the Sessions tab.
3. From the Session Definition list, select the sessions you created in Step 2 and defined a policy for in Step 3.
4. Click OK to apply changes.
Restart Oracle Web Cache. See Section 2.13.

6.8.7 Configuring Support for Session-Encoded URLs

You can configure Oracle Web Cache to substitute sessions within HTML hyperlink tags with the session values obtained from a session cookie, embedded URL parameter, or POST body parameter. To understand how Oracle Web Cache can cache one object for multiple sessions, even if the session parameter values in session-encoded URLs vary, see Section 6.5.5.

To substitute session values in session-encoded URLs:

Navigate to the Web Cache Home page in Fusion Middleware Control. See Section 2.6.2.
From the Web Cache menu, select Administration and then select Session Configuration.

The Session Definitions page displays.
Create a session definition in the Session Definitions table. See Section 2.12.

When entering data for the Default Value field, enter a default string for the value of the embedded URL parameter.

Oracle Web Cache uses the value you enter in the Default Value field for those requests without the value for an embedded URL parameter. For these requests, Oracle Web Cache substitutes the value with a default string. The string defaults to default. For example, the following <A HREF=...> contains a session_ID parameter without a value:
```
<A HREF="https://oraclestore.oracle.com/OA_HTML/ibeCCtpSctDspRte.jsp?section=11886&session_ID=">Master Index</A>
```
If the string is set to default, Oracle Web Cache substitutes the value with default.
```
<A HREF="https://oraclestore.oracle.com/OA_HTML/ibeCCtpSctDspRte.jsp?section=11886&session_ID=default">Master Index</A>
```
Create a caching rule. See Section 6.8.1.
From the Site Specific Caching Rules or the Global Caching Rules section of the Caching Rules page, select the rule you created and click Edit.

The Create Caching Rule page displays.
Click the Sessions tab.
Click Process for Session-Encoded URLs.
Click OK to apply changes.
Restart Oracle Web Cache. See Section 2.13.

6.8.8 Configuring Rules for Popular Pages with Session Establishment

Some Web sites require users to have sessions while surfing most pages. To preserve the session requirement, create a session caching rule for those pages. This way, Oracle Web Cache always forwards a request without a session to the origin server.

For some popular site entry pages, such as "/", that typically require session establishment, session establishment effectively makes the page non-cacheable to all new users without a session. To cache these pages while preserving session establishment, make the following minor modifications to your application:

Create a blank page for the entry URL, such as "/", that redirects to the real entry page.
Configure the origin server to create a session when the blank page is requested without a session cookie.
Create a session caching rule for the real entry page and the blank page, as described in Section 6.8.6, and click both the Cache With and Cache Without options.

With this configuration, all initial user requests to the entry URL first go to the blank page, which requires minimal resources to generate. The clients receive the response and session establishment from the application Web server. Subsequent redirected requests to the entry page carry the session, enabling the entry page to be served out of the cache.

Another solution is to use a Javascript that sets a session cookie for the pages requiring sessions:

Create a Javascript that sets a session cookie when one does not exist.
Add the Javascript to each of the pages that require the session.
Create caching rules for the Javascript and the session pages, as described in Section 6.8.1 and Section 6.8.6.

Note:

Using the Javascript solution, it is not necessary to create a session caching rule for the pages requiring sessions.

6.9 Monitoring Summary Settings for Caching Rules

Fusion Middleware Control provides statistics for assessing the effectiveness of configured caching rules.

To view caching-rule statistics:

Navigate to the Web Cache Home page in Fusion Middleware Control. See Section 2.6.2.
From the Web Cache menu, select Administration and then Caching Rules.

The Caching Rules page displays.
Scroll to the far right to view the statistics for a caching rule:
- Multi-Versionings: Shows whether this caching rule contains settings for requests with multiple versions.
- Sessions: Shows whether this caching rule contains settings for requests with a cookie, embedded URL parameter, or POST body parameter with user session information.
- Error Responses: Shows whether this caching rule contains settings for requests with HTTP error responses.
- Matched: Displays the number of requests that matched the caching rule.

See Section 8.2 to view the objects cached by Oracle Web Cache

6.10 Using the Surrogate-Control Response Header as an Alternative to Caching Rules

In addition to, or as an alternative to, creating caching rules with Fusion Middleware Control, application developers can choose to store many of the caching attributes in the header of an HTTP response message. This feature enables the application Web server to override the settings configured through Fusion Middleware Control interface, as well as allow other third-party caches to use Oracle Web Cache caching attributes. All except the following attributes described in Section 6.8 are supported:

Session caching rules
HTTP error response caching rules

To enable this feature, set the HTTP response with the Surrogate-Control response-header field as described in the following section.

For a description of how Oracle Web Cache uses caching attributes from the Surrogate-Control response header and Oracle Web Cache Manager to determine cache population, see Section 6.1.

6.10.1 Surrogate-Control Response-Header Field

The Surrogate-Control response-header field enables application developers to specify caching attributes of an object. This response-header field enables the application Web server to override the caching rules configured through administrative interfaces Fusion Middleware Control or Oracle Web Cache Manager.

The Surrogate-Control response-header field supports the following syntax:

Surrogate-Control:[content=content_type, content_type,..]
[no-store][max-age=expiration_time[+removal_time]]
[vary=headers(header header...)][cookie(cookie_name cookie_name...)]
[compress=yes|no]

Table 6-6 describes the supported control directives.

Table 6-6 Control Directives for Surrogate-Control

Control Directive	Description
`content`	Specify what kind of processing is required: `"ORAESI/9.0.4"` to process ESI tags with Oracle-proprietary additions for content assembly and partial page caching. `"ORAESI/9.0.4"` supports all the ESI tags provided by Oracle Web Cache in 10g (9.0.4) and later releases. `"ORAESI/9.0.2"` to process ESI tags with Oracle proprietary additions for content assembly and partial page caching. `"ORAESI/9.0.2"` supports all the ESI tags provided by Oracle Web Cache in Release 2 (9.0.2 and 9.0.3). `"ESI/1.0"` to process standard ESI tags for content assembly and partial page caching `"ESI-Inline/1.0"` to process `<esi:inline>` tags `"ESI-INV/1.0"` to process `<esi:invalidate>` tags `"webcache/1.0"` to process the `<!-- WEBCACHETAG-->` and `<!-- WEBCACHEEND-->` tags for personalized attributes `"ORAESI/9.0.2"`, `"ESI/1.0"`, and `"ESI-Inline/1.0"` are subsets of `"ORAESI/9.0.4"`. In this release, you specify only `"ORAESI/9.0.4"` for ESI assembly, `"ESI-INV/1.0"` for inline invalidation, or `"webcache/1.0"` for personalized attributes. For further information about the ESI tags supported for each processing version, see Chapter 11, "Caching Dynamic Content with ESI Language Tags."
`no-store`	Specify for Oracle Web Cache to not cache the object.
`vary`	Specify the HTTP request headers or cookies to instruct Oracle Web Cache to cache and identify multiple-version objects. Use the following format: `vary=[headers(header[/f] );] [cookies(cookie_name[/f] )]` Specify /f to instruct Oracle Web Cache to only cache versions of the object based on the existence of the HTTP request headers or cookies. Exclude `/f` to instruct Oracle Web Cache to cache versions of the object, regardless of whether the HTTP request headers or cookies exist. Usage notes: Specify at least one HTTP header or cookie. If you specify both HTTP request headers and cookies, specify the HTTP request header before the cookies. Use zero or more spaces between the parentheses and semicolons. When specifying multiple HTTP request headers or cookies, use one or more spaces between the HTTP request headers and cookie names.
`compress`	Specify `yes` for Oracle Web Cache to serve compressed cacheable and non-cacheable objects to all browser types; specify `no` for Oracle Web Cache to not serve compressed cacheable and non-cacheable objects to browsers. This control directive does not enable you to specify browser types. If you specify `yes` and must limit the browser types, specify a compression caching rule, as described in Section 6.8.1. To understand what Oracle Web Cache automatically compressed and does not compress, see Section 1.2.5.
`max-age`	Specify for Oracle Web Cache to cache the object. Specify the time, in seconds, to expire the object after it enters the cache. Optionally, specify the time, in seconds, to remove the object from the cache after the expiration time. Use the following format: `max-age=expiration_time[+removal_time]` Usage notes: The default removal time is 0 seconds `max-age=infinity` specifies that the object never expires

Usage Notes

Control directives are case sensitive.
content="ORAESI/9.0.4", content="ESI-Inline/1.0", content="ESI-INV/1.0", content="ESI/1.0" are mutually exclusive with content="webcache/1.0"

Refer to http://www.esi.org/spec.html for the Edge Architecture Specification, which contains specification information about the Surrogate-Control response header.

Example Usage

In the following example, the Surrogate-Control response-header field specifies that the object is to expire 30 seconds after it enters the cache and be removed 60 seconds after expiration. It also specifies that the object contains ESI tags that require processing:

Surrogate-Control: max-age=30+60, content="ORAESI/9.0.4"

In the following example, the Surrogate-Control response-header field specifies that the object is not to be cached:

Surrogate-Control: no-store

In the following example, the Surrogate-Control response-header field specifies ESI processing with the content control directive. The vary control directive specifies to cache versions of the multiple-version object based on the HTTP Accept request header value, regardless of whether the request contains the HTTP Accept request header.

Surrogate-Control: content="ORAESI/9.0.4", vary=headers(Accept)

In the following similar example, the Surrogate-Control response-header field specifies ESI processing with the content control directive. The vary control directive specifies to cache versions of the multiple-version object only if the request contains the Accept and MyCustomHeader headers and news and sports cookies.

Surrogate-Control: content="ORAESI/9.0.4", vary=headers(Accept/f MyCustomHeader/f);cookies(news/f sports/f)