The <cache> element allows a JSP author to cache a block of JSP output.

When a fresh (i.e., not expired) object is found in the cache for the specified key, the body of the cache tag will not be evaluated. Instead, the string value of the cached object will be written to the JSP writer.

Objects (output fragments) are identified to the cache via a "key" value. When stored, a "key" must be associated with each object. This object may later be retrieved (or cleared) using the same key.

In addition to keys, JSP authors may also associated a "group" key with an object. This makes it possible to clear a group of objects without clearing each directly.

The cache tag may be used to access several independent caches, each identified by a name attribute. Each named cache is an independent entity. This allows for multiple cache configurations to be used in one environment, and also helps each cache manage itself more effectively, since each the number of objects in each cache will be smaller than in a single, unified cache.

Note that in the current implementation, each named cache is shared among all objects within the scope of the current ClassLoader.

<!ELEMENT cache ANY>
<!ATTLIST cache
          key CDATA #REQUIRED
          group CDATA #IMPLIED
          ttl CDATA #IMPLIED
          expiresAt CDATA #IMPLIED
          lastModified CDATA #IMPLIED
          mustRevalidate (true|false) 'false'
          name CDATA #IMPLIED
>

To persistently store a block of JSP output (i.e., to cache an object that never goes stale) simply use:

<my:cache key="some key"><%-- arbitrary jsp code --%></my:cache>

As a more specific example, to cache the output of another JSP, you could use:

<c:cache key="/mycontext/foo.jsp">
  <jsp:include page="/foo.jsp" flush="true"/>
<c:cache>

As described above, there are three ways to specify an expiration time for the cached document.

As a duration for the document to remain fresh:

<my:cache key="some key" ttl="3600000">
  <%-- this content will live for 3,600,000 milliseconds, or 1 hour --%>
</my:cache>

<my:cache key="some key" ttl="1h">
  <%-- this content will live for 3,600,000 milliseconds, or 1 hour --%>
</my:cache>

<my:cache key="some key" expiresAt="972489026344">
  <%-- this content will expire at Wed Oct 25 10:50:26 GMT-0500 2000 --%>
</my:cache>

<my:cache key="some key" lastModified="972485426344">
  <%-- this content was last modified at Wed Oct 25  09:50:26 GMT-0500 2000 --%>
</my:cache>

To force a cached object to be refreshed, set the mustRevalidate attribute to true:

<my:cache key="some key" ttl="3600000" mustRevalidate="true">
  <%-- --%>
</my:cache>

Note that all attributes of the cache tag are run-time expression values. This is especially useful for conditionally clearing the cache, and for caclulating keys based upon request and session attributes. For example:

<% String key = "foo.jsp?id=" + request.getParameter("id"); %>
<my:cache key="<%= key %>" ttl="3600000">
  <%-- content that depends upon id --%>
</my:cache>

As described above, it is possible to configure multiple named caches. The cache tag allows you to access different caches using the name attribute. For example:

<my:cache key="foo" ttl="3h" name="cache1">
  <%-- ... --%>
</my:cache>

and

<my:cache key="foo" ttl="3h" name="cache2">
  <%-- ... --%>
</my:cache>

Will store into and retrieve from different instances of the cache.

The name attribute is optional, its value defaults to "default" so that:

<my:cache key="foo" ttl="3h" name="default">
  <%-- ... --%>
</my:cache>

and

<my:cache key="foo" ttl="3h">
  <%-- ... --%>
</my:cache>

refer to the same cache.

The <clear-cache> element allows a JSP author to remove an object from a cache by key or by group, or to remove all objects from a cache.

<!ELEMENT clear-cache EMPTY>
<!ATTLIST clear-cache
          key CDATA #IMPLIED
          group CDATA #IMPLIED
          name CDATA #IMPLIED
>

<c:cache name="primary" key="/mycontext/foo.jsp" group="group1">
  <g:grab page="/foo.jsp"/>
<c:cache>

<c:cache name="primary" key="/mycontext/foo2.jsp" group="group1">
  <g:grab page="/foo2.jsp"/>
<c:cache>

<c:cache name="primary" key="/mycontext/foo3.jsp" group="group2">
  <g:grab page="/foo3.jsp"/>
<c:cache>

<c:clear-cache name="primary" key="/mycontext/foo3.jsp"/>

<c:clear-cache name="primary" group="group1"/>

<c:clear-cache name="primary"/>

Each named pool is configured via a JOCL document. JOCL provides an XML syntax for creating Java objects by invoking their constructors. Hence configuring each cache is a matter of invoking the appropriate Java constuctors using the JOCL syntax.

For example, this JOCL document:

<?xml version="1.0"?>
<cache-config xmlns="http://apache.org/xml/xmlns/jakarta/commons/jocl">
  <object class="org.apache.commons.cache.SimpleCache">
   <object class="org.apache.commons.cache.MemoryStash">
    <int value="10000"/>
   </object>
   <object class="org.apache.commons.cache.LRUEvictionPolicy">
    <int value="5"/>
    <long value="60000"/>
   </object>
   <object class="org.apache.commons.cache.StashPolicy" null="true"/>
   <object class="org.apache.commons.cache.GroupMapImpl"/>
   <object class="java.io.File" null="true"/>
  </object>
</cache-config>

is equivalent to invoking:

new org.apache.commons.cache.SimpleCache( new org.apache.commons.cache.MemoryStash(10000), new org.apache.commons.cache.LRUEvictionPolicy(5,60000L), (org.apache.commons.cache.StashPolicy)null, new org.apache.commons.cache.GroupMapImpl(), (java.io.File)null )

See org.apache.commons.jocl.JOCLContentHandler (in commons-dbcp), for documentation of the JOCL syntax. See the org.apache.commons.cache package, especially the SimpleCache class, for details on constructing/configuring the cache.