7 Web Object Cache Tags and API

Cache Repository

The cache repository is the component that is responsible for data storage, data distribution, and cache expiration. There can be multiple repository implementations for a programmable Web cache (such as the Web Object Cache), depending on the tier and platform. For example, the file system might be used for secondary storage in the middle tier, and database tables might be used for primary storage in the database tier.

The Web Object Cache uses the Oracle Application Server Java Object Cache as its default repository. The Java Object Cache is a general-purpose Java caching service and API designed for application use, with objects being accessible by name.

The Java Object Cache is a powerful and flexible programming facility. There are no restrictions on the types of objects that can be cached or the original source of the objects. The management of each object can be easily customized. Each object has a set of attributes such as the following:

• How the object is loaded into the cache

• Where the object is stored (in memory, on disk, or both)

• The lifetime, also known as the time-to-live, of the object

• Whom to notify when the object is invalidated

Objects can be invalidated as a group or individually.

For more information about the Java Object Cache, see the Oracle Application Server Containers for J2EE Services Guide.

Cache Programming Interfaces

The front-end caching interfaces are used through JSP pages and servlets to handle HTTP processing and to direct the semantics relating to the cache policy (rules and specifications determining how the cache works).

The OC4J Web Object Cache programming interfaces can be further divided as follows:

• Web Object Cache API

  This is the common layer across servlets and JSP pages, dealing with the HTTP semantics and cache policy. This layer communicates with the cache repository.

• Web Object Cache tag library

  This is a convenient wrapper, using JSP custom tag functionality, for the Web Object Cache API. Use custom tags in a JSP page to control the caching, with the API being called through the underlying tag handler classes.

This chapter describes these programming interfaces and their interaction with the cache repository. Cache tags are described in "Web Object Cache Tag Descriptions". The underlying cache policy API is described in "Web Object Cache API Descriptions". In servlets, you will use the underlying API; in JSP pages, you will typically use the more convenient tags.

Memory-Oriented Repositories Versus Secondary Storage Repositories

There are two categories of repositories that can be used as the back-end of the Web Object Cache:

• Secondary storage cache repository such as a file system repository

• Memory-oriented cache repository such as the Oracle Application Server Java Object Cache, the default repository of the Web Object Cache

A secondary storage repository requires Java serialization during cache operations. During storage to the cache, objects are serialized into the repository; during retrieval from the cache, they are deserialized into memory. Therefore, as a result of the serialization/deserialization process, a complete and distinct copy of the cache object is automatically created during each cache operation.

This is not the case when you store or retrieve cache objects to or from a memory-oriented repository. With a memory-oriented repository, the identical object in the user application will be stored to the cache, or the identical object in the cache will be retrieved for the user. By default, no copy is made. If there are multiple retrievals, all retrievals share the same object.

Advantages in Cloning Copies of Cache Objects

In many cases in your applications, you will want to ensure that different retrievals use different copies of a cache object. There are two key reasons for this:

• If the identical cache object is shared across multiple retrievals, changes made to the data in one place might unintentionally affect values retrieved and used elsewhere.

• If the identical cache object is shared across multiple retrievals, then multiple Java threads might access the same object simultaneously. This would result in thread safety issues if the original object design was not thread-safe. Perhaps, for example, the object was originally intended for page-scope or request-scope usage only, where there could be only one thread for each object. This thread-behavior assumption would be violated.

To avoid these possible problems, use complete and hierarchical copies when you store and retrieve generic Java serializable data to or from a memory-oriented repository. "Complete and hierarchical" means copying not just the direct members referenced by the object, but also any indirect variables that are referenced. For example, assume an object xyz has a java.util.Vector instance as a member variable. Cloning a complete and hierarchical copy involves copying not just the Vector instance itself, but also all mutable objects or elements referenced by the Vector instance.

Use of the CloneableCacheObject Interface

If you implement the CloneableCacheObject interface and its cloneCacheObj() method in your cache objects, then the Web Object Cache will automatically call cloneCacheObj() to make a complete and hierarchical copy of each cache object whenever it is stored to or retrieved from a memory-oriented cache repository.

Cache Block Expiration

Because cache blocks mainly consist of semi-static fragments of information, the Oracle implementation does not require a tightly coherent expiration model. A looser model typically provides acceptable results and requires less synchronization overhead.

There are two categories of expiration for data in Web Object Cache blocks:

• Duration (time-to-live): Expiration occurs after data has been in the cache for a specified amount of time.

• Fixed time/day: Expiration occurs regularly at a set time, such as at a specified time each day or on a specified day each week.

Expiration details are determined by the settings of attributes in an instance of the oracle.jsp.jwcache.ExpirationPolicy class. This ExpirationPolicy object is an attribute of the CachePolicy object associated with the cache block. See "Expiration Policy Attributes".

