Source

oscache / docs / faq.html

<html>
<head>
<title>OSCache FAQ</title>
</head>

<body bgcolor="#FFFFFF">
<p><i>Got a question you'd like to ask? <a href="&#109;a&#105;&#108;&#116;&#111;:chris&#64;swebtec.&#99;&#111;&#109;">
Ask us</a> and we'll add it to the FAQ.</i></p>

<p><b>Questions</b></p>
<ul>
  <li><a href="#use">What can I use OSCache for exactly?</a></li>
  <li><a href="#where">Where is the data cached?</a></li>
  <li><a href="#objects">Can OSCache cache Java objects rather than portions
     of JSP pages? I mean if I create a Product object, can I cache it and use it later
     so that I don't have to fetch data again?</a></li>
  <li><a href="#features">What other features does OSCache have?</a></li>
  <li><a href="#examples">Can you give me some examples of how the OSCache
     tags are used?</a></li>
  <li><a href="#nested">Can OSCache tags be nested?</a></li>
  <li><a href="#size">What control do you have over the cache size? I can imagine
     the size of the in-memory cache getting very big. Is it possible to set a max cache
     size and then remove the least-recently-used entries from the cache?</a></li>
  <li><a href="#remove">How does OSCache decide which object to remove? What caching
     algorithm does OSCache use?</a></li>
  <li><a href="#clustering">How does OSCache's clustering work?</a></li>
  <li><a href="#expire">What happens if I need to expire data in the cache?</a></li>
  <li><a href="#group">Can you tell me more about grouping cache entries? How might this be
     used?</a></li>
  <li><a href="#api">I don't want to use the taglibs, I want to access OSCache directly
     from within my application. Where do I start?</a></li>
</ul>

<ul>
  <li><a href="#help">Where else can I go for help if I can't find an answer to my question here?</a></li>
</ul>

<p>&nbsp;</p>
<p><a name="use"></a><b>What can I use OSCache for exactly?</b></p>

<p>OSCache can be used on three different levels:
<ul>
  <li><b>JSP Caching</b> - The first and simplest approach is to use the supplied
    taglibs to cache portions of JSP pages after the page has been rendered. This
    sounds simple but it's remarkably powerful and useful for almost every JSP
    application.</li>
  <li><b>Request Caching</b> - OSCache comes with a filter that allows you to cache
    entire HTTP responses - including dynamically generated images!</li>
  <li><b>General-Purpose Cache</b> - You can also use OSCache as a general-purpose
    caching solution by calling its API directly from your code. This allows arbitrary
    Java objects to be cached, and provides more control over the cache's behaviour.
    Note that <em>any</em> Java application can use OSCache in this manner; there is
    no requirement for a web server to be present when calling the API directly.</li>
</ul></p>

<p>All three approaches can be mixed and matched within the same application.</p>

<br>
<p><a name="where"></a><b>Where is the data cached?</b></p>

<p>Out of the box, OSCache is capable of caching data in memory (so it is very
fast), and/or to disk (so your cache can be persistent across server restarts).
Support is also provided for managing a cluster of caches across multiple
servers.</p>
<p>In addition to these capabilities, it is possible to plug in custom
persistence code and custom event handlers, so you could easily extend OSCache
to persist cached objects to say a database or an LDAP directory.</p>

<br>
<p><a name="objects"></a><b>Can OSCache cache Java objects rather than portions of JSP pages? I mean
if I create a Product object, can I cache it and use it later so that I don't
have to fetch data again?</b></p>

<p>Yes, however to do this you will need to write code that talks to the
OSCache API directly. The taglibs are currently only designed to cache
rendered JSP content. This should hopefully not be too big a limitation since
any creation or manipulation of java objects should generally be performed in
beans or MVC action classes rather than JSP scriptlets anyway.</p>

<br>
<p><a name="features"></a><b>What other features does OSCache have?</b></p>

<p>There is a full list of features in the <a href="features.html">Features</a>
documentation.</p>

<br>
<p><a name="examples"></a><b>Can you give me some examples of how the OSCache tags are used?</b></p>
  <i>Example 1:</i></p>
<blockquote><tt><code> &lt;cache:cache time=&quot;600&quot;&gt;<br>
  &nbsp; &nbsp; &lt;%= myBean.getTitle() %&gt;<br>
  &lt;/cache:cache&gt; </code></tt></blockquote>
