Release 2 (9.0.2)
Part Number A95883-01
 Home |
 Solution Area |
 Contents |
 Index |
| Oracle9iAS Containers for J2EE JSP Tag Libraries and Utilities Reference Release 2 (9.0.2) Part Number A95883-01 |
|
This chapter describes the JESI (JSP to ESI) tag library that is supplied with OC4J. These portable tags operate on top of an Edge Side Includes (ESI) framework available in the Oracle9iAS Web Cache to provide ESI caching functionality in a JSP application.
The chapter includes the following topics:
For an overview of Web caching, including discussion of the Oracle9iAS Web Cache, the Oracle9i Application Server Java Object Cache, and the OC4J Web Object Cache, see "Overview of Oracle Caching Support for Web Applications".
This section provides background information about some of the underlying technology upon which the Oracle JESI tags are based.
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 ESI markup language.
Although the use of JESI tags is not dependent upon any particular ESI processor or caching system, it is reasonable to assume that most Oracle customers would use the Oracle9iAS Web Cache and its ESI processor.
This section covers the following topics:
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.edge-delivery.org
This section introduces the features of ESI technology and the concept of ESI "surrogates".
Edge Side Includes is an XML-style markup language that allows dynamic content assembly away from the origin Web server--at the "edge" of the network--and is designed to take advantage of available tools such as Web caches and content delivery networks (CDNs) to improve performance for end users.
ESI provides a means of reducing 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 end user's browser. A surrogate is commanded through HTTP headers. Such a surrogate can be referred to as an "ESI processor" and may 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. You can think of an aggregate page, which is the resource associated with the URL that an end user specifies, as simply a container for assembly, including retrieval and assembly instructions that are specified through the ESI tags.
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 in general, using similar freshness and validation mechanisms as the foundation. However, surrogates also possess additional control mechanisms.
Version 1.0 of the ESI language includes the following key areas of functionality:
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.
ESI supports the use of variables based on HTTP request attributes. ESI statements can use variables during processing or can output them directly into the processed markup.
ESI allows use of boolean comparisons for conditional logic in determining how pages are processed.
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.
This section introduces the Oracle9iAS Web Cache and its ESI processor. See the Oracle9iAS Web Cache Administration and Deployment Guide for more information.
Oracle offers Oracle9iAS 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 Oracle9i Application Server.
By storing pages from frequently accessed URLs in memory, Oracle9iAS 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, Oracle9iAS 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, there is greater performance enhancement than with legacy proxies, and much less load on application servers.
Conceptually, Oracle9iAS 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 Oracle9iAS Web Cache, which, in turn, acts as a virtual server for the application Web servers. If the requested content has expired, or has been invalidated, or is no longer accessible, then Oracle9iAS Web Cache retrieves the new content from the application Web servers.
Here are the steps for typical browser interaction with Oracle9iAS Web Cache:
This request, in turn, generates a request to the Domain Name System (DNS) for the IP address of the Web site.
Oracle9iAS 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 Oracle9iAS Web Cache environment can use the ESI language directly in their applications; however, for JSP developers, there are a number of reasons to use the JESI tag library that is provided as a convenient JSP interface to the ESI language. (See "Advantages of JESI Tags".)
This section introduces JESI functionality and the Oracle implementation, covering the following topics:
You can access the proposed JESI specification at the following Web site:
http://www.edge-delivery.org
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 in a JSP environment. Here are the main advantages in using JESI tags instead of using ESI tags directly:
For developers accustomed to using JSP pages or working in a JSP IDE environment, JESI tags allow use of the familiar and convenient features of JSP programming. For example, you can reference included pages by page-relative or application-relative syntax instead of the complete URL or file path.
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.
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.
The Oracle implementation of JESI is layered on top of the standard ESI framework. Because the JESI tag library is a standard implementation, note the following:
The Oracle JESI tag library supports the following tags:
control, JESI include, JESI template, and JESI fragment for page setup and content
invalidate (and subtags) for explicit invalidation of cached objects when appropriate
personalize for page customization
Included with the tag library are the following:
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 previously, in "Advantages of JESI Tags".
|
Note: The Oracle JESI tag library is a standard library. For general information about the standard JavaServer Pages tag library framework, refer to the Oracle9iAS Containers for J2EE Support for JavaServer Pages Reference. |
There are two models for how to use JESI tags to define aggregate pages and their cacheable components:
This section describes these models, and concludes with some special notes about the JESI include tag.
One approach to using JESI tags is a modular one, typically bringing most (or all) cacheable content into the aggregate page as included pages. Generally use this model as follows:
control tag in the top-level page to set caching parameters for content outside of the included content, if appropriate.
include tags to bring in dynamic content.
control tag inside each included page to set caching parameters for those pages, as appropriate.
This document refers to this modular approach as the control/include model. It is particularly convenient in a situation where you are developing new pages.
Each included file is a distinct cacheable object (although caching may be disabled according to tag settings), and any additional content in the aggregate 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.
For any page, either top-level or included, that does not specify cacheability through a JESI control tag, its cacheability depends on configuration settings of the ESI processor. This applies if the page has no JESI control tag, or if it has a JESI control tag that does not set the cache attribute.
See the following sections for tag syntax and examples:
Another JESI tag approach is one where content is in the aggregate page itself, and you split the page into separately cacheable fragments as desired. Use the JESI template tag to enclose the aggregate of all cacheable content. This tag sets caching parameters for the aggregate page outside the fragments. Use JESI fragment tags as desired to define fragments within the aggregate, to be cached separately.
This document refers to this scenario as the template/fragment model. It is particularly convenient in a situation where you are converting existing pages for JESI use. There can optionally be JESI include tags as well, either at the template level or the fragment level.
The JESI template tag and JESI fragment tag are always used together. If you do not need separate fragments in a page, use JESI control instead of JESI template.
Each fragment is a distinct cacheable object, and dynamic content at the template level, outside of any fragments, is a distinct cacheable object. Any included page is also a distinct cacheable object. The cacheability of the template code outside the fragments depends on the cache attribute setting, if any, of the JESI template tag. The cacheability of any fragment depends on the cache attribute setting, if any, of the JESI fragment tag. The cacheability of an included page depends on the cache attribute setting of the JESI control tag, if any, within that page. For any template, fragment, or included page that does not specify a cache attribute setting, its cacheability depends on configuration settings of the ESI processor.
Because the template and fragments are independent cacheable objects, they may expire at different points in time in the ESI processor. When a cache miss occurs or an object that has expired is requested, the ESI processor will make a request to the origin server (OC4J in the case of Oracle9iAS) for a fresh copy. If a requested object is a JESI template, the JSP engine will execute the template code; that is, all code in the page that is outside any fragments. In output generated by the JSP translator, the translator will also place ESI markup that designates where all the fragments should be included. The code contained in the JESI fragments will not be executed at that time.
When a fragment expires, the ESI processor will make a request to the origin server for that particular fragment. In order to execute a fragment, the OC4J JSP container will execute the template code (all code outside of the fragments) plus the code of the fragment being requested. In the resulting page, there will be the output of the template, ESI markers for the inclusion of the other fragments, and the results of the requested fragment. These fragment results will be inserted ("inlined") into the page at the appropriate point. Upon receiving the response, the ESI processor will find the inlined fragment in the page and cache the updated copy of that fragment. The Oracle ESI processor will discard the rest of the page. (Behavior may differ in other ESI processors.) The Oracle9iAS Web Cache does not update the template when it requests a fresh fragment.
Keep this behavior in mind when choosing expiration policies for your templates and fragments. In order to divide a page into template and fragments correctly and efficiently, it is important to remember what portion of a JSP page is executed during any particular update request. For example, because the template code is executed in every update request, try not to place an expensive computation at the template level, unless it must be executed every time. It is usually preferable to place expensive computation in a fragment that has as long an expiration time as possible.
Also be aware that no two fragments are ever executed during the same request. Therefore, 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, it should be declared and set in the template code. Similarly, but perhaps less obviously, 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.
See the following sections for tag syntax and examples:
In using either model, be aware of the following notes regarding the JESI include statement:
include statement that includes a page that in turn has its own JESI include statement, or as a JESI include statement inside a fragment defined with JESI fragment.
In the latter case, for example, the ESI processor first requests content of the aggregate page, next requests content of the fragment, and finally requests content of the included page within the fragment.
include and jsp:include, JESI include is not a perfect substitute for jsp:include 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 an aggregate page and a page it includes through a JESI include tag. If the code in the included page needs access to the request or response object of the aggregate page, you can put the code in a JESI fragment tag (within the JESI template tag of the aggregate page) instead of in an included page.
There may be situations where cached objects must be explicitly invalidated due to external circumstances, such as changes to relevant data in a database. There may also be situations where execution of one page may invalidate the data of cached objects corresponding to another page.
For this reason, JESI provides the JESI invalidate tag and several subtags. These tags allow you to invalidate pages based on appropriate combinations of the following:
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 "Tag and Subtag Descriptions for Invalidation of Cached Objects" for tag syntax and examples.
Dynamic Web pages frequently display customized information tailored to each individual user. For example, a welcome page may 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 this dependency, the Web page cannot be shared by multiple users at the ESI level.
See "Tag Description for Page Personalization" for tag syntax and examples.
|
Note: Do not confuse this tag with the Oracle9iAS Personalization tag library, which encompasses much more functionality. JESI personalization consists of the ESI processor simply replacing place holders in a cached page with dynamic strings that come from cookies sent in a request or response. This enables different users to share the same cached page. Oracle Personalization, using data mining on the back-end, is much more dynamic. It produces output that changes automatically according to user activity. See Chapter 9, "Oracle9iAS Personalization Tags" for more information. |
This section describes the syntax and attributes for the JESI tags provided with OC4J, followed by usage examples. Discussion is organized into the following categories:
The Oracle JESI tag library, a standard JavaServer Pages tag library implementation, is included in the ojsputil.jar file, which is provided with OC4J. Verify that this file is installed and in your classpath.
To use the JESI tag library, the tag library description file, jesitaglib.tld, must be deployed with the application. In an Oracle9iAS installation, this file is in the [Oracle_Home]/j2ee/tlds directory.
In your JSP pages, you must use a taglib directive such as the following:
<%@ taglib uri="/WEB-INF/jesitaglib.tld" prefix="jesi" %>
|
Notes:
|
This section summarizes the use of the following tags, and documents their syntax and attributes:
This section also provides examples of both the control/include model and the template/fragment model. See "JESI Usage Models" for overviews of these models.
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, or with a JESI control tag that has no cache attribute setting, cacheability is according to the configuration settings of the ESI processor. (See "JESI Usage Models".)
The JESI control tag should appear as early as possible in the page, before any other JESI tags or any buffer flushes in the page.
Be aware of the following:
control tags in a single JSP page. Also do not use additional JESI control tags in pages that are included, through jsp:include functionality, into the same response object. In either case, an exception will result.
control tag and a JESI template tag in the same page, or in separate pages that are included into the same response object. An exception will result.
control tag of the aggregate page has no effect on included pages. Use a JESI control tag in each included page as well, as necessary.
control tag depends on request parameters, consider whether you must cache the page with parameters (as opposed to without parameters) in the ESI server. 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 entries for the page.
<jesi:control [ expiration = "value" ] [ maxRemovalDelay = "value" ] [ cache = "yes" | "no" | "no-remote" ] />
expiration--Specifies the lifetime, in seconds, of the cached object. The default is 300.
maxRemovalDelay--Specifies the maximum time, in seconds, that the ESI processor can store the cached object after it has expired. The default is 0, for immediate removal.
cache--Specifies whether the object corresponding to the tag is cacheable. Set cache to "yes" to enable 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. If you do not set the cache parameter, then cacheability depends on the configuration settings of the ESI processor.
One reason to make a page non-cacheable, for example, is if you are using a JESI include tag with copyparam enabled. See "JESI include Tag" below.
The JESI include tag, as with a standard jsp:include tag, dynamically inserts output from the included page into output from the including page. Additionally, it directs the ESI processor to process and assemble the included pages. Each included page is a separate cacheable object (or non-cacheable, 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:
control tag or JESI template and fragment tags
control tag
template tag, outside of any fragments
fragment tag
(See "JESI Usage Models".)
The cacheability of an included page depends on the cache attribute setting of the JESI control tag (if any) within that page. If there is no cache setting, then cacheability depends on configuration settings of the ESI processor.
Although the JESI include tag has similarities in usage to jsp:include, its different semantics make it unsuitable for page inclusions where request or response objects must be passed between the originating page and the included page.
<jesi:include page = "uri" [ alt = "alternate_uri" ] [ ignoreError = "true" | "false" ] [ flush = "true" | "false" ] [ copyparam = "true" | "false" ] />
page (required)--Specifies the URI of the JSP page to be included, using either page-relative or application-relative syntax. (Refer to the Oracle9iAS Containers for J2EE Support for JavaServer Pages Reference for information about page-relative and application-relative syntax.) A full "http://..." or "https://..." URL is supported as well.
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 accessed. Syntax is the same as for the page attribute.
ignoreError--Set this to "true" for continued processing of the including page even if no included page (neither the page page nor alt page) can be accessed. The default value is "false".
flush--This attribute is ignored, but is supported to ease migration from jsp:include syntax.
copyparam--If the included page makes use of request parameters, set this to "true" to copy parameters and their values from the HTTP request string of the including 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 including page should not be cached (cache="no" in the JESI control, JESI template, or JESI fragment tag), or, in the ESI server, the included page should be cached with parameters (instead of without parameters). As an example, you should generally avoid scenarios such as the following:
<jesi:control cache="yes"/> ... <jesi:include page="arf.jsp" copyparam="true" />
The reason is that if you serve a copy of this including page from the cache, the page will not execute on the server or have a chance to properly copy 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:
arf.jsp page does not use the request parameters. In this case, though, it is advisable to remove the copyparam attribute or set it to "false".
or:
This section provides examples of JESI tag usage in the control/include model.
For a complete sample application using JESI tags, refer to the OC4J demos.
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="/WEB-INF/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>
This example uses the JESI control tag to specify non-default 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 continue even if neither page can be retrieved. The second JESI include tag specifies no alternate page, and processing will halt if the page cannot be retrieved.
As you can see, the HTML tags that "Example 1: Control/Include" uses are not actually required.
<%@ taglib uri="/WEB-INF/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" />
This is an example of an aggregate page whose output is conditional. A cookie represents the identity of a customer. If no cookie is found, the user will see a generic welcome page with general product information. If a cookie is found, the user will see 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 non-default values for maxRemovalDelay and expiration, and explicitly enables caching for the page.
<%@ taglib uri="/WEB-INF/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]%>" /> <% } } %>
This example illustrates the use of JESI include statements with request parameters. Assume 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 the page:
<%@ taglib uri="/WEB-INF/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, this page is non-cacheable, according to the cache="no" setting. In fact, remember that you should use the copyparam setting in a JESI include tag only when the including page is non-cacheable, because the request attributes may 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.
Use the JESI template tag to specify caching behavior for the aggregate page, outside any fragments, in the template/fragment usage model. (See "JESI Usage Models".) The corresponding HTTP header will be set according to the edge architecture specification. The aggregate content (outside the fragments) is a cacheable object, and each fragment set aside with a JESI fragment tag is a separate cacheable object.
Place the JESI template start tag as early in the page as possible--it must appear before any other JESI tags or any buffer flushes in the page. Place the JESI template end tag as late in the page as possible--it must appear after any other JESI tags in the page.
If a JESI template tag does not set the cache attribute, then cacheability of the corresponding object is according to configuration settings of the ESI processor.
The JESI template tag is always used together with JESI fragment tags. If you have no need for separate fragments, use a JESI control tag instead of a JESI template tag.
Be aware of the following:
template tags in a single JSP page. Also 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.
control tag and a JESI template tag in the same page, or in separate pages that are included into the same response object. An exception will result.
template tag settings have no effect on the enclosed fragments; fragments must provide their own settings.
template tag depends on request parameters, consider whether you must cache the page with parameters (instead of without parameters) in the ESI server. 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 entries for the page.
The JESI template tag has the same attributes, with the same usage, as the JESI control tag.
<jesi:template [ expiration = "value" ] [ maxRemovalDelay = "value" ] [ cache = "yes" | "no" | "no-remote" ] > ...page content, jesi:fragment tags, jesi:include tags... </jesi:template>
For attribute descriptions, see "JESI control Tag".
|
Note:
If request parameters are significant to the fragment, then either the enclosing template should not be cached ( |
Use one or more JESI fragment tags within a JESI template tag, between the JESI template start and end tags, in the template/fragment model. (See "JESI Usage Models".) The JESI fragment tag defines separate fragments of JSP code, as desired, for caching behavior. Each fragment is a separate cacheable object.
When a particular fragment is requested through the ESI mechanism, the ESI processor will retrieve only that fragment.
Each JESI fragment tag specifies its own instructions to the ESI processor. If the cache attribute is not set, then cacheability of the corresponding object is according to the configuration settings of the ESI processor. The settings of the surrounding JESI template tag have no effect on the fragments.
The JESI fragment tag has the same attributes, with the same usage, as the JESI control and JESI template tags.
<jesi:fragment [ expiration = "value" ] [ maxRemovalDelay = "value" ] [ cache = "yes" | "no" | "no-remote" ] > ...JSP code fragment... </jesi:fragment>
For attribute descriptions, see "JESI control Tag".
This section contains examples of JESI tag usage in the template/fragment model.
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 aggregate content (outside the fragments), according to the JESI template tag, uses an expiration of 3600 seconds. This applies to all the HTML blocks because they are all 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="/WEB-INF/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>
This example employs JESI include tags inside the fragments. The following are the cacheable objects for this page:
<%@ taglib uri="/WEB-INF/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>
Use the JESI invalidate tag and the following subtags, as appropriate, to explicitly invalidate cached objects in the ESI processor:
See "Invalidation of Cached Objects" for an overview.
You can use the JESI invalidate tag with its JESI object subtag to explicitly invalidate one or more cached objects.
Use the subtags as follows:
object subtag to specify what to invalidate according to URI or URI prefix.
cookie subtag or JESI header subtag of the JESI object tag to specify further criteria for what to invalidate, according to cookie or HTTP header information.
<jesi:invalidate [ url = "url" username = "username" 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 tags, or all in the configuration file referred to in the config attribute.
url--Specifies the URL of the cache server. If this attribute is omitted, you must specify the URL in the JESI configuration file.
username--Specifies the user name for logging in to the cache server. If this attribute is omitted, you must specify the user name in the JESI configuration file.
password--Specifies the password for logging in to the cache server. If this attribute is omitted, you must specify the password in the JESI configuration file.
config--Specifies a JESI configuration file. You can use this file to provide the cache server URL, user name, and password information instead of using the corresponding tag attributes. Specify the location in application-relative syntax, starting with "/". Refer to the Oracle9iAS Containers for J2EE Support for JavaServer Pages Reference for general information about application-relative syntax.
output--Optionally sets an output device to receive the invalidation response from the cache server. Currently, the only supported setting is "browser", to show the message in the user's Web browser. If you do not set this parameter, the confirmation message will not be displayed at all.
Following is an example of 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" ?> <ojsp-config> <web-cache> <url>http://yourhost.yourcompany.com:4001</url> <username>invalidator</username> <password>invpwd</password> </web-cache> </ojsp-config>
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 its JESI cookie subtag or JESI header subtag 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.
<jesi:object uri = "uri_or_uriprefix" [ maxRemovalDelay = "value" ] [ prefix = "yes" | "no" ] >
Optional subtag (described in "JESI cookie Subtag"):
<jesi:cookie ... />
Optional subtag (described in "JESI header Subtag"):
<jesi:header ... /> </jesi:object>
or (if not using either subtag):
<jesi:object uri = "uri_or_uriprefix" [ maxRemovalDelay = "value" ] [ prefix = "yes" | "no"] />
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 setting 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, and to "no" (default) if uri is to be interpreted as a complete URI.
maxRemovalDelay--Specifies the maximum time, in seconds, that the ESI processor can store the cached object after it has been invalidated. This is 0 by default, for immediate removal.
Use the JESI cookie subtag of the JESI object tag (which is a subtag of JESI invalidate) to use cookie information as a further criterion for invalidation. This is used in addition to the URI or URI prefix setting in the JESI object tag, and possibly in addition to a JESI header tag as well.
<jesi:cookie name = "cookie_name" value = "cookie_value" />
For a cached object to be invalidated, it must have a cookie that matches this name and value.
Use the JESI header subtag of the JESI object tag (which is a subtag of JESI invalidate) to use HTTP/1.1 header information as a further criterion for invalidation. This is in addition to the URI or URI prefix setting in the JESI object tag, and possibly in addition to a JESI cookie tag as well.
<jesi:header name = "header_name" value = "header_value" />
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 a cached object to be invalidated, it must have a header that matches this name and value.
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.
This example invalidates a single object in the ESI processor, specified by its complete URI. (By default, uri 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 login, and 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> ...
This is equivalent to Example 1: Page Invalidation, 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 uses application-relative syntax for the configuration file. As an example, suppose that myconfig.xml has the following content:
<?xml version="1.0" ?> <ojsp-config> <web-cache> <url>http://yourhost.yourcompany.com:4001</url> <username>invalidator</username> <password>invpwd</password> </web-cache> </ojsp-config>
This example invalidates all objects in the ESI processor, according to the URI prefix "/". It does not specify that the invalidation confirmation message 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> ...
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> ...
This example specifies the same object for invalidation as Example 1: Page Invalidation, but specifies that it should be invalidated only if it has a cookie named user_type with 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> ...
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.
Use the JESI personalize tag to allow page customization, by informing the ESI processor of dependencies on cookie and session information.
<jesi:personalize name = "cookie_name" [ value = "default_value" ] />
name (required)--Specifies the name of the cookie whose value is used as the basis for personalizing the page.
value--An optional default value in case the cookie is not found. This allows the ESI processor to avoid having to go back to the Web server to look for the cookie.
Following is an example showing use of the JESI personalize tag:
<jesi:personalize name="user_id" value="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 avoids having to send a request to the Web server.
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 translate JESI tags into ESI 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.
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 code such as in the following response.
In the response header:
Surrogate-Control: content="ESI/1.0",max-age=300+0
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 code; therefore, the caching mechanism looks inside the response body for <esi:> tags. In addition, the Surrogate-Control header sets the cache expiration and maximum delay interval for the page, in this case using the default expiration of 300 and the default maximum delay of 0 because there is no JESI control tag to specify otherwise.
In response to each of the three esi:include tags, the ESI processor makes an additional request to the URL 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 makes four requests to obtain it. This may 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 server.
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 on the ESI server.
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 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 the URL to the corporate page is as follows:
http://www.bigcorp.com/employee_page.jsp
Further assume you have modified the page as follows:
<%@ taglib uri="/WEB-INF/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> <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=300+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 server 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. In addition, the default expiration of 300 and the default maximum delay of 0 are used, because the JESI template tag does not specify otherwise.
The ESI server 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.
|
 Copyright © 2002 Oracle Corporation. All Rights Reserved. |
|