In JSP pages, you can set ExpirationPolicy attributes through attributes of the Web Object Cache cache tags. In servlets, you can use methods of the ExpirationPolicy object directly. (See "ExpirationPolicy Methods".) Alternatively, you can set ExpirationPolicy attributes through a cache policy descriptor. (See "Cache Policy Descriptor".)

Cache Block Invalidation

Instead of depending on expiration to invalidate a cache, you can invalidate it explicitly in one of the following ways:

• Use the invalidateCache tag. See "Web Object Cache invalidateCache Tag".

• Use the overloaded invalidateCache(), invalidateCacheLike(), or invalidateCacheOtherPathLike() method of a CachePolicy instance to explicitly invalidate one or more cache blocks. See "CachePolicy Methods".

Cache Policy Attribute Descriptions

Table 7-1 describes cache policy object attributes.

More About Cache Block Naming and the autoType Attribute

As discussed in "Cache Block Naming: Implicit Versus Explicit", cache blocks can be named either implicitly, sometimes called auto-naming, or explicitly, sometimes called user-naming.

More specifically, there are six ways for cache blocks to be named. Explicit naming is the first way. Specify this with an autoType setting of TYPE_USERSPECIFIED (an integer constant).

The other five ways are variations of implicit naming:

• Implicit naming with only the request URI being used in the name

  Specify this with an autoType setting of TYPE_URI_ONLY.

• Implicit naming according to the following:

  Request URI + query string + selected cookies

  Specify this with an autoType setting of TYPE_URI_QUERYSTR. Specify the cookies in the selectedCookies[] attribute.

• Implicit naming according to the following:

  Request URI + all parameters + selected cookies (default)

  Specify this with an autoType setting of TYPE_URI_ALLPARAM. Specify the cookies in the selectedCookies[] attribute.

• Implicit naming according to the following:

  Request URI + selected parameters + selected cookies

  Specify this with an autoType setting of TYPE_URI_SELECTEDPARAM. Specify the parameters in the selectedParameters[] attribute and the cookies in the selectedCookies[] attribute.

• Implicit naming according to the following:

  Request URI + all but excluded parameters + selected cookies

  Specify this with an autoType setting of TYPE_URI_EXCLUDEDPARAM. Specify the cookies in the selectedCookies[] attribute and the excluded parameters in the selectedParameters[] attribute.

As an example, assume that you have developed a JSP page, welcome.jsp, with a personalized greeting for each user. The data with the personalized greeting is the only cache block in the page. Further assume that you have specified "request URI + selected parameters + selected cookies" naming, with user as the only selected parameter for cache block naming and no selected cookies for naming.

Now assume the page is requested as follows:

http://host:port/a.jsp?user=Amy

In this case, a.jsp?user=Amy becomes the cache block name.

Now assume that the page is later requested by another user, as follows:

http://host:port/a.jsp?user=Brian

This will not reuse the "Amy" cache, because the value of user is different. Instead, a new cache block is created with a.jsp?user=Brian as the name.

Now assume a later request by the first user, as follows:

http://host:port/a.jsp?mypar=3&user=Amy

Because the user is again Amy, this request will reuse the first cache, displaying Amy's customized information without having to regenerate it. The mypar parameter is irrelevant to the caching mechanism because it was not included in the selectedParameters[] list of the cache policy object, presumably because the value of mypar is not relevant in terms of cacheable page output.

Now assume the following subsequent request:

http://host:port/a.jsp?yourpar=4&user=Brian&hello=true&foo=barfly

Because the user is again Brian, this request will reuse the second cache, displaying Brian's customized information without having to regenerate it. The yourpar, hello, and foo parameters are irrelevant to the caching mechanism because they were not included in the selectedParameters[] list of the cache policy object.

More About reusableTimeStamp and reusableDeltaTime

Be aware that the concept of reusable is different than the concept of time-to-live (TTL) and is intended for more advanced use. Time-to-live, which controls the general lifetime of a cache, is described in "Expiration Policy Attributes" below. Usually time-to-live is all that is required to appropriately limit the use of cached data.

The attributes for reusability—reusableTimeStamp and reusableDeltaTime—are intended for more specialized use and do not affect the expiration or invalidation of cached data. As an example, consider a situation where different users have different requirements for how up-to-date a Web report is. Assume that most users can accept a report produced anytime within the past day, and that they all want to be looking at the same version so they can compare figures. An appropriate TTL value, then, would be "one day".

Also presume, however, that there is a small group of privileged users for whom the data is much more time-sensitive. They want to have information that is no more than one hour old.

In this case, although TTL is set to "one day" for all users, there can be a reusableDeltaTime setting of "one hour" for the privileged users, which will result in the cache not being used for them if the data is more than one hour old. Remember, though, that reusableTimeStamp and reusableDeltaTime do not expire the cache or otherwise affect it. The cached data can still be used for non-privileged users, according to the time-to-live.