<p> This will only access your EJB once every 10 minutes. Every other request
  it will just serve the cached JSP content that was produced the first time (this
  results in much faster page loading). </p>
<p><i>Example 2:</i><br>
</p>
<blockquote><tt><code> &lt;cache:cache key=&quot;foobar&quot; scope=&quot;session&quot;&gt;<br>
  &nbsp; &nbsp; &lt;%= myBean.getTitle() %&gt;<br>
  &lt;/cache:cache&gt; </code></tt></blockquote>
<p>This time the cache is keyed (you could have a programmatic key here too, like
  &lt;%= foobarString %&gt;) and it's scoped by session. </p>
<p>This is revolutionary as far as caching goes. You can now have cached content,
  that's different for every user! No more full page caches with no dynamic content!</p>
<p><i>Example 3 (a very powerful &amp; useful way to use the taglibs):</i></p>
<blockquote><tt><code> &lt;cache:cache&gt;<br>
  &nbsp; &nbsp; &lt;% try { %&gt;<br>
  &nbsp; &nbsp; &nbsp; &nbsp; &lt;%= myBean.getTitle() %&gt;><br>
  &nbsp; &nbsp; &lt;% } catch (Exception e) { %&gt;<br>
  &nbsp; &nbsp; &nbsp; &nbsp; &lt;% application.log(&quot;Exception occurred in
  myBean.getTitle(): &quot; + e); %&gt;<br>
  &nbsp; &nbsp; &nbsp; &nbsp; &lt;cache:usecached /&gt;<br>
  &nbsp; &nbsp; &lt;% } %&gt;<br>
  &lt;/cache:cache&gt; </code></tt></blockquote>
<p>If a RemoteException occurs trying to get the EJB title (for example the database
  goes down) the cached content will be served so the user will not suspect a thing.
  No error page as per a normal JSP application. What does this mean? It means greater
  error tolerance in your JSP apps! </p>
<p>One example of where this is useful - when our machine restarts, our app server
  loads faster than the database server. No problem - because the cache is persistent,
  it serves cached content while the database boots, then seamlessly kicks in
  to the database for a cache refresh when the database is ready.</p>
<p>See the <a href="tags.html">Tag Reference</a> and the example web application for further
  taglib examples.</p>

<br>
<p><a name="nested"></a><b>Can OSCache tags be nested?</b></p>
<p>You can't currently nest &lt;cache&gt; tags within one another - not that
you'd probably want to. It is because of the cache object being placed in the
page scope for use by programmers within the tag.</p>

<p>We're not sure if anyone actually uses this so we might remove it to allow
for tag nesting (presumably across includes or something).</p>

<br>
<p><a name="size"></a><b>What control do you have over the cache size? I can imagine the size of
the in-memory cache getting very big. Is it possible to set a max cache size
and then remove the least-recently-used entries from the cache?</b></p>

<p>You can limit the memory cache by the number of objects that are cached.
When an object is added to the cache and the limit is exceeded, another
object will be removed from the cache to make room.</p>

<p>Currently the disk cache can either be set to unlimited, or tied to the same
size as the memory cache (ie, objects will be removed from the disk cache at
the same time as they are removed from the memory cache. Depending on the
useage patterns of your cache, restarting your application could mean that the
disk cache might continue to grow). We understand that this is not ideal and
there is room for improvement here. Stay tuned!</p>

<br>
<p><a name="remove"></a><b>How does OSCache decide which object to remove? What caching algorithm
does OSCache use?</b></p>

<p>The caching algorithm is configurable. OSCache currently ships with 3 different
algorithms - <b>LRU</b> (Least Recently Used), <b>FIFO</b> (First In First
Out), and <b>Unlimited</b>. Should one of those not prove suitable, it is also
possible to specify a custom algorithm class.</p>

<br>
<p><a name="clustering"></a><b>How does OSCache's clustering work?</b></p>

<p>The clustering is implemented as a listener that catches 'flush' events. These
events are then broadcast across the network (using either the
<a href="http://www.javagroups.com">JavaGroups</a> library or JMS) so that other nodes
in the cluster can flush the relevant object(s) from their local cache. Note that
for performance reasons, when objects are added to a cache they are <em>not</em>
broadcast to other nodes. This means that each node in the cluster maintains their
own relatively indedependent cache, yet still remains fresh.</p>

