11 Caching Dynamic Content with ESI Language Tags

ESI is an open specification co-authored by Oracle. Its purpose is to develop a uniform programming model to assemble dynamic pages in a dynamic content cache deployed as a surrogate or proxy between clients and origin servers.

ESI is an XML-like markup language that enables dynamic content assembly of fragments by Oracle Web Cache. A template page is configured with ESI markup tags that fetch and include dynamic HTML fragments. The fragments themselves can also contain ESI markup. You can assign caching rules to the template page and HTML fragments. By enabling page assembly in Oracle Web Cache rather than in the origin server, you can increase cache hit rates and improve performance.

11.1 Introduction to ESI for Partial Page Caching

Oracle Web Cache provides dynamic assembly of Web pages with both cacheable and non-cacheable page fragments. It provides for assembly by enabling Web pages to be divided into fragments of differing caching profiles. These fragments are maintained as separate elements in the cache. The fragments are assembled into HTML pages as appropriate when requested by end users.

By enabling dynamic assembly of Web pages on Oracle Web Cache rather than on the origin servers, you can choose to cache some fragments of assembled pages. With partial page caching, much more HTML content can be cached, and then assembled and delivered by Oracle Web Cache when requested. Furthermore, page assembly can be conditional, based on information provided in HTTP request headers or end-user cookies.

The basic structure that an application developer uses to create content for partial-page caching is a template page containing fragments. As depicted in Figure 11-1, the template consists of common elements, such as a logo, navigation bars, framework, and other "look and feel" elements of the page. The fragments represent dynamic subsections of the page.

The template page is associated with the URL that end users request. To include the fragments, the template page is configured with ESI markup tags that instruct Oracle Web Cache to fetch and include the HTML fragments. The fragments themselves are HTML files containing discrete text or other objects.