It is up to the application logic to set appropriate values of reusableTimeStamp and reusableDeltaTime for the privileged user group.

Web Object Cache cache Tag

This section documents the syntax and attributes of the cache tag, which you can use to set up general caching in a JSP application, in contrast to the caching of XML objects or Java serializable object.

<ojsp:cache
   [ policy = "filename" ]
   [ ignoreCache = "true" | "false" ]
   [ invalidateCache = "true" | "false" ]
   [ scope = "application" | "session" ]
   [ autoType = "user" | "URI" | "URI_query" | "URI_allParam" |
                 "URI_selectedParam" | "URI_excludedParam" ]
   [ selectedParam = "space-delimited_string_of_parameter_names" ]
   [ selectedCookies = "space-delimited_string_of_cookie_names" ]
   [ reusableTimeStamp = "yyyy.mm.dd hh:mm:ss z" |
                         "yyyy.mm.dd hh:mm:ss" | "yyyy.mm.dd"| "ignored" ]
   [ reusableDeltaTime = "number" | "ignored" ]
   [ name = "blockname" ]
   [ expirationType = "TTL" | "daily" | "weekly" | "monthly" ]
   [ TTL = "number" ]
   [ timeInaDay = "number" ]
   [ dayInaWeek = "Sunday" | "Monday" | "Tuesday" | "Wednesday" |
                  "Thursday" | "Friday" | "Saturday" ]
   [ dayInaMonth = "number" ]
   [ writeThrough = "true" | "false" ]
   [ printCacheBlockInfo = "true" | "false" ]
   [ printCachePolicy = "true" | "false" ]
   [ cacheRepositoryName = "name" ]
   [ reportException = "true" | "false" ] >

...Code for cache block...

</ojsp:cache>

<%@ taglib uri="http://xmlns.oracle.com/j2ee/jsp/tld/ojsp/jwcache.tld"
           prefix="ojsp" %>
<title>listitem.jsp</title>
<%
   String itemid=request.getParameter("itemid");
   if (itemid==null) {
     out.println("Please select a category from the above drop down box.");
     return;
   }
%>
<% long l1=(new java.util.Date()).getTime(); %>
<ojsp:cache autoType="URI_selectedParam" selectedParam="itemid" 
  printCacheBlockInfo="true" printCachePolicy="true"
  policy="/WEB-INF/test-policy.cpd" 
>
   Item List: <b><%= itemid %></b><br>
   Time: <%= new java.util.Date() %>
   <br>
   <jsp:useBean class="java.util.Hashtable" id="table" scope="application" />
   <hr>
   <%
     Vector list=(Vector) table.get(itemid);
     if (list==null) {
       out.println("No such item!");
     }
     else {
       for (int i=0; i<list.size(); i++) {
   %>
   <%= list.elementAt(i) %><br>
   <%    
       }
     }
   %>
   timestamp:<%= new java.util.Date() %>
   <br>
</ojsp:cache>
<% long l2=(new java.util.Date()).getTime(); %>
Time for general cache operation:<%= l2-l1 %>
<br>

Web Object Cache cacheXMLObj Tag

Generally speaking, use the cacheXMLObj tag instead of the cache tag if you are caching XML DOM objects.

The cacheXMLObj tag supports all the cache tag attributes described in "Web Object Cache cache Tag", as well as the attributes described here.

<ojsp:cacheXMLObj
   ...
   [ fromXMLObjName = "objectname" ]
   [ toXMLObjName = "objectname" ]
   [ toWriter = "true" | "false" ] >

[...Code for cache block...]

</ojsp:cacheXMLObj>

<ojsp:cacheXMLObj ... fromXMLObjName="..." ... />

<jesi:template cache="no">
<% String userStyleLoc="style/rowset.xsl"; %>
<h3>Transform DBQuery Tag Example</h3>
<h4>Current Time=<%= new java.util.Date() %></h4>
   <jesi:fragment expiration="60"> 
   <!-- You can cache HTML in OracleAS Web Cache with JESI
     or you can cache it in Oracle Web Object Cache -->
   <h4>Cached Time=<%= new java.util.Date() %></h4>
   <sql:dbOpen connId="conn1" dataSource="<%= dataSrcStr %>" />
   <xml:transform href="<%= userStyleLoc %>" > 
   <%-- The XML DOM object is produced by dbQuery
     And, the DOM object is cached in Oracle Web Object Cache.
     XSLT is performed on the cached object. --%>
     <ojsp:cacheXMLObj TTL="60" toWriter="false">
       <sql:dbQuery connId="conn1" output="xml" queryId="myquery" >
          select ENAME, EMPNO from EMP 
       </sql:dbQuery>
     </ojsp:cacheXMLObj>
   </xml:transform> 
   <sql:dbCloseQuery queryId="myquery" />
   <sql:dbClose connId="con1" />
   </jesi:fragment>
