Skip Headers

Oracle® Application Server Containers for J2EE JSP Tag Libraries and Utilities Reference 10g Release 2 (10.1.2) B14016-02 |
| Library | Product | Contents | Index

Previous | Next |

# 6 JESI Tags for Edge Side Includes

This chapter describes the Edge Side Includes for Java (JESI) tag library that is supplied with OC4J. These tags operate on top of an Edge Side Includes (ESI) framework that is available in the Oracle Application Server Web Cache to provide ESI caching functionality in a JSP application.

The chapter consists of the following sections:

- Overview of Edge Side Includes Technology and Processing

- Overview of JESI Functionality

- Oracle JESI Tag Descriptions

- JESI Tag Handling and JESI-to-ESI Conversion

For an overview of Web caching, including a discussion of the OracleAS Web Cache, the Oracle Application Server Java Object Cache, and the OC4J Web Object Cache, see "Summary of Oracle Caching Support for Web Applications".

Note: The JESI specification is not yet finalized. Although every effort has been made to comply with the latest working version, it is not possible to assure that the OC4J 10.1.2 implementation will fully comply with the final version of the JESI specification.

## Overview of Edge Side Includes Technology and Processing

JESI tags, which are used to break down dynamic content of JSP pages into cacheable components, are based upon the Edge Side Includes architecture and markup language.

Although the use of JESI tags does not depend on any particular ESI processor or caching system, a typical scenario among Oracle customers is to use the OracleAS Web Cache and its ESI processor.

The following sections provide background information about some of the underlying technology upon which the Oracle JESI tags are based.

- Edge Side Includes Technology

- Oracle Application Server Web Cache and ESI Processor

This discussion provides only a brief overview of the ESI architecture and language. For additional information about ESI technology, refer to the following Web site:

    http://www.esi.org

### Edge Si de Includes Technology

This section introduces the features of ESI technology and the concept of ESI surrogates.

#### Introduction to ESI

Edge Side Includes is an XML-style markup language that allows dynamic content assembly at the "edge" of the network, away from the origin Web server, and is designed to take advantage of available tools such as Web caches and content delivery networks (CDNs) to improve performance for users.

ESI provides a way to reduce the load on Web and application servers by promoting processing on intermediaries, known as surrogates or reverse proxies, that understand the ESI language and act on behalf of the Web server. ESI content is intended for processing somewhere between the time it leaves the originating Web server and the time it is displayed in the user's browser. A surrogate is commanded through HTTP headers. Such a surrogate can be referred to as an ESI processor and can be included as part of the functionality of a Web cache.

ESI lends itself to a partial-page caching methodology, where each dynamic portion of a Web page can be cached individually and retrieved separately and appropriately.

Using the ESI markup tags, a developer can define aggregate Web pages and the cacheable components that are to be retrieved and assembled, as appropriate, by the ESI processor for viewing in the HTTP client. Think of an aggregate page, which is the resource associated with the URL that a user specifies, as a container for assembly. This includes retrieval and assembly instructions that are specified through the ESI tags.

Important: Do not use ESI tags directly in a page where you use JESI tags.

#### More About Surrogates

Because surrogates act on behalf of Web servers, where page content is owned, they allow content owners to have sufficient control over their behavior. In this way, they offer greater potential for performance improvements than would otherwise be available.

The caching process in surrogates operates similarly to the caching process in HTTP, using similar freshness and validation mechanisms as the foundation. However, surrogates also possess additional control mechanisms.

#### Key ESI Features

Version 1.0 of the ESI language includes the following key areas of functionality:

- Inclusion

  An ESI processor assembles fragments of dynamic content, retrieved from the network, into aggregate pages to output to the user. Each fragment can have its own meta data to control its caching behavior. See Figure 6-1 below.

- Support of variables

  ESI supports the use of variables that are based on HTTP request attributes. ESI statements can use variables during processing or can output them directly into the processed markup.

- Conditional processing

  ESI allows the 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 (or both), such as an alternate Web page, if the primary resource cannot be found.

Figure 6-1 ESI Include Model

Description of "Figure 6-1 ESI Include Model"

### Oracle Application Server Web Cache and ESI Processor

This section introduces the OracleAS Web Cache and its ESI processor. See the Oracle Application Server Web Cache Administrator's Guide for more information.

#### Introduction to Oracle Application Server Web Cache

Oracle offers OracleAS Web Cache to help e-businesses manage Web site performance issues. It is a content-aware server accelerator, or reverse proxy server, that improves the performance, scalability, and availability of Web sites that run on the Oracle Application Server.

By storing pages from frequently accessed URLs in memory, OracleAS Web Cache eliminates the need to repeatedly process requests for those URLs on the application Web server. Unlike legacy proxy servers that handle only static documents, OracleAS Web Cache caches both static content and dynamically generated content from one or more application Web servers. As the result of more frequent cache hits, performance enhancement is greater than with legacy proxies and the load on application servers is less.

Conceptually, OracleAS Web Cache is positioned in front of application Web servers, caching their content and sending that content to Web browsers that request it. When Web browsers access the Web site, they send HTTP protocol or HTTPS protocol requests to OracleAS Web Cache, which, in turn, acts as a virtual server for the application Web servers. If the requested content has expired, has been invalidated, or is no longer accessible, then OracleAS Web Cache retrieves the new content from the application Web servers.

#### Steps in Oracle Application Server Web Cache Usage

Here are the steps for typical browser interaction with OracleAS Web Cache:

1. A browser sends a request to the Web site of a company.

2. The request, in turn, generates a request to the Domain Name System (DNS) for the IP address of the Web site.

3. DNS returns the IP address of OracleAS Web Cache.

4. The browser sends the request for the Web page to OracleAS Web Cache.

5. If the requested content is in its cache, then OracleAS Web Cache sends the content directly to the browser. This is known as a cache hit.

6. If OracleAS Web Cache does not have the requested content, or if the content is outdated or invalid, then the Web cache hands off the request to the application Web server. This is known as a cache miss.

7. The application Web server sends the content through OracleAS Web Cache.

8. OracleAS Web Cache sends the content to the client and makes a copy of the page in cache.

   Note: A page that is stored in the cache is removed at some point after it becomes invalid or outdated.

#### Oracle Application Server Web Cache ESI Processor

OracleAS Web Cache includes an ESI processor to support the use of the Edge Side Includes markup language in caching. (See "Edge Side Includes Technology".)

Web developers in an OracleAS Web Cache environment can use the ESI language directly in their applications; however, for JSP developers, there are several reasons to use the JESI tag library that is provided as a convenient JSP interface to the ESI language. See "Advantages of JESI Tags", which follows shortly.

## Over view of JESI Functionality

The following sections introduce JESI functionality and the Oracle implementation:

- Advantages of JESI Tags

- Overview of JESI Tags Implemented by Oracle

- JESI Usage Models

- Invalidation of Cached Objects

- Personalization of Cached Pages

- JESI Fallback Execution

You can access the proposed JESI specification at the following Web site:

    http://www.esi.org

### Advantages of JESI Tags

OC4J provides the JESI tag library as a convenient interface to ESI tags and Edge Side Includes functionality for Web caching. Developers have the option of using ESI tags directly in any Web application, but JESI tags provide additional convenience for JSP pages. Here are the main advantages in using JESI tags instead of using ESI tags directly:

- Standard JSP framework and convenient features

  - JESI tags allow use of the familiar and convenient features of JSP programming. For example, you can reference included pages according to page-relative or application-relative locations, instead of the complete URL or file path.

  - You can pass dynamic values to JESI tag attributes.

  - You can use JESI tags in combination with tags from other JSP tag libraries.

- JESI shortcut syntax

  JESI tags support convenient syntax and tag attributes for specifying meta data information (such as expiration for cached pages), explicitly invalidating pages as appropriate, and personalizing pages using cookie information.

- Application-level configuration files

  The JESI tag library can use application-level configuration files for convenient specification of deployment-time parameters and application default settings that are appropriate to a particular environment. In this way, you can deploy to different environments that have diverse needs and set appropriate defaults without changing application code. For example, you can use such a configuration file to preset the cache server URL, user name, and password for invalidation requests.

### Overview of JESI Tags Implemented by Oracle

The Oracle implementation of JESI is layered on top of the standard ESI framework. It also conforms with the pending (as of the OC4J 10.1.2 implementation) JESI standard, JSR-128, which is sponsored by the Java Community Process (JCP) organization. For more information about the JCP organization and the status of JSR-128, go to the following location:

    http://www.jcp.org

