[jboss-cvs] JBossCache/docs/tutorial/en ...
Manik Surtani
manik at jboss.org
Tue Apr 17 03:45:14 EDT 2007
User: msurtani
Date: 07/04/17 03:45:14
Modified: docs/tutorial/en master.xml
Log:
Rewrote tutorial
Revision Changes Path
1.17 +289 -374 JBossCache/docs/tutorial/en/master.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: master.xml
===================================================================
RCS file: /cvsroot/jboss/JBossCache/docs/tutorial/en/master.xml,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -b -r1.16 -r1.17
--- master.xml 23 Oct 2006 17:51:38 -0000 1.16
+++ master.xml 17 Apr 2007 07:45:14 -0000 1.17
@@ -3,35 +3,34 @@
<articleinfo>
<title>JBoss Cache core Cache Tutorial</title>
<releaseinfo>Release 2.0.0</releaseinfo>
- <pubdate>January 2007</pubdate>
- <author>
- <firstname>Ben</firstname>
- <surname>Wang</surname>
- <email>ben.wang at jboss.com</email>
- </author>
+ <pubdate>June 2007</pubdate>
<author>
- <firstname>Bela</firstname>
- <surname>Ban</surname>
- <email>bela at jboss.com</email>
+ <firstname>Manik</firstname>
+ <surname>Surtani</surname>
+ <email>manik at jboss.org</email>
</author>
</articleinfo>
<section>
<title>Introduction</title>
- <para>JBoss Cache is an in-memory replicated (synchronous or
- asynchronous), transactional, and fine-grained cache. It consists of two subsystems:
- Cache (generic cache) and PojoCache (object-oriented POJO cache).
- In this tutorial, we will demonstrate the usage of generic Cache feature.
- For details of the usage and APIs, please
- refer to the user manuals for <ulink
- url="http://labs.jboss.org/portal/jbosscache/docs/index.html">Cache</ulink>. There is a separate
- tutorial on PojoCache.</para>
+ <para>
+ JBoss Cache is an in-memory replicated, transactional, and fine-grained cache.
+ This tutorial focuses on the core Cache API. Please refer to the accompanying tutorial
+ for the Pojo Cache API if it is the Pojo Cache API you are interested in.
+ </para>
+ <para>
+ For details of configuration, usage and APIs, please refer to the
+ <ulink
+ url="http://labs.jboss.org/portal/jbosscache/docs/index.html">user manuals
+ </ulink>
+ .
+ </para>
</section>
<section>
- <title>Scope</title>
+ <title>What You Will Learn</title>
<itemizedlist>
<listitem>
@@ -39,15 +38,11 @@
</listitem>
<listitem>
- <para>Replication</para>
- </listitem>
-
- <listitem>
- <para>Transaction</para>
+ <para>Replication of state</para>
</listitem>
<listitem>
- <para>Cache loader</para>
+ <para>Transactions</para>
</listitem>
</itemizedlist>
</section>
@@ -55,33 +50,41 @@
<section>
<title>Configuration</title>
- <para>First download the standalone JBoss Cache (2.x) code from <ulink
- url="http://labs.jboss.org/portal/jbosscache/download/index.html">here</ulink>.
- Unzip it, and you will get a root directory (jboss-cache in our
- example).</para>
-
- <para>The configuration files are located under the etc directory. You can
- modify the behavior of Cache through editing the various configuration
- files.</para>
+ <para>First download the JBoss Cache 2.x distribution from
+ <ulink
+ url="http://labs.jboss.org/portal/jbosscache/download/index.html">the download page
+ </ulink>
+ . You probably want the
+ <literal>JBossCache-core-2.X.Y.zip</literal>
+ distribution.
+ Unzip it, and you will get a directory containing the distribution, such as
+ <literal>JBossCache-core-2.X.Y</literal>
+ .
+ For the sake of this tutorial, I will refer to this as
+ <literal>JBossCache</literal>
+ .
+ </para>
+
+ <para>The configuration files are located in the
+ <literal>JBossCache/etc</literal>
+ directory. You can
+ modify the behavior of the cache by editing the various configuration files.
+ </para>
<itemizedlist>
<listitem>
- <para><literal>log4j.xml</literal>. Logging output. You can turn on logging level or
- change log file directory (default is
- <literal>/tmp/jbosscache.log</literal>).</para>
+ <para>
+ <literal>log4j.xml</literal>
+ . Logging output. You can enable logging, specify log levels or
+ change the name and path to the log file.
+ </para>
</listitem>
<listitem>
- <para><literal>replSync-service.xml</literal>. Cache configuration file (file name
- is not fixed. You specify the file to be read in the
- <literal>Configuration</literal>). The settings are for a
- replicated, synchronous, and transactional cache. The default
- DummyTransactionManager is used with a transaction isolation level of
- REPEATABLE_READ. For details of the configuration parameters, please
- refer to the <ulink url="http://www.jboss.org/products/jbosscache/docs">Cache</ulink>. Note that
- this file is used in the BSH (<ulink
- url="http://www.beanshell.org/">BeanShell</ulink>, a lightweight Java
- compatible scripting language) script to configure the cache.</para>
+ <para>
+ <literal>META-INF/replSync-service.xml</literal>
+ . Cache configuration file used for this tutorial.
+ </para>
</listitem>
</itemizedlist>
</section>
@@ -89,289 +92,201 @@
<section>
<title>Script</title>
- <para>The script files that are needed (located under the installed directory)
- in this tutorial are:</para>
+ <para>The only script needed for this tutorial is the
+ <literal>JBossCache/build.xml</literal>
+ ant script and the accompanying
+ driver scripts (
+ <literal>build.sh</literal>
+ for Unix and
+ <literal>build.bat</literal>
+ for Windows).
+ </para>
+ </section>
+
+ <section>
+ <title>Running The Demo GUI</title>
+ <para>
+ The demo is run by calling the ant script (via the driver) with the
+ <literal>run.demo</literal>
+ target. E.g.,
+ </para>
+
+ <para>
+ <literal>./build.sh run.demo</literal>
+ </para>
+ <para>
+ This will cause a GUI window to appear, giving you a tree view of the cache in the top pane and a BeanShell
+ view
+ of the JVM in the lower pane.
+ </para>
+ <para>
+ The BeanShell view is preset with the following variables:
<itemizedlist>
<listitem>
- <para><literal>build.sh</literal> (or <literal>build.bat</literal> for DOS/Windows). Simple build script that wraps
- around ant. Users can simply type <literal>sh build.sh</literal> for
- help. Note from now on, we will only refer to the Unix version with
- the understanding that there is a corresponding DOS counterpart. The
- same goes for runDemoShell explained next.</para>
- </listitem>
-
- <listitem>
- <para><literal>runDemoShell.sh</literal>. Simple run script that wraps around BeanShell.
- This is used to operate the replicated cache through interactive
- command line.</para>
+ <literal>cache</literal>
+ - a reference to the Cache interface, used by the GUI instance.
</listitem>
-
<listitem>
- <para><literal>plain.bsh</literal>. Java code that instantiate and configure the cache.
- It also creates an example cache entry.</para>
+ <literal>root</literal>
+ - a reference to the root Node instance for the above cache.
</listitem>
-
<listitem>
- <para><literal>oodb.bsh</literal>. Java code that instantiate and configure the cache to use
- cache loader.</para>
+ <literal>transactionManager</literal>
+ - a reference to the registered transaction manager.
</listitem>
</itemizedlist>
+ The references made available to the BeanShell window point to the same cache instance used by the tree view in
+ the
+ GUI above.
+ </para>
+
+ <para>
+ To run the demo as a replicated demo, it is useful to start another command line window and run the ant script
+ again as you did above. Now you will have two cache instances running in two separate GUIs, replicating state
+ to
+ each other.
+ </para>
+
</section>
<section>
- <title>Demo</title>
+ <title>Tutorials</title>
+ Note that it is recommended that you shut down and restart the demo GUI for each of the following tutorials, to
+ ensure
+ clean caches every time.
+ <section>
+ <title>Caches and Nodes</title>
+ <para>
+ For this tutorial, start a single instance of the demo GUI. In this tutorial, we will:
- <para>To run the demo, you will need at least two windows: one to peruse
- the cache contents and the other to operate the
- cache directly. Of course, you can also open more than one GUI window to
- see the cache replication at work to multiple members. You will also need
- to run the scripts under jboss-cache installation directory after you
- unzip the release package (jboss-cache-dist.zip). Due to the limitation of the
- GUI, please note that:</para>
<itemizedlist>
- <listitem>For each
- demo example, it'd be best if you re-start the whole setup.</listitem>
+ <listitem>Create nodes under the root node.</listitem>
+ <listitem>Remove nodes under the root node, both individually and recursively.</listitem>
+ <listitem>Add and remove data from nodes.</listitem>
</itemizedlist>
- <para>The two demo programs to run are:</para>
+ <orderedlist>
+ <listitem>Set up the Fqns you need. In the BeanShell pane, create 3 Fqn variables:
+ <programlisting><![CDATA[
+
+ childFqn1 = Fqn.fromString("/child1");
+ childFqn2 = Fqn.fromString("/child2");
+ childFqn3 = Fqn.fromString("/child2/child3");
+
+ ]]></programlisting>
+ </listitem>
- <itemizedlist>
<listitem>
- <para>On the first window for the GUI, type <literal>sh
- build.sh</literal> to see the available commands. To run the GUI, type
- <literal>sh build.sh run.demo</literal>. It will startup a
- Cache GUI. Later on, you can click on a node to view the the
- contents. Note that you can also add/modify the node contents for
- generic cache entries. Since the GUI entry only accepts String for
- now, operation on aop cache from the GUI will not always work (unless
- it is a String type).</para>
+ Create child nodes under the root node.
+ <programlisting><![CDATA[
+
+ child1 = root.addChild(child1);
+ child2 = root.addChild(child2);
+ child3 = root.addChild(child3);
+
+ ]]></programlisting>
</listitem>
<listitem>
- <para>On the second window for the interactive Java commands, type sh
- runShellDemo.sh to fire off the BeanShell interactive command shell
- (you can use either ^D or ^Z in Windows and Unix to exit afterward).
- You can then read in the Java code scripts to showcase the cache
- capabilities (e.g., plain.bsh). See the
- following for details.</para>
+ Query the nodes
+ <programlisting><![CDATA[
+
+ root.hasChild(child1); // should return true
+ child2.hasChild(childFqn3.getLastElement()); // should return true
+ child3.getParent(); // should return child2
+ child2.getParent(); // should return root
+
+ ]]></programlisting>
</listitem>
- </itemizedlist>
- </section>
- <section>
- <title>Plain cache</title>
- <para>Once you are in the shell, you can either execute the script to
- populate the cache, or type it in manually by command line. To run the
- script, type <literal>sourceRelative("plain.bsh");</literal> under the
- interactive BSH shell. For this to work, you'll need to have your working
- directory set to the directory in which plain.bsh resides (otherwise give
- the full pathname of plain.bsh). Basically, the script will create cache
- entries that will be replicated onto the GUI. (You may have to type show() into
- the resulting beanshell window yourself)
- Here are the snippets for
- the script:</para>
-
- <programlisting>import org.jboss.cache.*;
-show(); // verbose mode for bean shell
-// This will start the cache automatically
-Cache cache = new DefaultCacheFactory().createCache("META-INF/replSync-service.xml");
-
-cache.put(Fqn.fromString("/a/b/c"), "key1", "val1");
-// Node "/a/b/c" will be created if not yet existed.</programlisting>
-
- <para>You should see in the GUI that a new entry of
- <literal>/a/b/c</literal> has been created. Click on the node c to see the
- content. You can modify the contents from the GUI as well. To create
- another node, for example, you can type in the shell:</para>
+ <listitem>
+ Put some data in the nodes.
+ <programlisting><![CDATA[
- <programlisting>tree.put(Fqn.fromString("/a/b/c/d"), "JBoss", "Open Source");
-tree.get(Fqn.fromString("/a/b/c/d"), "JBoss");</programlisting>
- </section>
+ child1.put("key1", "value1");
+ child1.put("key2", "value2");
+ child2.put("key3", "value3");
+ child2.put("key4", "value4");
+ child3.put("key5", "value5");
+ child3.put("key6", "value6");
- <section>
- <title>CacheLoader examples</title>
+ ]]></programlisting>
- <para>All the examples below are based on the JBossCache standalone
- distribution. We assume the ZIP file has been unzipped into a directory
- <literal>jboss-cache</literal>.</para>
+ By selecting the nodes in the tree view, you should see the contents of each node.
+ </listitem>
- <section>
- <title>Replicated cache with shared datastore</title>
+ <listitem>
+ Query some of the data.
- <para>The scenario that we'll run in this example is described in the
- documentation for JBossCache. It consists of 2 separate nodes that
- replicate their contents between each other. In addition, they both
- point to the <emphasis>same</emphasis> datastore. The configuration is
- in file
- <literal>jboss-cache/output/etc/META-INF/replAsyncSharedCacheLoader-service.xml</literal>:</para>
-
- <programlisting><!-- Whether or not to fetch state on joining a cluster -->
-<attribute name="FetchStateOnStartup">false</attribute>
-<attribute name="CacheLoaderClass">org.jboss.cache.loader.FileCacheLoader</attribute>
-<attribute name="CacheLoaderConfig">
- location=c:\\tmp
-</attribute>
-<attribute name="CacheLoaderShared">true</attribute>
-<attribute name="CacheLoaderPreload">/</attribute>
-<attribute name="CacheLoaderFetchTransientState">false</attribute>
-<attribute name="CacheLoaderFetchPersistentState">true</attribute></programlisting>
-
- <para>The <literal>FetchStateOnStartup</literal> attribute set to
- <literal>false</literal> means that a newly started cache will
- <emphasis>not</emphasis> attempt to fetch the state (neither transient
- nor persistent). Therefore, attributes
- <literal>CacheLoaderFetchTransientState</literal> and
- <literal>CacheLoaderFetchPersistentState</literal> will be ignored.
- <literal>CacheLoaderShared</literal> set to <literal>true</literal>
- means that both nodes will share the same datastore, which resides in
- <literal>c:\tmp</literal> in the example (this assumes that both nodes
- have access to the same file system). Please make sure that
- <literal>c:\tmp</literal> exists, or point the config string to a
- different existing directory.</para>
-
- <para>This configuration would essentially provide for two
- <literal>cold</literal> nodes, in the sense that all contents of a new
- cache is in the datastore, and is lazy-loaded via the CacheLoader when
- accessed. However, this is not true, as
- <literal>CacheLoaderPreload</literal> points to "/", which is the root
- of the entire tree. Therefore, all of the contents of the cache are
- recursively pre-loaded. This is probably a bad configuration when you
- have a lot of data in the cache, because <emphasis>all</emphasis> of
- your data will be loaded into the cache.</para>
-
- <para>Note that with a shared datastore, the node that makes a
- modification is the one who writes it to the store using the
- CacheLoader. This prevents both nodes from writing the same data
- twice.</para>
-
- <para>We can now start 2 instances by opening two shells and executing
- the following ANT target:</para>
-
- <programlisting>bela at laptop /cygdrive/c/jboss-cache
-$ ./build.sh run.demo.async.shared.cacheloader
-Buildfile: build.xml
-
-init:
-
-compile:
-
-run.demo.async.shared.cacheloader:
- [java] ** node loaded: /a
- [java] ** node loaded: /a/b
- [java] ** node loaded: /a/b/c
- [java] ** node loaded: /uno
- [java] ** node loaded: /uno/due
-
- [java] -------------------------------------------------------
- [java] GMS: address is 192.168.1.184:1357
- [java] -------------------------------------------------------
- [java] interceptor chain is:
- [java] class org.jboss.cache.interceptors.CallInterceptor
- [java] class org.jboss.cache.interceptors.ReplicationInterceptor
- [java] class org.jboss.cache.interceptors.CacheLoaderInterceptor
- [java] class org.jboss.cache.interceptors.TransactionInterceptor
- [java] ** view change: [192.168.1.184:1355|1] [192.168.1.184:1355, 192.168.1.184:1357]
- [java] ** node modified: /
-</programlisting>
-
- <para>2 GUI instances will appear, showing the tree structure of the
- cache graphically. Nodes can be added, modified or removed by
- right-clicking or using the menu. Any modification is replicated between
- the two nodes. If both nodes are killed, and subsequently one or both
- nodes are restarted, the state is the same as before shutdown as it was
- persisted to the shared store via the CacheLoader.</para>
+ <programlisting><![CDATA[
- <para>Note that the example above shows the 2 nodes running on the same
- machine (192.168.1.184) on ports 1355 and 1357.</para>
- </section>
+ child1.getKeys();
+ child2.getData();
- <section>
- <title>Replicated cache with unshared (local) datastore</title>
+ ]]></programlisting>
+ </listitem>
- <para>In this example, we'll run 2 nodes again, but this time, instead
- of sharing the same datastore, each node has its own datastore. The
- configuration is in file
- <literal>jboss-cache/output/etc/META-INF/node{1,2}.xml</literal>. We'll
- look at node1.xml:</para>
-
- <programlisting><attribute name="CacheLoaderClass">org.jboss.cache.loader.bdbje.BdbjeCacheLoader</attribute>
-<attribute name="CacheLoaderConfig">
- location=c:\\tmp\\node1
-</attribute>
-<attribute name="CacheLoaderShared">false</attribute>
-<attribute name="CacheLoaderPreload">/</attribute>
-<attribute name="CacheLoaderFetchTransientState">false</attribute>
-<attribute name="CacheLoaderFetchPersistentState">true</attribute>
-</programlisting>
-
- <para>Again, we use the Sleepycat CacheLoader implementation in
- <literal>CacheLoaderClass</literal>. The
- <literal>CacheLoaderConfig</literal> points to
- <literal>c:\tmp\node1</literal>. This is the directory in which the
- Sleepycat DB for node1 will reside. File node2.xml has a configuration
- that points to <literal>c:\tmp\node2</literal>, so we have 2 different
- unshared datastores. Note that, of course, we still have the same
- filesystem in our case, because we run the 2 nodes on the same machine.
- In practice those two directories would reside on two different
- machines, and each machine would run one JBossCache process. Note that
- the 2 directories have to exis</para>
-
- <para>To create an unshared datastore, we set the
- <literal>CacheLoaderShared</literal> attribute to
- <literal>false</literal>.</para>
-
- <para>The example can be run by again opening 2 shells, and running 2
- ANT targets (here we show the target for node1):</para>
-
- <programlisting>bela at laptop /cygdrive/c/jboss-cache
-$ ./build.sh run.demo.unshared.node2
-Buildfile: build.xml
-
-init:
-
-compile:
-
-run.demo.unshared.node2:
- [java] ** node loaded: /a
- [java] ** node loaded: /a/a2
-...</programlisting>
-
- <para>The <literal>run.demo.unshared.node2</literal> target runs node2,
- which will have its own store located at <literal>c:\tmp\node2</literal>
- (shown above). Whenever a change is made on either of the 2 nodes, it is
- replicated to the other node, and persisted in both local datastores.
- You can kill and restart a node, or even both nodes, and the data will
- still be available due to the persistent backend store(s).</para>
- </section>
- </section>
- <section>
- <title>Troubleshooting</title>
+ <listitem>
+ Remove some data in the nodes.
- <para>Here are some tips for troubleshooting, if you encounter problems
- during this demo.</para>
+ <programlisting><![CDATA[
+
+ child1.remove("key1");
+ child2.remove("key3");
+ child3.clearData();
+
+ ]]></programlisting>
+ </listitem>
- <itemizedlist>
<listitem>
- <para>Most of the time, the problem will come from cache replication
- layer, i.e., JGroups package. On the output window, you can see the
- JGroups membership view. See if it is updated when you run the BSH
- commands. It should show a view with at least two members. For
- example, on my window, I see</para>
-
- <programlisting> [java] ** view change: [BWANG-HOME:4381|1] [BWANG-HOME:4381, BWANG-HOME:4383]</programlisting>
-
- <para>with 2 members: 4381 and 4383. On the other hand, if you don't
- close the previous running cache instance, the membership view will
- also include the previous existing ones. This can corrupt the states.
- So you will have to make sure there is no running TreeCache processes
- before each demo. If you have problem with this, please consult the
- <ulink
- url="http://www.jgroups.org/javagroupsnew/docs/index.html">JGroups
- website</ulink>.</para>
+ Delete nodes
+
+ <programlisting><![CDATA[
+
+ root.removeChild(childFqn1); // will also remove any data held under child1
+ root.removeChild(childFqn2); // will recursively remove child3 as well.
+
+ ]]></programlisting>
</listitem>
- </itemizedlist>
+
+ </orderedlist>
+
+ In addition to the above, you should refer to the
+ <literal>Cache</literal>
+ and
+ <literal>Node</literal>
+ <ulink
+ url="http://labs.jboss.org/portal/jbosscache/docs/index.html">API docs
+ </ulink>
+ and try out the APIs in the BeanShell script.
+ </para>
</section>
+
+ <section>
+ <title>Replication</title>
+ <para>
+ For this tutorial, start two instances instance of the demo GUI. Repeat the exercises in the previous
+ tutorial,
+ only alternating between the two GUI windows when creating/removing nodes or adding/removing data. This
+ demonstrates
+ how the two cache instances in the two GUIs are kept in sync.
+ </para>
+ </section>
+
+ <section>
+ <title>Transactions</title>
+ <para>
+ For this tutorial, start two instances instance of the demo GUI. Repeat the exercises in the previous
+ tutorial,
+ only starting transactions before creating/removing nodes or adding/removing data. This will depict how
+ replication only occurs on transaction boundaries. Try rolling back a few transactions as well, to see how
+ nothing gets replicated in these cases.
+ </para>
+ </section>
+
+ </section>
+
</article>
More information about the jboss-cvs-commits
mailing list