</jesi:template>

Web Object Cache useCacheObj Tag

Use the useCacheObj tag to cache any Java serializable object.

The useCacheObj tag supports all the cache tag attributes described in "Web Object Cache cache Tag", as well as the attributes described here.

<ojsp:useCacheObj
   ...
     type="classname"
     id = "instancename" 
   [ cacheScope = "application" | "session" ] >

...Code for cache block...

</ojsp:useCacheObj>

<ojsp:useCacheObj id="a2" policy="/WEB-INF/test-policy.cpd" 
  type="examples.RStrArray" >
<%
   // create a temp writeable array 
   WStrArray tmpa2=new WStrArray(3);
   tmpa2.setStr(2,request.getParameter("testing4"));
   tmpa2.setStr(1,"def");
   tmpa2.setStr(0, (new java.util.Date()).toString() );
   // create a readonly copy for the cache
   a2=new RStrArray(tmpa2);  
   // storing the a2 into pagecontext
   // so useCacheObj tag can pick it up
   pageContext.setAttribute("a2",a2);
%>
</ojsp:useCacheObj>

Conditional Execution of Code Inside the Cache Tags

Be aware that code inside a cache tag (cache, cacheXMLObj, or useCacheObj) is executed conditionally. In particular:

• Any code inside a cache tag is executed only when the associated cache block is not reused.

  Consider the following example:

  <% String str=null; %>
  <% ojsp:useCacheObj ... >
     <% str = "abc"; //...more Java code...%>
  </ojsp:useCacheObj>
  <% out.print(str.length()); // May cause null pointer exception
  
  

  If the cache is available and reused, the code to properly initialize the string str is not executed.

• If you put a method-based variable declaration inside a cache tag, the variable is not available outside the tag.

  Consider the following example:

  <ojsp:useCacheObj ... >
     <% String str = "abc"; //...more Java code...%>
  </ojsp:useCacheObj>
  <% // String str will not be available here %>
  
  

If you are using the cache tag (not cacheXMLObj or useCacheObj), it might be helpful to break your cache blocks into separate JSP pages so that you would be less likely to fall into this type of situation. In this case, each cache block would be represented by its own URI and you could use dynamic-include functionality to combine the pages together as desired.

To make this more convenient, Oracle also provides the cacheInclude tag, described in the following section, "Web Object Cache cacheInclude Tag".

Web Object Cache cacheInclude Tag

The cacheInclude tag combines functionality of the cache tag (but not the cacheXMLObj tag or useCacheObj tag) and the standard jsp:include tag.

There are a number of advantages in putting cache blocks into separate pages and using cacheInclude, including general considerations of modularity and clarity as well as the issues discussed in the preceding section, "Conditional Execution of Code Inside the Cache Tags".

Be aware of the following limitations, however:

• You cannot use a runtime JSP expression in the cacheInclude tag.

• You must use implicit cache-block naming for the cache block.

• There is no flush parameter, unlike for the jsp:include tag.

If any of these limitations presents a problem, then use separate cache and jsp:include tags.

Also be aware of an important difference between the cacheInclude tag and the JESI include tag. (See "JESI include Tag" for information about that tag.) Because the OracleAS Web Cache is in a different caching layer than the Web Object Cache, the including page and included page for a JESI include tag cannot share the same request object. There is no such limitation with the cacheInclude tag, however. The including page and included page share the same request object, so beans and attributes of request scope can be passed between the two pages.

<ojsp:cacheInclude
     policy = "filename"
     page = "URI"
   [ printCacheBlockInfo = "true" | "false" ] 
   [ reportException = "true" | "false" ] >

...Code for cache block...

</ojsp:cacheInclude>

<ojsp:cacheInclude page="anotherPage.jsp" policy="foo.cpd" >

<ojsp:cache policy="foo.cpd" >
   <% pageContext.include("anotherPage.jsp"); %>
</ojsp:cache>

<jsp:include page="anotherPage.jsp" flush="true" />

<ojsp:cache policy="foo.cpd" >
...anotherPage.jsp contents...
</ojsp:cache>

Web Object Cache invalidateCache Tag

To explicitly invalidate a cache block through program logic, you can use the invalidateCache tag. This section documents the syntax and attributes of this tag.

<ojsp:invalidateCache
   [ policy = "filename" ]
   [ ignoreCache = "true" | "false" ]
   [ scope = "application" | "session" ]
   [ autoType = "user" | "URI" | "URI_query" | "URI_allParam" |
                "URI_selectedParam" | "URI_excludedParam" ]
   [ selectedParam = "space-delimited_string_of_parameter_names" ]
   [ selectedCookies = "space-delimited_string_of_cookie_names" ]
   [ name = "blockname" ]
   [ invalidateNameLike = "true" | "false" ]
   [ page = "URI" ]
   [ autoInvalidateLevel = "application" | "page" | "param" | "cookie" ] 
   [ cacheRepositoryName = "name" ]
   [ reportException = "true" | "false" ] />

