OSCache comes with a JSP tag library that controls all its major functions. The tags are listed below with descriptions, attributes and examples of use.
For instructions on installing OSCache in a web application, see the Installation Guide.
The tags are:
For all listed attributes, req means it that attribute is required and any value in [] is a default value. All attributes can accept runtime expressions.
From the title of the tag you can see whether or not the tag has a body.
Description:
This is the main tag of OSCache. The body of the tag will be cached according to the attributes specified. The first time a cache is used the body content is executed and cached.
Each subsequent time the tag is run, it will check to see if the cached content is stale. Content is considered stale due to one (or more) of the following being true:
- The cached body content has been in the cache for longer than the time specified by the time or duration attribute.
- The cron attribute matches a date/time that is more recent than the time the body content was originally cached.
- The scope the body content is cached in was flushed since the content was originally cached.
If the cached body content is stale, the tag will execute the body again and recache the new body content. Otherwise it will serve the cached content and the body will be skipped (resulting in a large speed increase).
Attributes:
com.opensymphony.oscache.web.WebEntryRefreshPolicy
. This allows you to
programmatically determine whether cached content should be exipired.Examples:
This will cache the JSP content using the current URI as a key (which means this must be the only cache tag on the page to work).
<cache:cache>
... some jsp content ...
</cache:cache>This will cache the content with a constant key in the user's session scope. Any page that uses this key will access one shared cache.
<cache:cache key="foobar" scope="session">
... some jsp content ...
</cache:cache>This will cache the content with a programmatic key (here a product ID) for 30 minutes. It will also refresh if the variable
needRefresh
is true.
<cache:cache key="<%= product.getId() %>" time="1800" refresh="<%= needRefresh %>">
... some jsp content ...
</cache:cache>This will cache the content with a programmatic key, expiring it every morning at 2am. It will also refresh if the variable
needRefresh
is true.
<cache:cache key="<%= product.getId() %>" cron="0 2 * * *" refresh="<%= needRefresh %>">
... some jsp content ...
</cache:cache>Suppose we had a dynamic list of categories that we pull from a database, and we also store currency exchange rates that get updated occasionally by calling a webservice. Suppose also that we have some content that displays information about both the categories and the current exchange rate values. The following example caches the body content and assigns it to two cache groups, "currencyData" and "categoryList". When the exchange rates or the category list is updated, the appropriate group can be flushed causing this content (along with any other content associated with that group) to be exipired and then rebuilt the next time the page is processed:
<cache:cache key="<%= product.getId() %>" time="-1" group="currencyData, categories">
... display category list ...
... display currency information ...
</cache:cache>
Description:
This tag is nested within a <cache> tag and tells its parent whether or not to use the cached version.
Attributes:
Example:
This is a good example of error tolerance. If an exception occurs, the cached version of this content will be output instead.
<cache:cache>
<% try { %>
... some jsp content ...
<% } catch (Exception e) { %>
<cache:usecached />
<% } %>
</cache:cache>
Description:
This tag is used to flush caches at runtime. It is especially useful because it can be coded into the administration section of your site so that admins can decide when to flush the caches.
Attributes:
Example:
This will flush the application scope.
<cache:flush scope="application" />
This will flush the cache entry with key "foobar" in the session scope.
<cache:flush scope="session" key="foobar" />
This will flush all cache entries in the "currencyData" group from the application scope.
<cache:flush scope="application" group="currencyData" />
Description:
This tag must be nested inside a <cache:cache/> tag. It allows groups to be dynamically added to a cached block. It is useful when the group(s) a cached block should belong to are unknown until the block is actually rendered. As each group is 'discovered', this tag can be used to add the group to the block's group list.
Attributes:
Example:
This will add the cache block with the key 'test1' to groups 'group1' and 'group2'.
<cache:cache key="test1">
<cache:addgroup group="group1" />
... some jsp content ...
<cache:addgroup group="group2" />
... some more jsp content ...
</cache:cache>