10g (9.0.4)
Part Number B10319-01
 Home |
 Contents |
 Index |
| Oracle Application Server Containers for J2EE JSP Tag Libraries and Utilities Reference 10g (9.0.4) Part Number B10319-01 |
|
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:
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".
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.
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
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 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.
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.
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. See Figure 6-1 below.
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.
ESI allows the 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 OracleAS Web Cache and its ESI processor. See the Oracle Application Server Web Cache Administrator's Guide for more information.
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.
Here are the steps for typical browser interaction with OracleAS Web Cache:
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".
The following sections introduce JESI functionality and the Oracle implementation:
You can access the proposed JESI specification at the following Web site:
http://www.esi.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 for JSP pages. Here are the main advantages in using JESI tags instead of using ESI tags directly:
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. It also conforms with the pending (as of the OC4J 9.0.4 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:
The Oracle JESI tag library supports the following tags:
control, JESI include, JESI param, JESI template, JESI fragment, and JESI codeblock for dynamic caching of page content
invalidate (and subtags) for explicit invalidation of cached objects, when appropriate
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. |
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.
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:
control tag in the top-level page to set caching parameters for content outside the included content, as applicable.
include tags to bring in dynamic content.
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:
control tag, cacheability depends on attribute settings or on the default attribute values, as applicable.
control tag, cacheability depends on configuration settings of the ESI processor.
control tag in the top-level page has no effect on included pages.
See the following sections for tag syntax and examples:
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:
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.
fragment tags as desired, between the template start-tag and end-tag, to define fragments within the aggregate, to be cached separately.
include tags as well, either at the template level or the fragment level.
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:
template tag attribute settings or on the default attribute values, as applicable.
fragment tag or on the default attribute values, as applicable.
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. Figure 6-2, which follows, illustrates this.
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. Figure 6-3, which follows, illustrates this.
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.
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.
See the following sections for tag syntax and examples:
In using either the control/include or template/fragment 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 that is defined with a JESI fragment statement.
In the second case, for example, the ESI processor executes the following steps:
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.
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:
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.
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.
|
Note: Do not confuse this tag with the Oracle Application Server Personalization tag library, which encompasses much more functionality. JESI personalization consists of the ESI processor replacing placeholders in a cached page with dynamic strings that come from cookies sent in a request or response. This process enables different users to share the same cached page. OracleAS Personalization, using data mining on the back-end, is much more dynamic and comprehensive. It produces output that changes automatically, according to user activity. See Chapter 10, "Personalization Tags" for more information. |
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:
control tags.
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.
template and fragment tags for proper nesting, but otherwise ignores them and executes all their tag bodies during a single request.
codeblock tags.
invalidation tags and all subtags.
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.
The following sections describe the syntax and attributes of the JESI tags provided with OC4J, followed by usage examples:
Note the following requirements for the JESI tag library:
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.
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 following sections cover the use of JESI tags for dynamic caching, document their syntax and attributes, and provide examples:
See "JESI Usage Models" for overviews of the control/include and template/fragment 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 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:
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.
control tag for the page in question.
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.
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.
template tag when it encounters a JESI control tag while still generating the same response, then the control tag is ignored.
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.
<jesi:control [ expiration = "value" ] [ maxRemovalDelay = "value" ] [ cache = "yes" | "no" | "no-remote" ] [ control = "uninterpreted_string" ] />
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:
|
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:
control tag or JESI template and fragment tags
control tag
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:
control tag, cacheability depends on attribute settings or on the default attribute values, as applicable.
control tag, cacheability depends on configuration settings of the ESI processor.
<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:
|
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:
arf.jsp page does not use the request parameters.
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.
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.
<jesi:include page = "uri" ... > <jesi:param name="param_name" value="param_value" /> ... </jesi:include>
name (required): Specifies the name of the parameter.
value (required): Specifies the value of the parameter.
This section provides examples of JESI tag usage in the control/include model.
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>
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" />
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]%>" /> <% } } %>
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.
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>
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.
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:
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.
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.
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.
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.
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.
template tag cacheability settings have no effect on the enclosed fragments; fragments provide their own settings (or default values).
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.
<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>
For attribute descriptions, see "JESI control 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:
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.
fragment tag within another JESI fragment tag.
template tag, and fragment tags as applicable, are required. Caching is always according to template or fragment tag attribute settings or the default values.
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.
<jesi:fragment [ expiration = "value" ] [ maxRemovalDelay = "value" ] [ cache = "yes" | "no" | "no-remote" ] [ control = "uninterpreted_string" ] > ...JSP code fragment... </jesi:fragment>
For attribute descriptions, see "JESI control 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:
or:
or:
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 |
<jesi:template ... > ... <jesi:codeblock execute = "template" | "fragment" | "always" > ...request-dependent JSP content... </jesi:codeblock> ... </jesi:template>
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.
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 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>
This example employs JESI include tags inside the fragments. The following are the cacheable objects for this page:
<%@ 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>
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>
Use the JESI invalidate tag and the following subtags, as appropriate, to explicitly invalidate cached objects in the ESI processor:
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:
See "Invalidation of Cached Objects" for an overview.
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 the URI or URI prefix.
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.
<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.
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:
config attribute. See "JESI Configuration File".
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.
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.
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.
As of the OC4J 9.0.4 implementation, 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:
invalidate tag specifies the username, password, and url attribute settings (all three), then those values are used.
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.
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.
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.
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>
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>
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.
<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>
Here is the syntax if you do not use 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 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.
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.
<jesi:cookie name = "cookie_name" [ value = "cookie_value" ] />
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.
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.
<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 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.
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, 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> ...
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>
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> ...
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 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> ...
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 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.
<jesi:personalize name = "cookie_name" [ default = "default_value" ] />
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.
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 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.
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.
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.
|
 Copyright © 2002, 2003 Oracle Corporation. All Rights Reserved. |
|