[jboss-cvs] JBossCache/docs/JBossCache-UserGuide/en/modules ...
Manik Surtani
manik at jboss.org
Tue Jul 17 12:16:43 EDT 2007
User: msurtani
Date: 07/07/17 12:16:43
Modified: docs/JBossCache-UserGuide/en/modules basic_api.xml
eviction_policies.xml
Log:
JBCACHE-758
Revision Changes Path
1.12 +371 -242 JBossCache/docs/JBossCache-UserGuide/en/modules/basic_api.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: basic_api.xml
===================================================================
RCS file: /cvsroot/jboss/JBossCache/docs/JBossCache-UserGuide/en/modules/basic_api.xml,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -b -r1.11 -r1.12
--- basic_api.xml 29 Jun 2007 18:22:40 -0000 1.11
+++ basic_api.xml 17 Jul 2007 16:16:43 -0000 1.12
@@ -38,27 +38,50 @@
<section id="api.create_start">
<title>Instantiating and Starting the Cache</title>
<para>
- An instance of the <literal>Cache</literal> interface can only be created
- via a <literal>CacheFactory</literal>. (This is unlike JBoss Cache 1.x,
- where an instance of the old <literal>TreeCache</literal> class could
+ An instance of the
+ <literal>Cache</literal>
+ interface can only be created
+ via a
+ <literal>CacheFactory</literal>
+ . (This is unlike JBoss Cache 1.x,
+ where an instance of the old
+ <literal>TreeCache</literal>
+ class could
be directly instantiated.)
</para>
<para>
- <literal>CacheFactory</literal> provides a number of overloaded methods
- for creating a <literal>Cache</literal>, but they all do the same thing:
+ <literal>CacheFactory</literal>
+ provides a number of overloaded methods
+ for creating a
+ <literal>Cache</literal>
+ , but they all do the same thing:
<itemizedlist>
- <listitem>Gain access to a <literal>Configuration</literal>, either
+ <listitem>Gain access to a
+ <literal>Configuration</literal>
+ , either
by having one passed in as a method parameter, or by parsing XML
content and constructing one. The XML content can come from a
provided input stream or from a classpath or filesystem location.
See the
- <link linkend="configuration">chapter on Configuration</link> for
- more on obtaining a <literal>Configuration</literal>.
+ <link linkend="configuration">chapter on Configuration</link>
+ for
+ more on obtaining a
+ <literal>Configuration</literal>
+ .
+ </listitem>
+ <listitem>Instantiate the
+ <literal>Cache</literal>
+ and provide
+ it with a reference to the
+ <literal>Configuration</literal>
+ .
+ </listitem>
+ <listitem>Optionally invoke the cache's
+ <literal>create()</literal>
+ and
+ <literal>start()</literal>
+ methods.
</listitem>
- <listitem>Instantiate the <literal>Cache</literal> and provide
- it with a reference to the <literal>Configuration</literal>.</listitem>
- <listitem>Optionally invoke the cache's <literal>create()</literal>
- and <literal>start()</literal> methods.</listitem>
</itemizedlist>
</para>
@@ -72,7 +95,9 @@
Cache cache = factory.createCache();
</programlisting>
- <para>Here we tell the <literal>CacheFactory</literal> to find and
+ <para>Here we tell the
+ <literal>CacheFactory</literal>
+ to find and
parse a configuration file on the classpath:
</para>
@@ -102,8 +127,12 @@
<section>
<title>Caching and Retrieving Data</title>
- <para>Next, let's use the <literal>Cache</literal> API to access
- a <literal>Node</literal> in the cache and then do some
+ <para>Next, let's use the
+ <literal>Cache</literal>
+ API to access
+ a
+ <literal>Node</literal>
+ in the cache and then do some
simple reads and writes to that node.
</para>
<programlisting>
@@ -144,8 +173,12 @@
</programlisting>
<para>
- The <literal>Cache</literal> interface also exposes put/get/remove
- operations that take an <link linkend="basic_api.fqn">Fqn</link> as an argument:
+ The
+ <literal>Cache</literal>
+ interface also exposes put/get/remove
+ operations that take an
+ <link linkend="basic_api.fqn">Fqn</link>
+ as an argument:
</para>
<programlisting>
@@ -168,29 +201,44 @@
</section>
<section id="basic_api.fqn">
- <title>The <literal>Fqn</literal> Class</title>
+ <title>The
+ <literal>Fqn</literal>
+ Class
+ </title>
<para>
- The previous section used the <literal>Fqn</literal> class in its
+ The previous section used the
+ <literal>Fqn</literal>
+ class in its
examples; now let's learn a bit more about that class.
</para>
<para>
A Fully Qualified Name (Fqn) encapsulates a list of names which represent
a path to a particular location in the cache's tree structure. The
- elements in the list are typically <literal>String</literal>s but can be
- any <literal>Object</literal> or a mix of different types.
+ elements in the list are typically
+ <literal>String</literal>
+ s but can be
+ any
+ <literal>Object</literal>
+ or a mix of different types.
</para>
<para>
This path can be absolute (i.e., relative to the root node), or relative
to any node in the cache. Reading the documentation on each API call that
- makes use of <literal>Fqn</literal> will tell you whether the API expects
- a relative or absolute <literal>Fqn</literal>.
+ makes use of
+ <literal>Fqn</literal>
+ will tell you whether the API expects
+ a relative or absolute
+ <literal>Fqn</literal>
+ .
</para>
<para>
- The <literal>Fqn</literal> class provides are variety of constructors;
+ The
+ <literal>Fqn</literal>
+ class provides are variety of constructors;
see the javadoc for all the possibilities. The following illustrates the
most commonly used approaches to creating an Fqn:
</para>
@@ -217,7 +265,10 @@
<para>
<programlisting><![CDATA[Fqn<String> f = new Fqn<String>("/a/b/c");]]></programlisting>
</para>
- <para>is <emphasis>not</emphasis> the same as</para>
+ <para>is
+ <emphasis>not</emphasis>
+ the same as
+ </para>
<para>
<programlisting><![CDATA[Fqn<String> f = Fqn.fromString("/a/b/c");]]></programlisting>
</para>
@@ -228,14 +279,18 @@
in a 3 element Fqn, where "c" idicates a child of "b", which is a child
of "a", and "a" hangs off the cache root. Another way to
look at it is that the "/" separarator is only parsed when it forms
- part of a String passed in to <literal>Fqn.fromString()</literal> and not
+ part of a String passed in to
+ <literal>Fqn.fromString()</literal>
+ and not
otherwise.
</para>
<para>
The JBoss Cache API in the 1.x releases included many overloaded
convenience methods that took a string in the "/a/b/c" format in place
- of an <literal>Fqn</literal>. In the interests of API simplicity, no
+ of an
+ <literal>Fqn</literal>
+ . In the interests of API simplicity, no
such convenience methods are available in the JBC 2.x API.
</para>
@@ -256,20 +311,33 @@
</programlisting>
<para>
- Not also that a cache that has had <literal>stop()</literal> invoked
- on it can be started again with a new call to <literal>start()</literal>.
- Similarly, a cache that has had <literal>destroy()</literal> invoked
- on it can be created again with a new call to <literal>create()</literal>
- (and then started again with a <literal>start()</literal> call).
+ Not also that a cache that has had
+ <literal>stop()</literal>
+ invoked
+ on it can be started again with a new call to
+ <literal>start()</literal>
+ .
+ Similarly, a cache that has had
+ <literal>destroy()</literal>
+ invoked
+ on it can be created again with a new call to
+ <literal>create()</literal>
+ (and then started again with a
+ <literal>start()</literal>
+ call).
</para>
</section>
<section>
<title>Cache Modes</title>
<para>
- Although technically not part of the API, the <emphasis>mode</emphasis>
+ Although technically not part of the API, the
+ <emphasis>mode</emphasis>
in which the cache is configured to operate affects the cluster-wide
- behavior of any <literal>put</literal> or <literal>remove</literal>
+ behavior of any
+ <literal>put</literal>
+ or
+ <literal>remove</literal>
operation, so we'll briefly mention the various modes here.
</para>
<para>
@@ -312,9 +380,12 @@
</listitem>
</itemizedlist>
</para>
- <para>See the <link linkend="clustering">chapter on Clustering</link> for
+ <para>See the
+ <link linkend="clustering">chapter on Clustering</link>
+ for
more details on how the cache's mode affects behavior. See the
- <link linkend="configuration">chapter on Configuration</link> for info
+ <link linkend="configuration">chapter on Configuration</link>
+ for info
on how to configure things like the cache's mode.
</para>
</section>
@@ -324,148 +395,196 @@
Adding a CacheListener
</title>
<para>
- The <literal>@org.jboss.cache.notifications.annotation.CacheListener</literal> annotation is a convenient
+ The
+ <literal>@org.jboss.cache.notifications.annotation.CacheListener</literal>
+ annotation is a convenient
mechanism for receiving notifications from a cache about events that happen in the cache. Classes annotated
- with <literal>@CacheListener</literal> need to be public classes. In addition, the class needs to have one or
- more methods annotated with one of the method-level annotations (in the <literal>org.jboss.cache.notifications.annotation</literal>
- package). Methods annotated as such need to be public, have a void return type, and accept a single parameter of
- type <literal>org.jboss.cache.notifications.event.Event</literal> or one of it's subtypes.
+ with
+ <literal>@CacheListener</literal>
+ need to be public classes. In addition, the class needs to have one or
+ more methods annotated with one of the method-level annotations (in the
+ <literal>org.jboss.cache.notifications.annotation</literal>
+ package). Methods annotated as such need to be public, have a void return type, and accept a single parameter
+ of
+ type
+ <literal>org.jboss.cache.notifications.event.Event</literal>
+ or one of it's subtypes.
<itemizedlist>
<listitem>
<para>
- <literal>@CacheStarted</literal> - methods annotated such receive a notification when the cache is
+ <literal>@CacheStarted</literal>
+ - methods annotated such receive a notification when the cache is
started. Methods need to accept a parameter type which is assignable from
- <literal>org.jboss.cache.notifications.event.CacheStartedEvent</literal>.
+ <literal>org.jboss.cache.notifications.event.CacheStartedEvent</literal>
+ .
</para>
</listitem>
<listitem>
<para>
- <literal>@CacheStopped</literal> - methods annotated such receive a notification when the cache is
+ <literal>@CacheStopped</literal>
+ - methods annotated such receive a notification when the cache is
stopped. Methods need to accept a parameter type which is assignable from
- <literal>org.jboss.cache.notifications.event.CacheStoppedEvent</literal>.
+ <literal>org.jboss.cache.notifications.event.CacheStoppedEvent</literal>
+ .
</para>
</listitem>
<listitem>
<para>
- <literal>@NodeCreated</literal> - methods annotated such receive a notification when a node is
+ <literal>@NodeCreated</literal>
+ - methods annotated such receive a notification when a node is
created. Methods need to accept a parameter type which is assignable from
- <literal>org.jboss.cache.notifications.event.NodeCreatedEvent</literal>.
+ <literal>org.jboss.cache.notifications.event.NodeCreatedEvent</literal>
+ .
</para>
</listitem>
<listitem>
<para>
- <literal>@NodeRemoved</literal> - methods annotated such receive a notification when a node is
+ <literal>@NodeRemoved</literal>
+ - methods annotated such receive a notification when a node is
removed. Methods need to accept a parameter type which is assignable from
- <literal>org.jboss.cache.notifications.event.NodeRemovedEvent</literal>.
+ <literal>org.jboss.cache.notifications.event.NodeRemovedEvent</literal>
+ .
</para>
</listitem>
<listitem>
<para>
- <literal>@NodeModified</literal> - methods annotated such receive a notification when a node is
+ <literal>@NodeModified</literal>
+ - methods annotated such receive a notification when a node is
modified. Methods need to accept a parameter type which is assignable from
- <literal>org.jboss.cache.notifications.event.NodeModifiedEvent</literal>.
+ <literal>org.jboss.cache.notifications.event.NodeModifiedEvent</literal>
+ .
</para>
</listitem>
<listitem>
<para>
- <literal>@NodeMoved</literal> - methods annotated such receive a notification when a node is
+ <literal>@NodeMoved</literal>
+ - methods annotated such receive a notification when a node is
moved. Methods need to accept a parameter type which is assignable from
- <literal>org.jboss.cache.notifications.event.NodeMovedEvent</literal>.
+ <literal>org.jboss.cache.notifications.event.NodeMovedEvent</literal>
+ .
</para>
</listitem>
<listitem>
<para>
- <literal>@NodeVisited</literal> - methods annotated such receive a notification when a node is
+ <literal>@NodeVisited</literal>
+ - methods annotated such receive a notification when a node is
started. Methods need to accept a parameter type which is assignable from
- <literal>org.jboss.cache.notifications.event.NodeVisitedEvent</literal>.
+ <literal>org.jboss.cache.notifications.event.NodeVisitedEvent</literal>
+ .
</para>
</listitem>
<listitem>
<para>
- <literal>@NodeLoaded</literal> - methods annotated such receive a notification when a node is
- loaded from a <literal>CacheLoader</literal>. Methods need to accept a parameter type which is assignable from
- <literal>org.jboss.cache.notifications.event.NodeLoadedEvent</literal>.
+ <literal>@NodeLoaded</literal>
+ - methods annotated such receive a notification when a node is
+ loaded from a
+ <literal>CacheLoader</literal>
+ . Methods need to accept a parameter type which is assignable from
+ <literal>org.jboss.cache.notifications.event.NodeLoadedEvent</literal>
+ .
</para>
</listitem>
<listitem>
<para>
- <literal>@NodeEvicted</literal> - methods annotated such receive a notification when a node is
+ <literal>@NodeEvicted</literal>
+ - methods annotated such receive a notification when a node is
evicted from memory. Methods need to accept a parameter type which is assignable from
- <literal>org.jboss.cache.notifications.event.NodeEvictedEvent</literal>.
+ <literal>org.jboss.cache.notifications.event.NodeEvictedEvent</literal>
+ .
</para>
</listitem>
<listitem>
<para>
- <literal>@NodeActivated</literal> - methods annotated such receive a notification when a node is
+ <literal>@NodeActivated</literal>
+ - methods annotated such receive a notification when a node is
activated. Methods need to accept a parameter type which is assignable from
- <literal>org.jboss.cache.notifications.event.NodeActivatedEvent</literal>.
+ <literal>org.jboss.cache.notifications.event.NodeActivatedEvent</literal>
+ .
</para>
</listitem>
<listitem>
<para>
- <literal>@NodePassivated</literal> - methods annotated such receive a notification when a node is
+ <literal>@NodePassivated</literal>
+ - methods annotated such receive a notification when a node is
passivated. Methods need to accept a parameter type which is assignable from
- <literal>org.jboss.cache.notifications.event.NodePassivatedEvent</literal>.
+ <literal>org.jboss.cache.notifications.event.NodePassivatedEvent</literal>
+ .
</para>
</listitem>
<listitem>
<para>
- <literal>@TransactionRegistered</literal> - methods annotated such receive a notification when the cache
- registers a <literal>javax.transaction.Synchronization</literal> with a registered transaction manager.
+ <literal>@TransactionRegistered</literal>
+ - methods annotated such receive a notification when the cache
+ registers a
+ <literal>javax.transaction.Synchronization</literal>
+ with a registered transaction manager.
Methods need to accept a parameter type which is assignable from
- <literal>org.jboss.cache.notifications.event.TransactionRegisteredEvent</literal>.
+ <literal>org.jboss.cache.notifications.event.TransactionRegisteredEvent</literal>
+ .
</para>
</listitem>
<listitem>
<para>
- <literal>@TransactionCompleted</literal> - methods annotated such receive a notification when the cache
+ <literal>@TransactionCompleted</literal>
+ - methods annotated such receive a notification when the cache
receives a commit or rollback call from a registered transaction manager.
Methods need to accept a parameter type which is assignable from
- <literal>org.jboss.cache.notifications.event.TransactionCompletedEvent</literal>.
+ <literal>org.jboss.cache.notifications.event.TransactionCompletedEvent</literal>
+ .
</para>
</listitem>
<listitem>
<para>
- <literal>@ViewChanged</literal> - methods annotated such receive a notification when the group structure
+ <literal>@ViewChanged</literal>
+ - methods annotated such receive a notification when the group structure
of the cluster changes. Methods need to accept a parameter type which is assignable from
- <literal>org.jboss.cache.notifications.event.ViewChangedEvent</literal>.
+ <literal>org.jboss.cache.notifications.event.ViewChangedEvent</literal>
+ .
</para>
</listitem>
<listitem>
<para>
- <literal>@CacheBlocked</literal> - methods annotated such receive a notification when the cluster
+ <literal>@CacheBlocked</literal>
+ - methods annotated such receive a notification when the cluster
requests that cache operations are blocked for a state transfer event. Methods need to accept a
- parameter type which is assignable from <literal>org.jboss.cache.notifications.event.CacheBlockedEvent</literal>.
+ parameter type which is assignable from
+ <literal>org.jboss.cache.notifications.event.CacheBlockedEvent</literal>
+ .
</para>
</listitem>
<listitem>
<para>
- <literal>@CacheUnblocked</literal> - methods annotated such receive a notification when the cluster
+ <literal>@CacheUnblocked</literal>
+ - methods annotated such receive a notification when the cluster
requests that cache operations are unblocked after a state transfer event. Methods need to accept a
- parameter type which is assignable from <literal>org.jboss.cache.notifications.event.CacheUnblockedEvent</literal>.
+ parameter type which is assignable from
+ <literal>org.jboss.cache.notifications.event.CacheUnblockedEvent</literal>
+ .
</para>
</listitem>
</itemizedlist>
</para>
<para>
- Refer to the javadocs on the annotations as well as the <literal>Event</literal> subtypes
+ Refer to the javadocs on the annotations as well as the
+ <literal>Event</literal>
+ subtypes
for details of what is passed in to your method, and when.
</para>
<para>
@@ -581,6 +700,16 @@
- an eviction policy that creates a first-in-first-out queue and evicts the oldest nodes when thresholds
are hit.
</listitem>
+ <listitem>
+ <literal>org.jboss.cache.eviction.ExpirationPolicy</literal>
+ - an eviction policy that selects nodes for eviction based on an expiry time each node is configured
+ with.
+ </listitem>
+ <listitem>
+ <literal>org.jboss.cache.eviction.ElementSizePolicy</literal>
+ - an eviction policy that selects nodes for eviction based on the number of key/value pairs held in the
+ node.
+ </listitem>
</itemizedlist>
Detailed configuration and implementing custom eviction policies are discussed in the
<link linkend="eviction_policies">chapter dedicated to eviction policies.</link>
1.14 +47 -20 JBossCache/docs/JBossCache-UserGuide/en/modules/eviction_policies.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: eviction_policies.xml
===================================================================
RCS file: /cvsroot/jboss/JBossCache/docs/JBossCache-UserGuide/en/modules/eviction_policies.xml,v
retrieving revision 1.13
retrieving revision 1.14
diff -u -b -r1.13 -r1.14
--- eviction_policies.xml 8 Jun 2007 14:21:42 -0000 1.13
+++ eviction_policies.xml 17 Jul 2007 16:16:43 -0000 1.14
@@ -144,7 +144,8 @@
<literal>Configuration.setEvictionConfig()</literal>
. See the
<link linkend="configuration">chapter on Configuration</link>
- for more on building a <literal>Configuration</literal>
+ for more on building a
+ <literal>Configuration</literal>
programatically.
</para>
@@ -155,8 +156,10 @@
assume we had an existing cache configured via XML with the
EvictionConfig element shown above. Now at runtime we wished to
add a new eviction region named "/org/jboss/fifo", using
- <literal>LRUPolicy</literal> but a different number of
- <literal>maxNodes</literal>:
+ <literal>LRUPolicy</literal>
+ but a different number of
+ <literal>maxNodes</literal>
+ :
</para>
<programlisting>
@@ -368,6 +371,28 @@
may happen a few seconds later than indicated.
</para>
</section>
+ <section>
+ <title>ElementSizePolicy - Eviction based on number of key/value pairs in a node</title>
+
+ <para>
+ <literal>org.jboss.cache.eviction.ElementSizePolicy</literal>
+ controls
+ the eviction in based on the number of key/value pairs in the node. Nodes The most recently
+ used nodes will be the first to evict with this policy. It has the following configuration parameters:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <literal>maxNodes</literal>
+ - This is the maximum number of nodes allowed in this region. 0 denotes no limit.
+ </listitem>
+ <listitem>
+ <literal>maxElementsPerNode</literal>
+ - This is the trigger number of attributes per node for the node to be selected for eviction. 0 denotes
+ no limit.
+ </listitem>
+ </itemizedlist>
+ </section>
</section>
<section>
@@ -430,7 +455,9 @@
<itemizedlist>
<listitem>
- <para>The <literal>EvictionPolicyConfig</literal> implementation
+ <para>The
+ <literal>EvictionPolicyConfig</literal>
+ implementation
should maintain
getter and setter methods for whatever configuration properties
the policy supports (e.g. for
More information about the jboss-cvs-commits
mailing list