[jboss-cvs] JBossCache/docs/JBossCache-UserGuide/en/modules ...
Brian Stansberry
brian.stansberry at jboss.com
Wed May 30 15:41:15 EDT 2007
User: bstansberry
Date: 07/05/30 15:41:15
Modified: docs/JBossCache-UserGuide/en/modules basic_api.xml
Log:
Add to API docs in prep for Configuration docs
Revision Changes Path
1.8 +229 -26 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.7
retrieving revision 1.8
diff -u -b -r1.7 -r1.8
--- basic_api.xml 30 Apr 2007 17:36:48 -0000 1.7
+++ basic_api.xml 30 May 2007 19:41:14 -0000 1.8
@@ -28,37 +28,101 @@
</mediaobject>
</para>
+
+ <para>
+ Reviewing the javadoc for the above interfaces is the best way
+ to learn the API. Below we cover some of the main points.
+ </para>
</section>
+
<section>
<title>Creating and Starting the Cache</title>
<para>
- Here is a simple example of using the API.
+ 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:
+ <itemizedlist>
+ <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="congfiguration">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>
+ </itemizedlist>
+ </para>
+
+ <para>
+ An example of the simplest mechanism for creating and starting
+ a cache, using the default configuration values:
+ </para>
+
<programlisting>
+ CacheFactory factory = DefaultCacheFactory.getInstance();
+ Cache cache = factory.createCache();
+ </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)
+ <para>Here we tell the <literal>CacheFactory</literal> to find and
+ parse a configuration file on the classpath:
+ </para>
+
+ <programlisting>
CacheFactory factory = DefaultCacheFactory.getInstance();
+ Cache cache = factory.createCache("cache-configuration.xml");
+ </programlisting>
- // 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("/cache-configuration.xml");
+ <para>Here we configure the cache from a file, but want to programatically
+ change a configuration element. So, we tell the factory not to start
+ the cache, and instead do it ourselves:
+ </para>
- // All nodes in the tree structure are identified by Fqn objects.
- Fqn peterGriffinFqn = Fqn.fromString("/griffin/peter");
+ <programlisting>
+ CacheFactory factory = DefaultCacheFactory.getInstance();
+ Cache cache = factory.createCache("cache-configuration.xml", false);
+ Configuration config = cache.getConfiguration();
+ config.setClusterName(this.getClusterName());
+
+ // Have to create and start cache before using it
+ cache.create();
+ cache.start();
+ </programlisting>
+
+ </section>
- // let's get a hold of the root node.
+ <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
+ simple reads and writes to that node.
+ </para>
+ <programlisting>
+ // Let's get ahold of the root node.
Node rootNode = cache.getRoot();
- // and create a child
+ // Remember, JBoss Cache stores data in a tree structure.
+ // All nodes in the tree structure are identified by Fqn objects.
+ Fqn peterGriffinFqn = Fqn.fromString("/griffin/peter");
+
+ // Create a new Node
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"));
+ // some tests (just assume this code is in a JUnit test case)
+ assertTrue(peterGriffin.get("isCartoonCharacter"));
assertEquals(peterGriffinFqn, peterGriffin.getFqn());
assertTrue(rootNode.hasChild(peterGriffinFqn));
@@ -68,18 +132,151 @@
assertEquals(keys, peterGriffin.getKeys());
+ // let's remove some data from the node
+ peterGriffin.remove("favouriteDrink");
+
+ assertNull(peterGriffin.get("favouriteDrink");
+
+ // let's remove the node altogether
+ rootNode.removeChild(peterGriffinFqn);
+
+ assertFalse(rootNode.hasChild(peterGriffinFqn));
+ </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:
+ </para>
+
+ <programlisting>
+ Fqn peterGriffinFqn = Fqn.fromString("/griffin/peter");
+
+ cache.put(peterGriffinFqn, "isCartoonCharacter", Boolean.TRUE);
+ cache.put(peterGriffinFqn, "favouriteDrink", new Beer());
+
+ assertTrue(peterGriffin.get(peterGriffinFqn, "isCartoonCharacter"));
+ assertTrue(cache.getRootNode().hasChild(peterGriffinFqn));
+
+ cache.remove(peterGriffinFqn, "favouriteDrink");
+
+ assertNull(cache.get(peterGriffinFqn, "favouriteDrink");
+
+ cache.removeNode(peterGriffinFqn);
+
+ assertFalse(cache.getRootNode().hasChild(peterGriffinFqn));
+ </programlisting>
+ </section>
+
+ <section id="basic_api.fqn">
+ <title>The <literal>Fqn</literal> Class</title>
+
+ <para>
+ 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.
+ </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>.
+ </para>
+
+ <para>
+ 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>
+
+ <programlisting>
+ <![CDATA[
+ // Create an Fqn pointing to node 'Joe' under parent node 'Smith'
+ // under the 'people' section of the tree
+
+ // Parse it from a String
+ Fqn<String> abc = Fqn.fromString("/people/Smith/Joe/");
+
+ // Build it directly. A bit more efficient to construct than parsing
+ String[] strings = new String[] { "people", "Smith", "Joe" };
+ Fqn<String> abc = new Fqn<String>(strings);
+
+ // Here we want to use types other than String
+ Object[] objs = new Object[]{ "accounts", "NY", new Integer(12345) };
+ Fqn<Object> acctFqn = new Fqn<Object>(objs);
+ ]]>
+ </programlisting>
+
+ <para>Note that</para>
+ <para>
+ <programlisting><![CDATA[Fqn<String> f = new Fqn<String>("/a/b/c");]]></programlisting>
+ </para>
+ <para>is <emphasis>not</emphasis> the same as</para>
+ <para>
+ <programlisting><![CDATA[Fqn<String> f = Fqn.fromString("/a/b/c");]]></programlisting>
+ </para>
+
+ <para>
+ The former will result in an Fqn with a single element, called "/a/b/c"
+ which hangs directly under the cache root. The latter will result
+ 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
+ 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
+ such convenience methods are available in the JBC 2.x API.
+ </para>
+
+ </section>
+
+ <section>
+ <title>Stopping and Destroying the Cache</title>
+ <para>
+ It is good practice to stop and destroy your cache when you are done
+ using it, particularly if it is a clustered cache and has thus
+ used a JGroups channel. Stopping and destroying a cache ensures
+ resources like the JGroups channel are properly cleaned up.
+ </para>
+
+ <programlisting>
cache.stop();
+ cache.destroy();
</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).
</para>
</section>
<section>
<title>Cache Modes</title>
<para>
+ 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>
+ operation, so we'll briefly mention the various modes here.
+ </para>
+ <para>
JBoss Cache modes are denoted by the
<literal>org.jboss.cache.config.Configuration.CacheMode</literal>
enumeration.
- They comprise of:
+ They consist of:
<itemizedlist>
<listitem>
<emphasis>LOCAL</emphasis>
@@ -116,6 +313,11 @@
</listitem>
</itemizedlist>
</para>
+ <para>See the <link linkend="replication">chapter on Clustering</link> for
+ more details on how the cache's mode affects behavior. See the
+ <link linkend="congfiguration">chapter on Configuration</link> for info
+ on how to configure things like the cache's mode.
+ </para>
</section>
<section id="api.listener">
@@ -149,7 +351,8 @@
{
public void nodeCreated(Fqn fqn, boolean pre, boolean isLocal)
{
- System.out.println("Node " + fqn + (pre ? "is about to be created" : "has been created"));
+ System.out.println("Node " + fqn + (pre ? "is about to be created"
+ : "has been created"));
}
};
@@ -160,7 +363,7 @@
</programlisting>
Refer to the javadocs on the
- <literal>CacheLoader</literal>
+ <literal>CacheListener</literal>
interface for details on the parameters passed in
to each of the callback methods.
</para>
More information about the jboss-cvs-commits
mailing list