head	1.1;
access;
symbols;
locks; strict;
comment	@# @;


1.1
date	2001.05.23.22.18.36;	author leonardr;	state Exp;
branches;
next	;


desc
@@


1.1
log
@New document describing the business object caching system.
@
text
@<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>
 <head>
  <title>The Helm Business Object Caching System</title>
 </head>

<body>

<h1>The Helm Business Object Caching System</h1>

<p>Leonard Richardson &lt;leonardr at collab dot net&gt;<br>
May 23, 2001<br>
<small>$Id: migration.html,v 1.1 2001/05/16 16:35:24 leonardr Exp $</small>

<h2>Abstract</h2>

<p>The Helm business object caching system is designed to be a
flexible, extensible system of caches which is as fast and which saves
as many database hits as possible. Periods of cache dirtiness lasting
up to 3 seconds are tolerated. Communication across JVMs in a cluster
is handled through the database.

<h2>Cache Invalidation Events</h2>

<p>A cache invalidation event for a business object class occurs when
an instance of the class has its <code>save()</code> method called, or
when the class' Peer has its <code>doDelete()</code> method
called. For each class, the time of the class' most recent cache
invalidation event is stored in the HELM_CLUSTER_EVENT table. This
table is neccessary so that invalidation events which occur on one JVM
can be propagated to all JVMs in the cluster.

<p>The following classes of business objects cause cache invalidation
events: <code>Project</code>, <code>ProjectProjectgroup</code>,
<code>Resource</code>, <code>Role</code>,
<code>RoleActionResource</code>, <code>User</code>,
<code>UserRoleProject</code>, <code>UserUsergroup</code>. More can be
added, should this ever prove neccessary.

<h2><code>RegisterableCache</code></h2>

<p><code>RegisterableCache</code> is an abstract class describing a
cache which is interested in certain types of invalidation events,
which can respond to such events, and which can describe its own
contents. <code>RegisterableCache</code subclasses are generally
implemented as inner classes of Peers; commonly accessed methods of a
Peer with a cache (such as <code>getInstance</code> methods) are
written to check the cache before hitting the database, thus saving on
database hits. There is a concrete
<code>SimpleRegisterableCache</code> class which does much of the
administration for you, and which can often be used instead of writing
a subclass of <code>RegisterableCache</code>.

<p>Each <code>RegisterableCache</code> subclass must, upon
initialization, register itself with the JVM's
<code>CacheRegistry</code>service. As part of the registration
process, the <code>RegisterableCache</code> provides the
<code>CacheRegistry</code> with a list of types of cache invalidation
events it considers interesting; for instance, the
<code>ACLCache</code> inner class of <code>AccessControlList</code> is
interested in every single type of cache invalidation event, whereas
the <code>ProjectCache</code> inner class of <code>ProjectPeer</code>
is interested only in Project invalidations.

<p>The <code>CacheRegistry</code>service monitors periodically for
cache invalidation events, and when it finds one it informs all
interested <code>RegisterableCache</code>s. It is up to the individual
<code>RegisterableCache</code>to do any neccessary invalidation
(though <code>SimpleRegisterableCache</code> does invalidation for
you).

<h2>CacheDump</h2>

<p>If you are logged in as the host admin, you can visit the CacheDump
servlet to see all the currently registered
<code>RegisterableCache</code> subclassess, their contents, and the
invalidation events in which each is interested. This is useful when
debugging caching code; check CacheDump, do something which would
cause a cache invalidation event of the type you're interested in,
then check CacheDump again and verify that all interested caches have
undergone invalidation.

<p>Note that the cache dump you will see will be the dump for the JVM
on which your session resides; if you are testing on an install with
multiple JVMs, there is no reliable way of look at the caches on every
JVM.

<h2>The future</h2>

<p><b>Selective invalidation:</b> Right now, a cache invalidation
event describes only the type of object which was invalidated. It
would save database hits in the long run if events could specify which
specific object was invalidated, allowing the registered
<code>RegisterableCache</code>s to selectively invalidate themselves.

</body>
</html>@