Because the JESI tag library is a standard implementation, note the following:

- An application that uses JESI tags does not depend on the OC4J JSP container. It is portable to any standard JSP container. (Outside of OC4J, you can use either the reference implementation to be provided with JSR-128, or the JESI implementation that is provided with the JSP container you are using, if applicable.)

- Even though this document discusses the OracleAS Web Cache and its ESI processor in particular, the JESI tag library does not depend on any particular caching environment and can work with any ESI processor that conforms to the ESI 1.0 specification.

The Oracle JESI tag library supports the following tags:

- JESI `control`, JESI `include`, JESI `param`, JESI `template`, JESI `fragment`, and JESI `codeblock` for dynamic caching of page content

- JESI `invalidate` (and subtags) for explicit invalidation of cached objects, when appropriate

- JESI `personalize` for page customization through cookies

JSP developers use these tags (such as JESI `include`) instead of corresponding ESI tags (such as `esi:include`). The usefulness and convenience of this is discussed in "Advantages of JESI Tags".

Note: The Oracle JESI tag library is implemented according to general standards for JSP custom tag libraries. For information about the standard JavaServer Pages tag library framework, refer to the Oracle Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide.

### JESI Usage Models

There are two models for how to use JESI tags to define aggregate pages and their cacheable components:

- Control/include model

- Template/fragment model

This section describes these models and concludes with some special notes about the JESI `include` tag.

#### Co ntrol/Include Model

The control/include approach to using JESI tags is modular, typically bringing most (or all) cacheable content into the aggregate page as included pages. This is particularly convenient when you are developing new pages. Use this model as follows:

- Use the JESI `control` tag in the top-level page to set caching parameters for content outside the included content, as applicable.

- Use JESI `include` tags to bring in dynamic content.

- Use a JESI `control` tag inside each included page to set caching parameters for those pages, as appropriate.

Each included file is a distinct cacheable object (although caching can be disabled according to tag settings), and any content in the top-level page is also a distinct object.

Both tags are optional, depending on the situation. A page can have a JESI `control` tag without any JESI `include` tags. In fact, this is a simple way to convert an existing page for JESI use. There is also no requirement for a JESI `control` tag in a page that uses JESI `include` tags. The ESI processor will be appropriately notified of the presence of the JESI `include` tags, regardless. And there is no requirement for an included page to have a JESI `control` tag.

The cacheability of a page, either top-level or included, is determined as follows.

- If there is a JESI `control` tag, cacheability depends on attribute settings or on the default attribute values, as applicable.

- If there is no JESI `control` tag, cacheability depends on configuration settings of the ESI processor.

- The JESI `control` tag in the top-level page has no effect on included pages.

See the following sections for tag syntax and examples:

- "JESI control Tag"

- "JESI include Tag"

- "JESI param Tag"

- "Examples: Control/Include Model"

#### Te mplate/Fragment Model

In the template/fragment approach, content is contained in a single page and you split the page into separately cacheable fragments as desired. This model is particularly convenient when you are converting existing pages for JESI use and want certain portions to be separate cacheable components. Use this model as follows:

- Use the JESI `template` tag to enclose the aggregate of all visible content. This tag sets caching parameters for the content outside the fragments. There must be no visible content outside the `template` tag.

- Use JESI `fragment` tags as desired, between the `template` start-tag and end-tag, to define fragments within the aggregate, to be cached separately.

- Optionally use JESI `include` tags as well, either at the template level or the fragment level.

- Optionally use `codeblock` tags within the template tag, outside of any fragments, to mark conditional execution of blocks of code.

The JESI `template` tag and JESI `fragment` tag are always used together. If you do not need separate fragments in a page, use the JESI `control` tag instead of the JESI `template` tag.

Each fragment is a distinct, cacheable object. Any content at the template level, outside any fragments, is a distinct, cacheable object. Any page that is included through a JESI `include` tag is also a distinct, cacheable object. Cacheability is determined as follows.

- The cacheability of the template (content outside any fragments) depends on the JESI `template` tag attribute settings or on the default attribute values, as applicable.

- Similarly, the cacheability of a fragment depends on the attribute settings of the JESI `fragment` tag or on the default attribute values, as applicable.

- The cacheability of an included page is determined as follows.

  - If there is a JESI `control` tag, cacheability depends on attribute settings or on the default attribute values, as applicable.

  - If there is no JESI `control` tag, cacheability depends on configuration settings of the ESI processor.

Note: It is permissible for the template/fragment model to be used in a response that has already processed a JESI `control` tag. This might be required, for example, in a case where conditional generation of the aggregate response can include response from any of a set of alternative pages. In this case, the JSP container uses the attribute settings of the `control` tag, ignores the attribute settings of the `template` tag, but notes the fact that there is a `template` tag properly enclosing any `fragment` tags, as required. As is always the case in the template/fragment model, there must be no cacheable content outside the `template` tag.

Because the template and fragments are independent, cacheable objects, they can expire at different times in the ESI processor. When a cache miss occurs or an object that has expired is requested, the ESI processor makes a request to the origin server (OC4J in the case of Oracle Application Server) for a fresh copy.

If a requested object is a JESI template, the JSP container executes code in the page that is outside any fragments. In output that is generated by the JSP translator, the translator also places ESI markup that designates where all the fragments should be included. The code that is contained in the JESI fragments will not be executed at that time. The following figure illustrates this.

Figure 6-2 JESI Request for Template

Description of "Figure 6-2 JESI Request for Template"

When a fragment expires, the ESI processor makes a request to the origin server for that particular fragment. To execute a fragment, the OC4J JSP container executes the template code (code outside of any fragments) plus the code of the fragment being requested. The template code is executed to allow a fragment to rely on certain side effects, such as declaration or initialization of variables.

The output of the fragment code is returned in the response; the output of the template code is discarded. Upon receiving the response, the ESI processor will cache the updated copy of the fragment. The following figure illustrates this.

Figure 6-3 JESI Request for Fragment

Description of "Figure 6-3 JESI Request for Fragment"

Note: To avoid needlessly repeating the execution of expensive template code, strategically place the code within JESI `codeblock` tags. Configure each `codeblock` tag according to when you want the code within it to be executed (whenever the template is requested, whenever a fragment is requested, or always).

Remember this behavior when choosing code placement and expiration policies for your templates and fragments. In particular, because template code is executed in every update request, be aware of where you place any expensive code. Do not place an expensive computation at the template level unless it must be executed every time or is appropriately placed within a `codeblock` tag. Otherwise, place expensive computation in a fragment that has as long an expiration time as possible.

Figure 6-4 shows one `codeblock` tag scenario, in which the code block is to be executed only when a fragment is requested. In this figure, the request is for the template, so the code block is not executed.

Figure 6-5 shows another `codeblock` tag scenario, in which the code block is still to be executed only when a fragment is requested. This time, however, the request is for the fragment, so the code block is executed.

Figure 6-4 JESI codeblock Fragment Execution with Request for Template

Description of "Figure 6-4 JESI codeblock Fragment Execution with Request for Template"

Figure 6-5 JESI codeblock Fragment Execution with Request for Fragment

Description of "Figure 6-5 JESI codeblock Fragment Execution with Request for Fragment"

Additionally, remember that no two fragments are ever executed during the same request. For example, you should not declare or set the value of a scriptlet variable in one fragment and depend on that variable or the set value in another fragment. If a variable is needed in more than one fragment, then it should be declared and set in the template code (possibly inside a `codeblock` tag). Similarly, do not set a request or session attribute in one fragment and then try to read it in another fragment. Such "page-global logic" should also be placed at the template level.

Finally, remember that the different fragments of a page will be refreshed at different times, according to invalidation messages and expiration settings. Typically, in a well-tuned application, most fragments would be served from the ESI cache, having to be regenerated only infrequently.

Note: You can intersperse JESI `template`, JESI `fragment`, and JESI `include` tags with `jsp:include` tags if the JESI tags follow JESI rules and are properly nested with respect to each other. For example, you can have a page with a JESI `template` tag, have a `jsp:include` tag within the `template` tag, and have JESI `fragment` tags in the included page. You can also use the JESI `template` tag within an included page if there is no other `template` tag at a higher level, and if all output to the response buffer is within the `template` tag.

See the following sections for tag syntax and examples:

- "JESI template Tag"

- "JESI fragment Tag"

- "JESI include Tag"

