16 Edge Side Includes (ESI) Language Tags

ESI Tag Descriptions

This section describes the following ESI tags, which are used for partial page caching operations:

• ESI choose | when | otherwise Tags

• ESI comment Tag

• ESI environment Tag

• ESI include Tag

• ESI inline Tag

• ESI invalidate Tag

• ESI remove Tag

• ESI try | attempt | except Tags

• ESI vars Tag

• ESI <!--esi-->Tag

ESI choose | when | otherwise Tags

The <esi:choose>, <esi:when>, and <esi:otherwise> conditional tags provide the ability to perform logic based on Boolean expressions.

Syntax

<esi:choose>
  <esi:when test="BOOLEAN_expression">
    Perform this action
  </esi:when>
  <esi:when test="BOOLEAN_expression">
    Perform this action
  </esi:when>
  <esi:otherwise>
    Perform this other action
  </esi:otherwise>
</esi:choose>

Attributes

test—Specifies the Boolean operation

Usage

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

• OracleAS Web Cache will execute 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 will be executed.

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

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 or not 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.

  
  

  <esi:choose>
    <esi:when test="$(logindata{name}) == null">
      <esi:include src=/login/$(logindata{name})"/>
   </esi:when>
   <esi:otherwise>
     <esi:include src=/login/guest.html"/>
   <esi:otherwise>
  </esi:choose>  
  
  

The following expressions show correct usage of Boolean operators:

!(1==1)
!('a'<='c')
(1==1)|('abc'=='def')
(4!=5)&(4==5)

The following expressions show incorrect usage of Boolean operators:

(1 & 4)
("abc" | "edf")

Statements

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

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

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:

<esi:choose>
  <esi:when test="$(HTTP_COOKIE{group})=='Advanced'">
    <esi:include src="http://www.company.com/advanced.html"/>
  </esi:when>
  <esi:when test="$(HTTP_COOKIE{group})=='Basic User'">
    <esi:include src="http://www.company.com/basic.html"/>
  </esi:when>
  <esi:otherwise>
    <esi:include src="http://www.company.com/new_user.html"/>
  </esi:otherwise>
</esi:choose>

ESI comment Tag

The <esi:comment> tag enables you to comment ESI instructions, without making the comments available in the output.

Syntax

<esi:comment text="text commentary"/>

<esi:comment> is an empty element, and does not have an end tag.

Usage

The <esi:comment> tag is not evaluated by OracleAS Web Cache. If comments need to be visible in the HTML output, use standard XML/HTML comment tags.

Example

The following ESI markup provides a comment for an included GIF file:

<esi:comment text="the following animation will have a 24 hour TTL"/>
<esi:include src="http://www.company.com/logo.gif" onerror="continue" />

ESI environment Tag

The <esi:environment> tag enables you to include custom environment variables from included fragments. Once included, these variables can then be used with the other ESI tags.

Syntax

There are two forms of this tag. In the first form, <esi:environment> does not have a closing </esi:environment> tag:

<esi:environment src="environment_URL" name="environment_name"  [max-age="expiration_time [+ removal_time]]" [method="GET|POST"] [onerror="continue"] [timeout="fetch_time"]/>

In the second form with elements, <esi:environment> has a closing </esi:environment> tag:

<esi:environment src="environment_URL" name="environment_name"
   [max-age="expiration_time [+ removal_time]"] [method="GET|POST"]
   [onerror="continue"] [timeout="fetch_time"]>
  [<esi:request_header name="request_header" value="value"/>]
  [<esi:request_body value="value"/>]
  [<esi:log>log_message</esi:log>]
</esi:environment>

Attributes

• src—Specifies the URL from which to obtain environment variables and their values.

  The URL can be either an absolute or relative URL. When specifying an absolute URL, use one of 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 result sets the ESI environment for the current template.

  The source code of the URL requires the following XML format:

  <?xml version="1.0"?>
  <esi:environment esiversion="ORAESI/9.0.4">
    <variable_name>variable_value</variable_name>
    <variable_name>variable_value</variable_name>
  </esi:environment>
  
  

• name—Specifies the name to use to refer to the environment variable.

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

• max-age—Specifies the time, in seconds, to expire the XML file, and optionally, specifies the time, in seconds, to remove the XML file after the expiration time.

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

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

Elements

• request_body—Specifies the HTTP request body of the fragment.

• request_header—Specifies an HTTP request header field and value for OracleAS Web Cache to use.

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

  
  

  See Also: Table 15-6 for further information about the x-esi-info log field

  
  

Syntax Usage

• Specify only one <esi:environment> tag for each template page, before other ESI tags.

• The attributes do not need to be in a particular order.

• Do not specify more than one request_body element.

• You can have zero or more request_header elements.

  Use multiple request_header elements to specify multiple HTTP request header fields:

  <esi:environment src="environment_URL" 
     [max-age="expiration_time [+ removal_time]"][method="GET|POST"]
     [onerror="continue"] [timeout="fetch_time"]>
    <esi:request_header name="request_header" value="value"/>
    <esi:request_header name="request_header" value="value"/>
  </esi:environment>
  
  

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

• Do not specify more than one log element.

  
  

  See Also: "Variable Expressions" for usage instructions for variables "ESI include Tag" for usage notes on max-age, method, onerror, request_body, and request_header "Exceptions and Errors" for usage notes on onerror

  
  

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:

<esi:environment src="/catalog.xml" name="logindata"/>
<esi:include src="http://provider.com/intranetprovider?vendorID=$(logindata{vendorID})"/>

The file catalog.xml has the following content:

<?xml version="1.0"?>
<esi:environment esiversion="ORAESI/9.0.4">
  <product_description>stereo</product_description>
  <vendorID>3278</vendorID>
  <partner1>E-Electronics</partner1>
  <partner2>E-City</partner2>
</esi:environment>

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.

<esi:environment src="/esi/env.dat" name="env">
  <esi:log>Used environment /esi/env.dat</esi:log>
</esi:environment>

<esi:include src="/cached/dir1.txt">
  <esi:log>Fragment:/cache/dir1.txt is included, by $(env{xl_name})</esi:log>
</esi:include>

<font color="red">Including /cgi-bin/esi-fetch.sh?/esi/esi-log2.html in esi-log1.html </font>
<esi:include src="/cgi-bin/esi-fetch.sh?/esi/esi-log2.html">
  <esi:log>Fragment: /cgi-bin/esi-fetch.sh?/esi/esi-log2.html is included
 </esi:log>

ESI include Tag

The <esi:include> tag provides syntax for including fragments.

Syntax

There are two forms of this tag. In the first form, <esi:include> does not have a closing </esi:include> tag:

<esi:include src="URL_fragment" [alt="URL_fragment"]
[max-age="expiration_time [+removal_time]]" [method="GET|POST"] [onerror="continue"] [redirect=yes|no] [timeout="fetch_time"]/>

In the second form, with elements, <esi:include> has a closing </esi:include> tag:

<esi:include src="URL_fragment" [alt="URL_fragment"]
   [max-age="expiration_time[+removal_time]"] [method="GET|POST"]
   [onerror="continue"] [redirect=yes|no] [timeout="fetch_time"]>
  [<esi:request_header name="request_header" value="value"/>]
  [<esi:request_body value="value"/>]
  [<esi:log>log_message</esi:log>]
</esi:include>

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 one of 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 as long as the XML file fragment is valid XML. For example, the following specifies that OracleAS Web Cache use XSL Transformations (XSLT) to transform the XML into HTML using a stylesheet. The stylesheet maps XML formats to HTML formats:

  <?xml version="1.0"?>
  <?xml-stylesheet type="text/xml" href="stylesheet.xsl"?>
  
  

  Ensure that both the XML fragment and the XSL stylesheet response pages are configured with a Content-Type response-header field that includes text and XML media types. For example:

  Content-Type: text/xml
  

  
  

  See Also: http://www.xslt.com/ for complete information about XSLT

  
  

• 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 in place of 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.

  
  

  See Also: "Exceptions and Errors" for usage notes on alt and onerror

  
  

Elements

• request_body—Specifies the HTTP request body of the fragment.

• request_header—Specifies an HTTP request header field and value for OracleAS 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.

  
  

  See Also: Table 15-6 for further information about the x-esi-info log field

  
  

Syntax Usage

• <esi:include> supports up to three levels of nesting.

• <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 need to be in a particular order.

• The src attribute supports both HTTP and HTTPS. OracleAS 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 OracleAS Web Cache Manager, then OracleAS Web Cache uses the protocol configured for the origin server in the Site-to-Server Mapping page. OracleAS Web Cache also reports the following warning message to the event log:

    [Date] [warning 11250] [ecid: request_id, serial_number]
    ESI include fragment protocol does not match origin server protocol: 
    Origin Server Protocol=protocol URL=URL
    
    

    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:

    [03/Feb/2005:23:16:46 +0000] [warning 11250] [ecid: 90125204378,0] 
    ESI include fragment protocol does not match origin server protocol:
    Origin Server Protocol=http URL=https://www.company.com:80/gifs/frag1.gif
    
    

• Do not specify more than one request_body element.

• You can have zero or more request_header elements.

• Use multiple request_header elements to specify multiple HTTP request header fields:

  <esi:include src="URL_fragment" 
    [max-age="expiration_time[+removal_time]"] [method="GET|POST"]
    [onerror="continue"] [timeout="fetch_time"]>
    <esi:request_header name="request_header" value="value"/>
    <esi:request_header name="request_header" value="value"/>
  </esi:include>
  
  

• Do not specify more than one log element.

Usage

The <esi:include> tag instructs OracleAS 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.

OracleAS 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 OracleAS Web Cache.

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

Examples

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

<esi:include src="/frag1.htm" timeout="60" maxage="300+480" onerror="continue"/>

The following ESI output includes the result of a dynamic query:

<esi:include src="/search?query=$QUERY_STRING(query)"/>

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" is written to the access_log.fragment file when the x-esi-info log field is set and the fragment is requested.

<esi:include src="/PersonalGreeting">
  <esi:request_header name="Cookie" value="pname=Scott Tiger"/>
  <esi:request_body value="day=05, month=10, year=2001"/>
  <esi:log>Fragment: /Personalized Greeting is included</esi:log>
</esi:include>

ESI inline Tag

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

Syntax

<esi:inline name="URL" fetchable="yes|no" 
 [max-age="expiration_time [+ removal_time]"] [timeout="fetch_time"]
 Embedded HTML code
</esi:inline>

Attributes

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

• fetchable—yes instructs OracleAS 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 OracleAS 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.

Usage

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

When a non-fetchable <esi:inline> fragment is not found in the cache, OracleAS 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.

Example

The following ESI output embeds financial headlines:

<esi:inline name="/Top_News_Finance">
Latest News for Finance
<TABLE>
  <TR>
    Blue-Chip Stocks Cut Losses; Nasdaq Up MO
    French rig factory with explosives New York Times
    Volkswagen faces Brazil strike CNN Europe
    Airbuss reliability record BBC
  </TR>
</TABLE>
</esi:inline>

ESI invalidate Tag

The <esi:invalidate> tag enables you to configure an invalidation request within the response of a browser page.

Syntax

Basic invalidation syntax:

<esi:invalidate [output="yes"]>
 <?xml version="1.0"?>
 <!DOCTYPE INVALIDATION SYSTEM "internal:///WCSinvalidation.dtd">
  <INVALIDATION VERSION="WCS-1.1">
    <SYSTEM>
     <SYSTEMINFO NAME="name" VALUE="value"/>
    </SYSTEM>  
    <OBJECT>
      <BASICSELECTOR URI="URL"/>
      <ACTION REMOVALTTL="TTL"/>
      <INFO VALUE="value"/>
    </OBJECT>
 </INVALIDATION>
</esi:invalidate>

Advanced invalidation syntax:

<esi:invalidate [output="yes"]>
 <?xml version="1.0"?>
 <!DOCTYPE INVALIDATION SYSTEM "internal:///WCSinvalidation.dtd">
 <INVALIDATION VERSION="WCS-1.1">
    <SYSTEM>
     <SYSTEMINFO NAME="name" VALUE="value"/>
    </SYSTEM>  
       <OBJECT>
         <ADVANCEDSELECTOR URIPREFIX="prefix"
                           URIEXP="URL_expression"
                           HOST="host_name:port"
                           METHOD="HTTP_request_method"
                          BODYEXP="HTTP_body"/>
          <COOKIE NAME="cookie_name" VALUE="value"/>
          <HEADER NAME="HTTP_request_header" VALUE="value"/>
          <OTHER NAME="URI|BODY|QUERYSTRING_PARAMETER|SEARCHKEY"
                 TYPE="SUBSTRING|REGEX"
                 VALUE="value"/>
         </ADVANCEDSELECTOR>
      <ACTION REMOVALTTL="TTL"/>
      <INFO VALUE="value"/>
      </OBJECT>
 </INVALIDATION>
</esi:invalidate>

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.

Usage

Example

ESI remove Tag

The <esi:remove> tag allows for specification of non-ESI markup output if ESI processing is not enabled with the Surrogate-Control header or there is not an ESI-enabled cache.

Syntax

<esi:remove> HTML output...</esi:remove>

Usage

Any HTML or ESI elements can be included within this tag, except other <esi:remove> tags. Note that nested ESI tags are not processed.

Example

The following ESI markup includes http://www.company.com if the <esi:include> content cannot be included:

<esi:include src="http://www.company.com/ad.html"/>
<esi:remove>
  <A HREF="http://www.company.com">www.company.com</A>
</esi:remove>

Normally, when OracleAS 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.

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.

Syntax

In the following form, only one <esi:except> tag is supported:

<esi:try>
  <esi:attempt>
    Try this...
  </esi:attempt>
  <esi:except>
    If the attempt fails, then perform this action...
  </esi:except>
</esi:try>

In the following form, multiple <esi:except> tags with different types are supported:

<esi:try>
  <esi:attempt>
    Try this...
  </esi:attempt>
  <esi:except [type="type"]>
    If the attempt fails, then perform this action...
  </esi:except>
  <esi:except [type="type"]>
    Perform this action...
  </esi:except>
  <esi:except>
    If the attempt fails, then perform this action...
  </esi:except>
</esi:try>

Usage

OracleAS Web Cache first processes the contents of <esi:attempt>. A failed <esi:attempt> triggers an error and causes OracleAS 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 OracleAS Web Cache-to-origin server request queue limit being reached.

• noconnection: An error occurs because the cache is unable to 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.

• httpservererror: An error occurs because the origin server returns an HTTP 5xx status code, a server error.

• 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-Control content control directive.

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

• incorrectesifragment: An error occurs when OracleAS 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 OracleAS Web Cache.

Example

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

<esi:try>
  <esi:attempt>
    <esi:comment text="Include an ad"/>
    <esi:include src="http://www.company.com/ad1.htm"/>
  </esi:attempt>
  <esi:except>
    <esi:comment text="Just write some HTML instead"/>
    <a href=www.company.com>www.company.com</a>
  </esi:except>
</esi:try>

The following ESI markup attempts to fetch a fragment. If the fragment cannot be included because of httpclienterror, then OracleAS Web Cache includes /cgi-bin/esi-fetch?/esi/tryNestL1.html instead.

<esi:try>
  <esi:attempt>
    <esi:include src="/frag.html"/>
  </esi:attempt>
  <esi:except type="httpclienterror">
    <esi:include src="/cgi-bin/esi-fetch?/esi/tryNestL1.html"/>
  </esi:except>
</esi:try>

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, OracleAS Web Cache returns an Unknown ESI Exception error.

<esi:try>
  <esi:attempt>
    <esi:include src="http://server.portal.com/pls/ppcdemo/!PCDEMO.wwpro_app_provider.execute_portlet/513104940/26" timeout="15000" >
      <esi:request_header name="X-Oracle-Device.MaxDocSize" value="0"/>
      <esi:request_header name="Accept" 
      value="text/html,text/xml,text/vnd.oracle.mobilexml"/>
      <esi:request_header name="User-Agent" 
        value="Mozilla/4.0 (compatible; MSIE 5.5; Windows; YComp 5.0.0.0) 
        RPT-HTTPClient/0.3-3"/>
      <esi:request_header name="Device.Orientation" value="landscape"/>
      <esi:request_header name="Device.Class" value="pcbrowser"/>
      <esi:request_header name="PORTAL-SUBSCRIBER" value="us"/>
      <esi:request_header name="Device.Secure" value="false"/>
      <esi:request_header name="PORTAL-SUBSCRIBER-DN"
         value="dc=us,dc=oracle,dc=com"/>
      <esi:request_header name="PORTAL-SUBSCRIBER-GUID"
         value="A5EE385440E6252BE0340800208A8B00"/>
      <esi:request_header name="Accept-Language" value="en-us"/>
      <esi:request_header name="PORTAL-USER-DN"
         value="cn=public,cn=users,dc=us,dc=oracle,dc=com"/>
      <esi:request_header name="PORTAL-USER-GUID"
         value="A5EE55B396E22651E0340800208A8B00"/>
      <esi:request_header name="Content-Type"
         value="application/x-www-form-urlencoded"/>
    </esi:include>
  </esi:attempt>
  <esi:except type="incompatiblefragmentversion" >
     This happens when a fragment's processing requirement is not supported 
     or not compatible with the template.
  </esi:except>
  <esi:except type="noconnection" >
     The cache is unable to connect to the origin server serving this fragment.
  </esi:except>
  <esi:except type="nestingtoodeep" >
     The fragment include depth has exceeded the maximum include depth. The
     default value defined in Web Cache is 3.
  </esi:except>
  <esi:except type="httpservererror" >
     The origin server returns an HTTP 5xx status code, a server error.
  </esi:except>
  <esi:except type="httpclienterror" >
     The origin server returns an HTTP 4xx status code, a client error, such as
     a malformed HTTP request or an unauthorized access.
  </esi:except>
  <esi:except type="incorrectresponseheader" >
     This happens when the response headers for a fragment cause the error.
  </esi:except>
  <esi:except type="incorrectxmlfragment" >
     This happens when there is any kind of error in OracleAS Web Cache XSLT
     retrieval, parsing, or processing.
  </esi:except>
  <esi:except type="originserverbusy" >
     The origin server for this fragment is busy and cannot accept new requests
     now. This is caused by OracleAS Web Cache-to-origin server request queue
    limit.
  </esi:except>
  <esi:except type="networktimeout" >
     This is thrown by a fragment whose request to the origin server has timed
     out in the network connection. 
  </esi:except>
  <esi:except type="incorrectesifragment" >
     An error is encountered when OracleAS Web Cache tries to parse or process
     the ESI fragment response body due to errors in the body.
  </esi:except>
  <esi:except>
     Unknown ESI Exception
  </esi:except>
</esi:try>

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.

Syntax

<esi:vars>Optional HTML code $(VARIABLE_NAME{key}) Optional HTML code</esi:vars>

Syntax Usage

• If the variable does not use the complete $(VARIABLE_NAME{key}) format, OracleAS Web Cache reports the following error message to the event log:

  [Date] [error 12086] [ecid: request_id, serial_number]ESI syntax error. Unrecognized keyword keyword is at line line.
  
  

• Do not nest the <esi:vars> tag within an HTML code line. The following is an example of incorrect syntax:

  HTML code <esi:vars>$(VARIABLE_NAME{key})</esi:vars>HTML code
  
  

  For example, the following is invalid:

  <IMG SRC="http://www.example.com/<esi:vars>$(HTTP_COOKIE{type})</esi:vars>/hello.gif"/>
  

Usage

Example

The following ESI markup includes the cookie type and its value as part of the included URL:

<esi:vars>
  <IMG SRC="http://www.example.com/$(HTTP_COOKIE{type})/hello.gif"/>
</esi:vars>

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.

<esi:vars>
  <A HREF="welcome.jsp?name=$(logindata{name})">
  <A HREF="/shopping.jsp?sessionID=$(QUERY_STRING{sessionID})&type=$(QUERY_STRING{type})">
  <IMG SRC="/img/shopping.gif">
  </A>
  <A HREF="/news.jsp?sessionID=$(QUERY_STRING{sessionID})&type=$(QUERY_STRING{type})">
  <IMG SRC="/img/news.gif">
  </A>
  <A HREF="/sports.jsp?sessionID=$(QUERY_STRING{sessionID})&type=$(QUERY_STRING{type})">
  <IMG SRC="/img/sports.gif">
  </A>
  <A HREF="/fun.jsp?sessionID=$(QUERY_STRING{sessionID})&type=$(QUERY_STRING{type})">
  <IMG SRC="/img/fun.gif">
  </A>
  <A HREF="/about.jsp?sessionID=$(QUERY_STRING{sessionID})&type=$(QUERY_STRING{type})">
  <IMG SRC="/img/about.gif">
  </A>
 </esi:vars>

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, OracleAS 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 will not interfere with the final HTML output.

Syntax

<!--esi
 ESI elements
-->

Usage

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

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.