<p>If this mechanism does not suit your requirements, you can always code up a
different solution by writing a custom event handler.</p>

<br>
<p><a name="expire"></a><b>What happens if I need to expire data in the cache?</b></p>

<p>Cache entries can be flushed explicitly in several ways:
<ul>
<li>Individual entries can be flushed by specifying the cache key of the entry
to flush eg <code>&lt;cache:flush key=&quot;myKey&quot; scope=&quot;application&quot;/&gt;</code></li>
<li>When adding an entry to the cache, it can optionally be placed into one or
more groups. An entire group of entries can then be flushed by specifying the
name of the group to flush. eg <code>&lt;cache:flush group=&quot;group1&quot; scope=&quot;application&quot;/&gt;</code></li>
<li>A pattern can be specified; all keys that contain the supplied pattern will
be flushed. eg <code>&lt;cache:flush pattern=&quot;menu&quot; scope=&quot;application&quot;/&gt;</code> will
flush all keys that contain the string &quot;menu&quot;. (note that this approach
is now deprecated. The cache grouping is more flexible and performs better than
pattern flushing.)</li>
</ul>
In addition, cached data can be expired at retrieval time by specifying a maximum
age for the data, or by indicating what dates and/or times the data should expire.
See the <code>time</code>, <code>duration</code> and <code>cron</code> attributes
of the <a href="tags.html#cache">&lt;cache&gt;</a> tag for more information.</p>

<br>
<p><a name="group"></a><b>Can you tell me more about grouping cache entries? How might this be
used?</b></p>

<p>This is a powerful feature that makes it easy to manage your cache content.
Suppose you are rendering a website and the pages that you are caching depend
on various factors. Perhaps they use various shared templates, some database
content, and maybe some of them depend on an external data feed. By creating
a cache group for each of these factors, each cached page can be placed into
the group(s) that the page is dependent on. Then when say an external datafeed
is updated it is trivial to flush all pages that depend on that datafeed.</p>
<p>For example:</p>

inside displayProduct.jsp:

<blockquote><tt><code>...<br>
&lt;cache:cache key=&quot;myKey1&quot; groups=&quot;product100,datafeed&quot;&gt;<br>
  &nbsp; &nbsp; &lt;%= myProductBean.getProduct(100).getName() %&gt;<br>
  &nbsp; &nbsp; &lt;%= myDatafeedBean.getDataFeed().getTotal() %&gt;<br>
  &lt;/cache:cache&gt;<br>
...
</code></tt></blockquote>

inside updateDatafeed.jsp:

<blockquote><tt><code>...<br>
&lt;%= myDatafeedBean.refreshDatafeed() %&gt;<br><br>
&lt;%-- Flush all cache entries that depend on the datafeed --%&gt;<br>
&lt;cache:flush group=&quot;datafeed&quot; scope=&quot;application&quot;&gt;<br>
...
</code></tt></blockquote>

<br>
<p><a name="api"></a><b>I don't want to use the taglibs, I want to access OSCache directly from within
my application. Where do I start?</b></p>

<p>We'd suggest the best place to start would be to look at the <code>GeneralCacheAdministrator</code>
class. It provides a simple wrapper for a single cache instance and should give you all
the basic functionality you need. If you want to work with multiple caches or manipulate
your cache beyond what <code>GeneralCacheAdministrator</code> provides, consider either
writing your own administrator class using GeneralCacheAdministrator as a starting point,
or just create and use the Cache class directly. See the Javadocs for more information.</p>

<br>
<p><a name="help"></a><b>Where else can I go for help if I can't find an answer to my question here?</b></p>

<p>The best place to try is on the OSCache <a href="http://sourceforge.net/mail/?group_id=9890">mailing list</a>.
It reaches a wide audience and is your best chance of getting a fast response. Remember to search the archives
first to see if your question has already been answered.</p>

<br>
<p>
<i>Got a question you'd like to ask? <a href="&#109;a&#105;&#108;&#116;&#111;:chris&#64;swebtec.&#99;&#111;&#109;">Ask us</a>
and we'll add it to the FAQ.</i>
</body>

</html>