[jboss-cvs] JBossCache/docs/JBossCache-UserGuide/en/modules ...
Manik Surtani
msurtani at jboss.com
Mon Jan 22 22:04:03 EST 2007
User: msurtani
Date: 07/01/22 22:04:03
Modified: docs/JBossCache-UserGuide/en/modules configuration.xml
configuration_reference.xml introduction.xml
basic_api.xml
Log:
finished API docs up to chapter 3.
Revision Changes Path
1.3 +61 -215 JBossCache/docs/JBossCache-UserGuide/en/modules/configuration.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: configuration.xml
===================================================================
RCS file: /cvsroot/jboss/JBossCache/docs/JBossCache-UserGuide/en/modules/configuration.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -b -r1.2 -r1.3
--- configuration.xml 22 Jan 2007 22:50:09 -0000 1.2
+++ configuration.xml 23 Jan 2007 03:04:03 -0000 1.3
@@ -1,235 +1,81 @@
<chapter id="configuration">
<title>Configuration</title>
- <para>All properties of the cache are configured via setters and can be
- retrieved via getters. This can be done either manually, or via the
- <literal>PropertyConfigurator</literal>
- and an XML file.
- </para>
- <para>You should refer to
- <link linkend="configuration_reference">the Configuration Reference chapter</link>
- for a comprehensive list of all confiruration options available.
- </para>
<section>
- <title>Sample XML-Based Configuration</title>
+ <title>XML-based Configuration</title>
<para>
- A sample XML configuration file is shown
- below:
+ The most convenient way to configure JBoss Cache is via an XML file. The JBoss Cache distribution ships
+ with a number of configuration files for common use cases. It is recommended that these files are used as
+ a starting point, and tweaked to meet specific needs.
</para>
- <programlisting>
- <![CDATA[
- <?xml version="1.0" encoding="UTF-8" ?>
- <server>~/
- <classpath codebase="./lib" archives="jboss-cache.jar, jgroups.jar" />
-
- <!-- ==================================================================== -->
- <!-- Defines TreeCache configuration -->
- <!-- ==================================================================== -->
- <mbean code="org.jboss.cache.TreeCache" name="jboss.cache:service=TreeCache">
- <depends>jboss:service=Naming</depends>
- <depends>jboss:service=TransactionManager</depends>
-
-
- <!-- Configure the TransactionManager -->
- <attribute name="TransactionManagerLookupClass">org.jboss.cache.DummyTransactionManagerLookup</attribute>
-
- <!-- Node locking scheme : PESSIMISTIC (default)
- OPTIMISTIC
- -->
- <attribute name="NodeLockingScheme">PESSIMISTIC</attribute>
-
- <!-- Node locking isolation level : SERIALIZABLE
- REPEATABLE_READ (default)
- READ_COMMITTED
- READ_UNCOMMITTED
- NONE
-
- (ignored if NodeLockingScheme is OPTIMISTIC)
- -->
- <attribute name="IsolationLevel">REPEATABLE_READ</attribute>
-
- <!-- Valid modes are LOCAL
- REPL_ASYNC
- REPL_SYNC
- INVALIDATION_ASYNC
- INVALIDATION_SYNC
- -->
- <attribute name="CacheMode">LOCAL</attribute>
-
- <!-- Whether each interceptor should have an mbean
- registered to capture and display its statistics. -->
- <attribute name="UseInterceptorMbeans">true</attribute>
-
- <!-- Name of cluster. Needs to be the same for all TreeCache nodes in a
- cluster, in order to find each other -->
- <attribute name="ClusterName">JBoss-Cache-Cluster</attribute>
-
- <!-- Uncomment next three statements to enable JGroups multiplexer.
- This configuration is dependent on the JGroups multiplexer being
- registered in an MBean server such as JBossAS. -->
- <!--
- <depends>jgroups.mux:name=Multiplexer</depends>
- <attribute name="MultiplexerService">jgroups.mux:name=Multiplexer</attribute>
- <attribute name="MultiplexerStack">udp</attribute>
- -->
-
- <!-- JGroups protocol stack properties. ClusterConfig isn't used if the
- multiplexer is enabled and successfully initialized. -->
- <attribute name="ClusterConfig">
- <config>
- <!-- UDP: if you have a multihomed machine,
- set the bind_addr attribute to the appropriate NIC IP address
- -->
- <!-- UDP: On Windows machines, because of the media sense feature
- being broken with multicast (even after disabling media sense)
- set the loopback attribute to true
- -->
- <UDP mcast_addr="228.1.2.3" mcast_port="45566" ip_ttl="64" ip_mcast="true"
- mcast_send_buf_size="150000" mcast_recv_buf_size="80000" ucast_send_buf_size="150000"
- ucast_recv_buf_size="80000" loopback="false" />
- <PING timeout="2000" num_initial_members="3" up_thread="false" down_thread="false" />
- <MERGE2 min_interval="10000" max_interval="20000" />
- <FD shun="true" up_thread="true" down_thread="true" />
- <VERIFY_SUSPECT timeout="1500" up_thread="false" down_thread="false" />
- <pbcast.NAKACK gc_lag="50" max_xmit_size="8192" retransmit_timeout="600,1200,2400,4800"
- up_thread="false" down_thread="false" />
- <UNICAST timeout="600,1200,2400" window_size="100" min_threshold="10" down_thread="false" />
- <pbcast.STABLE desired_avg_gossip="20000" up_thread="false" down_thread="false" />
- <FRAG frag_size="8192" down_thread="false" up_thread="false" />
- <pbcast.GMS join_timeout="5000" join_retry_timeout="2000" shun="true"
- print_local_addr="true" />
- <pbcast.STATE_TRANSFER up_thread="false" down_thread="false" />
- </config>
- </attribute>
-
- <!-- The max amount of time (in milliseconds) we wait until the
- initial state (ie. the contents of the cache) are retrieved from
- existing members in a clustered environment
- -->
- <attribute name="InitialStateRetrievalTimeout">5000</attribute>
-
- <!-- Number of milliseconds to wait until all responses for a
- synchronous call have been received.
- -->
- <attribute name="SyncReplTimeout">10000</attribute>
-
- <!-- Max number of milliseconds to wait for a lock acquisition -->
- <attribute name="LockAcquisitionTimeout">15000</attribute>
-
- <!-- Name of the eviction policy class. -->
- <attribute name="EvictionPolicyClass">org.jboss.cache.eviction.LRUPolicy</attribute>
-
- <!-- Specific eviction policy configurations. This is LRU -->
- <attribute name="EvictionPolicyConfig">
- <config>
- <attribute name="wakeUpIntervalSeconds">5</attribute>
- <!-- Cache wide default -->
- <region name="/_default_">
- <attribute name="maxNodes">5000</attribute>
- <attribute name="timeToLiveSeconds">1000</attribute>
- <!-- Maximum time an object is kept in cache regardless of idle time -->
- <attribute name="maxAgeSeconds">120</attribute>
- </region>
-
- <region name="/org/jboss/data">
- <attribute name="maxNodes">5000</attribute>
- <attribute name="timeToLiveSeconds">1000</attribute>
- </region>
-
- <region name="/org/jboss/test/data">
- <attribute name="maxNodes">5</attribute>
- <attribute name="timeToLiveSeconds">4</attribute>
- </region>
- </config>
- </attribute>
-
- <!-- New 1.3.x cache loader config block -->
- <attribute name="CacheLoaderConfiguration">
- <config>
- <!-- if passivation is true, only the first cache loader is used; the rest are ignored -->
- <passivation>false</passivation>
- <preload>/a/b, /allTempObjects, /some/specific/fqn</preload>
- <shared>false</shared>
-
- <!-- we can now have multiple cache loaders, which get chained -->
- <cacheloader>
- <class>org.jboss.cache.loader.FileCacheLoader</class>
- <!-- same as the old CacheLoaderConfig attribute -->
- <properties>
- location=/tmp/myFileStore
- </properties>
- <!-- whether the cache loader writes are asynchronous -->
- <async>false</async>
- <!-- only one cache loader in the chain may set fetchPersistentState to true.
- An exception is thrown if more than one cache loader sets this to true. -->
- <fetchPersistentState>true</fetchPersistentState>
- <!-- determines whether this cache loader ignores writes - defaults to false. -->
- <ignoreModifications>false</ignoreModifications>
- <!-- if set to true, purges the contents of this cache loader when the cache starts up.
- Defaults to false. -->
- <purgeOnStartup>false</purgeOnStartup>
- </cacheloader>
-
- <cacheloader>
- <class>org.jboss.cache.loader.JDBCCacheLoader</class>
- <!-- same as the old CacheLoaderConfig attribute -->
- <properties>
- cache.jdbc.driver=com.mysql.jdbc.Driver
- cache.jdbc.url=jdbc:mysql://localhost:3306/jbossdb
- cache.jdbc.user=root
- cache.jdbc.password=
- </properties>
- <!-- whether the cache loader writes are asynchronous -->
- <async>true</async>
- <!-- only one cache loader in the chain may set fetchPersistentState to true.
- An exception is thrown if more than one cache loader sets this to true. -->
- <fetchPersistentState>false</fetchPersistentState>
- <!-- determines whether this cache loader ignores writes - defaults to false. -->
- <ignoreModifications>true</ignoreModifications>
- <!-- if set to true, purges the contents of this cache loader when the cache starts up.
- Defaults to false. -->
- <purgeOnStartup>false</purgeOnStartup>
- </cacheloader>
-
- </config>
- </attribute>
-
-
- </mbean>
- </server> ]]></programlisting>
+ <para>
+ A sample XML file is in
+ <link linkend="sample_xml_file">the configuration reference</link>
+ section of this book,
+ along with
+ <link linkend="configuration_reference">a handy look-up table</link>
+ of
+ the various options.
+ </para>
+ </section>
- <para>The PropertyConfigurator.configure() method needs to have as
- argument a filename which is located on the classpath; it will use be used
- to configure JBoss Cache from the properties defined in it. Note that
- this configuration file is used to configure JBoss Cache both as a
- standalone cache, and as an MBean if run inside the JBoss
- container.
- <footnote>
- <para>We will switch to using an XMBean in a future release.</para>
- </footnote>
+ <section>
+ <title>Programmatic Configuration</title>
+ <para>
+ In addition to the XML-based configuration above, a programmatic configuration option is available.
+ <literal>org.jboss.cache.config.Configuration</literal>
+ is central to configuring JBoss Cache programmatically,
+ and an instance is is created, configured and passed in to a
+ <literal>org.jboss.cache.CacheFactory</literal>
+ to
+ create a cache.
</para>
+ <para>
+ When constructed, the
+ <literal>Configuration</literal>
+ object is preset with JBoss Cache defaults and can even
+ be used as-is for a quick start.
+ </para>
+ </section>
+ <section>
+ <title>Dynamic Reconfiguration</title>
+ <para>
+ Dynamically changing the configuration of certain options while the cache is running is supported for
+ certain options, by programmatically obtaining the
+ <literal>Configuration</literal>
+ object from the
+ running cache and changing values. E.g.,
+ <programlisting>
+ Configuration liveConfig = cache.getConfiguration();
+ liveConfig.setLockAcquisitionTimeout(2000);
+ </programlisting>
+ A complete listing of which options may be changed dynamically is in the
+ <link linkend="configuration_reference">configuration reference</link>
+ section. A
+ <literal>org.jboss.cache.config.ConfigurationException</literal>
+ will be thrown if you attempt to change a
+ setting that is not dynamic.
+ </para>
</section>
<section>
- <title>Overriding options</title>
+ <title>Overriding Configuration Options</title>
<para>
- As of JBoss Cache 1.3.0, a new API has been introduced, to allow you to override certain behaviour of the cache
- on a per invocation basis.
+ The Option API allows you to override certain behaviour of the cache on a per invocation basis.
This involves creating an instance of
<literal>org.jboss.cache.config.Option</literal>
- , setting the options you wish to override on the
+ , setting the options
+ you wish to override on the
<literal>Option</literal>
- object and passing it in as a parameter to overloaded versions of
- <literal>get()</literal>
- ,
- <literal>put()</literal>
- and
- <literal>remove()</literal>
- . See the javadocs on the
+ object and passing it in the
+ <literal>InvocationContext</literal>
+ before invoking your method on the cache. More of this is discussed later.
+ </para>
+ <para>
+ See the javadocs on the
<literal>Option</literal>
- class for details on these options.
+ class for details on the options available.
</para>
</section>
-
</chapter>
\ No newline at end of file
1.2 +423 -410 JBossCache/docs/JBossCache-UserGuide/en/modules/configuration_reference.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: configuration_reference.xml
===================================================================
RCS file: /cvsroot/jboss/JBossCache/docs/JBossCache-UserGuide/en/modules/configuration_reference.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- configuration_reference.xml 22 Jan 2007 22:50:09 -0000 1.1
+++ configuration_reference.xml 23 Jan 2007 03:04:03 -0000 1.2
@@ -1,8 +1,20 @@
-<chapter id="configuration_reference">
+<chapter id="configuration_reference_chapter">
+ <title>Configuration References</title>
+ <section id="sample_xml_file">
+ <title>Sample XML Configuration File</title>
+ <para>
+ This is what a typical XML configuration file looks like. It is recommended that you use one of the
+ configurations
+ shipped with the JBoss Cache distribution and tweak according to your needs rather than write one from scratch.
+ </para>
+ </section>
+
+
+ <section id="configuration_reference">
<title>
- Definition of XML attributes
+ Reference table of XML attributes
</title>
- <para>A list of definitions of each of the XML attributes used above:</para>
+ <para>A list of definitions of each of the XML attributes used above.</para>
<informaltable frame="all">
<tgroup cols="2">
@@ -408,4 +420,5 @@
</tbody>
</tgroup>
</informaltable>
+ </section>
</chapter>
\ No newline at end of file
1.3 +45 -9 JBossCache/docs/JBossCache-UserGuide/en/modules/introduction.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: introduction.xml
===================================================================
RCS file: /cvsroot/jboss/JBossCache/docs/JBossCache-UserGuide/en/modules/introduction.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -b -r1.2 -r1.3
--- introduction.xml 23 Jan 2007 01:12:37 -0000 1.2
+++ introduction.xml 23 Jan 2007 03:04:03 -0000 1.3
@@ -104,20 +104,56 @@
</section>
<section>
+ <title>
+ Requirements
+ </title>
+ <para>
+ Although written in and baselined against Java 5.0, JBoss Cache does ship with a Java 1.4.x compatible jar as
+ well,
+ making use of
+ <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JBossRetro">JBossRetro</ulink>
+ to retroweave the Java 5.0 binaries.
+ </para>
+ <para>
+ In addition, JBoss Cache has dependencies on
+ <ulink url="http://www.jgroups.org">JGroups</ulink>
+ , Apache's
+ <ulink
+ url="http://jakarta.apache.org/commons/logging/">commons-logging
+ </ulink>
+ and
+ <ulink url="http://labs.jboss.com/portal/serialization/">JBoss-serialization</ulink>
+ for
+ performant serialization of objects. JBoss Cache ships with all dependent libraries necessary to run out of the
+ box.
+ </para>
+ </section>
+
+ <section>
<title>License</title>
<para>
JBoss Cache is an open source product, using the business and OEM-friendly
<ulink url="http://www.opensource.org/">OSI-approved</ulink>
- <ulink url="http://www.gnu.org/copyleft/lesser.html">LGPL license</ulink>
- . Commercial development support,
- production support and training for JBoss Cache is available through
- <ulink url="http://www.jboss.com">JBoss, a division of Red Hat Inc</ulink>
- .
- </para>
+ <ulink url="http://www.gnu.org/copyleft/lesser.html">LGPL license.</ulink>
+ Commercial development support,
+ production support and training for JBo
+ s avai able through
+ <ulink url="http://www.jboss.com">JBos
+ s, a div
+ Red Ha
+ /ulink
+
+ /para>
<para>
- JBoss Cache is a part of the JBoss Professional Open Source
- <ulink url="http://www.jboss.com/products/index">JEMS</ulink>
- (JBoss Enterprise Middleware Suite).
+ JBoss Cache is a part of the J
+ ssiona Open Source
+ <ulink url="http://www.j
+ boss.com
+ index">JEMS</ulink>
+ (JBoss
+ ise Mid
+ are Suite)
+
</para>
</section>
</chapter>
1.2 +234 -178 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.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- basic_api.xml 19 Jan 2007 17:01:00 -0000 1.1
+++ basic_api.xml 23 Jan 2007 03:04:03 -0000 1.2
@@ -1,180 +1,236 @@
<chapter id="api">
- <title>Basic API</title>
-
- <para>Here's some sample code before we dive into the API itself:</para>
-
- <programlisting>TreeCache tree = new TreeCache();
- tree.setClusterName("demo-cluster");
- tree.setClusterProperties("default.xml"); // uses defaults if not provided
- tree.setCacheMode(TreeCache.REPL_SYNC);
- tree.createService(); // not necessary, but is same as MBean lifecycle
- tree.startService(); // kick start tree cache
- tree.put("/a/b/c", "name", "Ben");
- tree.put("/a/b/c/d", "uid", new Integer(322649));
- Integer tmp = (Integer) tree.get("/a/b/c/d", "uid");
- tree.remove("/a/b");
- tree.stopService();
- tree.destroyService(); // not necessary, but is same as MBean lifecycle
- </programlisting>
-
- <para>The sample code first creates a
- <literal>TreeCache</literal>
- instance and then
- configures it. There is another constructor which accepts a number of
- configuration options. However, the
- <literal>TreeCache</literal>
- can be configured entirely
- from an XML file (shown later) and we don't recommend manual configuration
- as shown in the sample.
- </para>
-
- <para>The cluster name, properties of the underlying JGroups stack, and
- cache mode (synchronous replication) are configured first (a list of
- configuration options is shown later). Then we start the
- <literal>TreeCache</literal>
- . If
- replication is enabled, this will make the
- <literal>TreeCache</literal>
- join the cluster, and acquire initial state from an existing node.
- </para>
-
- <para>Then we add 2 items into the cache: the first element creates a node
- "a" with a child node "b" that has a child node "c". (
- <literal>TreeCache</literal>
- by default
- creates intermediary nodes that don't exist). The key "name" is then
- inserted into the "/a/b/c" node, with a value of "Ben".
- </para>
-
- <para>The other element will create just the subnode "d" of "c" because
- "/a/b/c" already exists. It binds the integer 322649 under key
- "uid".
- </para>
-
- <para>The resulting tree looks like this:</para>
-
- <figure>
- <title>Sample Tree Nodes</title>
-
+ <title>User API</title>
+ <section>
+ <title>API Classes</title>
+ <para>
<mediaobject>
<imageobject>
- <imagedata fileref="images/TreeNodeExample.gif"/>
+ <imagedata fileref="images/PublicAPI.png" format="PNG"/>
</imageobject>
</mediaobject>
- </figure>
- <para>The
- <literal>TreeCache</literal>
- has 4 nodes "a", "b", "c" and "d". Nodes "/a/b/c" has
- values "name" associated with "Ben" in its map, and node "/a/b/c/d"
- has values "uid" and 322649.
- </para>
+ The
+ <literal>Cache</literal>
+ interface is the primary mechanism for interacting with JBoss Cache. It is
+ constructed and optionally started using the
+ <literal>CacheFactory</literal>
+ . The
+ <literal>CacheFactory</literal>
+ allows you to create a
+ <literal>Cache</literal>
+ either from a
+ <literal>Configuration</literal>
+ object
+ or an XML file. Once you have a reference to a
+ <literal>Cache</literal>
+ , you can use it to look up
+ <literal>Node</literal>
+ objects in the tree structure, and store data in the tree.
+ </para>
+ </section>
+ <section>
+ <title>Creating and Starting the Cache</title>
+ <para>
+ Here is a simple example of using the API.
+ <programlisting>
+
+ // Let's start a cache using default config values.
+ // We could have created and configured a Configuration object to be passed in to the factory instead,
+ // or even passed in the name of an XML file (which would need to be available in the class path)
+ CacheFactory factory = DefaultCacheFactory.getInstance();
+
+ // The factory method used creates a cache with default settings, and starts it.
+ // There are many overloaded factory methods; see CacheFactory javadocs for details.
+ Cache cache = factory.createCache();
+
+ // All nodes in the tree structure are identified by Fqn objects.
+ Fqn peterGriffinFqn = Fqn.fromString("/griffin/peter");
+
+ // let's get a hold of the root node.
+ Node rootNode = cache.getRoot();
+
+ // and create a child
+ Node peterGriffin = rootNode.addChild(peterGriffinFqn);
+
+ // let's store some data in the node
+ peterGriffin.put("isCartoonCharacter", Boolean.TRUE);
+ peterGriffin.put("favouriteDrink", new Beer());
+
+ // some tests
+ assertTrue(peterGriffin.get("isCartroonCharacter"));
+ assertEquals(peterGriffinFqn, peterGriffin.getFqn());
+ assertTrue(rootNode.hasChild(peterGriffinFqn));
+
+ Set keys = new HashSet();
+ keys.add("isCartoonCharacter");
+ keys.add("favouriteDrink");
- <para>Each node can be retrieved by its absolute name (e.g. "/a/b/c") or
- by navigating from parent to children (e.g. navigate from "a" to "b", then
- from "b" to "c").
- </para>
+ assertEquals(keys, peterGriffin.getKeys());
- <para>The next method in the example gets the value associated with
- key="uid" in node "/a/b/c/d", which is the integer 322649.
- </para>
-
- <para>The remove() method then removes node "/a/b" and all subnodes
- recursively from the cache. In this case, nodes "/a/b/c/d", "/a/b/c" and
- "/a/b" will be removed, leaving only "/a".
+ cache.stop();
+ </programlisting>
</para>
+ </section>
- <para>Finally, the
- <literal>TreeCache</literal>
- is stopped. This will cause it to leave the
- cluster, and every node in the cluster will be notified. Note that
- <literal>TreeCache</literal>
- can be stopped and started again. When it is stopped, all
- contents will be deleted. And when it is restarted, if it joins a cache
- group, the state will be replicated initially. So potentially you can
- recreate the contents.
- </para>
+ <section>
+ <title>Cache Modes</title>
+ <para>
+ JBoss Cache modes are denoted by the
+ <literal>org.jboss.cache.config.Configuration.CacheMode</literal>
+ enumeration.
+ They comprise of:
+ <itemizedlist>
+ <listitem>
+ <emphasis>LOCAL</emphasis>
+ - local, non-clustered cache. Local caches don't join a cluster and don't
+ communicate with other caches in a cluster. Therefore their contents don't need to be Serializable;
+ however, we recommend making them Serializable, allowing you the flexibility to change the cache mode at
+ any time.
+ </listitem>
+ <listitem>
+ <emphasis>REPL_SYNC</emphasis>
+ - synchronous replication. Replicated caches replicate all changes to the other
+ caches in the cluster. Synchronous replication means that changes are replicated and the caller blocks
+ until replication acknowledgements are received.
+ </listitem>
+ <listitem>
+ <emphasis>REPL_ASYNC</emphasis>
+ - asynchronous replication. Similar to REPL_SYNC above, replicated caches replicate
+ all changes to the other caches in the cluster. Being asynchronous, the caller does not block until
+ replication acknowledgements are received.
+ </listitem>
+ <listitem>
+ <emphasis>INVALIDATION_SYNC</emphasis>
+ - if a cache is configured for invalidation rather than replication,
+ every time data is changed in a cache other caches in the cluster
+ receive a message informing them that their data is now stale and should
+ be evicted from memory. This reduces replication overhead while still being able to invalidate stale data
+ on
+ remote caches.
+ </listitem>
+ <listitem>
+ <emphasis>INVALIDATION_ASYNC</emphasis>
+ - as above, except this invalidation mode causes invalidation messages
+ to be broadcast asynchronously.
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section>
+ <title>
+ Adding a CacheListener
+ </title>
+ <para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/Listeners.png" format="PNG"/>
+ </imageobject>
+ </mediaobject>
+ The
+ <literal>org.jboss.cache.CacheListener</literal>
+ interface is a convenient mechanism for receiving notifications from a Cache
+ about events that happen in the Cache. The interface may be implemented directly, or as a convenience,
+ <literal>org.jboss.cache.AbstractCacheListener</literal>
+ can be extended.
+ <literal>AbstractCacheListener</literal>
+ implements all the methods in
+ <literal>CacheListener</literal>
+ as no-ops, so you could just override the callbacks
+ that you are interested in.
+ <programlisting>
+
+ CacheListener myListener = new AbstractCacheListener()
+ {
+ public void nodeCreated(Fqn fqn, boolean pre, boolean isLocal)
+ {
+ System.out.println("Node " + fqn + (pre ? "is about to be created" : "has been created"));
+ }
+ };
- <para>In the sample, replication was enabled, which caused the 2 put() and
- the 1 remove() methods to replicated their changes to all nodes in the
- cluster. The get() method was executed on the local cache only.
- </para>
+ cache.addCacheListener(myListener);
- <para>Keys into the cache can be either strings separated by slashes
- ('/'), e.g. "/a/b/c", or they can be fully qualified names Fqns . An Fqn
- is essentially a list of Objects that need to implement hashCode() and
- equals(). All strings are actually transformed into Fqns internally. Fqns
- are more efficient than strings, for example:
- </para>
+ assertTrue(cache.getCacheListeners().contains(myListener));
- <programlisting>String n1 = "/300/322649";
- Fqn n2 = new Fqn(new Object{new Integer(300), new Integer(322649)});
</programlisting>
+ </para>
+ </section>
- <para>In this example, we want to access a node that has information for
- employee with id=322649 in department with id=300. The string version
- needs two map lookups on Strings, whereas the Fqn version needs two
- map lookups on Integers. In a large hashtable, the hashCode() method
- for String may have collisions, leading to actual string comparisons.
- Also, clients of the cache may already have identifiers for their objects
- in Object form, and don't want to transform between Object and Strings,
- preventing unnecessary copying.
- </para>
-
- <para>Note that the modification methods are put() and remove(). The only
- get method is get().
- </para>
-
- <para>There are 2 put() methods
- <footnote>
- <para>Plus their equivalent helper methods taking a String as node
- name.
- </para>
- </footnote>
- :
- <literal>put(Fqn node, Object key, Object key)</literal>
- and
- <literal>put(Fqn node, Map values)</literal>
- . The former takes the
- node name, creates it if it doesn't yet exist, and put the key and value
- into the node's map, returning the previous value. The latter takes a
- map of keys and values and adds them to the node's map,
- overwriting existing keys and values. Content that is not in the new
- map remains in the node's map.
- </para>
-
- <para>There are 3 remove() methods:
- <literal>remove(Fqn node, Object
- key)
- </literal>
- ,
- <literal>remove(Fqn node)</literal>
- and
- <literal>removeData(Fqn node)</literal>
- . The first removes the given key
- from the node. The second removes the entire node and all subnodes, and
- the third removes all elements from the given node's map.
- </para>
-
- <para>The get methods are:
- <literal>get(Fqn node)</literal>
- and
- <literal>get(Fqn node, Object key)</literal>
- . The former returns a
- Node
- <footnote>
- <para>This is mainly used internally, and we may decide to remove
- public access to the Node in a future release.
- </para>
- </footnote>
- object, allowing for direct navigation, the latter returns
- the value for the given key for a node.
- </para>
-
- <para>Also, the
- <literal>TreeCache</literal>
- has a number of getters and setters. Since the
- API may change at any time, we recommend the Javadoc for up-to-date
- information.
+ <section>
+ <title>Using Cache Loaders</title>
+ <para>
+ CacheLoaders are an important part of JBoss Cache. They allow persistence of nodes to disk or to remote cache
+ clusters, and allow for passivation when caches run out of memory. In addition, CacheLoaders allow JBoss Cache
+ to perform 'warm starts', where in-memory state can be preloaded from persistent storage. JBoss Cache ships
+ with a number of CacheLoader implementations.
+ <itemizedlist>
+ <listitem>
+ <literal>org.jboss.cache.loader.FileCacheLoader</literal>
+ - a basic, filesystem based cache loader that persists data to disk. Non-transactional and not very
+ performant, but a very simple solution.
+ </listitem>
+ <listitem>
+ <literal>org.jboss.cache.loader.JDBCCacheLoader</literal>
+ - uses a JDBC connection to store data. Connections could be created and maintained in an internal pool,
+ or from a configured DataSource. The database this CacheLoader connects to could be local or remotely
+ located.
+ </listitem>
+ <listitem>
+ <literal>org.jboss.cache.loader.BdbjeCacheLoader</literal>
+ - uses Oracle's BerkeleyDB file-based transactional database to persist data. Transactional and very
+ performant, but potentially restrictive license.
+ </listitem>
+ <listitem>
+ <literal>org.jboss.cache.loader.JdbmCacheLoader</literal>
+ - an upcoming open source alternative to the BerkeleyDB.
+ </listitem>
+ <listitem>
+ <literal>org.jboss.cache.loader.tcp.TcpCacheLoader</literal>
+ - uses a TCP socket to "persist" data to a remote cluster, using a "far cache" pattern.
+ </listitem>
+ <listitem>
+ <literal>org.jboss.cache.loader.ClusteredCacheLoader</literal>
+ - used as a "read-only" CacheLoader, where other nodes in the cluster are queried for state.
+ </listitem>
+ </itemizedlist>
+ These CacheLoaders, along with advanced aspects and tuning issues, are discussed in the
+ <link linkend="cache_loaders">chapter dedicated to CacheLoaders</link>
+ .
+ </para>
+ </section>
+
+ <section>
+ <title>Using Eviction Policies</title>
+ <para>
+ Eviction policies are the counterpart to CacheLoaders. They are necessary to make sure the cache does not run
+ out of memory and when the cache starts to fill,
+ the eviction algorithm running in a separate thread offloads in-memory state to the CacheLoader and frees up
+ memory. Eviction policies can be configured
+ on a per-region basis, so different subtrees in the cache could have different eviction preferences.
+
+ JBoss Cache ships with several eviction policies:
+ <itemizedlist>
+ <listitem>
+ <literal>org.jboss.cache.eviction.LRUPolicy</literal>
+ - an eviction policy that evicts the least recently used nodes when thresholds are hit.
+ </listitem>
+ <listitem>
+ <literal>org.jboss.cache.eviction.LFUPolicy</literal>
+ - an eviction policy that evicts the least frequently used nodes when thresholds are hit.
+ </listitem>
+ <listitem>
+ <literal>org.jboss.cache.eviction.MRUPolicy</literal>
+ - an eviction policy that evicts the most recently used nodes when thresholds are hit.
+ </listitem>
+ <listitem>
+ <literal>org.jboss.cache.eviction.FIFOPolicy</literal>
+ - an eviction policy that creates a first-in-first-out queue and evicts the oldest nodes when thresholds
+ are hit.
+ </listitem>
+ </itemizedlist>
+ Detailed configuration and implementing custom eviction policies are discussed in the
+ <link linkend="eviction_policies">chapter dedicated to eviction policies.</link>
+ .
</para>
+ </section>
</chapter>
\ No newline at end of file
More information about the jboss-cvs-commits
mailing list