oracle.portal.provider.v2.cache.esi
Class ESIUtils

java.lang.Object
  oracle.portal.provider.v2.cache.esi.ESIUtils

public class ESIUtils
extends java.lang.Object

Contains utility methods and constants for including and caching ESI fragments.

Constructor Summary

ESIUtils()

Method Summary

static java.lang.String	generateESIInclude(java.lang.String url, int expirationTimeInSeconds, int removalTimeInSeconds, java.lang.String method, java.lang.String queryString, boolean onErrorContinue, int timeoutInSeconds, java.lang.String timeoutMessage, NameValue[] esiRequestHeaders) Generates an ESI include directive that can be inserted into a portlet's rendered HTML.
static java.lang.String	generatePortalESIInclude(PortletRenderRequest prr, java.lang.String url, int expirationTimeInSeconds, int removalTimeInSeconds, java.lang.String method, java.lang.String queryString, boolean onErrorContinue, int timeoutInSeconds, java.lang.String timeoutMessage, int cacheLevel, java.lang.String cacheEncryptionKey) Generates an ESI include directive which uses Portal portlet render request headers to cache the ESI fragment at either the Portal user or Portal system level.
static void	setESIResponseHeaders(javax.servlet.http.HttpServletResponse response, int expirationTimeInSeconds, int removalTimeInSeconds, java.lang.String[] varyHeaders) Sets the servlet reponse headers for an ESI fragment using Portal specific headers to cache the ESI fragment at either the Portal user or Portal system level.
static void	setPortalESIResponseHeaders(javax.servlet.http.HttpServletResponse response, int expirationTimeInSeconds, int removalTimeInSeconds) Sets the servlet reponse headers for an ESI fragment using Portal specific headers to cache the ESI fragment at either the Portal user or Portal system level.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ESIUtils

public ESIUtils()

Method Detail

generateESIInclude

public static java.lang.String generateESIInclude(java.lang.String url,
                                                  int expirationTimeInSeconds,
                                                  int removalTimeInSeconds,
                                                  java.lang.String method,
                                                  java.lang.String queryString,
                                                  boolean onErrorContinue,
                                                  int timeoutInSeconds,
                                                  java.lang.String timeoutMessage,
                                                  NameValue[] esiRequestHeaders)

Generates an ESI include directive that can be inserted into a portlet's rendered HTML.

This method allows for complete control of all the attributes that make up an ESI include directive.

The ESI include directive is placed within an ESI try block and will have one of the two following formats:

•  <esi:try>
     <esi:attempt>
       <esi:include src="URL_fragment" 
         [max-age="expiration_time [+ removal_time]]" [method="GET|POST"] 
         [onerror="continue"] [timeout="fetch_time"]/>
     </esi:attempt>
     <esi:except>
       Time Out Message
     </esi:except>
   </esi:try>
   

•  <esi:try>
     <esi:attempt>
       <esi:include src="URL_fragment" 
         [max-age="expiration_time [+ removal_time]"] [method="GET|POST"] 
         [onerror="continue"] [timeout="fetch_time"]>
         [<esi:request_header name="request_header" value="value"/>
         [<esi:request_body value="value"/>
       </esi:include>
     </esi:attempt>
     <esi:except>
       Time Out Message
     </esi:except>
   </esi:try>
   

See the OracleAS Web Cache Administration and Deployment Guide for a more in-depth discussion of ESI and the ESI include directive.

Parameters:

url - the URL of the ESI fragment

expirationTimeInSeconds - time, in seconds, to expire the fragment. The maxage attribute is added to the ESI include directive only if the expirition time is greater than 0. If not added then the expiration time specified in the ESI response will be used. Submit a positive expiration time if the including page has a higher tolerance for stale fragments than specified by the expiration time parameters in fragment responses. If max-age is set in both the ESI request and the ESI response then Webcache uses the greater of the two. Oracle Corporation recommends setting the max-age attribute in the ESI request to a longer time than the max-age control directive in the ESI response.

removalTimeInSeconds - optional, the time, in seconds, to remove the fragment after the expiration time. A removal time less than or equal to 0 will not be added to the ESI request. Webcache uses a heuristic to remove a cached entry some time after the end of the expiration period and before the end of the removal period.

method - the HTTP method used - either "GET" or "POST". If method is not set, i.e. is null or of 0 length, then GET is assumed. However, if a valid queryString (non-null and of non-zero length) is sent, then POST is assumed.

queryString - the body of the HTTP request that fetches the ESI fragment. Ignored if null or length is 0.

onErrorContinue - if true then the onerror="continue" attribute is added to the ESI include directive which directs Webcache, in the case of a failed fetch on the ESI fragment, to ignore the ESI tag and serve the page.

timeoutInSeconds - if the fragment has not been fetched within this timeout interval, then the fetch is aborted. Timeout is added to the ESI include only if greater than 0.

timeoutMessage - the message rendered if the fetch times out.

esiRequestHeaders - the headers sent with the HTTP request that fetches the ESI fragment.

Returns:

a string representation of the ESI include directive.

generatePortalESIInclude

public static java.lang.String generatePortalESIInclude(PortletRenderRequest prr,
                                                        java.lang.String url,
                                                        int expirationTimeInSeconds,
                                                        int removalTimeInSeconds,
                                                        java.lang.String method,
                                                        java.lang.String queryString,
                                                        boolean onErrorContinue,
                                                        int timeoutInSeconds,
                                                        java.lang.String timeoutMessage,
                                                        int cacheLevel,
                                                        java.lang.String cacheEncryptionKey)

Generates an ESI include directive which uses Portal portlet render request headers to cache the ESI fragment at either the Portal user or Portal system level.

This method allows for complete control of all the attributes that make up an ESI include directive except for the ESI request headers. By specifying a cache level using the cachelevel parameter, Portal request headers will sent with the ESI fragment HTTP request resulting in the ESI fragment being cached at either the Portal user level or the Portal system level.

The ESI include directive is placed within an ESI try block and will have one of the two following formats:

•  <esi:try>
     <esi:attempt>
       <esi:include src="URL_fragment" 
         [max-age="expiration_time [+ removal_time]]" [method="GET|POST"] 
         [onerror="continue"] [timeout="fetch_time"]/>
       </esi:attempt>
     <esi:except>
       Time Out Message
     </esi:except>
   </esi:try>
   

•  <esi:try>
     <esi:attempt>
       <esi:include src="URL_fragment" 
         [max-age="expiration_time [+ removal_time]"] [method="GET|POST"] 
         [onerror="continue"] [timeout="fetch_time"]>
         [<esi:request_header />
         [<esi:request_body value="value"/>
       </esi:include>
     </esi:attempt>
     <esi:except>
         Time Out Message
     </esi:except>
   </esi:try>
   

See the OracleAS Web Cache Administration and Deployment Guide for a more in-depth discussion of ESI and the ESI include directive.

Parameters:

url - the URL of the ESI fragment

expirationTimeInSeconds - time, in seconds, to expire the fragment. The maxage attribute is added to the ESI include directive only if the expirition time is greater than 0. If not added then the expiration time specified in the ESI response will be used. Submit a positive expiration time if the including page has a higher tolerance for stale fragments than specified by the expiration time parameters in fragment responses. If max-age is set in both the ESI request and the ESI response then Webcache uses the greater of the two. Oracle Corporation recommends setting the max-age attribute in the ESI request to a longer time than the max-age control directive in the ESI response.

removalTimeInSeconds - optional, the time, in seconds, to remove the fragment after the expiration time. A removal time less than or equal to 0 will not be added to the ESI request. Webcache uses a heuristic to remove a cached entry some time after the end of the expiration period and before the end of the removal period.

method - the HTTP method used - either "GET" or "POST". If method is not set, i.e. is null or of 0 length, then GET is assumed. However, if a valid queryString (non-null and of non-zero length) is sent, then POST is assumed.

queryString - the body of the HTTP request that fetches the ESI fragment. Ignored if null or length is 0.

onErrorContinue - if true then the onerror="continue" attribute is added to the ESI include directive which directs Webcache, in the case of a failed fetch on the ESI fragment, to ignore the ESI tag and serve the page.

timeoutInSeconds - if the fragment has not been fetched within this timeout interval, then the fetch is aborted. Timeout is added to the ESI include only if greater than 0.

timeoutMessage - the message rendered if the fetch times out.

cacheLevel - the level at which the ESI fragment will be cached.

cacheEncryptionKey - a string of a least 20 bytes in length that is used to encrypt the Portal cache key header (a composite of several non-encrypted Portal headers). If not supplied or if not valid, i.e. less than 20 bytes in length, then the cache key is not encrypted.

Returns:

a string representation of the ESI include directive.

setESIResponseHeaders

public static void setESIResponseHeaders(javax.servlet.http.HttpServletResponse response,
                                         int expirationTimeInSeconds,
                                         int removalTimeInSeconds,
                                         java.lang.String[] varyHeaders)

Sets the servlet reponse headers for an ESI fragment using Portal specific headers to cache the ESI fragment at either the Portal user or Portal system level.

Use this method to have an ESI fragment cached at the Portal user or Portal system level. Even though the including page may be cached at the same level as the ESI fragment it may have a different expiry time.

See the OracleAS Web Cache Administration and Deployment Guide for a more in-depth discussion of ESI and the ESI include directive.

Parameters:

response - the servlet response object

expirationTimeInSeconds - time, in seconds, to expire the fragment. The maxage attribute is added to the ESI response directive only if the expirition time is greater than 0. If not added then the expiration time specified in the ESI request will be used. Submit a positive expiration time if the including page has a higher tolerance for stale fragments than specified by the expiration time parameters in fragment responses. If max-age is set in both the ESI request and the ESI response then Webcache uses the greater of the two. Oracle Corporation recommends setting the max-age attribute in the ESI request to a longer time than the max-age control directive in the ESI response.

removalTimeInSeconds - optional, the time, in seconds, to remove the fragment after the expiration time. A removal time less than or equal to 0 will not be added to the ESI response.

varyHeaders - specifies the headers to be used for caching the ESI fragment

setPortalESIResponseHeaders

public static void setPortalESIResponseHeaders(javax.servlet.http.HttpServletResponse response,
                                               int expirationTimeInSeconds,
                                               int removalTimeInSeconds)

Sets the servlet reponse headers for an ESI fragment using Portal specific headers to cache the ESI fragment at either the Portal user or Portal system level.

Use this method to have an ESI fragment cached at the Portal user or Portal system level. Even though the including page may be cached at the same level as the ESI fragment it may have a different expiry time.

See the OracleAS Web Cache Administration and Deployment Guide for a more in-depth discussion of ESI and the ESI include directive.

Parameters:

response - the servlet response object

expirationTimeInSeconds - time, in seconds, to expire the fragment. The maxage attribute is added to the ESI response directive only if the expirition time is greater than 0. If not added then the expiration time specified in the ESI request will be used. Submit a positive expiration time if the including page has a higher tolerance for stale fragments than specified by the expiration time parameters in fragment responses. If max-age is set in both the ESI request and the ESI response then Webcache uses the greater of the two. Oracle Corporation recommends setting the max-age attribute in the ESI request to a longer time than the max-age control directive in the ESI response.

removalTimeInSeconds - optional, the time, in seconds, to remove the fragment after the expiration time. A removal time less than or equal to 0 will not be added to the ESI response.