- "JESI codeblock Tag"

- "Examples: Template/Fragment Model"

#### Notes About JESI and JSP Includes

In using either the control/include or template/fragment model, be aware of the following notes regarding the JESI `include` statement:

- A nested JESI inclusion is supported, either as a JESI `include` statement that includes a page that, in turn, has its own JESI `include` statement, or as a JESI `include` statement inside a fragment that is defined with a JESI `fragment` statement.

  In the second case, for example, the ESI processor executes the following steps:

  1. It requests the content of the aggregate page.

  2. It locates the content of the fragment in the cache (if applicable) or requests it.

  3. It locates the content of the included page in the cache (if applicable) or requests it.

- Despite conceptual similarities between the JESI `include` tag and the standard `jsp:include` tag, there are situations in which you should not substitute a JESI include tag for a `jsp:include` tag when you convert a JSP page for caching. Because the ESI processor uses separate HTTP requests, you are unable to pass an HTTP request or response object between one page and a page it includes through a JESI `include` tag. If the code in the included page requires access to the request or response object of the originating page, then you should consider using the JESI template/fragment model and putting the code in a JESI `fragment` tag (within the JESI `template` tag of the aggregate page) instead of using the JESI `include` tag.

### Inv alidation of Cached Objects

There might be situations where cached objects must be explicitly invalidated due to external circumstances, such as changes to relevant data in a database. There might also be situations where execution of one page might invalidate the data of cached objects corresponding to another page.

For this reason, JESI provides the JESI `invalidate` tag and related subtags. These tags allow you to invalidate pages based on appropriate combinations of the following:

- Full URI or URI prefix

- Cookie name-value pair (optional)

- HTTP/1.1 request header name-value pair (optional)

Invalidation messages are in an XML-based format and specify the URLs to be invalidated. These messages are initiated by the JSP container when it executes the JESI `invalidate` tag, and transmitted to the cache server over HTTP using a `POST` method. The cache server then replies with an invalidation response, sent back over HTTP.

See "Descriptions of Tags and Subtags for Invalidation of Cached Objects" for tag syntax and examples.

### Pers onalization of Cached Pages

Dynamic Web pages frequently display customized information tailored to each individual user. For example, a welcome page might display the user's name and a special greeting, or current quotes for stocks the user owns.

For this kind of tailored output, the Web page depends on cookie information, which can be provided through the JESI `personalize` tag. Without this tag to inform the ESI processor of the need to perform cookie substitution, the Web page cannot be shared by multiple users at the ESI level.

See "Description of Tag for Page Personalization" for tag syntax and examples.

### JESI Fallback Execution

If no ESI processor is available for a page that uses JESI tags (such as on a system without OracleAS Web Cache, or in which Web Cache or its ESI processor is down), then the OC4J JSP container steps in to assemble the pages appropriately. Essentially, it takes over and provides the most crucial functionality to execute the pages properly. Caching does not take place, nor does error-checking of JESI tag attribute values.

In these circumstances, the JSP container processes the particular JESI tags as follows:

- It ignores JESI `control` tags.

- It executes JESI `include` tags as though they are `jsp:include` tags, and the associated JESI `param` tags as though they are `jsp:param` tags. Note that any scriptlet code that is nested within a JESI `include` tag will still be executed.

  Note: In this circumstance, unlike with JESI `include` functionality, there is no longer a separate response object for an included page.

- It checks JESI `template` and `fragment` tags for proper nesting, but otherwise ignores them and executes all their tag bodies during a single request.

- It unconditionally executes any code in JESI `codeblock` tags.

- It ignores JESI `invalidation` tags and all subtags.

- For JESI `personalize` tags, it inserts the cookie value into the response body if the cookie previously existed. If the cookie did not previously exist and a default value is specified in the `personalize` tag, then the JSP container inserts the default value into the response body. If the cookie did not previously exist and no default value is specified, then the `personalize` tag has no effect.

## Oracle JESI Tag Des criptions

The following sections describe the syntax and attributes of the JESI tags provided with OC4J, followed by usage examples:

- Descriptions of Tags for Dynamic Caching

- Descriptions of Tags and Subtags for Invalidation of Cached Objects

- Description of Tag for Page Personalization

Note the following requirements for the JESI tag library:

- The Oracle JESI tag library, a standard JavaServer Pages tag library implementation, is included in the `ojsputil.jar` file, which is provided with OC4J and is located in the "well-known" tag library directory. Verify that this file is installed and in your classpath.

- The ta g library descriptor, `jesitaglib.tld`, must be available to the application, and any JSP page using the library must have an appropriate `taglib` directive. In an Oracle Application Server installation, the TLD is in the `ojsputil.jar` file. The `uri` value for `jesitaglib.tld` is the following:

      http://xmlns.oracle.com/j2ee/jsp/tld/ojsp/jesitaglib.tld

Refer to the Oracle Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide for information about `taglib` directives, the well-known tag library directory, TLD files, and the meaning of `uri` values.

Notes: The prefix "jesi:" is used in the tag syntax here. This is by convention and is not required. You can specify any desired prefix in your `taglib` directive. See "Tag Syntax Symbology and Notes" for general information about tag syntax conventions in this manual.

### Descriptions of Tags for Dynamic Caching

The following sections cover the use of JESI tags for dynamic caching, document their syntax and attributes, and provide examples:

- JESI control Tag

- JESI include Tag

- JESI param Tag

- Examples: Control/Include Model

- JESI template Tag

- JESI fragment Tag

- JESI codeblock Tag

- Examples: Template/Fragment Model

See "JESI Usage Models" for overviews of the control/include and template/fragment models.

#### JESI contr ol Tag

The JESI `control` tag controls caching characteristics for JSP pages in the control/include usage model. You can use a JESI `control` tag in the top-level page or any included page, but it is not mandatory. For any page without a JESI `control` tag in the control/include model, cacheability is according to the configuration settings of the ESI processor. (See "JESI Usage Models".)

Because action resulting from the JESI `control` tag sets the HTTP response header, this tag should appear as early as possible in the page, before any other JESI tags or any buffer flushes in the page.

Note the following:

- All attributes of the JESI `control` tag are optional. If you use a tag without any settings, then, by default, the cacheability of a response has an expiration setting of 24 hours, with immediate removal of expired objects.

- If you want caching behavior to be determined by the configuration of the ESI processor, then do not use a JESI `control` tag for the page in question.

- The JESI `control` tag of an originating page (a page with a JESI `include` tag) has no effect on included pages. Use a JESI `control` tag in each included page as well, as necessary.

- If the JSP container encounters multiple JESI `control` tags while generating a single response, then only the first one is processed. The rest are ignored. Note that a page that is included through a JESI `include` tag (where such a page might have its own JESI `control` tag) results in a separate response.

- If the JSP container has already encountered a JESI `template` tag when it encounters a JESI `control` tag while still generating the same response, then the `control` tag is ignored.

- If a page with a JESI `control` tag depends on request parameters, consider whether you must cache different versions of the page, depending on the request query string. Another alternative is to not cache the page at all (set `cache="no"`) if you anticipate that too many different request parameter values will result in too many cached versions of the page.

##### Syntax

    <jesi:control
                 [ expiration = "value" ]
                 [ maxRemovalDelay = "value" ]
                 [ cache = "yes" | "no" | "no-remote" ]
                 [ control = "uninterpreted_string" ] />

##### Attributes

- `expiration`: Specifies the lifetime, in seconds, of the cached object. The default is 86400 (24 hours).

- `maxRemovalDelay`: Specifies the maximum time, in seconds, that the ESI processor continues to store the cached object after it has expired. The default is 0, for immediate removal.

- `cache`: Specifies whether the response corresponding to the tag is cacheable. A "`yes`" setting (the default) enables caching. Alternatively, you can set `cache` to "`no`" to disable caching, or to "`no-remote`" to enable caching only on the closest cache (instead of on a remote ESI processor or content delivery network).

  One reason to make a page noncacheable, for example, is if you are using a JESI `include` tag with `copyParam="yes"`. See "JESI include Tag" below.

- `control`: The value of this attribute is appended without change to the `Surrogate-Control` response header that was created during processing of the JESI `control` tag. The OracleAS Web Cache ESI processor does not use this attribute; however, it would be useful if you are using another ESI processor for your application and want to pass it any additional proprietary information in the header.

Notes: Do not confuse the `control` attribute name with the `control` tag name. "JESI Tag Handling and JESI-to-ESI Conversion" includes some discussion of the `Surrogate-Control` header.