Each included fragment is a separate object with its own caching policy. Content providers may want to cache the template for several days, but only cache a particular fragment, such as an advertisement or stock quote, for a matter of seconds or minutes. Other fragments (such as a user's bank account total) may be declared non-cacheable.

11.1.1 ESI Features

ESI can be used with HTML, XML, JSP, ASP, and any Web programming technology. The ESI language includes the following features:

Inclusion

An ESI processor assembles HTTP or HTTPS fragments of dynamic content, retrieved from the network, into aggregate pages to output to the user. Each fragment can have its own caching rules.

Support of variables

ESI supports the use of variables based on HTTP request attributes, as well as custom variables from included HTML fragments. Variables can be used by ESI statements during processing or can be output directly into the processed markup.

Conditional processing

ESI allows use of Boolean comparisons for conditional logic in determining how pages are processed.

Error handling and alternative processing

Some ESI tags support specification of a default resource or an alternative resource, such as an alternate Web page, if the primary resource cannot be found. Further, it provides an explicit exception-handling statement block.

Character set conversion

ESI fragments in different character sets are converted to one character set. This way, all partial pages are assembled in a fixed character set. Character set conversion works in the following manner:

Oracle Web Cache receives a request for a template page.

Oracle Web Cache fetches the fragments, and converts all of the fragments to the template's character set. The default character set is ISO-8859-1.

Oracle Web Cache does not perform character set conversion for non-ESI pages.

11.1.1.1 ESI for Java (JESI)

Oracle Web Cache provides the JESI tag library as a convenient interface to ESI tags and functionality. In addition, you can deploy the JESI tag library on Oracle WebLogic Server. Developers have the option of using ESI tags directly in any Web application, but JESI tags provide additional convenience in a JSP environment.

Because ESI and JESI are open standards, you can use the JESI tag library in any standard JSP environment if an ESI processor, such as Oracle Web Cache, is available.

Even though JSP developers can always use ESI, JESI provides an even easier way for JSP developers to express the modularity of pages and the cacheability of those modules, without requiring developers to learn a new syntax.

For further information about using JESI with Oracle WebLogic Server, see:

11.1.2 ESI Language Elements in the Surrogate-Control Response Header

Oracle Web Cache supports the ESI language tags, elements, and attributes listed in Table 11-2. The rightmost column specifies, for each ESI tag, attribute, or element, all the feature sets that support it. For example, the <esi:invalidate> tag is only supported by the "ESI-INV/1.0" feature set. To enable the correct processing in Oracle Web Cache, specify all the feature sets that an ESI template uses in the content control directive of the Surrogate-Control response header. However, you do have to specify features sets used within an ESI fragment directly or indirectly included in the template. For example, if an ESI template uses an <esi:invalidate> and an <esi:environment> tag with an <esi:log> element, the content control directive must include "ESI-INV/1.0" and "ORAESI/9.0.4", as follows:

Surrogate-Control: content="ESI-INV/1.0 ORAESI/9.0.4"

See Section 6.10 for further information about configuring the Surrogate-Control response header.

11.1.3 About the Surrogate-Control Response Header and Surrogate-Capability Request Header for Cached Objects

To enable Oracle Web Cache to process ESI tags, you set an HTTP Surrogate-Control response-header field in the HTTP response message of the pages that use ESI tags.

Surrogate-Control: content="ESI-INV/1.0 ORAESI/9.0.4"

For each requested object from the cache, Oracle Web Cache appends a Surrogate-Capability request-header field to an object's HTTP request message. The Surrogate-Capability request-header serves the following purposes:

Enables applications to detect Oracle Web Cache

Identifies the types of ESI operations that Oracle Web Cache can perform

The Surrogate-Capability request-header enables Oracle Web Cache to identify the operations it can perform to origin servers acting as caches. The Surrogate-Capability request-header field supports the following syntax:

Surrogate-Capability: orcl="operation_valueoperation_value ..."

where "operation_value" is one or more of the following:

"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.

"webcache/1.0" to process the <!-- WEBCACHETAG--> and <!-- WEBCACHEEND--> tags for personalized attributes

The values "ORAESI/9.0.2", "ESI/1.0", and "ESI-Inline/1.0" are subsets of "ORAESI/9.0.4". For 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.

See Table 11-3 or further information about the ESI tags supported for each operation_value.

11.1.4 Syntax Rules

ESI elements and attributes adhere to XML syntax but can be embedded in other objects, such as HTML or XML objects. When Oracle Web Cache processes the page, the ESI elements themselves are stripped from the output.

ESI syntax generally adheres to XML syntax rules. Keep the following in mind when using the tags:

ESI tags and attributes are case sensitive.

They are generally lowercase.

Supported CGI environment variables are case sensitive.

They are generally uppercase.

ESI does not support the use of whitespace next to the equal sign (=) or between the "<" and "esi:"

The following shows an invalid construction:

<esi:include src = "www.foo.com"/>

The following shows the correct form:

<esi:include src="www.foo.com"/>

11.1.5 Nesting Elements

As shown in Example 11-3, an ESI tag can contain nested ESI elements and other HTML markup.

11.1.6.1 Variable Usage

To refer to a variable, prefix it with a dollar sign and surround the variable name with parentheses:

$(VARIABLE_NAME)

For example:

$(HTTP_HOST)

Variables are accessed by a key as follows:

$(VARIABLE_NAME{key})

To access a variable's substructure, append the variable name with braces containing the key which is being accessed. For example:

$(HTTP_COOKIE{username})

The key is case sensitive and optional. If a key is not specified, the environment variable returns the whole content of the environment fragment. Oracle advises specifying an environment variable without a key only for testing whether the environment is empty. In the following ESI markup, $(logindata) is a variable that is evaluated against a null value:

Result: Returns the value of fullname decoded. In this example, CEO returns a value of Jane Doe.

$(QUERY_STRING)

Not Applicable

Not Applicable/String

Specifies to return the entire query string encoded

Variable Setting:

$(QUERY_STRING)

Query Request Contains:

CEO=Jane%20Doe&CFO=John%20Doe

Result: Returns the entire query string encoded:

CEO=Jane%20Doe&CFO=John%20Doe

$(QUERY_STRING_ENCODED{parameter})

Not Applicable

Dictionary/String

Given a parameter name in a query string, returns the value of the parameter with URL encoding. The query string can be in an URL or a request body.

Variable Setting:

$(QUERY_STRING{fullname})

Query Request Contains:

fullname=Jane%20Doe

Result: Returns the value of fullname encoded:

Jane%20Doe

$(QUERY_STRING_ENCODED)

Not Applicable

Not Applicable/String

The same as $(QUERY_STRING)

Variable Setting:

$(QUERY_STRING_ENCODED)

Query Request Contains:

fullname=Jane%20Doe

Result: Returns the entire query string encoded:

fullname=Jane%20Doe

$(QUERY_STRING_DECODED{parameter})

Not Applicable

Dictionary/String

The same as $(QUERY_STRING{parameter})

Variable Setting:

$(QUERY_STRING_DECODED{CEO})

Query Request Contains:

fullname=Jane%20Doe

Result: Returns the value of fullname decoded. In this example, fullname returns a value of Jane Doe.

11.1.7 Exceptions and Errors

ESI uses several mechanisms to handle exceptions encountered during an ESI fragment request. In a given situation, you can make use of all mechanisms simultaneously, or use one at a time, depending on the business logic you are developing.

The first mechanism is found in the ESI language, which provides three specific elements for fine-grain control over content assembly in error scenarios:

The alt attribute of the <esi:include> tag

The onerror attribute of the <esi:include> tag

The try |attempt |except block

Default page for the fragment

When the fragment specified for the src attribute of the <esi:include> tag cannot be fetched, the fragment specified with the alt attribute is used as an alternative. If the alt attribute is not used or the fragment cannot be fetched, the onerror attribute is used. The onerror attribute is used before the try |attempt |except block. If the try |attempt |except block does not exist, the exception handling is propagated to the parent or template page. If all the ESI language controls fail, Oracle Web Cache displays a default page for the fragment.

11.1.8.1 Using Inline for Non-Fetchable Fragmentation

Most existing applications are only designed to output an entire Web page to HTTP requests. These fragments and templates are non-fetchable, meaning they are not to be fetched independently from the origin server. If a cache needs any of these fragments or templates, the corresponding full Web page must be requested. To use ESI page assembly for non-fetchable fragments, an application can output the full page response just as it does normally, with the exception that at the beginning and the end of each fragment, an <esi:inline> tag is inserted with a fragment name to demarcate the fragment. Oracle Web Cache stores the enclosed portions as separate fragments and the original page as a page template without the enclosed fragments. Fragments are shared among templates if their names are identical and they are from the same site.

Example 11-4 shows a simple <esi:inline> example. The HTML table enclosed by the <esi:inline> tag is the fragment content. The area preceding <esi:inline name="/news101"> and the area following </esi:inline> form the page template. If another page contains an <esi:inline> tag with the same name "/news101", the two fragments logically share the same content.

When an application uses non-fetchable <esi:inline> fragments, the full page must be requested for every cache miss. At first, it can appear that there is no apparent cache benefit for cache misses. However, non-fetchable <esi:inline> fragments improves overall caching by:

Increasing the cache hit ratio

Because shared fragments can be extracted into separate fragments, the size of the dynamic portion is reduced. A reduced space requirement results in a higher cache hit ratio than full page caching.

Reducing cache update frequency

Dynamic shared fragments require only one update. For example, a shared stock market fragment may expire much more frequently than any other parts of the page. With <esi:inline> fragmentation, only one cache update of any full page containing this fragment is enough to bring all full pages sharing this fragment current. Therefore, even non-fetchable <esi:inline> fragments can significantly reduce cache update frequency. The cost reduction is proportional to the degree of sharing.

To invalidate non-fetchable fragments, you must invalidate both the template object and the non-fetchable fragments to ensure the fragments are invalidated.

11.1.8.2 Using Inline for Fetchable Fragmentation

<esi:inline> fragments are by default non-fetchable. If an application supports independently fetchable fragments, it is possible to use the <esi:inline> for fetchable fragments by setting the fetchable attribute to yes.

Example 11-5 shows an <esi:inline> example with a fetchable fragment named /news101. A request for the page returns the template page and the fetchable fragment.

11.1.8.3 Using Include for Fragmentation

The <esi:include> tag is another way to define fragments and templates in an HTTP output for dynamic content caching and assembly. It is in many ways similar to the <esi:inline> tag. It defines a name for the defined fragment. The page including an <esi:include> tag is a template that references the defined fragment. However, it also has some key differences which make its applicable scenarios very different from those of <esi:inline>:

An <esi:include> tag in a template only defines the reference to a fragment.

It does not enclose an embedded fragment directly in the template. As a result, a template with <esi:include> tags can be applied to multiple users. In contrast, a template with embedded <esi:inline> tags must be unique to each user.

A fragment referenced by an <esi:include> tag must always be independently fetchable by HTTP or HTTPS.

The requested URL equals the fragment name. In contrast, an <esi:inline> tag's name only identifies the uniqueness of the fragment and is not used to fetch the actual content. The attribute defining the fragment name in <esi:include> fragment is src instead of name.

There are at least two scenarios where using <esi:include> tags is beneficial:

Some applications, such as a Web portal, naturally assemble content from external sources. The application only provides a template that is used to fetch various fragments from third-party sources. In this case, the <esi:include> tags fetch and assemble directly, reducing one layer of redundancy.

Some applications offer faster responses for template-only requests than full-page requests that use <esi:inline> tags. If <esi:include> is used for page fragmentation and assembly, Oracle Web Cache can miss only on the templates when most or all fragments are already cached, saving effective cache miss cost. In many cases, it is also valuable to cache the personalized templates because these seldom change.

11.1.8.4 Selecting the Fragmentation Mechanism for Your Application

Although both <esi:include> and <esi:inline> enable Oracle Web Cache to fetch fragments for the client browser, <esi:include> is more robust for performing this task and provides an easy way in which to manage fragments. Because <esi:include> affects the application flow, it is best to incorporate <esi:include> early in the design phase of an application. For an existing application, <esi:inline> is better mechanism because it requires minimal change to your application.

11.1.9 Referer Request-Header Field

When Oracle Web Cache receives a client request for a template page with a Referer request-header field, it forwards the request with the Referer request header to the origin server. In turn, the origin server returns fragments to Oracle Web Cache with the URL of the template as the value for the Referer header. This functionality associates the fragment request with the template request.

11.1.10 Cookie Management for Template Pages and Fragments

Session cookie establishment for ESI templates and fragments works much the same way as typical Oracle Web Cache objects with the following additional features:

Cookie request-header field inheritance

When a client requests an ESI template page that includes fragments, requests for fragment pages are generated in Oracle Web Cache. A fragment request inherits the Cookie request-header field from the template request if the value of the Host request-header field matches the value of Host request-header field in the template request.

Set-Cookie response-header field accumulation

When assembly of fragments is complete, Oracle Web Cache includes a Set-Cookie response-header field in the response with the cookie information from the template. For those fragments with a Host request-header field that matches the Host request-header field in the template, Oracle Web Cache also accumulates the Set-Cookie response-header fields with that of the template. For those fragments with a Host request-header field that does not match the Host request-header field in the template, Oracle Web Cache does not accumulate the Set-Cookie response-header field with that of the template and other matching fragments.

See Section 11.1.6 for a description of how you can use the HTTP_COOKIE variable in ESI markup.

11.2.2 Using ESI for Simple Personalization

You can use variable expressions for simple personalization.

For example, the following HTML substitutes a user's name based on the value the client browser passes with username cookie. In addition, the session information contained within the sessionID cookie is used to replace session information for one user with another user.

This page is assembled by Oracle Web Cache. A template page configured with ESI markup tags for a personalized greeting, weather, stocks, promotional advertisement, news, and sports fragments is assembled based on Mark's preferences. For example, because Mark chose San Francisco weather, the application looks up San Francisco weather information and puts it into the final full HTML page output. Because of its dynamic content, this page would not be cacheable. On the other hand, with ESI markup tags, Oracle Web Cache assembles and caches most of the content.

The following sections describe how the template page and its fragments are implemented using <esi:inline> and <esi:include> tags:

11.2.3.1.1 Portal Example Using inline Tags

This section describes how <esi:inline> tag fragmentation and assembly can drastically increase the value of dynamic content caching for pages that do not contain real-time elements. It shows how to apply the <esi:inline> tag for an existing application that supports non-fetchable fragments. The <esi:inline> tag helps reduce space consumption and improves cache hit ratios by isolating the dynamic content.

Note:

If an application supports independently fetchable fragments, it is possible to use the <esi:inline> for fetchable fragments by setting the fetchable attribute to yes. See Section 11.4.5 for further information about the fetchable attribute.

To use the <esi:inline> tag, the logical fragments in portal.esi are marked with the <esi:inline> tags. The personalized greeting, Weather Forecast, My Stocks, Promotion campaign, Latest News, and Latest Sports News naturally become fragments because they have individual caching properties and can be shared. The My Stock fragment is further broken down into five sub-fragments, one for each stock quote. In addition, to achieve the maximum fragment sharing, the common HTML code sections between each two personalized fragments are also enclosed as ESI fragments and are given constant names, so that the varying template contains as little common data as possible.

Example 11-7shows the markup for the personalized greeting. The fragment is common to all personalized pages belonging to different users. Because the <esi:inline> tag assigns this fragment a constant name, a different user, such as John, would have the same fragment in his template with the same fragment name. Two fragments are shared if and only if their names are identical. This way, the same shared fragment in all templates only need a single update when it expires or is invalidated. $(QUERY_STRING{username}) is an ESI environment variable that provide access to value of the username. This variable is used here because this application uses the username query string parameter to pass along the user's name. By using this variable, the first fragment becomes common to all users.

Example 11-9 shows the markup for My Stocks. The stock quotes fragment encloses all stock picks in Mark's page. It is further divided into five sub-fragments, one for each stock pick, using nested <esi:inline> tags. Thus, Mark's ESI template references his stock selection fragment, which in turn references five particular stock pick fragments. While the stock picks are shared by many user's stock selection fragment, the stock selection fragment itself is also a template uniquely owned by Mark. This markup separates the unique information from the shared information, maximizing the reduction of cache updates and space consumption of personal stock selection.

Rotating advertisements that change in every response is an example of real- time content that renders little value in non-fetchable ESI <esi:inline> caching. Even the smallest portion of real-time content embedded as a non-fetchable ESI inline fragment would require the entire response to be regenerated and fetched, effectively creating cache misses all the time. To use ESI and dynamic content caching for these real-time fragments, use the <esi:include> tag.

See Section 11.2.3.1.2 for an example of using <esi:include> tag for real-time advertisements

The Latest News and Latest Sports News fragments are similar to the weather fragment. All the common areas are also defined as fragments. Although it is possible to leave them as part of the template, that would consume unnecessary storage space. Example 11-11 shows the markup.

Example 11-15shows the markup for the personalized greeting Welcome, Mark!. The personalized greeting is achieved by the <esi:vars> tag, which bases the greeting on the username parameter embedded in the URL. The parameter username is the registered user's name. This markup enables the personalized greeting to be included in the cacheable template page.

Example 11-15 portal.esi Example with vars tag: Personalized Greeting

<esi:vars>Welcome, $(QUERY_STRING{username})!</esi:vars>

Example 11-16shows the markup for Weather Forecast. Weather Forecast includes a servlet fragment name Weather, which uses the value of the user's city and state environment variables in GetProfile to display the correct weather forecast for the user. Because GetProfile has a value of San Francisco for the city environment variable and California for the state environment variable, the weather forecast is for San Francisco, California.

The markup for My Stocks is depicted in Example 11-17. My Stocks includes a servlet fragment named PersonalizedStockSelection. The displayed stocks are based on the userID parameter encoded in the URL. userID is the registered user's unique ID.

Because the output is different for each user, the PersonalizedStockSelection fragment is not cacheable. However, the response to each of the included quotes is cacheable, enabling stock quotes to be shared by multiple users. Even when many users share quotes, only one browser reload is needed when the quotes are updated. For example, the PersonalizedStockSelection fragment for another user named Scott is depicted in Example 11-19. It includes fragments for three stock quotes: IBM, ORCL, and SCO. As described, IBM and ORCL are also shared by Mark. If Mark reloads the page first and caches the quotes, then the IBM and ORCL quotes for Scott are automatically refreshed.

Example 11-20 shows the markup for rotating advertisements in the Promotion section. The advertisements rotates in the sense that the advertisement changes for each response. By separating the generation of the included image fragment response from the template page, Oracle Web Cache can cache the template and integrate the dynamic advertisement into the template.

As shown in Example 11-21, the response to the included image fragment for the banner is not cacheable. When a user requests this page, Oracle Web Cache sends the request to the application Web server to generate the banner. From the application Web server, Advert generates the banner for the request.

Latest News displays the news headlines based on the user's news category, internet, finance, or technology, by using conditional processing with the <esi:choose> tag. Because GetProfile has a value of finance for the news environment variable, the headlines displayed relate to finance, /servlet/News?type=Top&topic=business.

Similarly, Latest Sports News displays the sports headlines based on the user's sports category, golf, soccer, basketball, baseball, or soccer, by using conditional processing. Because GetProfile has a value of soccer for the sports environment variable, the output includes headlines relating to soccer, /servlet/News?type=Sports&topic=soccer.

11.3 Using Inline Invalidation in HTTP Responses

Inline invalidation is implemented as part of Edge Side Includes (ESI) and provides a useful way for origin servers to "piggyback" invalidation messages on transactional responses sent to Web Cache. For instance, when a customer purchases a vegetarian cookbook on an e-commerce site, the confirmation response could contain instructions for invalidating all catalog pages related to the book, its author and vegetables. The ability to send invalidation message inline reduces the connection overhead associated with sending out-of-band invalidations and is a useful tool for ESI developers.

To configure inline invalidation:

In the template page, configure the HTTP response with the Surrogate-Control response-header field that includes content="ESI-INV/1.0":

Surrogate-Control: content="ESI-INV/1.0"

In the body of the same response, use the <esi:invalidate> tag to insert either a basic or advanced inline invalidation request.

You can insert an inline invalidation request anywhere in the ESI template. You can insert multiple requests, but only the first one processes. The execution of the inline invalidation is blocking. That is, if the ESI template contains other ESI features, inline invalidation is executed first.

11.3.1 Example: Using Inline Invalidation

Following is an example about an online bike shop using inline invalidation in their simple Web application. It has two CGI scripts written in Perl. show_bike.pl displays how many bikes of a certain model are in stock. Since it involves database query and its result remains the same until a purchase occurs, show_bike.pl is cached. buy_bike.pl is used by customers to buy a bike. When this page is requested, show_bike.pl is no longer valid—an invalidation is needed.

To facilitate debugging, the application developer can perform the following:

Add the Surrogate-Capability request header that includes "ESI-INV/1.0":

Surrogate-Capability: content="ESI-INV/1.0"

When the Surrogate-Capability request header is added for inline invalidation, Oracle Web Cache includes the invalidation request in the response.

Enable the output attribute of the <esi:invalidate> tag.

When the output attribute is enabled, Oracle Web Cache includes the invalidation result in the response enclosed within comments <!--result-->.

Example 11-29 shows the browser response of buy_bike.pl when both the Surrogate-Capability request header is enabled for the inline invalidation and the output attribute of the <esi:invalidate> tag is enabled.

11.4.1.2 Attributes

test—Specifies the Boolean operation

11.4.1.3 Usage

Each <esi:choose> tag must have a least one <esi:when> tag, and may optionally contain exactly one <esi:otherwise> tag.

Oracle Web Cache executes the first <esi:when> tag whose test attribute evaluates truthfully, and then exit the <esi:choose> tag. If no <esi:when> tag evaluates to true and an <esi:otherwise> tag is present, that element's content executes.

Other HTML or ESI element can be included inside <esi:when> or <esi:otherwise> elements.

11.4.1.4 Boolean Expressions

The test attribute uses Boolean expressions to determine how to evaluate true or false logic. ESI supports the following Boolean operators:

== (equal to)

!= (not equal to)

> (greater than)

< (less than)

>= (greater than or equal to)

<= (less than or equal to)

& (and)

| (or)

! (not)

Note the following about the use of Boolean expressions:

Operands associate from left to right.

Sub-expressions can be grouped with parentheses to explicitly specify association.

If both operands are numeric, then the expression is evaluated numerically.

If either operand is non-numeric, then both operands are evaluated as strings. For example, 'a'==3 evaluates to 'a'=='3', where 3 is evaluated as a string.

The comparison of two Boolean expressions results in an undefined operation.

If an operand is empty or undefined, then the expression always evaluates to false.

The logical operators (&, !, and|) are used to qualify expressions, but cannot be used to make comparisons.

Use single quotes (') for constant strings. For example, the following string is a valid construction:

$(HTTP_COOKIE{name})=='typical'

Escaped single quotes (\') are not permitted. For example, the following is not supported:

$(HTTP_COOKIE{'user\'s name'})=='typical'

Arithmetic operations and assignments are not permitted.

A null value evaluates whether a variable is empty.

When a number is compared with null, that number is converted into an equivalent string and compared against an empty string. In the following ESI markup, $(logindata{name}) is a variable that provides access to the value of the name. If name is empty and evaluates to null, then the expression evaluates to true; if name is not empty and does not evaluate to null, then the expression evaluates to false.

Note:

If a variable exists but evaluates to an empty string, then the value is not considered null.

11.4.1.5 Statements

Statements must be placed inside a <esi:when> or <esi:otherwise> subtag. Statements outside the subtags cannot be evaluated as conditions. Example 11-30 shows invalid placement of statements.

Example 11-30 Statement Placement

<esi:choose>
This markup is invalid because any characters other than whitespace are not allowed in this area.
<esi:when test="$(HTTP_HOST) == 'www.company.com'">
<esi:include src="/company.html" />
</esi:when>
This markup is invalid because any characters other than whitespace are not allowed in this area.
<esi:when test="$(HTTP_COOKIE{fragment) == 'First Fragment'">
<img src="/img/TheImage.gif">
</esi:when>
This markup is invalid because any characters other than whitespace are not allowed in this area.
<esi:otherwise>
The default selection.
</esi:otherwise>
This markup is invalid because any characters other than whitespace are not allowed in this area.
</esi:choose>

11.4.1.6 Example

The following ESI markup includes advanced.html for requests that use the cookie Advanced and basic.html for requests that use the cookie Basic:

11.4.3.3 Elements

log—Specifies a log message of the fragment to be included in the access_log_file.fragment file when the x-esi-info log field is set. You can provide a descriptive text string that identifies the fragment and the application that generated the fragment. By providing descriptive text, you can easily identify the fragment in the log file, enabling you to determine how often the fragment is requested.

11.4.3.5 Example

The following ESI output specifies logindata to refer to the environment variables stored in catalog.xml. The file catalog.xml enables access to the value of the vendorID environment variable, which is used as a parameter in the included URL:

The following ESI output specifies logindata to refer to the environment variables stored in env.dat. The file env.dat enables access to the value of the env environment variable, which is used as a parameter in the included log message for dir1.txt. The log messages for dir1.txt and esi-log2.html are written to the access_log.fragment file when the x-esi-info log field is set and the fragments are requested.

11.4.4.2 Attributes

src—Specifies the URL of the fragment to fetch. The URL can be a literal string or it can include variables.

The URL can either be an absolute or relative URL. When specifying an absolute URL, use the following formats:

"http://host_name:port/path/filename"

"https://host_name:port/path/filename"

If you specify the host name for an absolute URL, you must prefix it with http:// or https://. An HTML parser treats the host:80 in the following URL as a folder name rather than a host name:

src="host:80/index.htm"

To make this URL valid, you specify the following:

src="http://host:80/index.htm"

Relative URLs are resolved relative to the template page. The included result replaces the element in the markup served to the browser.

You can specify an XML fragment if the XML file fragment is valid XML. For example, the following specifies that Oracle Web Cache use XSL Transformations (XSLT) to transform the XML into HTML using a style sheet. The style sheet maps XML formats to HTML formats:

alt—Specifies an alternative resource if the src is not found. The requirements for the value are the same as those for src.

max-age—Specifies the time, in seconds, to expire the fragment, and optionally, specifies the time, in seconds, to remove the fragment after expiration time. Use this attribute if the template page has a higher tolerance for stale fragments than specified by the time-to-live parameters in fragment responses.

method—Specifies the HTTP request method of the fragment. Valid values are GET or POST.

onerror—Specifies that if the fetch failed on the src object to ignore the ESI tag and serve the page.

redirect—Specifies how to serve the fragment when the src fragment resides temporarily under a different URL. yes specifies that the URL be redirected and displayed; no specifies that the fragment URL not be redirected and an HTTP 302 Found status code be served for the fragment. yes is the default.

timeout—Specifies the time, in seconds, for the fragment to be fetched. If the fragment has not been fetched within the time interval, the fetch is aborted.

11.4.4.3 Elements

request_body—Specifies the HTTP request body of the fragment.

request_header—Specifies an HTTP request header field and value for Oracle Web Cache to use. You can specify multiple HTTP request headers. When this attribute is specified, all request headers from the parent fragment or template page are ignored.

log—Specifies a log message of the fragment to be included in the access_log.fragment file when the x-esi-info log field is set. You can provide a descriptive text string that identifies the fragment and the application that generated the fragment. By providing descriptive text, you can easily identify the fragment in the log file, enabling you to determine how often the fragment is requested.

11.4.4.4 Syntax Usage

<esi:include> does not support escaped double quotes (\"). For example, the following is not supported:

<esi:include src="file\"user.htm"/>

The attributes do not have to be in a particular order.

The src attribute supports both HTTP and HTTPS. Oracle Web Cache permits the template and fragments to use different protocols. Note the following:

If the src attribute specifies a fragment's relative path, such as src="/PersonalizedGreeting", the template's protocol is used.

If the protocol used in the src attribute does not match the protocol specified in the Site-to-Server Mapping page (Origin Servers, Sites, and Load Balancing > Site-to-Server Mapping) of Oracle Web Cache Manager, then Oracle Web Cache uses the protocol configured for the origin server in the Site-to-Server Mapping page. Oracle Web Cache also reports the following warning message to the event log:

For example, if the template page is configured with <esi:include> src="https://www.company.com:80/gifs/frag1.gif"/> and the site-to-server mapping specifies HTTP for the origin server, then http://www.company.com:80/gifs/frag1.gif is used and the following message appears in the event log:

11.4.4.5 Usage

The <esi:include> tag instructs Oracle Web Cache to fetch the fragment specified by the src attribute.

If the include is successful, the contents of the fetched src URL are displayed. The included object is included exactly at the point of the include tag. For example, if the include tag is in a table cell, the fetched object is displayed in the table cell.

The max-age control directive in the Surrogate-Control response-header field applies to the response; the max-age attribute applies only to that particular usage of the fragment response through the <esi:include> tag. If both the max-age control directive in the Surrogate-Control response-header field and the max-age attribute are set, then the effective expiration and removal time-to-live for this particular inclusion are the longest maximum age of the expiration and the removal time-to-live, respectively. If a particular page has a greater tolerance for staleness of a fragment, then set the max-age attribute to a longer time than the max-age control directive. Use the max-age attribute to increase cache hits by serving fragments stale until the removal time. max-age=infinity specifies that the object never expires.

If method is not set, then GET is assumed. However, if the request_body element is set, then POST is assumed.

Oracle Web Cache generates the following HTTP request headers for all fragment requests:

Host

Content-Length

Surrogate-Capability

Connection

The request_header element enables you to control HTTP headers other than these. Do not specify these HTTP request headers as request_header attributes, as a conflict can affect the operation of Oracle Web Cache.

If no request_header elements are specified, Oracle Web Cache uses other request headers from the parent page.

See Section 11.1.8 for a comparison of <esi:inline> and <esi:include> usage.

11.4.4.6 Examples

The following ESI markup includes a file named frag1.htm. The fragment must be fetched within 60 seconds. If the fetch fails, Oracle Web Cache ignores the includes and serves the page. If the fetch succeeds, Oracle Web Cache includes the fragment. Oracle Web Cache expires the fragment after five minutes, and removes it after another eight minutes.

The following ESI output includes a personalized greeting, a Cookie HTTP request header, and an HTTP request body that includes the date. Log message "Fragment: /Personalized Greeting is included" writes to the access_log.fragment file when the x-esi-info log field is set and the fragment is requested.

For more information, see Section 11.2.3.1 for an extended example of <esi:include> usage.

11.4.5 ESI inline Tag

The <esi:inline> tag marks a fragment as a separately cacheable fragment, embedded in the HTTP response of another object. Oracle Web Cache stores and assembles these fragments independently as <esi:include> fragments.

See Section 11.1.8 for a comparison of <esi:inline> and <esi:include> usage.

11.4.5.1 Syntax

11.4.5.2 Attributes

name—Specifies a unique name for the fragment in URL format.

fetchable—yes instructs Oracle Web Cache to fetch a fragment from the origin server when it expires. The template for the fragment is not included during this fetching process. no instructs Oracle Web Cache to fetch the entire template from the origin server when there is a cache miss, and then try to extract all the fragments from the template.

max-age—Specifies the time, in seconds, to expire the fragment, and optionally, specifies the time, in seconds, to remove the fragment after the expiration time. Use this attribute if the template page has a higher tolerance for stale fragments than specified by the time-to-live parameters in fragment responses.

timeout—Specifies the time, in seconds, for the fragment to be fetched. If the fragment has not been fetched within the time interval, the fetch is aborted.

11.4.5.3 Usage

Some inline fragments are only delivered as part of an HTTP response for another object. These are not independently fetchable by Oracle Web Cache the way <esi:include> fragments are. When a non-fetchable fragment is needed by Oracle Web Cache, it must request the object from which the inline fragment was extracted.

When a non-fetchable <esi:inline> fragment is not found in the cache, Oracle Web Cache re-fetches the fragment's parent template. This behavior implies that the parent cannot be another non-fetchable <esi:inline> fragment. If the parent is an <esi:inline> non-fetchable fragment, the response returned to the browser is undefined.

11.4.6.2 Attributes

output—yes specifies that the invalidation result be included in the browser response, enclosed within comments <!--result-->. no specifies that the invalidation result not be displayed in the output. Specify a value of yes for a test environment; specify a value of no for a production environment.

Normally, when Oracle Web Cache processes this example block, it fetches the ad.html file and includes it into the template page while silently discarding the <esi:remove> tag and its contents. If ESI processing is not enabled, all of the elements are passed through to the browser, which ignores ESI markup. However, the browser displays the <A HREF=...> HTML link.

11.4.8 ESI try | attempt | except Tags

The <esi:try> tag provides for exception handling. The <esi:try> tag must contain exactly one instance of an <esi:attempt> tag and one or more <esi:except> tags. See Section 11.1.7 for usage notes on alt and onerror.

11.4.8.2 Usage

Oracle Web Cache first processes the contents of <esi:attempt>. A failed <esi:attempt> triggers an error and causes Oracle Web Cache to process the contents of the <esi:except> tag.

Specify an <esi:except> tag without a type for general errors; specify an <esi:except> tag with a type for specific errors. The <esi:except> tag accepts the following case-insensitive types:

nestingtoodeep: An error occurs because the fragment include depth has exceeded the maximum include depth.

originserverbusy: An error occurs because the origin server for this fragment is busy and cannot accept new requests now. This is caused by Oracle Web Cache-to-origin server request queue limit being reached.

noconnection: An error occurs because the cache cannot connect to the origin server serving this fragment.

networktimeout: An error occurs because a fragment request to the origin server has timed out in the network connection.

httpclienterror: An error occurs because the origin server returns an HTTP 4xx status code, a client error, such as a malformed HTTP request or an unauthorized access.

incompatiblefragmentversion: An error occurs because a fragment's processing requirement is not supported or not compatible with the template. <!-- WEBCACHETAG--> and <!-- WEBCACHEEND--> processing in an ESI fragment is not compatible with ESI processing. A fragment may be plain data that does not need any processing in the cache, or it may be an ESI template itself that requires processing of ESI features supported in this release. The ESI features in use are specified by the Surrogate-Controlcontent control directive.

incorrectresponseheader: An error occurs because the response headers for a fragment causes the error.

incorrectesifragment: An error occurs when Oracle Web Cache tries to parse or process the ESI fragment response body due to errors in the body.

incorrectxmlfragment: An error occurs because there is an error in XSLT retrieval, parsing, or processing by Oracle Web Cache.

11.4.8.3 Example

The following ESI markup attempts to fetch an advertisement. If the advertisement cannot be included, Oracle Web Cache includes a static link instead.

The following <esi:try> attempts to include the fragment http://server.portal.com/pls/ppcdemo/!PCDEMO.wwpro_app_provider.execute_portlet/513104940/26 containing several HTTP request headers. If the fragment cannot be included because of various type errors, Oracle Web Cache returns an Unknown ESI Exception error.

11.4.9 ESI vars Tag

The <esi:vars> tag enables you to use variables outside of ESI tags. For example, instead of specifying a variable inside a <esi:include> or <esi:choose> block, you can use the <esi:vars> tag to specify a variable inside HTML code.

11.4.9.4 Example

The following ESI output refers to logindata as part of the <A HREF=...> link for the Welcome page. logindata refers to an XML file that contains custom environment variables. The output also includes the user's sessionID and category type cookie values as part of the other <A HREF=...> links.

11.4.10 ESI <!--esi-->Tag

The <!--esi...---> tag enables HTML marked up with ESI tags to display to the browser without processing the ESI tags. When a page is processed with this tag, Oracle Web Cache removes the starting <!--esi and ending --> elements, while still processing the contents of the page. When the markup cannot be processed, this tag assures that the ESI markup does not interfere with the final HTML output.

11.4.10.1 Syntax

<!--esi
ESI elements
-->

11.4.10.2 Usage

Any ESI or HTML elements can be included within this tag, except other <!--esi...--> tags.

11.4.10.3 Example

In the following ESI markup, the <!--esi and --> are removed in the final
output. The output displays the content generated by <p><esi:vars>Hello, $(HTTP_COOKIE{name})!</esi:vars></p>,
plus any surrounding text.
<!--esi
<p><esi:vars>Hello, $(HTTP_COOKIE{name})!</esi:vars></p>
-->

If the ESI markup cannot be processed, then the <p><esi:vars>Hello, $(HTTP_COOKIE{name})!</esi:vars></p> is displayed in the HTML output.

Scripting on this page enhances content navigation, but does not change the content in any way.