Example: Use of Cache Invalidation Tag

This section provides a brief example of cache invalidation.

<%@ taglib uri="http://xmlns.oracle.com/j2ee/jsp/tld/ojsp/jwcache.tld"
           prefix="ojsp" %>
<title>added.jsp</title>
<jsp:useBean class="java.util.Hashtable" id="table" scope="application" />
<%
   String itemid=request.getParameter("itemid");
   String addItem=request.getParameter("addItem");
   Vector list=(Vector) table.get(itemid);
   if (list==null) {
     list=new Vector();
     table.put(itemid,list);
   }
   list.addElement(addItem);
%>
<b><%= addItem %></b> was added into category <b><%= itemid %></b>.<br>
<% String viewPage="listitem.jsp?itemid="+itemid; %>
<% long l1=(new java.util.Date()).getTime(); %>
<ojsp:invalidateCache page="<%= viewPage %>" autoInvalidateLevel="param" 
  policy="/WEB-INF/test-policy.cpd"
    />
<% long l2=(new java.util.Date()).getTime(); %>
Existing cache entry has been invalidated. <br>
Invalidation took <%= l2-l1 %> milliseconds.
<br>
<jsp:include page="<%= viewPage %>" flush="true" />
<br>
<a href="seeitems.jsp" >Select items</a>
or
<a href="additem.html" >Add items</a>
<br>

Using the lookupPolicy() Method

In most situations, the most convenient way to create a CachePolicy object is through the static lookupPolicy() method of the CacheClientUtil class, as in the following example:

CachePolicy cachePolicyObject = oracle.jsp.jwcache.CacheClientUtil.lookupPolicy
                                (servletConfig, request, "/WEB-INF/foo.cpd");

Input a servlet configuration object (a javax.servlet.ServletConfig instance), a request object (a javax.servlet.http.HttpServletRequest instance), and the URI path, relative to the application root, of an XML cache policy descriptor file.

Here is a simple example of a cache policy descriptor file:

<!-- 
test-policy.cpd 
-->

<cachePolicy scope="application">
   <expirationPolicy expirationType="TTL" TTL="25" timeInaDay="00:10:00" 
                     writeThrough="true" />
</cachePolicy>

See "Cache Policy Descriptor" for more information.

Using a CachePolicy Constructor

The CachePolicy class has three public constructors: a simple constructor requiring only a servlet configuration object, a "copy" constructor that copies another CachePolicy object, and a "copy" constructor with a given servlet configuration object, as follows:

public CachePolicy(javax.servlet.ServletConfig config)

public CachePolicy(CachePolicy cPolicy)

public CachePolicy(javax.servlet.ServletConfig config,
                   CachePolicy cPolicy)

CachePolicy Method Signatures and Common Parameters

The following abbreviated code, for illustration purposes only, contains signatures for key methods available in CachePolicy objects.

See "Cache Policy Attributes" for a discussion of relevant attributes.

class CachePolicy 
{
   boolean isRecent(CacheBlock block);
   void putCache(Object data, HttpServletRequest req, SectionId sectionId);
   void putCache(Object data, HttpServletRequest req, String specifiedName);
   void putAutoCacheForOtherPath(Object data, HttpServletRequest req,
                       String otherPath, StringSectionid sectionId);
   void putAutoCacheForOtherPath(Object data, HttpServletRequest req,
        String otherPath, Cookie[] newCookies, StringSectionid sectionId);
   CacheBlock getCache(HttpServletRequest req, SectionId sectionId);
   CacheBlock getCache(HttpServletRequest req, String specifiedName);
   CacheBlock getAutoCacheForOtherPath(HttpServletRequest req, 
                         String otherPath, StringSectionId sectionId);
   CacheBlock getAutoCacheForOtherPath(HttpServletRequest req, 
        String otherPath, Cookie[] newCookies, StringSectionId sectionId);
   void invalidateCache(HttpServletRequest req, SectionId sectionId);
   void invalidateCache(HttpServletRequest req, String specifiedName);
   void invalidateCacheLike(HttpServletRequest req, String specifiedName);
   void invalidateCacheLike(HttpServletRequest req, int autoInvalidateLevel);
   void invalidateCacheLike(HttpServletRequest req, String specifiedName,
                           int autoInvalidateLevel);
   void invalidateCacheOtherPathLike(HttpServletRequest req, String otherPath);
   void invalidateCacheOtherPathLike(HttpServletRequest req, String otherPath,
                         Cookie[] newCookies, int autoInvalidateLevel);
   Date getCurrentTime();
}

These methods use several common parameters:

• req, a javax.servlet.http.HttpServletRequest instance

  This is the current HTTP request object.