#### JESI in clude Tag

The JESI `include` tag, as with a standard `jsp:include` tag, allows dynamic insertion of output from the included page into output from the originating page. It does so by directing the ESI processor to process and assemble the included pages. Each included page is a separate cacheable object (but might not be cached, depending on settings).

You can use this tag in either the control/include model or the template/fragment model, in any of the following scenarios:

- By itself, without a JESI `control` tag or JESI `template` and `fragment` tags

- In the control/include model, after a JESI `control` tag

- In the template/fragment model, within a JESI `fragment` tag, or within the JESI `template` tag but outside any fragments

(See "JESI Usage Models".)

In addition, it is permissible to nest JESI includes, either by using a JESI `include` tag inside a page that is itself included through a JESI `include` tag, or by using a JESI `include` tag inside a page that is included through a standard `jsp:include` tag.

The cacheability of an included page is determined as follows:

- If there is a JESI `control` tag, cacheability depends on attribute settings or on the default attribute values, as applicable.

- If there is no JESI `control` tag, cacheability depends on configuration settings of the ESI processor.

##### Syntax

    <jesi:include page = "uri"
                [ alt = "alternate_uri" ]
                [ ignoreError = "true" | "false" ]
                [ flush = "true" | "false" ]
                [ copyParam = "true" | "false" ] >

    ...optional jesi:param tags, related scriptlets...

    </jesi:include>

Notes: As with standard `jsp:include` tags and their optional `jsp:param` subtags, you can use JESI `param` tags nested within a JESI `include` tag to specify new parameters that will be sent to the originating page (the page with the JESI `include` tag). See "JESI param Tag" for tag syntax. In addition, the body of a JESI `include` tag can contain scriptlet code to be used in evaluating the added parameters. Output from the scriptlet code, however, and from the body of any JESI `include` tag in general, is discarded. In some cases, JESI `include` tags behave differently from `jsp:include` tags. This is because the JESI `include` tag results in separate request and response objects for the included page. A JESI `include` tag is not suitable, for example, when the originating page sets a request attribute and the included page reads this attribute from the request object. For backward compatibility, the deprecated "`copyparam`" form of the `copyParam` attribute is accepted. The change from `copyparam` to `copyParam` was made to comply with the proposed JESI specification. It is likely that `copyparam` will be desupported at some point.

##### Attributes

- `page` (required): Specifies the URI of the JSP page to be included, either a page-relative or application-relative location. (Refer to the Oracle Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide regarding syntax for page-relative and application-relative locations.) A full "`http://...`" or "`https://...`" URL is supported as well.

  The URI can optionally specify additional query parameters and values to pass to the included page, but using JESI `param` subtags is a preferred mechanism for this. See "JESI param Tag".

- `alt`: Specifies a URI for an alternate page that is to be included if the page that is specified in the `page` attribute cannot be found. Syntax is the same as for the `page` attribute.

- `ignoreError`: Set this to "`true`" for continued processing of the originating page, even if no included page can be accessed (neither the `page` page nor the `alt` page). The default is "`false`".

- `flush`: This attribute is ignored, but is allowed in order to ease migration from `jsp:include` syntax.

- `copyParam`: If the included page makes use of request parameters, set this to "`true`" if you want to copy parameters and their values from the HTTP request string of the originating page to the included page. The default value is "`false`".

  If request parameters are significant to the included page and `copyParam="true"`, then either the originating page should not be cached (`cache="no"` in the JESI `control`, JESI `template`, or JESI `fragment` tag), or multiple versions of the originating page should be cached, according to parameter settings.

  As an example, avoid scenarios such as the following:

      <jesi:control cache="yes"/>
      ...
      <jesi:include page="arf.jsp" copyParam="true" />

  The reason is that if a copy of this originating page is served from the cache, and if parameters of this subsequent request are different than those of the original request, then the page will not execute on the server or have a chance to properly copy new parameters into `arf.jsp`. This would result in clients being served `arf.jsp` generated from incorrect parameters.

  However, this scenario would not be problematic in certain circumstances, such as either of the following:

  - The `arf.jsp` page does not use the request parameters.

  - Appropriate versions of the originating page and `arf.jsp` are cached in the ESI processor, based on URL parameters. See the Oracle Application Server Web Cache Administrator's Guide for more information.

#### JESI par am Tag

The JESI `param` tag is an optional subtag of the JESI `include` tag. These tags work together in the same way that standard `jsp:include` and `jsp:param` tags work together.

You can use one or more JESI `param` subtags to pass additional query parameters to the target page of the JESI `include` tag. Doing this is more straightforward than the alternative, which is to specify parameters in the `page` URI of the JESI `include` tag. If you use both mechanisms, then parameters from `param` tags are appended after parameters from the `include` tag `page` URI. Any parameters that are copied from the original request, through an `include` tag `copyParam="yes"` setting, are appended after parameters from JESI `param` tags.

See "Example 5: Control/Include with param Tag" for a sample.

Note: Be aware that the parameter name and value will be evaluated when the originating page (the page with the JESI `include` and `param` tags) is generated. If, afterward, the originating page is cached in an ESI processor, then the name and value of the parameter, passed down to the included page, remain unchanged until the originating page is regenerated. (This is similar to the treatment of request parameters that are copied from the request through a `copyParam="true"` setting.)

##### Syntax

    <jesi:include page = "uri" ... >
       <jesi:param name="param_name"
             value="param_value" />
       ...
    </jesi:include>

##### Attributes

- `name` (required): Specifies the name of the parameter.

- `value` (required): Specifies the value of the parameter.

#### Exa mples: Control/Include Model

This section provides examples of JESI tag usage in the control/include model.

##### Example 1: Control/Include

The following example employs default cache settings; no JESI `control` tag is necessary. The JESI `include` tags specify no alternate files, and a "file not found" error will halt processing. The `flush` attribute is permissible, but ignored.

    <%@ taglib uri="http://xmlns.oracle.com/j2ee/jsp/tld/ojsp/jesitaglib.tld"
               prefix="jesi" %>
    <html>
    <body>
    <jesi:include page="stocks.jsp" flush="true" />
    <p>
    <hr>
    <jesi:include page="/weather.jsp" flush="true" />
    <p>
    <hr>
    <jesi:include page="../sales.jsp" flush="true" />
    </body>
    </html>

##### Example 2: Control/Include

This example uses the JESI `control` tag to specify nondefault cache settings for `maxRemovalDelay` and `expiration`. In addition, it explicitly enables caching of the page, though this is already enabled by default. The first JESI `include` tag specifies an alternate page in case `order.jsp` cannot be retrieved by the ESI processor, and specifies that processing should continue even if neither page can be retrieved. The second JESI `include` tag specifies no alternate page; processing will halt if the page cannot be retrieved.

    <%@ taglib uri="http://xmlns.oracle.com/j2ee/jsp/tld/ojsp/jesitaglib.tld"
               prefix="jesi" %>

    <jesi:control maxRemovalDelay="1000" expiration="300" cache="yes"/>
    <jesi:include page="order.jsp" alt="alt.jsp" ignoreError="true"/>
    <jesi:include page="commit.jsp" />

##### Example 3: Control/Include

This example is of an aggregate page with conditional output. A cookie represents the identity of a customer. If no cookie is found, the user will be shown a generic welcome page with general product information. If a cookie is found, the user will be shown a list of products according to the user profile. This list is brought into the page through a JESI `include` statement.

The JESI `control` tag also sets nondefault values for `maxRemovalDelay` and `expiration` and explicitly enables caching for the page.

    <%@ taglib uri="http://xmlns.oracle.com/j2ee/jsp/tld/ojsp/jesitaglib.tld"
               prefix="jesi" %>

    <jesi:control maxRemovalDelay="1000" expiration="300" cache="yes"/>
    <%
      String customerId=CookieUtil.getCookieValue(request,"customerid");
      if (customerId==null) {
        // some unknown customer
    %>
        <jesi:include page="genericwelcome.jsp" />
    <%
      }
      else {
        // a known customer; trying to retrieve recommended products from profiling
        String recommendedProductsDescPages[]=
                   ProfileUtil.getRecommendedProductsDescURL(customerId);
        for (int i=0; i < recommendedProductsDescPages.length; i++) {
    %>
        <jesi:include page="<%=recommendedProductsDescPages[i]%>" />
    <%
        }
      }
    %>

##### Example 4: Control/Include

