12 Creating Caching Rules

Selectors

When OracleAS Web Cache receives a client request, it uses selectors to filter through the caching rules to locate the appropriate rule for the request. During caching rule creation, you specify the following selectors:

• Expression type

  The expression type is one of the following:

  • File Extension Expression Type

  • Path Prefix Expression Type

  • Regular Expression

• URL expression

  Specify the URL based on the expression type.

• HTTP request method

  Specify the GET, GET with query string, or POST HTTP request methods of the objects.

• URL and POST body parameters

  Specify any embedded URL parameters or embedded POST body parameters.

• POST body expressions

  If the POST HTTP request method is selected, specify the HTTP POST body in regular expression syntax.

Caching Policy

A caching policy specifies whether an object should be cached or not cached. A caching policy of Cache instructs OracleAS Web Cache to serve requests from objects in its cache; a caching policy of Don't Cache instructs OracleAS Web Cache to forward requests to the origin server and to not cache the content.

Examples of content that administrators typically declare non-cacheable include updating transactions, shopping cart views, and personal account views. One of the easiest ways to set up caching rules in OracleAS Web Cache is either to first specify the non-cacheable content, and then use a broad "catch-all" rule for the cacheable content, or to first specify the cacheable content followed by a non-cacheable catch-all rule. In practice, cacheable and non-cacheable rules can be interspersed.

Cache-Key Policy

A cache-key policy enables OracleAS Web Cache to map requests to the appropriate objects in the cache. After OracleAS Web Cache uses the selectors and caching policy to filter requests, it uses the cache-key policy to locate the correct object in the cache.

OracleAS Web Cache composes a cache key with the following attributes that you specify:

• Site name

• URL

• HTTP methods

• POST body expression

• Cookie names and values for multiple-version objects

• HTTP request header names and values for multiple-version objects

Together, these attributes create a unique ID for a cached object, which OracleAS Web Cache then uses for request lookups.

Priority

You order the priority of caching rules. Higher priority rules are matched first.

When ordering caching rules for cacheable and non-cacheable objects, give the non-cacheable objects a higher priority than the cacheable objects. For example, if you want all URLs containing /cec/cstage?ecaction=ecpassthru to be cached except for /cec/cstage?ecaction=ecpassthru2, you would enter the rules with either regular expression or path prefix syntax, in the order shown in Table 12-2.

If the order were reversed, all objects starting with /cec/cstage?ecaction=ecpassthru would be cached, including /cec/cstage?ecaction=ecpassthru2.

In the rules shown in Table 12-3, Rule 2 caches objects of the URL that use the GET and GET with query string methods, and Rule 3 caches objects of the URL that use the POST method and a POST body matching action=search.

Default Caching Rules

When OracleAS Web Cache is installed, site-specific and global caching rules are established for the configured default site.

Figure 12-1 displays the Rules page of Application Server Control Console (Web Cache Home page > Administration tab > Properties > Application > Rules), and Figure 12-2 displays the Caching, Personalization, and Compression Rules page of OracleAS Web Cache Manager (Rules for Caching, Personalization, and Compression > Caching, Personalization, and Compression Rules).

Figure 12-1 Default Caching Rules in Application Server Control Console

Description of "Figure 12-1 Default Caching Rules in Application Server Control Console"

Figure 12-2 Default Caching Rules in OracleAS Web Cache Manager

Description of "Figure 12-2 Default Caching Rules in OracleAS Web Cache Manager"

Table 12-4 describes the default caching rules. Rule 1 is intended for Oracle Application Server Wireless. If you are not using this Oracle Application Server component, you can delete this rule.

Task 1: Create Caching Rules

To create caching rules in Application Server Control Console, navigate to Web Cache Home page > Administration tab > Properties > Application > Rules.

To create caching rules in OracleAS Web Cache Manager:

1. In the navigator frame, select Rules for Caching, Personalization, and Compression > Caching, Personalization, and Compression Rules.

   The Caching, Personalization, and Compression Rules page appears.

2. From the For Site list, select the Web site for which to view or create site-specific caching rules.

3. If no rules exist, choose Create Site Specific Rule or Create Global Rule. If rules already exist, then select a rule and choose Insert Above or Insert Below.

   The Edit/Add Caching, Personalization, and Compression Rule dialog box appears.

4. Specify the objects to which to apply the caching rule:

   1. From the Expression Type list, select one of the following options:

      • File Extension: Applies the caching rule to objects ending in a particular file extension, such as .gif

      • Path Prefix: Applies the caching rule to objects matching a path prefix

      • Regular Expression: Applies the caching rule to object matching regular expression syntax

   2. In the URL Expression field, specify the expression based on the selection you made for Expression Type:

      • File Extension: Enter the file extension. Because OracleAS Web Cache internally starts the file extension with a period (.), it is not necessary to enter it.

      • Path Prefix: Enter the path prefix of the objects. Because OracleAS Web Cache internally starts the path with http://host_name:port/ or "/", it is not necessary to enter this information.

        The prefix is interpreted literally, including reserved regular expression characters. These characters include periods (.), question marks (?), asterisks (*), brackets ([]), curly braces ({}), carets (^), dollar signs ($), and backslashes (\).

      • Regular Expression: Enter the regular expression of the objects. Remember to use "^" to denote the start of the URL and "$" to denote the end of the URL.

        See Also: "Selectors" for caching rule syntax

5. In the HTTP Method(s) section, select to cache objects that use GET, GET with query string, or POST HTTP request methods.

   You can select more than one request method.

   
   

   Note: If your Web site's GET with query string or POST methods are used for forms that make changes to the origin server or database, do not select GET with query string or POST. These options should only be selected if the forms are used in search forms.

   
   

6. For the File Extension and Path Prefix expression types, in the URL and POST Body Parameters section, enter any embedded URL parameters or POST body parameters and their values in the corresponding Name and optional Value fields. Then click Add.

   For the Regular Expression expression type, you must alphabetically sort and enter the embedded URL parameters in the URL Expression field.

   The request URL that client browsers send to OracleAS Web Cache and the internal URL expression that OracleAS Web Cache uses for that request are different. When OracleAS Web Cache serves a page request, it alphabetically sorts any embedded URL parameters of the URL. However, the caching rules are matched against only the internal representation of the URL in which any embedded URL parameters are sorted. To ensure caching rules are matched correctly, you either use the URL and POST Body Parameters section or manually enter the embedded URL parameters alphabetically in regular expression syntax. When you use the URL and POST Body Parameters section, the embedded URL parameters are automatically sorted.

   For example, consider the following URL:

   http://my.oracle.com/servlet/page?_pageid=53&_dad=moc&_schema=MOC
   
   

   If you enter the regular expression without manually sorting the embedded URL parameters in the URL Expression field, ^/servlet/page\?_pageid=53&_dad=moc&_schema=MOC$, then the caching rule will not match the internal representation of the URL used by OracleAS Web Cache. To ensure matching, you must enter the regular expression in the URL Expression field as:

   ^/servlet/page\?_dad=moc&_pageid=53&_schema=MOC$
   
   

7. If you selected POST in the HTTP Method(s) section and did not specify POST body parameters in the URL and POST Body Parameters section, specify the HTTP POST body in the POST Body Expression field.

   To apply this rule to any POST request body, enter ".*" in the field.

8. In Caching Policy, select either Cache or Don't Cache for the objects matching the URL.

9. In ESI Propagation Policy, select either Propagate or Don't Propagate. The default is Propagate.

   • Select Propagate to enable Edge Side Includes (ESI)-compliant proxy caches to process ESI tags. Select this option if you prefer clients acting as caches to perform the ESI processing rather than OracleAS Web Cache.

   • Select Don't Propagate to disallow other ESI-compliant caches or services from processing ESI tags.

     
     

     See Also: "Configuring Rules for Content Assembly and Partial Page Caching"

     
     

10. Optionally, to help keep track of the meaning of rules, enter a comment for the caching rule in the Comment field.