• newCookies, a javax.servlet.http.Cookie[] array

  This is an array of new cookies. If you pass in new cookies, they are used in cache operations that use the otherPath parameter (such as the putAutoCacheForOtherPath() method), assuming the cache policy selects some cookies and invalidation is at the cookie level. If you do not pass in new cookies, then cookies of the current HTTP request are used instead.

• specifiedName, a Java string

  For explicit cache-block naming, this is the name—either the desired cache block name if you are creating a new cache block, or the existing cache block name if you are retrieving an existing cache block.

• sectionId, an oracle.jsp.jwcache.SectionId instance, specifically a StringSectionId or NumberSectionId instance

  For implicit cache-block naming, this is a counter that is used in tracking cache blocks. In JSP pages, it is used, incremented, and maintained by JSP cache tag handlers. It is stored in the JSP pageContext object.

  SectionId is an interface that is implemented by two classes: StringSectionId and NumberSectionId. Where StringSectionId is specified in a method signature, you must use an instance of that class. Where SectionId is specified, you can use an instance of either class, but should typically use StringSectionId. The NumberSectionId class is primarily intended for use by JSP tag handlers.

  In a servlet, you must create a section ID instance manually. "Servlet Page: DemoCacheServlet.java" demonstrates the use of a StringSectionId instance.

  
  

  Note: When you construct a StringSectionId instance, the string must begin with an alphabetic (not numeric) character.

  
  

• otherPath, a Java string

  This is the URI of another JSP page that has an associated cache block that you want to store, retrieve, or invalidate.

• autoInvalidateLevel, an integer

  For implicit cache-block naming, you can use this to specify a level of invalidation, either application, page, parameter, or cookie. Use the CachePolicy integer constant AUTO_INVALIDATE_APP_LEVEL, AUTO_INVALIDATE_PAGE_LEVEL, AUTO_INVALIDATE_PARAM_LEVEL, or AUTO_INVALIDATE_COOKIE_LEVEL.

CachePolicy Method Descriptions

The CachePolicy methods function as follows:

• isRecent()

  This method checks the timestamp of the specified cache block and determines whether it is recent enough, given the current time and the values of the cache policy reusableTimeStamp and reusableDeltaTime attributes.

• putCache(data)

  Use this method to place an object into the cache repository. The data parameter is any serializable Java object you want to cache that will not require any further modification or mutation. In JSP pages, the JSP cache tag handler calls putCache() to cache a BodyContent instance. The cacheXMLObj tag handler calls it to cache an XML DOM object. In a servlet or useCacheObj tag, the cache target object can be any Java serializable object.

  You must also provide an HTTP request object, along with a cache block name (for explicit naming) or a section ID (for implicit naming).

  
  

  Note: The putCache() method does nothing if the cache policy ignoreCache attribute is set to "true".

  
  

• putAutoCacheForOtherPath(...)

  Place the specified object into the cache repository according to a specified string-based section ID and a specified page path, optionally using specified cookies as well. You must also input an HttpServletRequest object. The cache policy must not use explicit naming (in other words, must not have autoType=TYPE_USERSPECIFIED).

• getCache(...)

  Use this method to retrieve a cached item from the repository, in the form of a CacheBlock instance. You can specify the cache block name (for explicit naming) or the section ID (for implicit naming). You must also provide an HTTP request object.

  
  

  Note: The getCache() method does nothing if the cache policy ignoreCache attribute is true.

  
  

• getAutoCacheForOtherPath(...)

  Retrieve a cached item from the repository according to a specified string-based section ID and a specified page path, optionally using specified cookies as well. You must also input an HttpServletRequest object. The cache policy must not use explicit naming, otherwise an exception is thrown. (In other words, you cannot have autoType=TYPE_USERSPECIFIED.)

• invalidateCache(...)

  Use this method to invalidate a single cache block. Invalidation is according to the HTTP request object and also according to the specified cache block name (for explicit naming) or section ID (for implicit naming).

• invalidateCacheLike(...)

  Use this method to invalidate multiple cache blocks. If you use explicit cache-block naming and the cache repository supports wild-card naming, you can input the specifiedName parameter with "*" wild card characters. The Oracle Application Server Java Object Cache currently does not support wild card characters.

  If you use implicit cache-block naming, you must specify the autoInvalidateLevel parameter to determine, in combination with the HttpServletRequest object and optionally the specifiedName parameter, what cache blocks are invalidated. The autoInvalidateLevel parameter has the same functionality as in a JSP invalidateCache tag, as explained in "Web Object Cache invalidateCache Tag" (using information from the request object, instead of using information from the page parameter of the invalidateCache tag).

• invalidateCacheOtherPathLike(...)

  Use this method to invalidate cache blocks associated with the URI you provide in the otherPath parameter. In the signature taking only a request object and the URI, the autoInvalidateLevel parameter is set automatically according to the URI. It is set to param level if there is a question mark ("?") in the URI or to page level otherwise.

  The detailed signature of this method enables you to specifically control the autoInvalidateLevel setting and the cookies used in invalidation.

