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)