11. In the Compression section:

    • Select None to not serve compressed cacheable and non-cacheable objects to browsers.

    • Select For all browsers to serve compressed objects to all browser types.

    • Select For non-Netscape browsers only to serve compressed objects for all browsers other than Netscape.

    Note that even if compression is enabled, OracleAS Web Cache does not compress the following:

    • GIF, JPEG, PDF, PNG, SWF, and ZIP files

    • Responses containing a Content-Encoding response-header field, which is typically used to denote compression

    • Responses containing a Content-Disposition response-header field, which is typically used for attachments

      Responses with Content-Disposition response-header fields show incorrect file names when they are compressed.

    • For certain browsers, JavaScript files

      Compressed JavaScript files cause some browsers to behave erratically and possibly fail. This issue only affects files that are referenced with the src attribute of the script tag; it does not include files that contain inline JavaScript.

      OracleAS Web Cache does not compress JavaScript files for Netscape 4.x and Internet Explorer 5.5 browsers. For other browsers, it compresses the file if compression is enabled.

    • For certain browsers, cascading style sheets (.css)

      OracleAS Web Cache does not compress cascading style sheets for Netscape 4.x and Internet Explorer 5.5 browsers. With these browsers, compressed cascading style sheets can cause background attributes, such as background images, to not appear in the output.

    Oracle recommends not compressing executables and files that are already zipped with utilities like WinZip and GZIP. Compressing these files incurs additional overhead without the benefits of compression.

    
    

    See Also: "Compression" for an overview of compression

    
    

12. In the Enabled section, select Yes to enable the caching rule, or select No to disable the caching rule.

    Oracle recommends deselecting a caching rule for test systems