This example illustrates the use of JESI `include` statements with request parameters. Assume that the main page is accessed through the following URL:

    http://host:port/application1/main.jsp?p2=abc

The main page takes the parameter setting `p2=abc`. Here is that page:

    <%@ taglib uri="http://xmlns.oracle.com/j2ee/jsp/tld/ojsp/jesitaglib.tld"
               prefix="jesi" %>
    <html>
    <jesi:control cache="no" />
    <jesi:include page="a.jsp?p1=v1" />
    <h3>hello ...</h3>
    <jesi:include page="b.jsp" />
    <h3>world ...</h3>
    <jesi:include page="c.jsp?p1=v2" copyParam="true" />
    </html>

The `a.jsp` page takes the parameter setting `p1=v1`. The `c.jsp` page takes the setting `p1=v2` as well as the setting `p2=abc`, as a result of the `copyParam` setting and the `p2` setting in the URL for the main page.

Additionally, the top-level page is noncacheable, according to the `cache="no"` setting. In fact, remember that you should use the `copyParam` setting in a JESI `include` tag only when the originating page is noncacheable, because the request attributes might change from one request to the next. Remember, too, that the `cache="no"` setting has no effect on the included pages. They are still cacheable by default. In other words, each is cacheable unless it has its own JESI `control` tag with `cache="no"` for some reason.

##### Example 5: Control/Include with param Tag

This example illustrates use of a JESI `param` tag to add runtime values as new parameters to the included page request. Assume the main page is accessed through a URL such as the following, taking the parameter setting `p1=v1`:

    http://host:port/application/main.jsp?p1=v1