• getCurrentTime()

  Retrieve the current time value, as a java.util.Date instance, of the underlying cache repository specified in this cache policy.

CachePolicy Getter and Setter Methods

You can use the following methods to retrieve or alter CachePolicy object attributes. See "Cache Policy Attributes" for a discussion of these attributes.

• boolean getIgnoreCache()

• void setIgnoreCache(boolean ignoreCache)

• void setIgnoreCache(String ignoreCacheStr)

• int getScope()

• void setScope(int scope)

  For scope values, use the integer constants SCOPE_APP and SCOPE_SESSION.

• int getAutoType()

• void setAutoType(int autoType)

  For autoType values, use the integer constants TYPE_USERSPECIFIED, TYPE_URI_ONLY, TYPE_URI_QUERYSTR, TYPE_URI_ALLPARAM, TYPE_URI_SELECTEDPARAM, and TYPE_URI_EXCLUDEDPARAM.

• String[] getSelectedParam()

• void setSelectedParam(String[] selectedParameters)

• void setSelectedParam(String selectedParamStr)

• String[] getSelectedCookies()

• void setSelectedCookies(String[] selectedCookies)

• void setSelectedCookies(String selectedCookiesStr)

• Date getReusableTimeStamp()

• void setReusableTimeStamp(Date reusableTimeStamp)

• void setReusableTimeStamp(long reusableTimeStamp)

  For reusableTimeStamp values, the integer constant REUSABLE_ALWAYS indicates that the cache is always reusable.

• long getReusableDeltaTime()

• void setReusableDeltaTime(long reusableDeltaTime)

  For reusableDeltaTime values, the integer constant REUSABLE_ALWAYS indicates that the cache is always reusable.

• ExpirationPolicy getExpirationPolicy()

• void setExpirationPolicy(ExpirationPolicy expirationPolicy)

• String getCacheRepositoryName()

• void setCacheRepositoryName(String repoName)

• boolean getReportException()

• void setReportException(boolean reportException)

• void setReportException(String reportExceptionStr)

The following methods are also available, but are primarily intended for use by the Web Object Cache tag handlers:

• void setScope(String scopeStr)

  For scope values, there are the string constants SCOPE_APP_STR and SCOPE_SESSION_STR.

• void setAutoType(String autoTypeStr)

• void setReusableTimeStamp(String reusableTimeStampStr)

  For reusableTimeStamp values, the string constant REUSABLE_IGNORED indicates that the cache is always reusable.

• void setReusableDeltaTime(String reusableDeltaTimeStr)

  For reusableDeltaTime values, the string constant REUSABLE_IGNORED indicates that the cache is always reusable.

Simple JSP Page: tagcode.jsp

<%@ taglib uri="http://xmlns.oracle.com/j2ee/jsp/tld/ojsp/jwcache.tld"
           prefix="ojsp" %>
<title>tagcode.jsp</title>
<pre>
tagcode.jsp
<ojsp:cache policy="/WEB-INF/test-policy.cpd" >
  fragment#1  (expires in 25 seconds based on TTL value test-policy)
  <%= new java.util.Date() %>
</ojsp:cache>
<ojsp:cache policy="/WEB-INF/test-policy.cpd" TTL="15" >
  fragment#2 (expires in 15 seconds because TTL overrides test-policy value)
  <%= new java.util.Date() %>
</ojsp:cache>
</pre>

Scriptlet JSP Page: servletcode.jsp

Code notes are the same as for the servlet version in the next section, "Servlet Page: DemoCacheServlet.java".