13. If you selected Cache in the Cache Policy section, select the options in Table 12-5 that apply, and then click Submit.

    Table 12-5 Options for Rules with a Cache Policy of Cache

    Option	Explanation
    Expiration Policy	From the list, select an expiration policy to apply to the objects. If you do not see an expiration policy suitable for the objects, in the navigator frame, select Rules for Caching, Personalization, and Compression > Expiration Policy Definitions to create a new policy. See Also: "Expiration" for an overview "Configuring Expiration Policies" for additional configuration details
    Multiple Objects with the Same Selector by Cookies	To cache multiple versions of an object that rely on category cookie values, select the required cookies. If you do not see a cookie that can be applied to these objects, in the navigator frame, select Rules for Caching, Personalization, and Compression > Cookie Definitions to create a new cookie definition. See Also: "Multiple Versions of the Same Object" for an overview "Configuring Cookie Definitions for Multiple-Version Objects Containing Cookies" for additional configuration details
    Multiple Objects with the Same Selector by Other Headers	To cache multiple versions of an object that rely upon HTTP request header values, select one or more of the following: Accept: Specifies which media types are acceptable for the response Accept-Charset: Specifies which character sets are acceptable for the response Accept-Encoding: Restricts the content-encodings that are acceptable in the response Accept-Language: Specifies the set of languages that are preferred as a response User-Agent: Contains information about the client that initiated the request An example of a request made with a Netscape 4.6 browser with HTTP request headers follows: User-Agent: Mozilla/4.61 [en] (WinNT; U) Accept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, image/png,*/*s Accept-Encoding: gzip Accept-Language: en Accept-Charset: iso-8859-1,*,utf-8 Note: OracleAS Web Cache does not interpret the values of these HTTP request headers. If the values for two pages are different, OracleAS Web Cache caches both pages separately. This issue is especially problematic with the User-Agent request header, whereby the browser type, version, and operating system can result in multiple cache entries. You can override this behavior for the User-Agent request header by configuring OracleAS Web Cache to cache and serve the same page for the same browser type, as described in "Recognizing Similar Browser Types for Multiple-Version Objects Containing HTTP Request Headers". See Also: "Multiple Versions of the Same Object" for an overview
    Session Caching Policies	To cache or serve objects based on session or personalized attribute information contained within a cookie, embedded URL parameter, or POST body parameter, select the sessions and corresponding policy. If you do not see a session that can be applied to these objects, in the navigator frame, select Rules for Caching, Personalization, and Compression > Session Definitions to create a new session. See Also: "Controlling How the Cache Serves Personalized Attribute Requests" or "Controlling How Session Requests Are Served by the Cache" for an overview "Configuring Session or Personalized Attribute Caching Policies" for additional configuration details
    Session-Encoded URL	Select No to not substitute session values used in session-encoded URLs or personalized attribute values enclosed within <!-- WEBCACHETAG--> and the <!-- WEBCACHEEND--> HTML tags. Select Yes to substitute session or personalized attribute values. OracleAS Web Cache will replace the value information based on the value of the cookie, embedded URL parameter, or POST body parameter. OracleAS Web Cache then serves these pages for client requests that contain the cookie or the parameter. See Also: "Substituting Session Information in Session-Encoded URLs" or "Personalized Attributes" for an overview "Configuring Rules for Popular Pages with Session Establishment" for additional configuration details
    Avoid Unwanted Copies	To define additional embedded URL or POST body parameters for which OracleAS Web Cache ignores the values, click Global URL Parameters to Ignore to apply the parameter to all caching rules or Site-Specific URL Parameters to Ignore for rules configured for this site. By configuring OracleAS Web Cache to ignore the value of embedded URL or POST body parameters, you enable OracleAS Web Cache to serve one cached object to multiple sessions requesting the same page. OracleAS Web Cache caches the response to the first request and serves subsequent requests for the page from its cache. See Also: "Excluding the Value of Embedded URL or POST Body Parameters" for an overview "Configuring OracleAS Web Cache to Exclude the Value of Embedded URL or POST Body Parameters" for additional configuration details
    HTTP Error Caching	Enter the HTTP error codes you want OracleAS Web Cache to cache and serve for this rule. If you enter multiple codes, use a comma to separate them. If there is a problem on the origin server that does not result in a 200 OK HTTP response status for this rule, then OracleAS Web Cache serves the cached HTTP error, saving origin server resources. The origin server must generate the HTTP error itself. OracleAS Web Cache caches the error pages according to the expiration policy of the rule. After the problem is resolved, invalidate the HTTP errors. See Also: Chapter 13, "Sending Invalidation Requests"

    
    

14. Repeat Steps 2 through 13 for each caching rule.

Task 2: Prioritize Rules

After you configure the caching rules, order them. Only the first matching rule is honored.

To order rules:

1. In the Caching, Personalization, and Compression Rules page, select a caching rule, and then choose Move Up or Move Down to order the rules.

2. Apply changes and restart OracleAS Web Cache:

   1. In the OracleAS Web Cache Manager main window, choose Apply Changes.

   2. In the Cache Operations page, select a cache, and then click Restart to restart OracleAS Web Cache.

Task 3: (Optional) Associate Multiple Rules with Caching Policy Features

In OracleAS Web Cache Manager, you can associate a group of rules with the following cache policy features:

• ESI propagation

• Compression

• Expiration

• Cookies for multiple-version objects

• HTTP request headers for multiple-version objects

• Session caching

• Session-encoded URLs

• HTTP error caching

To associate multiple rules with a cache policy feature:

1. In the navigator frame, select Rule Association > Policy Association.

   The Association page for the cache policy feature appears.

2. In the Association page, select the policy, and then click Change Rule Association.

   The Change Association dialog box for the cache policy feature appears.

3. Select one or more caching rules in the right list, and then click Make Association.

   If the caching rule you require does not exist, create a caching rule, as described in "Configuring Caching Rules and Rule Association".

4. Apply changes and restart OracleAS Web Cache:

   1. In the OracleAS Web Cache Manager main window, click Apply Changes.

   2. In the Cache Operations page, select a cache, and then click Restart to restart OracleAS Web Cache.

Configuring Expiration Policies

You can create policies that specify when to expire objects in the cache. In addition, you can specify how long objects can reside in the cache after they have expired. When an object expires, OracleAS Web Cache removes it either immediately or as permitted by origin server capacity up to a maximum time limit.

To configuration expiration policies in Application Server Control Console, navigate to Web Cache Home page > Administration tab > Properties > Application > Rules > Expiration Policies.

To create expiration policies in OracleAS Web Cache Manager:

1. In the navigator frame, select Rules for Caching, Personalization, and Compression > Expiration Policy Definitions.

   The Expiration Policy Definitions page appears.

2. In the Expiration Policy Definitions page, click Add.

   The Create Expiration Policy dialog box appears.

3. In the Expire section, specify when to expire objects by selecting one of the following options:

   • <time> after cache entry: Select this option to base expiration on when the objects entered the cache. Enter a number and select an interval, such as seconds, to expire the objects.

   • <time> after object creation: Select this option to base expiration on when the objects were created. Enter a number and select an interval, such as seconds, to expire the objects.

   • as per HTTP Expires header: Select this option to respect the HTTP Expires response-header field. This is the default. To use this option, objects must use the HTTP Expires or Cache-Control response-header fields.

   While the first two options enable you to set expiration for OracleAS Web Cache-specific rules, the third option recognizes the expiration policy established for the objects already programmed with an HTTP Expires or Cache-Control response-header field.

4. In the After Expiration section, specify how you want OracleAS Web Cache to process objects after they have expired:

   • Remove immediately: OracleAS Web Cache marks objects as invalid and then removes them immediately. An object is refreshed from the origin server when the cache receives the next request for it.

   • Refresh on demand as application Web server capacity permits AND no later than <time> after expiration: OracleAS Web Cache marks objects as invalid and then refreshes them based on origin server capacity. Enter the maximum time in which the objects can reside in the cache.

     
     

     Note: Performance assurance heuristics apply when you configure objects to be refreshed based on when the origin servers can refresh them; performance assurance heuristics do not apply to objects immediately removed.

     
     

5. Click Submit.

6. Repeat Steps 3 through 6 for each expiration policy.

7. In the navigator frame, select Rule Association > Expiration Policy Association.

   The Expiration Policy Association page appears.

8. In the Expiration Policy Association page, select the newly-created policy, and then click Change Rule Association.

   The Change Expiration Association dialog box appears.

9. Select a caching rule in the right list, and then click Make Association.

   The caching rule moves to the left list and the dialog box closes.

   If the caching rule you require does not exist, create a caching rule, as described in "Configuring Caching Rules and Rule Association". In Step 13 of the procedure, select an expiration rule in the Expiration Policy row of the Edit/Add Caching, Personalization, and Compression Rule dialog box.

10. Apply changes and restart OracleAS Web Cache:

    1. In the OracleAS Web Cache Manager main window, click Apply Changes.

    2. In the Cache Operations page, select a cache, and then click Restart to restart OracleAS Web Cache.

Configuring Cookie Definitions for Multiple-Version Objects Containing Cookies

You can specify which category cookies whose values OracleAS Web Cache will use to cache and identify multiple-version objects.

To specify cookie values for multiple-version URLs in Application Server Control Console, navigate to Web Cache Home page > Administration tab > Properties > Application > Rules.

To specify cookie values for multiple-version URLs in OracleAS Web Cache Manager:

1. In the navigator frame, select Rules for Caching, Personalization, and Compression > Cookie Definitions.

   The Cookie Definitions page appears.

2. In the Cookie Definitions page, click Add.

   The Edit/Add Cookie Definition dialog box appears.

3. In the Enter cookie name field, enter the name of the cookie.

4. For the prompt Also cache objects whose requests do not contain this cookie?, select either Yes or No:

   • Select Yes to cache versions of the object that do not contain this cookie. This option enables OracleAS Web Cache to serve objects from the cache for client requests that do not contain this cookie.

   • Select No to not cache versions of objects that do not contain this cookie.

5. Click Submit.

6. In the navigator frame, select Rule Association > Cookie Association.

   The Cookie Association page appears.

7. In the Cookie Association page, select the newly-created cookie definition, and then click Change Rule Association.

   The Change Cookie Association dialog box appears.

8. Select a caching rule in the right list, and then click Make Association.

   The caching rule moves to the left list and the dialog box closes.

   If the caching rule you require does not exist, create a caching rule, as described in "Configuring Caching Rules and Rule Association". In Step 13 of the procedure, select a cookie in the Multiple Objects with the Same Selector by Cookies field of the Edit/Add Caching, Personalization, and Compression Rule dialog box.

9. Apply changes and restart OracleAS Web Cache:

   1. In the OracleAS Web Cache Manager main window, click Apply Changes.

   2. In the Cache Operations page, select a cache, and then click Restart to restart OracleAS Web Cache.

Recognizing Similar Browser Types for Multiple-Version Objects Containing HTTP Request Headers

By default, OracleAS Web Cache does not interpret the values of the HTTP request headers. When the Multiple Objects with the Same Selector by Other Headers for the User-Agent request-header field is selected in OracleAS Web Cache Manager and the value of the User-Agent request header of the same URL differ, then OracleAS Web Cache caches both pages separately. For example, if one request sends an HTTP request header of User-Agent: Mozilla/4.0 (compatible; MSIE 5.5; Windows) and another request sends an HTTP request header of User-Agent: Mozilla/4.0 (compatible; MSIE 5.0; Windows; DigExt) for different versions of Internet Explorer, OracleAS Web Cache caches two separate pages.

You can override this default behavior by configuring OracleAS Web Cache with a User-Agent pattern string for a particular client. For the affected multiple-version objects, OracleAS Web Cache adds an x-Oracle-Mapped-User request-header field, and uses the value of the string rather than the entire User-Agent value:

x-Oracle-Mapped-User: MAPPEDUSERAGENT_String

To configure OracleAS Web Cache to cache and serve the same page for each browser type:

1. Create a caching rule for the pages that support the User-Agent request header, as described in "Configuring Caching Rules and Rule Association". In Step 13 of the procedure, select User-Agent in the Multiple Objects with the Same Selector by Other Headers section of the Edit/Add Caching, Personalization, and Compression Rule dialog box.

2. Use a text editor to open the webcache.xml file.

3. Locate the GLOBALCACHINGRULES element.

4. For each browser type, add the following subelements in the next line after the GLOBALCACHINGRULES element:

   <USERAGENTREMAPRULE MATCHSTRING="browser" MAPPEDUSERAGENT="x-Oracle-Mapped-User-Agent_value" MAPTYPE="USERAGENT"/>
   
   

   If you enter multiple entries, order them according to how you want OracleAS Web Cache to match. The order of these rules work in the same fashion as priority works for caching rules.

   Table 12-6 describes how to enter values for the subelements.

   Table 12-6 GLOBALCACHINGRULES Subelements

   Subelement	Description
   MATCHSTRING	Enter the pattern that will be used to match the incoming request header. Note: You can use the wildcard * to pattern match for multiple browser type variants. For example, Mozilla* can be used to match all variations of Mozilla.
   MAPPEDUSERAGENT	Enter a unique value of the User-Agent pattern that will be added to the x-Oracle-Mapped-User-Agent request header by OracleAS Web Cache.
   MAPTYPE	Enter USERAGENT to pattern match on the User-Agent request header.

   
   

   The following webcache.xml fragment shows the User-Agent remapping:

   <USERAGENTREMAPRULE MATCHSTRING="MSIE *" MAPPEDUSERAGENT="MSIE" MAPTYPE="USERAGENT"/>
   <USERAGENTREMAPRULE MATCHSTRING="Mozilla*" MAPPEDUSERAGENT="MOZ" MAPTYPE="USERAGENT"/>
   
   

   If an incoming request does not match any of the rules, OracleAS Web Cache appends a default mapping to the request. The default value of the x-Oracle-Mapped-User-Agent header is "DEFAULT_USER_AGENT."

   These mapping rules are executed for every incoming request. If you create several mapping rules, you may experience a performance degradation.

5. Locate the <MULTIVERSIONHEADERSRULE> subelement of CACHEABILITYRULE for the caching rule created in Step 0.

   <MULTIVERSIONHEADERSRULE>
        <HTTPHEADER NAME="User-Agent"/>
   </MULTIVERSIONHEADERSRULE>
   
   

6. To match on the value of the MAPPEDUSERAGENT string rather than the entire User-Agent value, change the "User-Agent" header to "x-Oracle-Mapped-User-Agent" in the HTTPHEADER attribute of the rule:

   <MULTIVERSIONHEADERSRULE>
        <HTTPHEADER NAME="x-Oracle-Mapped-User-Agent"/>
   </MULTIVERSIONHEADERSRULE>
   
   

7. Save webcache.xml.

8. Restart OracleAS Web Cache with the following command:

   opmnctl restartproc ias-component=WebCache
   

Configuring OracleAS Web Cache to Exclude the Value of Embedded URL or POST Body Parameters

You can configure OracleAS Web Cache to ignore the value of embedded URL or POST body parameters. This configuration instructs OracleAS Web Cache to serve the same page to multiple sessions requesting the same page. OracleAS Web Cache caches the response to the first request and serves subsequent requests for the page from its cache.

You have three configuration options for specifying parameters to ignore. You can:

• Establish global URL parameters.

  • In Application Server Control Console, use the Global URL Parameters to Ignore link in the Sites page (Web Cache Home page > Administration tab > Properties > Application > Sites). See "Excluding the Value of Embedded URL or POST Parameters " in Enterprise Manager Online Help.

  • In OracleAS Web Cache, navigate to the Avoid Unwanted Copies section in the Site Definitions page (Origin Servers, Sites, and Load Balancing > Site Definitions). See "Creating Site Definitions".

• Specify site-specific parameters overrides.

  • In Application Server Control Console, select a configured site in the Sites page (Web Cache Home page > Administration tab > Properties > Application > Sites), and click Edit. In the Create or Edit Named Site: Advanced tabbed page, navigate to the URL Parameters to Ignore section. See "Configuring Site Properties for a Named Site" in Enterprise Manager Online Help.

  • In OracleAS Web Cache Manager, select a configured site in the Site Definitions page (Origin Servers, Sites, and Load Balancing > Site Definitions), and then click Edit Site. See the online help for the Site Definitions page.

• When creating a caching rule, specify either global or site-specific parameters.

  • In Application Server Control Console, create a new caching rule in the Rules page (Web Cache Home page > Administration tab > Properties > Application > Rules). In the Create Rule: Advanced Caching Instructions tabbed page, navigate to the Avoid Unwanted Copies section. See "Configuring Advanced Settings for Caching Rules" in Enterprise Manager Online Help.

  • In OracleAS Web Cache Manager, create a new caching rule in the Caching, Personalization, and Compression Rules page (Rules for Caching, Personalization, and Compression > Caching, Personalization, and Compression Rules). In the Edit/Add Caching, Personalization, and Compression Rules page, navigate to the Avoid Unwanted Copies section. See "Task 1: Create Caching Rules".

Configuring Session or Personalized Attribute Caching Policies

You can specify how OracleAS Web Cache serves requests with the existence or nonexistence of session or personalized attribute cookies, embedded URL parameters, or POST parameters.

To create caching policies for pages that support session cookies or personalized attributes in Application Server Control Console, navigate to Web Cache Home page > Administration tab > Properties > Application > Rules.

To create caching policies for pages that support session cookies or personalized attributes in OracleAS Web Cache Manager:

1. In the navigator frame, select Rule Association > Session Caching Policy Association.

   The Session Caching Policy Association page appears.

2. In the Session Caching Policy Association page, click Add.

   The Add Session Caching Policy dialog box appears.

3. From the Please select a session list, select a session or personalized attribute, and then proceed to Step 5.

   If the sessions or personalized attributes listed do not contain the definition you require, then click Cancel to exit the Add Session Caching Policy dialog box. Continue to Step 5.

4. Create a session or personalized attribute definition:

   1. In the navigator frame, select Rules for Caching, Personalization, and Compression > Session Definitions.

      The Session Definitions page appears.

   2. From the For Site list, select the Web site for which to create site-specific definitions.

   3. Click Add or Create.

      The Edit/Add Session Definition dialog box appears.

   4. Select either This Site Only or For All Sites.

   5. In the Session Name field, enter an easy-to-remember unique name for the session or personalized attribute.

   6. In the Extract Value From field, enter the cookie name in the Cookie Name field, or enter the embedded URL parameter or POST parameter in the URL or POST body parameter field.

      If you enter both a cookie name and parameter, keep in mind that both must be used to support the same session or personalized attribute. If they support different sessions or personalized attributes, create separate definitions. You can specify up to 20 definitions for each page.

      
      

      Note: When a cookie expires, the client browser removes the cookie and subsequent requests for the object are directed to the origin server. To avoid pages from being served past the client session expiration time, ensure that the session cookie expires before the application Web server expires the client session.

      
      

   7. In the Default Value (Optional) field, enter a default string that can be used for session-encoded URLs or personalized attributes.

      
      

      See Also: Step 1g of "Configuring Support for Session-Encoded URLs" for further information about this field for session-encoded URLs Step 1g of "Configuring Support for Personalized Attributes" for further information about this field for personalized attributes

      
      

   8. Optionally, in the Comment field, enter a description of the definition.

   9. Click Submit.

   10. Repeats Steps 2 through 4.

5. Select YES or NO to the prompts in the Add Session Caching Policy dialog box:

   
   

   Note: With an embedded URL or POST body parameter, OracleAS Web Cache ignores the existence of an embedded URL parameter in the request. In other words, OracleAS Web Cache caches the response, even if the parameter in the request does not match the parameter in the response. To force the existence of the parameter in the client request, answer YES to the first prompt and NO to the second prompt.

   
   

   1. For the prompt 1. Cache objects whose requests contain this session?, select either YES or NO:

      • Select YES to cache versions of objects that use the cookie or parameter.

      • Select NO to not cache versions of objects that use the cookie or parameter.

   2. For the prompt 2. Cache objects whose requests do NOT contain this session?, select either YES or NO:

      • Select YES to cache versions of objects that do not use the cookie or parameter. This selection enables OracleAS Web Cache to serve objects from the cache for client requests without the session or personalized attribute information.

      • Select NO to not cache versions of objects that do not use the cookie or parameter.

   3. If you answered YES to the prompts described in Steps 5` and 5b, for the prompt 3. Can the default session value be used for substitution when the request does not contain this session?, select either YES or NO:

      • Select YES to cache one version of the object.

      • Select NO to cache two different versions of the object. OracleAS Web Cache serves one version to those requests that support the cookie or parameter and serves the other version to those requests that do not support the cookie or parameter.

6. In the Add Session Caching Policy dialog box, click Submit.

7. Associate the rule with URLs:

   1. In the Session Caching Policy Association page, select the newly-created rule, and then click Change Rule Association.

      The Change Session Caching Association dialog box appears.

   2. Select a selector from the right list, and then click Make Association.

      The selector moves to the left list and the dialog box closes.

      If the selector you require does not exist, create a caching rule for the pages the support session or personalized attributed cookie or embedded URL parameter, as described in "Configuring Caching Rules and Rule Association". In Step 13 of the procedure, select a policy in the Session Caching Policies row of the Edit/Add Caching, Personalization, and Compression Rule dialog box.

8. Repeat Steps 2 through 7 for each policy.

9. Apply changes and restart OracleAS Web Cache:

   1. In the OracleAS Web Cache Manager main window, click Apply Changes.

   2. In the Cache Operations page, select a cache, and then click Restart to restart OracleAS Web Cache.

Configuring Support for Session-Encoded URLs

You can specify caching rules for personalized pages that use session-encoded URLs. Session-encoded URLs enable Web sites to keep track of user sessions through session information contained within <A HREF=...> HTML tags. You can configure OracleAS Web Cache to substitute sessions within HTML hyperlink tags with the session values obtained from a session cookie, embedded URL parameter, or POST body parameter.

To cache instructions for substituting session information in session-encoded URLs in Application Server Control Console, navigate to Web Cache Home page > Administration tab > Properties > Application > Sessions.

To cache instructions for substituting session information in session-encoded URLs in OracleAS Web Cache Manager:

1. As necessary, create session definitions for those pages with session-encoded URLs:

   1. In the navigator frame, select Rules for Caching, Personalization, and Compression > Session Definitions.

      The Session Definitions page appears.

   2. From the For Site list, select the Web site for which to create site-specific session definitions.

   3. Click Add or Create.

      The Edit/Add Session Definition dialog box appears.

   4. Select either This Site Only or For All Sites.

   5. In the Session Name field, enter an easy-to-remember unique name for the session. You can use the same session definition used for ignoring a URL parameter.

   6. In the Extract Value From field, enter the cookie name in the Cookie Name field, or enter the embedded URL or POST body parameter in the URL or POST body parameter field.

      If you enter both a cookie name and parameter, keep in mind that both must support the same session substitution. If they support different substitutions, create separate session definitions. You can specify up to 20 definitions for each page.

      
      

      Note: Ensure that the size of cookies is not greater than 3 KB.

      
      

   7. In the Default Value (Optional) field, enter a default string for the value of the embedded URL parameter.

      OracleAS Web Cache uses the default string for those requests without the value for an embedded URL parameter. For these requests, OracleAS Web Cache substitutes the value with a default string. The string defaults to default. For example, the following <A HREF=...> contains a session_ID parameter without a value:

      <A HREF="https://oraclestore.oracle.com/OA_HTML/ibeCCtpSctDspRte.jsp?section=11886&session_ID=">Master Index</A>
      
      

      If the string is set to default, OracleAS Web Cache substitutes the value with default.

      <A HREF="https://oraclestore.oracle.com/OA_HTML/ibeCCtpSctDspRte.jsp?section=11886&session_ID=default">Master Index</A>
      
      

      If you want to instead require that the request get the cookie or parameter settings from the origin server, perform Step 3.

   8. In the Comment field, enter a description for the definition.

   9. Click Submit.

2. Create a caching rule for the objects that use the session, as described in "Configuring Caching Rules and Rule Association".

   In Step 13 of the procedure, select Yes in the Session-Encoded URL field of the Edit/Add Caching, Personalization, and Compression Rule dialog box to substitute session information in session-encoded URLs.

3. If you want to require that the request obtain the cookie, embedded URL parameter, or POST body parameter value from the origin server, perform these additional steps:

   1. Create a session caching policy for the page to track the session, as described in "Configuring Session or Personalized Attribute Caching Policies".

   2. In Step 5` of the procedure, select YES as the response.

   3. In Step 5b of the procedure, select NO as the response.

4. Apply changes and restart OracleAS Web Cache:

   1. In the OracleAS Web Cache Manager main window, click Apply Changes.

   2. In the Cache Operations page, select a cache, and then click Restart to restart OracleAS Web Cache.

Configuring Support for Personalized Attributes

You can specify caching rules for personalized pages that use personalized attributes. Personalized attributes are often in the form of a personalized greeting like "Hello, Name." Personalized attributes can come in other forms, such as icons, addresses, or shopping cart snippets. You can configure OracleAS Web Cache to substitute personalized attributes within <!-- WEBCACHETAG--> and <!-- WEBCACHEEND--> tags with the values obtained from a cookie, embedded URL parameter, or POST parameter.

To cache instructions for substituting session information in session-encoded URLs in Application Server Control Console, navigate to Web Cache Home page > Administration tab > Properties > Application > Sessions.

To create rules for personalized pages in OracleAS Web Cache Manager:

1. As necessary, create attribute definitions for those pages with personalized attributes:

   1. In the navigator frame, select Rules for Caching, Personalization, and Compression > Session Definitions.

      The Session Definitions page appears.

   2. From the For Site list, select the Web site for which to create site-specific personalized attribute definitions.

   3. Click Add or Create.

      The Edit/Add Session Definition dialog box appears.

   4. Select either This Site Only or For All Sites.

   5. In the Session Name field, enter an easy-to-remember unique name for the attribute.

      For example, if the attribute is for a personalized greeting that uses the first name, you could enter first_name01.

   6. In the Extract Value From field, enter the cookie name in the Cookie Name field, or enter the embedded URL or POST body parameter in the URL or POST body parameter field.

      If you enter both a cookie name and parameter, keep in mind that both must support the same personalized attribute substitution. If they support different substitutions, create separate personalized definitions. You can specify up to 20 definitions for each page.

      
      

      Notes: Ensure that the size of cookies is not greater than 3 KB. You can also substitute session values between the <!-- WEBCACHETAG--> and <!-- WEBCACHEEND--> tags. To substitute session values, enter the session cookie in the Cookie Name field or the session parameter in the URL or POST body parameter field.

      
      

   7. In the Default Value (Optional) field, enter a default string for the value of the cookie, embedded URL parameter, or POST body parameter.

      OracleAS Web Cache uses the default string for those requests without the value for the personalized attribute for pages containing the <!-- WEBCACHETAG--> and <!-- WEBCACHEEND--> tags. For these requests, OracleAS Web Cache uses the value of the default string. The string defaults to default. For example:

      <B><!-- WEBCACHETAG="first_name01"-->default<!-- WEBCACHEEND--></B>
      
      

      If you want to instead require that the request get the cookie or parameter settings from the origin server, perform Step 3.

   8. In the Comment field, enter a description for the definition.

   9. Click Submit.

2. Create a caching rule for the personalized page:

   • Create a caching rule, as described in "Configuring Caching Rules and Rule Association". In Step 13 of the procedure, select Yes in the Session-Encoded URL row of the Edit/Add Caching, Personalization, and Compression Rule dialog box to substitute information in personalized attributes.

   • Configure the page with a Surrogate-Control response-header field, as described in "Surrogate-Control Response-Header Field":

     Surrogate-Control: content="webcache/1.0"
     
     

3. If you want to require that the request obtain the cookie, embedded URL parameter, or POST body parameter value from the origin server, perform these additional steps:

   1. Create a caching policy for the page to track the session, as described in "Configuring Session or Personalized Attribute Caching Policies".

   2. In Step 5` of the procedure, select YES as the response.

   3. In Step 5b of the procedure, select NO as the response.

4. Apply changes and restart OracleAS Web Cache:

   1. In the OracleAS Web Cache Manager main window, click Apply Changes.

   2. In the Cache Operations page, select a cache, and then click Restart to restart OracleAS Web Cache.

5. Configure the pages that use personalized attributes with the tags <!-- WEBCACHETAG--> and<!-- WEBCACHEEND--> as follows:

   <!-- WEBCACHETAG="personalized_attribute"-->
   personalized attribute HTML segment
   <!-- WEBCACHEEND-->
   
   

   Ensure that both tags have a space after <!--.

   
   

   Important: The <!-- WEBCACHETAG--> and <!-- WEBCACHEEND--> tags cannot be used on a page that contains ESI tags for content assembly and partial page caching. If you require simple personalization and are using ESI, see "Using ESI for Simple Personalization".

   
   

   The <!-- WEBCACHETAG--> and<!-- WEBCACHEEND--> tags can appear anywhere the <!-- ...--> comment tags are permitted in HTML. For example, you can use the <!-- WEBCACHETAG--> and<!-- WEBCACHEEND--> tags between other HTML tag pairs, but you cannot use them within an HTML tag.

   In the following example, the placement of <!-- WEBCACHETAG="p_name"--> within the <input> tag is an invalid use of the <!-- WEBCACHETAG-->:

   htp.p('<FORM ACTION="test" METHOD="GET">'); 
   htp.p('<TABLE BORDER="0" > 
            <TR> 
            <TD><INPUT TYPE="text" NAME="p_name" SIZE="8" VALUE="<!--
                WEBCACHETAG="p_name"-->'||p_name||'<!-- WEBCACHEEND-->"></td> 
            </TR> 
            <TR> 
            <TD><input type="submit" value="Search"></TD> 
            </TR> 
     </TABLE>'); 
   
   

To achieve personalization within an HTML tag, use ESI.

Example: Personalized Page Configuration

To understand how to cache personalized content, consider the HTML page monthly.htm in Figure 12-3.

Figure 12-3 monthly.htm

Description of "Figure 12-3 monthly.htm"

October is personalized content that can be substituted with other values.

The page has a URL of monthly.htm?Month=month, where Month is an embedded URL parameter.

To cache monthly.htm and its personalized content, take the following steps:

1. Map a personalized attribute of TestMonth to the embedded URL parameter Month in the Edit/Add Session Definition dialog box, as shown in the following figure:

   
   Description of the illustration pers_ed.gif
   
   

2. In the Add Session Caching Policy dialog box, create a session caching policy that uses the session TestMonth, which uses the embedded URL parameter Month, as shown in the following figure:

   
   Description of the illustration pers_add.gif
   
   
   
   

   See Also: "Configuring Session or Personalized Attribute Caching Policies" for more information about creating personalized attribute caching rules

   
   

3. Add the <!-- WEBCACHETAG--> and <!-- WEBCACHEEND--> HTML tags to monthly.htm.

   Current Month is:
   <!-- WEBCACHETAG="TestMonth"-->October<!-- WEBCACHEEND-->
   
   

4. Create a caching policy for monthly.htm in the Edit/Add Caching, Personalization, and Compression Rule dialog box:

   1. In the Session Caching Policies row, choose the caching policy for the embedded URL Month.

   2. In the Session-Encoded URL row, select Yes to cache substitution instructions for personalized attributes. The following figure shows the dialog box:

   
   Description of the illustration pers_2.gif
   
   

5. Apply the configuration changes:

   1. In the OracleAS Web Cache Manager main window, click Apply Changes.

   2. In the Cache Operations page, restart OracleAS Web Cache.

To verify that OracleAS Web Cache is caching monthly.htm:

1. Request an initial request for monthly.htm at the URL monthly.htm?Month=October. Because the initial request was forwarded by OracleAS Web Cache to the application Web server, the value October is set for the Month parameter. This initial request is inserted monthly.htm into the cache.

2. Send a subsequent request for monthly.htm to the URL monthly.htm?Month=January.

   OracleAS Web Cache substitutes October with the value of January, as shown in Figure 12-4.

Figure 12-4 monthly.htm When Cached

Description of "Figure 12-4 monthly.htm When Cached"

Configuring Rules for Popular Pages with Session Establishment

Some Web sites require users to have sessions while surfing most pages. If you want to preserve the session requirement, create a Session/Personalized Attribute Related Caching Rule for those pages. This way, a request without a session will always be served by the origin server.

For some popular site entry pages, such as "/", that typically require session establishment, session establishment effectively makes the page non-cacheable to all new users without a session. To cache these pages while preserving session establishment, make the following minor modifications to your application:

1. Create a blank page for the entry URL, such as "/", that redirects to the real entry page.

2. Configure the origin server to create a session when the blank page is requested without a session cookie.

3. Create a caching rule for the real entry page and the blank page, as described in "Configuring Caching Rules and Rule Association".

   In Step 13 of the procedure, select a session caching policy with a value of Cache with session and Cache without session in the Session Caching Policies row of the Edit/Add Caching, Personalization, and Compression Rule dialog box.

With this configuration, all initial user requests to the entry URL first go to the blank page, which requires minimal resources to generate. The clients receive the response and session establishment from the application Web server. Subsequent redirected requests to the entry page carry the session, enabling the entry page to be served out of the cache.

Another solution is to use a JavaScript that sets a session cookie for the pages requiring sessions:

1. Create a JavaScript that sets a session cookie when one does not exist.

2. Add the JavaScript to each of the pages that require the session.

3. Create caching rules for the JavaScript and the session pages, as described in "Configuring Caching Rules and Rule Association".

Surrogate-Control Response-Header Field

The Surrogate-Control response-header field enables application developers to specify caching attributes of an object. This response-header field enables the application Web server to override the caching rules configured through administrative interfaces Oracle Enterprise Manager 10g Application Server Control Console or OracleAS Web Cache Manager.

The Surrogate-Control response-header field supports the following syntax:

Surrogate-Control:[content=content_type, content_type,..]
[no-store][max-age=expiration_time[+removal_time]]
[vary=headers(header header...)][coookie(cookie_name cookie_name...)]
[compress=yes|no]

Table 12-7 describes the supported control directives.

Usage Notes

• Control directives are case sensitive.

• content="ORAESI/9.0.4", content="ESI-Inline/1.0", content="ESI-INV/1.0", content="ESI/1.0" are mutually exclusive with content="webcache/1.0"

  
  

  See Also: http://www.esi.org/spec.html for the Edge Architecture Specification, which contains specification information about the Surrogate-Control response header

  
  

Example Usage

In the following example, the Surrogate-Control response-header field specifies that the object is to expire 30 seconds after it enters the cache and be removed 60 seconds after expiration. It also specifies that the object contains ESI tags that require processing:

Surrogate-Control: max-age=30+60, content="ORAESI/9.0.4"

In the following example, the Surrogate-Control response-header field specifies that the object is not to be cached:

Surrogate-Control: no-store

In the following example, the Surrogate-Control response-header field specifies ESI processing with the content control directive. The vary control directive specifies to cache versions of the multiple-version object, regardless of whether the request contains the HTTP Accept request header.

Surrogate-Control: content="ORAESI/9.0.4", vary=headers(Accept)

In the following similar example, the Surrogate-Control response-header field specifies ESI processing with the content control directive. The vary control directive specifies to cache versions of the multiple-version object only if the request contains the Accept and MyCustomHeader headers and news and sports cookies.

Surrogate-Control: content="ORAESI/9.0.4", vary=headers(Accept/f);cookies(news/f sports/f)

Enabling Partial Page Caching

To enable partial page caching:

1. Configure the template page as follows:

   1. Use ESI markup tags in the template to fetch and include the fragments.

      
      

      Important: ESI tags cannot be used on a page that contains <!-- WEBCACHETAG--> and <!-- WEBCACHEEND--> tags. If you require simple personalization and are using ESI, see "Using ESI for Simple Personalization".

      
      

   2. In the template page, configure the HTTP response with the Surrogate-Control response-header field. For example:

      Surrogate-Control: max-age=30+60, content="ORAESI/9.0.4"
      
      

   3. If the Surrogate-Control response-header field does not include all the caching attributes required for the template page, create a caching rule for the page.

2. Configure the fetchable fragments:

   • Use a Surrogate-Control response-header field in the HTTP response message.

   • If the Surrogate-Control response-header field does not include all the caching attributes required for the fragment, create a caching rule for the fragment.

Using ESI for Simple Personalization

You can use variable expressions to achieve the same substitution as personalized attributes and session-encoded URLs. Oracle recommends using ESI for simple personalization when you are utilizing other ESI features, otherwise continue to use the methods described in "Configuring Rules for Popular Pages with Session Establishment".

For example, the following HTML excerpt uses the <!-- WEBCACHETAG--> and<!-- WEBCACHEEND--> tags to substitute a user's name based on the value the client browser passes with UserName cookie. In addition, the session information contained within the sessionID cookie is used to replace session information for one user with another user.

Welcome <!-- WEBCACHETAG="UserName"-->John<!-- WEBCACHEEND -->!
Here is a <A HREF="/jsp/myPage.jsp?sessionID=13001">link</A>.

The same effect is achieved with the following ESI markup:

<esi:vars>
 Welcome $(HTTP_COOKIE{'username'})!
 Here is a <A HREF="/jsp/myPage.jsp?sessionID=$(QUERY_STRING{'sessionid'})">link</A>.
</esi:vars>        

The <esi:vars> tag enables you to use an ESI environment variable outside of an ESI tag. Variables can also be used with other ESI tags.

Examples of ESI Usage

This section provides examples of ESI usage in the following topics:

• Example of a Portal Site Implementation

• Example of Simple Personalization with Variable Expressions

Example of a Portal Site Implementation

Figure 12-5 shows a portal site response page, http://www.company.com/servlet/oportal?username=Mark, for a registered user named Mark.

Figure 12-5 Portal Site Page

Description of "Figure 12-5 Portal Site Page"

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

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

• Portal Example Using inline Tags

• Portal Example Using Include Tags

Portal Example Using inline Tags

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

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

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

Example 12-1 shows portal.esi with <esi:inline> tags.

Example 12-1 portal.esi with inline Tags

<esi:inline name="/Common_Fragment_1" >
<!-- First common fragment -->
<HTML>
...
<!-- Personalized Greeting With ESI variable -->
  Welcome, $(QUERY_STRING{username})!
</esi:inline>

<esi:inline name="/Weathers_San_Francisco" >
...
<!-- Personalized Weather Forecast -->
Weather Forecast for San Francisco
<TABLE>
  <TR>
    <TD> 
      Currently: 50F
    </TD>
  </TR>
</TABLE>
</esi:inline>

<esi:inline name="/Common_Fragment_2" >
<!-- Second common fragment -->
...
</esi:inline>

<esi:inline name="/Stocks_$(QUERY_STRING{username})" >
<!-- Personalized Stock Quote Selections -->
<TABLE>
  <TR>
    <TD>
    <esi:inline name="/ticker_IBM">
      IBM 84.99
    </esi:inline>
    <BR>
    <esi:inline name="/ticker_ORCL">
      ORCL 13.379
    </esi:inline>
    <BR>
    <esi:inline name="/ticker_YHOO">
      YHOO 27.15
    </esi:inline>
    <TD>
  </TR>
</TABLE>
</esi:inline>

<esi:inline name="/Common_Fragment_3">
<!-- Third common fragment -->
...
</esi:inline>

<esi:inline name="/ExternalAdvertisement">
<!-- External Advertisement -->
<TABLE>
  <TR> 
    <TD>
    <a href="http://www.companyad.com/advert?promotionID=126532">
    <img src="http://www.companyad.com/advert_img?promotionID=126532">
    </a>
    </TD>
  </TR>
</TABLE>
</esi:inline>

<esi:inline name="/Common_Fragment_4">
<!-- Fourth common fragment -->
...
</esi:inline>

<esi:inline name="/Top_News_Finance">
<!-- Personalized Top News -->
Latest News for finance
<TABLE>
  <TR>
     Tech Spending Growth Indexes Little Changes
     Home Sales Hit Record High
     Gas Prices Dip Again
  </TR>
</TABLE>
</esi:inline>

<esi:inline name="/Sports_News_Soccer" >
<!-- Personalized Sports News -->
Latest Sports News for Soccer

<TABLE>
  <TR>
  Preparation for World Cup
  Youth Cup game on a Sunday
  Latest Scores
  </TR>
</TABLE>
</esi:inline>

<esi:inline name="/Common_Fragment_5" >
...
</esi:inline>

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

Example 12-2 portal.esi Example with inline Tags: Personalized Greeting

<esi:inline name="/Common_Fragment_1" >
<!-- First common fragment -->
<HTML>
...
<!-- Personalized Greeting With ESI variable -->
  Welcome, $(QUERY_STRING{username})!
</esi:inline>

Example 12-3 shows the markup for Weather Forecast. The fragment is unique to each city. Every template selecting the same city would share this fragment with Mark's page due to the fragment naming.

Example 12-3 portal.esi Example with inline Tags: Weather Forecast

<esi:inline name="/Weathers_San_Francisco" >
<!-- Personalized Weather Forecast -->
Weather Forecast for San Francisco
<TABLE>
  <TR>
    <TD> 
      Currently: 50F
    </TD>
  </TR>
</TABLE>
</esi:inline>

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

Example 12-4 portal.esi Example: My Stocks Fragment

<esi:inline name="/Stocks_$(QUERY_STRING{username})" >
<!-- Personalized Stock Quote Selections -->
<TABLE>
  <TR>
    <TD>
    <esi:inline name="/ticker_IBM">
      IBM 84.99
    </esi:inline>
    <BR>
    <esi:inline name="/ticker_ORCL">
      ORCL 13.379
    </esi:inline>
    <BR>
    <esi:inline name="/ticker_YHOO">
      YHOO 27.15
    </esi:inline>
    <TD>
  </TR>
</TABLE>
</esi:inline>

Example 12-5 shows the markup for referencing an advertisement in the Promotion section. promotionID is the based on the user's identification.

Example 12-5 portal.esi Example with inline Tags: Promotion

<esi:inline name="/ExternalAdvertisement">
<!-- External Advertisement -->
<TABLE>
  <TR> 
    <TD>
    <a href="http://www.companyad.com/advert?promotionID=126532">
    <img src="http://www.companyad.com/advert_img?promotionID=126532">
    </a>
    </TD>
  </TR>
</TABLE>
</esi:inline>

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

See Also: "Portal Example Using Include Tags" for an example of using <esi:include> tag for real-time advertisements

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

Example 12-6 portal.esi Example with inline Tags: Latest News and Latest Sports News

<esi:inline name="/Top_News_Finance">
<!-- Personalized Top News -->
Latest News for finance
<TABLE>
  <TR>
     Tech Spending Growth Indexes Little Changes
     Home Sales Hit Record High
     Gas Prices Dip Again
  </TR>
</TABLE>
</esi:inline>


<esi:inline name="/Sports_News_Soccer" >
<!-- Personalized Sports News -->
Latest Sports News for Soccer
<TABLE>
  <TR>
  Preparation for World Cup
  Youth Cup game on a Sunday
  Latest Scores
  </TR>
</TABLE>
</esi:inline>

Portal Example Using Include Tags

This section shows how the <esi:include> tag can be used for fragmentation and assembly of fetchable fragments whose content are not embedded in the template.

Example 12-7 shows portal.esi with <esi:include> tags.

Example 12-7 portal.esi with include Tags

<HTML>
...
<!-- Personal Profile -->
<esi:comment text="Profile refers to environment variables stored in
/servlet/GetProfile. GetProfile servlet enables access to a set of environment
variables with personal profile information."/>
<esi:environment src="/servlet/GetProfile?username=$(QUERY_STRING{username})"
name="Profile"/>
...

<!-- Personalized Greeting With ESI variable -->
<esi:vars>Welcome, $(QUERY_STRING{username})!</esi:vars>
...


<!-- Personalized Weather Forecast -->
<TABLE>
  <TR> 
    <TD> 
      <esi:include src="/servlet/Weather?city=$(Profile{city})&state=$(Profile{state})"/>
    </TD>
  </TR>
</TABLE>
...

<!-- Personalized Stock Quote Selections -->
<TABLE>
  <TR> 
    <TD>
      <esi:include src="/servlet/PersonalizedStockSelection?username=$(QUERY_STRING{username})"/>
    </TD>
  </TR>
</TABLE>
...

<!-- External Advertisement -->
<TABLE>
  <TR> 
    <TD>
      <esi:try>
        <esi:attempt>
          <esi:comment text="Include an ad"/> 
          <esi:include src="/servlet/Advert"/>
        </esi:attempt>
        <esi:except> 
         <esi:comment text="Just write an HTML link instead"/>
         <A HREF="http://www.oracle.com">http://www.oracle.com</a> 
        </esi:except>
      </esi:try>
    </TD>
  </TR>
</TABLE>
...

<!-- Personalized Top News -->
Latest News for <esi:vars>$(Profile{news})</esi:vars>
<TABLE>
  <TR> 
    <TD>
      <esi:choose>
        <esi:when test="$(Profile{news}) == 'Internet'">
          <esi:include src="/servlet/News?type=Top&topic=internet"/> 
        </esi:when>
        <esi:when test="$(Profile{news}) == 'finance'">
         <esi:include src="/servlet/News?type=Top&topic=business"/> 
        </esi:when>
      <esi:otherwise>
      <esi:include src="/servlet/News?type=Top&topic=technology"/> 
      </esi:otherwise>
      </esi:choose>
    </TD>
  </TR>
</TABLE>
...


<!-- Personalized Sports News -->
Latest Sports News for <esi:vars>$(Profile{sport})</esi:vars>
<TABLE>
  <TR> 
    <TD>
      <esi:choose>
        <esi:when test="$(Profile{sport}) == 'golf'">
          <esi:include src="/servlet/News?type=Sports&topic=golf"/> 
        </esi:when>
        <esi:when test="$(Profile{sport}) == 'soccer'">
          <esi:include src="/servlet/News?type=Sports&topic=soccer"/> 
        </esi:when>
        <esi:when test="$(Profile{sport}) == 'basketball'">
          <esi:include src="/servlet/News?type=Sports&topic=basketball"/> 
        </esi:when>
        <esi:when test="$(Profile{sport}) == 'baseball'">
          <esi:include src="/servlet/News?type=Sports&topic=baseball"/> 
        </esi:when>
        <esi:otherwise>
          <esi:include src="/servlet/News?type=Sports&topic=soccer"/> 
        </esi:otherwise>
      </esi:choose>
    </TD>
  </TR>
</TABLE>

Example 12-8 specifies Profile to refer to the environment variables stored in GetProfile. GetProfile enables access to user profile variables, which are used as parameters in the included fragments:

Example 12-8 portal.esi Example: Custom Profile Environment Variable Setting

<!-- Personal Profile -->
<esi:comment text="Profile refers to environment variables stored in
/servlet/GetProfile. GetProfile servlet enables access to a set of environment
variables with personal profile information."/>

<esi:environment src="/servlet/GetProfile?username=$(QUERY_STRING{username})"
name="Profile"/>

Example 12-9 shows GetProfile, which provides access to the city, state, news, and sports environment variables.

Example 12-9 portal.esi Example: GetProfile File with Environment Variables

<?xml version="1.0"?>
<esi-environment esiversion="ORAESI/9.0.4">
  <city>San_Francisco</city>
  <state>CA</state>
  <news>finance</news>
  <sports>soccer</sports>
</esi-environment>

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

Example 12-10 portal.esi Example with vars tag: Personalized Greeting

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

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

Example 12-11 portal.esi Example with include Tags: Weather Forecast

<TABLE>
  <TR> 
    <TD> 
      <esi:include src="/servlet/Weather?city=$(Profile{city})&state=$(Profile{state})"/>
    </TD>
  </TR>
</TABLE>

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

Example 12-12 portal.esi Example with include Tags: My Stocks Fragment

<TABLE>
  <TR> 
    <TD>
      <esi:include src="/servlet/PersonalizedStockSelection?username=$(QUERY_STRING{username})"/>
    </TD>
  </TR>
</TABLE>

The markup for the included fragment PersonalizedStockSelection is depicted in Example 12-13. It includes fragments for three stock quotes: IBM, ORCL, and YHOO.

Example 12-13 portal.esi Example: PersonalizedStockSelection Fragment for Mark

<TABLE>
  <TR> 
    <TD>
    <BR>
    <esi:include src="Quote?symbol=IBM"/>
    <BR>
    <esi:include src="Quote?symbol=ORCL"/>
    <BR>
    <esi:include src="Quote?symbol=YHOO"/>
    <BR>
    </TD>
  </TR>
</TABLE>

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

Example 12-14 portal.esi Example: PersonalizedStockSelection Fragment for Scott

<TABLE>
  <TR> 
    <TD>
    <BR>
    <esi:include src="Quote?symbol=IBM"/>
    <BR>
    <esi:include src="Quote?symbol=ORCL"/>
    <BR>
    <esi:include src="Quote?symbol=SCO"/>
    <BR>
    </TD>
  </TR>
</TABLE>

Example 12-15 shows the markup for rotating advertisements in the Promotion section. The advertisements rotates in the sense that the advertisement changes for each response. By separating the generation of the included image fragment response from the template page, OracleAS Web Cache is able to cache the template and integrate the dynamic advertisement into the template.

Example 12-15 portal.esi Example with include Tags: Promotion

<TABLE>
  <TR> 
    <TD>
      <esi:try>
        <esi:attempt>
          <esi:comment text="Include an ad"/> 
          <esi:include src="/servlet/Advert"/>
       </esi:attempt>
       <esi:except> 
         <esi:comment text="Just write an HTML link instead"/>
          <A HREF="www.oracle.com">www.oracle.com</a> 
       </esi:except>
      </esi:try>
    </TD>
  </TR>
</TABLE>

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

Example 12-16 portal.esi Example: Rotating Banner Output

<TABLE>
  <TR> 
    <TD>
      <A HREF="http://www.companyad.com/redirect?refID=11934502">
      <IMG src="http://www.companyad.com/advert_img?refID=11934502"></A>
    </TD>
  </TR>
</TABLE>

As shown in Example 12-17, the next time the user reloads the page, Advert generates another banner for the request.

Example 12-17 portal.esi Example: Rotating Banner Reload

<TABLE>
  <TR> 
    <TD>
      <A HREF="http://www.companyad.com/redirect?refID=123456602">
      <IMG src="http://www.companyad.com/advert_img?refID=123456602"></A>
    </TD>
  </TR>
</TABLE>

The banner relies on alternate processing with the <esi:try> tag. If the servlet cannot run Advert, a link to www.oracle.com appears in the banner's place.

Example 12-18 shows the markup for Latest News and Latest Sports News:

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

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

Example 12-18 portal.esi Example with include Tags: Latest News and Sports Sections

Latest News for <esi:vars>$(Profile{news})</esi:vars>
<TABLE>
  <TR> 
    <TD>
      <esi:choose>
        <esi:when test="$(Profile{news}) == 'internet'">
          <esi:include src="/servlet/News?type=Top&topic=internet"/> 
        </esi:when>
        <esi:when test="$(Profile{news}) == 'finance'">
         <esi:include src="/servlet/News?type=Top&topic=business"/> 
        </esi:when>
      <esi:otherwise>
      <esi:include src="/servlet/News?type=Top&topic=technology"/> 
      </esi:otherwise>
      </esi:choose>
    </TD>
  </TR>
</TABLE>
...
<!-- Personalized Sports News -->
Latest Sports News for <esi:vars>$(Profile{sport})</esi:vars>

<TABLE>
  <TR> 
    <TD>
      <esi:choose>
        <esi:when test="$(Profile{sport}) == 'golf'">
          <esi:include src="/servlet/News?type=Sports&topic=golf"/> 
        </esi:when>
        <esi:when test="$(Profile{sport}) == 'soccer'">
          <esi:include src="/servlet/News?type=Sports&topic=soccer"/> 
        </esi:when>
        <esi:when test="$(Profile{sport}) == 'basketball'">
          <esi:include src="/servlet/News?type=Sports&topic=basketball"/> 
        </esi:when>
        <esi:when test="$(Profile{sport}) == 'baseball'">
          <esi:include src="/servlet/News?type=Sports&topic=baseball"/> 
        </esi:when>
        <esi:otherwise>
          <esi:include src="/servlet/News?type=Sports&topic=soccer"/> 
        </esi:otherwise>
      </esi:choose>
    </TD>
  </TR>
</TABLE>

htp.p('<form action="test" method="GET">');
htp.p('<table border="0" >
      <tr>
      <td><input type="text" name="p_name" size="8" value="'||p_name||'"></td>
      </tr>
      <tr>
      <td><input type="submit" value="Search"></td>
      </tr>
</table>');

htp.p('<form action="test" method="GET">'); 
htp.p('<table border="0" > 
    <tr><esi:vars> 
         <td><input type="text" name="p_name" size="8" 
                          value="$(HTTP_COOKIE{'p_name'}"></td> 
         </tr></esi:vars> 
         <tr> 
         <td><input type="submit" value="Search"></td> 
         </tr> 
  </table>');