Here is the page:

    <jesi:control cache="yes" />
    <jesi:include page="a.jsp" >
       <% String v2 = null;
          if(request.getParameter("p1").equals("v1")
              v2 = "v1 set";
          else
              v2 = "v2 unset";
       %>
       <jesi:param name="p2" value="<%=v2%>" />
    </jesi:include>

#### JESI te mplate Tag

Use the JESI `template` tag to specify caching behavior for the template content, outside any fragments, in the template/fragment usage model. (See "JESI Usage Models".) The corresponding HTTP header will be set according to the ESI specification. The content outside the fragments is referred to here as the template content and is a separate cacheable object, and the content of each fragment set aside with a JESI `fragment` tag is a separate cacheable object.

Important: All response output must be generated between the `template` start-tag and end-tag. Place the JESI `template` start-tag as early in the page as possible. It must appear before any JESI `fragment` tags or any buffer flushes in the page. It must also appear before any other visible output content such as text, HTML markup, new lines, or white space. Place the JESI `template` end-tag as late in the page as possible, after any JESI `fragment` tags and any other visible output content.

Always use the JESI `template` tag together with JESI `fragment` tags. If you have no need for separate fragments, then use a JESI `control` tag instead of a JESI `template` tag.

Note the following:

- All attributes of the JESI `template` tag are optional. If you use a tag without any settings, then, by default, the cacheability of a response has an expiration setting of 24 hours, with immediate removal of expired objects.

- In the template/fragment model, you cannot delegate decisions about cacheability to the ESI processor. You must have a JESI `template` tag, and cacheability of the template content is according to the `template` tag attribute settings or default values, as applicable. Similarly, each fragment must be set aside with a JESI `fragment` tag, and cacheability of each fragment is according to its `fragment` tag attribute settings or default values.

- Do not use multiple JESI `template` tags in a single JSP page. In addition, do not use additional JESI `template` tags in pages that are included, through `jsp:include` functionality, into the same response object. In either case, an exception will result.

- It is permissible to place a JESI `template` tag inside a page that is included through a standard `jsp:include` tag, as long as there is no `template` tag in any higher-level pages and you follow any other relevant restrictions that are mentioned in this section.

- If the JSP container has already encountered a JESI `control` tag when it encounters a JESI `template` tag while still generating the same response, then any attributes of the `template` tag are ignored and caching is according to the `control` tag.

  Note: In this situation, the `template` tag is not ignored completely. When the template/fragment model is used in a page that also has a JESI `control` tag (which can happen if a page with a `template` tag is included dynamically, and usually conditionally), the JSP container notes the fact that there is a `template` tag properly enclosing any `fragment` tags, as required.

- The JESI `template` tag cacheability settings have no effect on the enclosed fragments; fragments provide their own settings (or default values).

- If request parameters are significant to a fragment, then either the enclosing template content should not be cached (`cache="no"` in the JESI `template` tag), or separate versions of the template content should be cached, according to parameter values. Different versions of the fragment should also be cached, according to parameter values.

  In the background, a fragment involves an additional request, as with a page included through a JESI `include` tag. Request parameters (if any) are always passed from the template to the fragment, equivalent to JESI `include` tag functionality with a setting of `copyParam="true"`. (This kind of issue is also discussed in "JESI include Tag".)

The JESI `template` tag has the same attributes, with the same usage, as the JESI `control` tag.

##### Syntax

    <jesi:template
                 [ expiration = "value" ]
                 [ maxRemovalDelay = "value" ]
                 [ cache = "yes" | "no" | "no-remote" ]
                 [ control = "uninterpreted_string" ] >

    ...page content, jesi:fragment tags, optional jesi:include tags, optional jesi:codeblock tags..

    </jesi:template>

##### Attributes

For attribute descriptions, see "JESI control Tag".

#### JESI fra gment Tag

Use one or more JESI `fragment` tags within a JESI `template` tag, between the JESI `template` start-tag and end-tag, in the template/fragment model. (See "JESI Usage Models".) Each JESI `fragment` tag defines a separate fragment of the JSP page, as desired, for caching behavior. Each fragment is a separate cacheable object.

When a particular fragment is requested for inclusion into the aggregate response through the ESI mechanism, the ESI processor retrieves only that fragment.

The JESI `fragment` tag has the same attributes, with the same usage, as the JESI `control` and JESI `template` tags.

Note the following:

- Each JESI `fragment` tag specifies its own caching instructions to the ESI processor. Cacheability is according to the specified attribute settings or the default values, as applicable. The settings of the surrounding JESI `template` tag have no effect on the fragments.

- You cannot nest a JESI `fragment` tag within another JESI `fragment` tag.

- Unlike with the control/include model, it is not possible to delegate caching instructions to the ESI processor in the template/fragment model, given that a `template` tag, and `fragment` tags as applicable, are required. Caching is always according to `template` or `fragment` tag attribute settings or the default values.

- As long as you follow the restrictions mentioned in this section, it is permissible to place a JESI `fragment` tag inside a page that is included through a standard `jsp:include` tag. The JESI `template` tag that encloses the JESI `fragment` tag can appear in the same included page or in a higher level page such as the page containing the `jsp:include` statement.

##### Syntax

    <jesi:fragment
                 [ expiration = "value" ]
                 [ maxRemovalDelay = "value" ]
                 [ cache = "yes" | "no" | "no-remote" ]
                 [ control = "uninterpreted_string" ] >

    ...JSP code fragment...

    </jesi:fragment>

##### Attributes

For attribute descriptions, see "JESI control Tag".

#### JESI codeblo ck Tag

In the template/fragment model, you can optionally use one or more JESI `codeblock` tags within template code, outside of any fragments, to mark conditional execution of particular blocks of code. Each `codeblock` tag surrounds a block of code and specifies when it should be executed:

- Only when the template is requested

or:

- Only when a fragment (any fragment) is requested

or:

- Always (whether a template or fragment is requested)

Without use of this tag, all template code is executed with every request—with each request for the template as well as with each request for any fragment, although template output is discarded in the case of a request for a fragment.

Although it is important to execute the template whenever a fragment is requested—to allow fragments to depend on template code side effects such as variable declaration or initialization—there might be blocks of code that are not critical to fragments. You can place any such code block into a `codeblock` tag with a specification to execute the block only when the template is requested.

Alternatively, there might be blocks of template code that are potentially vital to all fragments, but not to the template itself. You can place any such code block into a `codeblock` tag with a specification to execute the block only when any fragment is requested.

Note: It is advisable to not generate any visible output within a JESI `codeblock` tag. This is to avoid unexpected behavior due to differences in execution between requests for the template and requests for fragments. If `execute="template"` (or "`always`") and the template is requested, then the code is executed and the content is output, as presumably intended. However, if `execute="fragment"` (or "`always`") and the request is for a fragment, then the code is executed but the entire output of the template is suppressed, as is always the case when a fragment is requested. See Figure 6-3 in "Template/Fragment Model".

##### Syntax

    <jesi:template ... >
    ...
       <jesi:codeblock execute = "template" | "fragment" | "always" >
          ...request-dependent JSP content...
       </jesi:codeblock>
    ...
    </jesi:template>

##### Attributes

- `execute` (required): Specify the value "`template`" to execute the code block only when the template is requested. Specify the value "`fragment`" to execute the code block only when any fragment is requested. A setting of "`always`" results in the code block being executed with every request for the page, and is equivalent to not using a `codeblock` tag at all.

#### Exa mples: Template/Fragment Model

This section contains examples of JESI tag usage in the template/fragment model.

##### Example 1: Template/Fragment

This is a general example showing use of the JESI `template` and JESI `fragment` tags. Because only the `expiration` attribute is set in any of the tags, all other settings are according to defaults. The setting of the `cache` attribute defaults to "`yes`", so the template and all three fragments are cached.

The template content (outside the fragments) uses an expiration of 3600 seconds, according to the JESI `template` tag. This applies to all the HTML blocks because they are outside the fragments. JSP code block #1 is cached with an expiration setting of 60; JSP code block #2 is cached with the default expiration setting; and JSP code block #3 is cached with an expiration setting of 600.

    <%@ taglib uri="http://xmlns.oracle.com/j2ee/jsp/tld/ojsp/jesitaglib.tld"
               prefix="jesi" %>
    <jesi:template expiration="3600">
    ...HTML block #1...
       <jesi:fragment expiration="60">
       ...JSP code block #1...
       </jesi:fragment>
    ...HTML block #2...
       <jesi:fragment>
       ...JSP code block #2...
       </jesi:fragment>
    ...HTML block #3...
      <jesi:fragment expiration="600">
       ...JSP code block #3...
       </jesi:fragment>
    ...HTML block #4...
    </jesi:template>

##### Example 2: Template/Fragment

This example employs JESI `include` tags inside the fragments. The following are the cacheable objects for this page:

- Each included page

- Each fragment, outside of the page it includes

- The aggregate of the HTML blocks, which are all at the template level outside any fragments

    <%@ taglib uri="http://xmlns.oracle.com/j2ee/jsp/tld/ojsp/jesitaglib.tld"
               prefix="jesi" %>
    <jesi:template expiration="3600">
    ...HTML block #1...
       <jesi:fragment expiration="60">
       ...JSP code block #1...
       <jesi:include page="stocks.jsp" />
       </jesi:fragment>
    ...HTML block #2...
       <jesi:fragment>
       ...JSP code block #2...
       <jesi:include page="/weather.jsp" />
       </jesi:fragment>
    ...HTML block #3...
       <jesi:fragment expiration="600">
       ...JSP code block #3...
       <jesi:include page="../sales.jsp" />
       </jesi:fragment>
    ...HTML block #4...
    </jesi:template>

##### Example 3: Template/Fragment with Codeblock

This is a conceptual example of how you can use the `codeblock` tag in the template/fragment model. In this case, to improve performance, the code that connects to the database would be placed in the code block so that it is not reexecuted needlessly.

    <%@ taglib uri="http://xmlns.oracle.com/j2ee/jsp/tld/ojsp/jesitaglib.tld"
               prefix="jesi" %>
    <jesi:template>
    Welcome to the Frequent Flyer Home page!
    <jesi:codeblock execute="fragment" >
      /* Open a database connection and store it in the variable dbConn. */
    </jesi:codeblock>
    BEST DEALS
    <jesi:fragment expiration="600" maxRemovalDelay="180">
    ...in Air Travel
    /* Select the three cheapest USA domestic round-trip fares, using the database
       connection stored in dbConn. */
    </jesi:fragment>

    <jesi:fragment expiration="600" maxRemovalDelay="180">
    ...in Accommodations
    /* select the three best hotel deals, using the database connection stored in dbConn. */
    </jesi:fragment>

    Click here to access your current Mileage account <...>
    </jesi:template>

### Descriptions of Tags and Subtags for Invalidation of Cached Objects

Use the JESI `invalidate` tag and the following subtags, as appropriate, to explicitly invalidate cached objects in the ESI processor:

- JESI `object`

- JESI `cookie` (subtag of JESI `object`)

- JESI `header` (subtag of JESI `object`)

The following sections cover the syntax of these tags, the JESI configuration file (which can be used to specify the user name, password, and URL to log in for invalidation), and some examples:

- JESI invalidate Tag

- JESI Configuration File

- JESI object Subtag

- JESI cookie Subtag

- JESI header Subtag

- Examples: Page Invalidation

See "Invalidation of Cached Objects" for an overview.

#### JESI in validate Tag

Use the JESI `invalidate` tag with its JESI `object` subtag to explicitly invalidate one or more cached objects.

Use the subtags as follows:

- Use the required JESI `object` subtag to specify what to invalidate, according to the URI or URI prefix.

- Optionally use JESI `cookie` subtags or JESI `header` subtags (or both) of the JESI `object` tag to specify further criteria for what to invalidate, according to cookie or HTTP header information.

##### Syntax

    <jesi:invalidate
                 [ url = "url"
                   username = "user_name"
                   password = "password" ]
                 [ config = "configfilename" ]
                 [ output = "browser" ] >

Required subtag (described in "JESI object Subtag"):

                 <jesi:object ... >

Optional subtag of JESI `object` (described in "JESI cookie Subtag"):

                       <jesi:cookie ... />

Optional subtag of JESI `object` (described in "JESI header Subtag"):

                       <jesi:header ... />

                 </jesi:object>

    </jesi:invalidate>

Either specify the user, password, and URL all through their individual attributes, or all in the configuration file that is either referred to in the `config` attribute or is found in the default location. The default location is `/WEB-INF/jesi.xml` or, for backward compatibility, `/WEB-INF/config.xml`. See "JESI Configuration File" for information about the file. If the user name, password, and URL are specified through the configuration file as well as through the attribute settings, then the attribute settings take precedence.

If you specify a `<user>` element for the OracleAS Web Cache "invalidator" account in the OC4J `jazn-data.xml` file, then you can use special syntax in the `password` attribute to refer to the information in `jazn-data.xml` instead of specifying the password in clear text. The password is specified in `jazn-data.xml` in an obfuscated form. See the `username` and `password` attribute descriptions below. See the Oracle Application Server Containers for J2EE Security Guide for information about the `jazn-data.xml` file.

Note: It is permissible to have multiple `object` tags within an `invalidate` tag.

##### Attributes

- `url`: Specifies the URL of the cache server. If this attribute is omitted, then you must specify the URL, as well as the user name and password, in the JESI configuration file.

- `username`: Specifies the user name for logging in to the cache server to perform invalidation. OracleAS Web Cache typically requires an "invalidator" user name. If this attribute is omitted, then you must specify the user name, as well as the password and URL, in the JESI configuration file.

  If the OC4J `jazn-data.xml` file contains a `<user>` element for the OracleAS Web Cache "invalidator" account, then you can use that account name for the `username` value, such as:

  `username="invalidator"`

- `password`: Specifies the password for logging in to the cache server to perform invalidation. If this attribute is omitted, then you must specify the password, as well as the user name and URL, in the JESI configuration file.

  If the OC4J `jazn-data.xml` file contains a `<user>` element for the OracleAS Web Cache "invalidator" account, then you can get the de-obfuscated password from that file by using special right-arrow syntax with a dash ("`-`") and right-carrot ("`>`") followed by the invalidator account name, such as:

  `password="->invalidator"`

- `config`: Specifies a JESI configuration file, using either an application-relative or a page-relative location. You can use this file to provide the cache server URL, user name for invalidation, and password instead of using the corresponding tag attributes. Note the following:

  - You can use a configuration file in the default location instead of specifying one through the `config` attribute. See "JESI Configuration File".

  - No configuration file is consulted if `username`, `password`, and `url` are all specified through tag attributes.

- `output`: Optionally sets an output device to receive the invalidation response from the cache server. Currently, the only supported setting is "`browser`", which wraps the Web cache response with HTML formatting to show the message in the user's Web browser. If you do not set this parameter, then the invalidation response will not be displayed.

#### JESI Co nfiguration File

The proposed JESI specification supports the use of a configuration file. Currently, you can use a configuration file only to specify the user name, password, and URL for invalidation. (Alternatively, you can specify the user name, password, and URL through attributes of each JESI `invalidate` tag. See "JESI invalidate Tag".)

A JESI configuration file must have a `<jesi-config>` top-level element, an `<invalidation>` subelement under that, and `<username>`, `<password>`, and `<url>` subelements under the `<invalidation>` element.

Note: For backward compatibility, the deprecated elements `<ojsp-config>` and `<web-cache>` are currently acceptable instead of `<jesi-config>` and `<invalidation>`, respectively. The new elements are to comply with the proposed JESI specification. It is likely that the `<ojsp-config>` and `<web-cache>` will be desupported in a future release.

In the current implementation there are two possible default files, or you can place the file anywhere within your application and specify its name and location through the `config` attribute of the `invalidate` tag, specifying either an application-relative or a page-relative location.

The preferred default file is `/WEB-INF/jesi.xml`, which conforms with the proposed JESI specification. For backward compatibility, the previous default file, `/WEB-INF/config.xml`, is also supported.

The following precedence is used to obtain the user name, password, and URL for invalidation:

1. If the JESI `invalidate` tag specifies the `username`, `password`, and `url` attribute settings (all three), then those values are used.

   Note: If the `invalidate` tag specifies one or two of these attributes but not all three, an exception is raised. An exception is also raised if one or more of the attribute values is an empty string or null.

2. If you do not specify `username`, `password`, and `url` in the `invalidate` tag, but the `config` attribute specifies a configuration file, then values from the specified configuration file are used.

3. If you do not specify `username`, `password`, `url`, and `config` in the `invalidate` tag, then the JSP container attempts to use a default configuration file. First, the container searches for `/WEB-INF/jesi.xml` and uses the settings from that file if it is found. If that file is not found, then the container searches for `/WEB-INF/config.xml` and uses the settings from that file if it is found.

   Notes: If the `invalidate` tag does not specify the user name, password, and URL, an exception is thrown under either of the following circumstances: If at any point a configuration file is found that does not specify all three attributes If no configuration file is found

If the OC4J `jazn-data.xml` file contains a `<user>` element for the OracleAS Web Cache "invalidator" account, you can that account name in the JESI configuration file and get the password from `jazn-data.xml` by using special right-arrow syntax with a dash ("`-`") and right-carrot ("`>`"), followed by the invalidator account name. See "Example 2: Configuration File Obtaining Password from jazn-data.xml" below.

##### Example 1: Configuration File with Clear Text for Password

The following example shows a configuration file that is used instead of the `url`, `username`, and `password` attributes to set the URL and login information:

    <?xml version="1.0" ?>
    <jesi-config>
      <invalidation>
          <url>http://yourhost.yourcompany.com:4001</url>
          <username>invalidator</username>
          <password>invpwd</password>
      </invalidation>
    </jesi-config>

##### Example 2: Configuration File Obtaining Password from jazn-data.xml

The following example, instead of using clear text to specify the password, uses special "`->`" syntax to obtain the de-obfuscated password from the `jazn-data.xml` file. This example assumes `jazn-data.xml` contains a `<user>` element for the OracleAS Web Cache "invalidator" account:

    <?xml version="1.0" ?>
    <jesi-config>
      <invalidation>
          <url>http://yourhost.yourcompany.com:4001</url>
          <username>invalidator</username>
          <password>->invalidator</password>
      </invalidation>
    </jesi-config>

#### JESI obje ct Subtag

Use the required JESI `object` subtag of the JESI `invalidate` tag to specify cached objects to invalidate, according to either the complete URI or a URI prefix. Optionally, use JESI `cookie` subtags or JESI `header` subtags (or both) to specify further criteria for invalidation, based on cookie or HTTP header information.

Specify either the complete URI or the URI prefix in the `uri` attribute setting. Whether this field is interpreted as a full URI or as a prefix depends on the setting of the `prefix` attribute.

##### Syntax

    <jesi:object uri = "uri_or_uriprefix"
               [ maxRemovalDelay = "value" ]
               [ prefix = "yes" | "no" ] >

Optional subtag (described in "JESI cookie Subtag" below):

                       <jesi:cookie ... />

Optional subtag (described in "JESI header Subtag"):

                       <jesi:header ... />

    </jesi:object>

Here is the syntax if you do not use either subtag:

    <jesi:object uri = "uri_or_uriprefix"
               [ maxRemovalDelay = "value" ]
               [ prefix = "yes" | "no"] />

Notes: It is permissible to have multiple `object` tags within an `invalidate` tag. It is permissible to have multiple `cookie` tags or `header` tags within an `object` tag.

##### Attributes

- `uri` (required): Specifies either the complete URI of the page whose corresponding cached object is to be invalidated (if `prefix="no"`), or a URI prefix that specifies objects for multiple pages to be invalidated according to location (if `prefix="yes"`).

  If a prefix is specified, then cached objects for all pages under that location are invalidated. For example, for a prefix of "`/abc/def`", cached objects for all pages in the corresponding directory and any subdirectories are invalidated.

- `prefix`: Set this to "`yes`" if the `uri` attribute is to be interpreted as a URI prefix only. Use the default "`no`" setting if the `uri` value is to be interpreted as a complete URI.

- `maxRemovalDelay`: Specifies the maximum delay, in seconds, between the time when a cached object is invalidated and the time when it is removed and, therefore, can no longer be served by the ESI processor. This delay is 0 by default, for immediate removal.

#### JESI co okie Subtag

Use one or more JESI `cookie` subtags of the JESI `object` tag (which is a subtag of the JESI `invalidate` tag) if you want to use cookie information as further criteria for invalidation. This cookie information is in addition to the URI or URI prefix setting in the JESI `object` tag, and possibly in addition to JESI `header` tags as well. The `cookie` tag is useful for invalidating objects that have had multiple versions cached, based on cookie information.

The `cookie` tag has no body.

##### Syntax

    <jesi:cookie name = "cookie_name"
               [ value = "cookie_value" ] />

Notes: It is permissible to have multiple `cookie` tags within an `object` tag. Unlike most other JESI tag attributes, it is permissible for the `value` attribute to have a null or empty-string value.

##### Attributes

- `name` (required): This is the name of the cookie.

- `value`: This is the value of the cookie.

For each use of the `cookie` subtag, the request URL of the object to be invalidated must have a cookie that matches the `name` attribute setting and, if specified, the `value` attribute setting.

#### JESI he ader Subtag

Use one or more JESI `header` subtags of the JESI `object` tag (which is a subtag of the JESI `invalidate` tag) if you want to use HTTP/1.1 header information as further criteria for invalidation. This header information is in addition to the URI or URI prefix setting in the JESI `object` tag, and possibly in addition to JESI `cookie` tags as well. The `header` tag is useful for invalidating objects that have had multiple versions cached, based on header information.

The `header` tag has no body.

##### Syntax

    <jesi:header name = "header_name"
                 value = "header_value" />

Note: It is permissible to have multiple `header` tags within an `object` tag.

##### Attributes

- `name` (required): This is the name of the HTTP/1.1 header.

- `value` (required): This is the value of the HTTP/1.1 header.

For each use of the `header` subtag, the request URL of the object to be invalidated must have a header that matches the `name` and `value` attribute settings.

#### Exa mples: Page Invalidation

This section provides examples of page invalidation using the JESI `invalidate` tag, its JESI `object` subtag, and the JESI `cookie` subtag of the JESI `object` tag.

##### Example 1: Page Invalidation

This example invalidates a single object in the ESI processor, specified by its complete URI. (By default, the `uri` attribute of the `object` tag specifies a full URI, not a URI prefix.) The JESI `invalidate` tag also specifies the URL for the cache server, and the user name and password for the invalidation account. In addition, it specifies that the invalidation response from the cache server should be displayed in the user's browser.

    ...
    <jesi:invalidate url="http://yourhost.yourcompany.com:4001"
                     username="invalidator" password="invpwd"
                     output="browser">
         <jesi:object uri="/images/logo.gif"/>
    </jesi:invalidate>
    ...

##### Example 2: Page Invalidation

This example is equivalent to "Example 1: Page Invalidation" immediately above, but uses a configuration file to specify the cache server URL and login information.

    ...
    <jesi:invalidate config="/myconfig.xml" output="browser">
         <jesi:object uri="/images/logo.gif"/>
    </jesi:invalidate>
    ...

The JESI `invalidate` tag specifies an application-relative location for the configuration file. As an example, suppose `myconfig.xml` has the following content:

    <?xml version="1.0" ?>
    <jesi-config>
      <invalidation>
          <url>http://yourhost.yourcompany.com:4001</url>
          <username>invalidator</username>
          <password>invpwd</password>
      </invalidation>
    </jesi-config>

##### Example 3: Page Invalidation

This example invalidates all objects in the ESI processor, according to the URI prefix "`/`". It does not specify that the invalidation response should be displayed in the browser, so it will not be displayed at all.

    ...
    <jesi:invalidate url="http://yourhost.yourcompany.com:4001"
                     username="invalidator" password="invpwd">
         <jesi:object uri="/" prefix="yes"/>
    </jesi:invalidate>
    ...

##### Example 4: Page Invalidation

This example invalidates a single object but allows it to be served stale for up to 30 minutes (1800 seconds).

    ...
    <jesi:invalidate url="http://yourhost.yourcompany.com:4001"
                     username="invalidator" password="invpwd">
         <jesi:object uri="/images/logo.gif" maxRemovalDelay="1800"/>
    </jesi:invalidate>
    ...

##### Example 5: Page Invalidation

This example specifies the same object for invalidation as "Example 1: Page Invalidation", but specifies that it should be invalidated only if its request URL has a cookie named `user_type` with the value `customer`.

    ...
    <jesi:invalidate url="http://yourhost.yourcompany.com:4001"
                     username="invalidator" password="invpwd">
         <jesi:object uri="/images/logo.gif">
              <jesi:cookie name="user_type" value="customer"/>
         </jesi:object>
    </jesi:invalidate>
    ...

### Description of Tag for Page Personalization

To allow page customization when sharing the same cached page between multiple users, the ESI processor must be informed of dependencies by the page on cookie and session information. Cookie value replacement, for example, occurs in the ESI processor instead of in the Web server.

#### JESI pers onalize Tag

Use the JESI `personalize` tag to allow page customization, by directing the ESI processor to substitute cookie values from a current request before serving a cached page.

The effect of this tag is to insert an ESI placeholder with the cookie name and value into the response body. If the cookie that is specified in the `name` attribute is found in the request and has a non-null value, its value is used. If the cookie is not found in the request or has a null value, but a value is specified through the `default` attribute, then a new cookie is created and the `default` value is used. If the cookie did not previously exist and no `default` value is specified, the tag has no effect.

The `personalize` tag has no body.

##### Syntax

    <jesi:personalize name = "cookie_name"
                    [ default = "default_value" ] />

Notes: For backward compatibility, the deprecated "`value`" form of the `default` attribute is accepted. The change from `value` to `default` was made to comply with the proposed JESI specification. It is likely that `value` will be desupported in a future release. OC4J automatically places single quotes around the specified `default` (or `value`) setting to comply with the ESI specification. Prior to the OC4J 9.0.4 implementation, you had to include the single quotes as part of your setting.

##### Attributes

- `name` (required): Specifies the name of the cookie whose value is used as the basis for personalizing the page.

- `default`: This is an optional default value in case the cookie is not found or has a null value.

#### Example: Page Personalization

The following example shows usage of the JESI `personalize` tag:

    <jesi:personalize name="user_id" default="guest" />

The corresponding ESI tag that is generated allows the ESI processor to find the necessary information. In this case, it looks for a cookie named `user_id` and retrieves its value. If it cannot find the cookie, it uses a default value of "`guest`".

Handling this cookie-value replacement in the ESI processor allows the ESI processor to serve multiple customized pages from a single cached copy, without involving the application server.

## JESI Ta g Handling and JESI-to-ESI Conversion

JESI tag handler classes, supplied as part of the JESI tag library with OC4J, provide the bridge from JSP functionality to ESI functionality. Tag handlers generate ESI tags from JESI tags and, as appropriate, generate HTTP requests for invalidation, set HTTP response headers, and so on. Be aware, however, that there is not always a simple one-to-one mapping between JESI tags and ESI tags, or between JESI tag attributes and ESI tag attributes.

### Example: JESI-to-ESI Conversion for Included Pages

As an example of JESI-to-ESI conversion, consider the following JSP code:

    <p>BEGIN</p>
    <jesi:control cache="no"/>
    <jesi:include page="stocks.jsp" flush="true" />
    <p>
    <hr>
    <jesi:include page="/weather.jsp" copyParam="true" flush="true" />
    <p>
    <hr>
    <jesi:include page="../sales.jsp?tax=local" copyParam="true" flush="true" />
    <p>END</p>

Assume that this JSP code is part of a page with the following URL:

    http://host:port/application1/top.jsp

Further assume the following request:

    http://host:port/application1/top.jsp?city=Washington_DC

In this case, the JESI `include` tag handler generates ESI markup such as in the following response.

In the response header:

    Surrogate-Control: content="ESI/1.0",max-age=86400+0,no-store

In the response body:

    <p>BEGIN</p>
    <esi:include src="/application1/stocks.jsp"/>

    <p>
    <hr>
    <esi:include src="/weather.jsp?city=Washington_DC"/>

    <p>
    <hr>
    <esi:include src="/sales.jsp?tax=local&city=Washington_DC"/>

    <p>END</p>

This response is read by the ESI processor before being delivered to the client. A `Surrogate-Control` header alerts the ESI processor that the response body contains ESI markup; therefore, the caching mechanism looks inside the response body for ESI tags. In addition, the `Surrogate-Control` header sets the cache directive to `no-store`, according to the `cache="no"` attribute setting. Expiration and maximum delay interval have no impact in this case.

In response to each of the three `esi:include` tags, the ESI processor makes an additional request to the URL that is specified. Each response is included into the top-level page, and only after that is the assembled page delivered to the client. Note that the client receives one response, but the cache initially makes four requests to obtain it. This might seem like a lot of overhead; however, the overall efficiency will be improved if many additional requests also use the same included pages, such as `weather.jsp`. No requests for these pages are required, because they are cached separately on the ESI processor.

### Example: JESI-to-ESI Conversion for a Template and Fragment

Suppose that when employees connect to a corporate intranet site, the content of their pages is dynamic except for a few features that are present in every response. In particular, there is always a footer displaying the stock chart and latest business headlines for the company, and the business headlines are obtained from an external business news site. Because all returned pages will have to include the same information, and it is expensive to obtain, it is more efficient to cache the footer in the ESI processor.

The remainder of the page response is dynamic, incorporating the stock fragment in a slightly different way each time. To avoid having to rewrite the page, you can mark the footer as a JESI fragment and the enclosing page as a JESI template.

Also assume that a charity campaign is in progress and that the organizers want to display a bar chart showing their goal amount and the current donation amount as part of all corporate pages. This information is stored in a special database table and is updated twice a day. The chart is a good candidate to be an additional JESI fragment. Therefore, you would add a JESI `template` tag at the top of the page and use JESI `fragment` tags to enclose the fragments that are to be cached as separate entities.

Assume that the URL to the corporate page is as follows:

    http://www.bigcorp.com/employee_page.jsp

Further assume that you have modified the page as follows:

    <%@ taglib uri="http://xmlns.oracle.com/j2ee/jsp/tld/ojsp/jesitaglib.tld"
               prefix="jesi" %>
    <jesi:template cache="no" >

       <p>BEGIN</p>
       ... some dynamic page content...
       <jesi:fragment>
       This_is_the_body_of_Charity_Chart
       </jesi:fragment>
       ... some more dynamic content...
       <jesi:fragment>
       This_is_the_body_of_Business_Footer
       </jesi:fragment>
    </jesi:template>
    <p>END</p>

When the page is requested, an HTTP response is generated as follows.

In the response header:

    Surrogate-Control: content="ESI/1.0",max-age=86400+0,no-store

In the response body:

    <p>BEGIN</p>
    ... some dynamic page content...
    <esi:include src="/employee_page.jsp?__esi_fragment=1"/>
    ... some more dynamic content...
    <esi:include src="/employee_page.jsp?__esi_fragment=2"/>
    <p>END</p>

As with the JESI `include` example in "Example: JESI-to-ESI Conversion for Included Pages", the ESI processor is alerted by the `Surrogate-Control` response header. Note the `no-store` directive, generated because of the `cache="no"` setting in the JESI `template` tag.

The ESI processor makes two additional requests, where it fetches and caches the two fragments. After that, the composite page is returned to the employee. When the employee works with the page again, the dynamic content will be newly generated but the chart and the footer will be served from the cache.

Note: `Surrogate-Control` headers are consumed by the ESI processor and are not seen in the final response to the client.