<%@ page import="oracle.jsp.jwcache.*,java.io.*" %>
<title>servletcode.jsp</title>
<pre>
servletcode.jsp
<%
  CachePolicy cachePolicyObj = CacheClientUtil.lookupPolicy(config,request,
                              "/WEB-INF/test-policy.cpd" );  // Note A
  StringSectionId sectionId=new StringSectionId("s1");   // Note B
  CacheBlock cacheBlockObj=null;
  
  cacheBlockObj = cachePolicyObj.getCache(request,sectionId); // Note C
  if (!cachePolicyObj.isRecent(cacheBlockObj)) {  // Note D
    CharArrayWriter newOut=new CharArrayWriter();    
    PrintWriter pw=new PrintWriter(newOut);

    // actual logic within a cache block 
    pw.println
          ("fragment#1 (expires in 25 seconds based on TTL value test-policy)");
    pw.println(new java.util.Date());
    // which generates content into the "out" object

    if (cacheBlockObj == null) {   // Note E
      cachePolicyObj.putCache(newOut.toCharArray(),request,sectionId);  
      // Note F
    }
    
    out.write(newOut.toCharArray());
    // writing out newly created data back to the original writer
  }
  else {
    out.write((char[])cacheBlockObj.getData());
    // writing the existing cached data to the writer
  }

  sectionId=new StringSectionId("s2");
  long timeToLive = 15;   // now set TTL to 15 on this block
  ExpirationPolicy expirationPolicy = cachePolicyObj.getExpirationPolicy();
  expirationPolicy.setTTL(timeToLive);
  cachePolicyObj.setExpirationPolicy(expirationPolicy);
  cacheBlockObj = cachePolicyObj.getCache(request,sectionId); 
  if (!cachePolicyObj.isRecent(cacheBlockObj)) { 
    CharArrayWriter newOut=new CharArrayWriter();    
    PrintWriter pw=new PrintWriter(newOut);

    // actual logic within a cache block 
    pw.println
 ("fragment#2 (expires in 15 seconds because TTL overrides test-policy value)");
    pw.println(new java.util.Date());
    // which generates content into the "out" object

    if (cacheBlockObj == null) {  
      cachePolicyObj.putCache(newOut.toCharArray(),request,sectionId);
    }
    
    out.write(newOut.toCharArray());
    // writing out newly created data back to the original writer
  }
  else {
    out.write((char[])cacheBlockObj.getData());  
    // writing the existing cached data to the writer
  }

%>
</pre>

Servlet Page: DemoCacheServlet.java

Code notes are explained at the end of the code.

package demoPkg;

import javax.servlet.*;
import javax.servlet.http.*;
import java.io.IOException;

import java.io.PrintWriter;
import java.io.CharArrayWriter;

import oracle.jsp.jwcache.CachePolicy;
import oracle.jsp.jwcache.ExpirationPolicy;
import oracle.jsp.jwcache.StringSectionId;
import oracle.jsp.jwcache.CacheBlock;
import oracle.jsp.jwcache.CacheClientUtil;

public class DemoCacheServlet extends HttpServlet{

  public void service(HttpServletRequest request, HttpServletResponse response) 
    throws ServletException, IOException
  {
    // standard writer object from servlet engine
    PrintWriter out=response.getWriter();
    ServletConfig config=getServletConfig();

    try {
      CachePolicy cachePolicyObj = CacheClientUtil.lookupPolicy(config,request,
        "/WEB-INF/test-policy.cpd" );  // Note A
      StringSectionId sectionId=new StringSectionId("s1");   // Note B
      CacheBlock cacheBlockObj=null;

      cacheBlockObj = cachePolicyObj.getCache(request,sectionId); // Note C
      if (!cachePolicyObj.isRecent(cacheBlockObj)) {  // Note D
        CharArrayWriter newOut=new CharArrayWriter();    
        PrintWriter pw=new PrintWriter(newOut);
        
        // actual logic within a cache block 
        pw.println("fragment#1");
        pw.println(new java.util.Date());
        // which generates content into the "out" object
        
        if (cacheBlockObj == null) {   // Note E
          cachePolicyObj.putCache(newOut.toCharArray(),request,sectionId);  
          // Note F
        }
        
        out.write(newOut.toCharArray());
        // writing out newly created data back to the original writer
      }
      else {
        out.write((char[])cacheBlockObj.getData());  
        // writing the existing cached data to the writer
      }

      sectionId=new StringSectionId("s2");
      long timeToLive = 15;   // now set TTL to 15 on this block
      ExpirationPolicy expirationPolicy = cachePolicyObj.getExpirationPolicy();
      expirationPolicy.setTTL(timeToLive);
      cachePolicyObj.setExpirationPolicy(expirationPolicy);
      cacheBlockObj = cachePolicyObj.getCache(request,sectionId);
      if (!cachePolicyObj.isRecent(cacheBlockObj)) { 
        CharArrayWriter newOut=new CharArrayWriter();    
        PrintWriter pw=new PrintWriter(newOut);
        
        // actual logic within a cache block 
        pw.println("fragment#2");
        pw.println(new java.util.Date());
        // which generates content into the "out" object
        
        if (cacheBlockObj == null) { 
          cachePolicyObj.putCache(newOut.toCharArray(),request,sectionId);
        }
        
        out.write(newOut.toCharArray());
        // writing out newly created data back to the original writer
      }
      else {
        out.write((char[])cacheBlockObj.getData());  
        // writing the existing cached data to the writer
      }

    } catch (Throwable th) {
      // your exception handling code here
      th.printStackTrace(out);
    }
  }
}

Cache Policy Descriptor: test-policy.cpd

This cache policy descriptor is used by all three approaches to the sample application: tagcode.jsp, servletcode.jsp, and DemoCacheServlet.java:

<!-- 
test-policy.cpd 
-->

<cachePolicy scope="application">
   <expirationPolicy expirationType="TTL" TTL="25" timeInaDay="00:10:00" 
                     writeThrough="true" />
</cachePolicy>