[jboss-cvs] JBossCache/docs/tutorial/en ...
Ben Wang
bwang at jboss.com
Wed Sep 27 04:03:33 EDT 2006
User: bwang
Date: 06/09/27 04:03:32
Modified: docs/tutorial/en master.xml
Log:
Separated PojoCache tutorial from Cache one.
Revision Changes Path
1.15 +41 -286 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.14
retrieving revision 1.15
diff -u -b -r1.14 -r1.15
--- master.xml 10 Jul 2006 14:50:02 -0000 1.14
+++ master.xml 27 Sep 2006 08:03:32 -0000 1.15
@@ -1,9 +1,9 @@
<?xml version="1.0" encoding="UTF-8"?>
<article lang="en">
<articleinfo>
- <title>JBossCache TreeCache and PojoCache Tutorial</title>
-<releaseinfo>Release 1.4.0 "Jalapeno"</releaseinfo>
- <pubdate>July 2006</pubdate>
+ <title>JBoss Cache core Cache Tutorial</title>
+<releaseinfo>Release 2.0</releaseinfo>
+ <pubdate>October 2006</pubdate>
<author>
<firstname>Ben</firstname>
<surname>Wang</surname>
@@ -20,14 +20,14 @@
<section>
<title>Introduction</title>
- <para>JBossCache is an in-memory replicated (synchronous or
+ <para>JBoss Cache is an in-memory replicated (synchronous or
asynchronous), transactional, and fine-grained cache. It consists of two subsystems:
- TreeCache (plaing cache) and PojoCache (object-oriented POJO cache).
- In this tutorial, we will demonstrate the usage of both cache features.
+ 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">TreeCache</ulink> and <ulink
- url="http://labs.jboss.org/portal/jbosscache/docs/index.html">PojoCache</ulink>.</para>
+ url="http://labs.jboss.org/portal/jbosscache/docs/index.html">Cache</ulink>. There is a separate
+ tutorial on PojoCache.</para>
</section>
<section>
@@ -43,11 +43,11 @@
</listitem>
<listitem>
- <para>PojoCache</para>
+ <para>Transaction</para>
</listitem>
<listitem>
- <para>Transaction</para>
+ <para>Cache loader</para>
</listitem>
</itemizedlist>
</section>
@@ -55,13 +55,13 @@
<section>
<title>Configuration</title>
- <para>First download the standalone TreeCache code from <ulink
+ <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 TreeCache through editing the various configuration
+ modify the behavior of Cache through editing the various configuration
files.</para>
<itemizedlist>
@@ -72,32 +72,24 @@
</listitem>
<listitem>
- <para><literal>replSync-service.xml</literal>. Tree cache configuration file (file name
- is not fixed. You specify the file to be read in in
- <literal>PropertyConfigurator</literal>). The settings are for a
+ <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">Treecache</ulink>. Note that
+ 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>
</listitem>
-
- <listitem>
- <para><literal>jboss-aop.xml</literal>. AOP pointcut and advice definition for the
- example POJO classes, Person and Address, respectively. For details of
- how to put your own class under AOP, please refer to the <ulink
- url="http://www.jboss.org/products/jbosscache/docs">PojoCache</ulink>. This file is read in
- when the process is started.</para>
- </listitem>
</itemizedlist>
</section>
<section>
<title>Script</title>
- <para>The script files that are needed (located under install directory)
+ <para>The script files that are needed (located under the installed directory)
in this tutorial are:</para>
<itemizedlist>
@@ -121,61 +113,17 @@
</listitem>
<listitem>
- <para><literal>aop.bsh</literal>. Java codes that instantiate and configure the aop
- cache. In addition, it also sets up the example POJO (plaing old Java
- object) classes (e.g., Person and Address).</para>
- </listitem>
-
- <listitem>
- <para><literal>aopWithTx.bsh</literal>. Same with aop.bsh except it also instantiates a
- transaction context.</para>
+ <para><literal>oodb.bsh</literal>. Java code that instantiate and configure the cache to use
+ cache loader.</para>
</listitem>
</itemizedlist>
</section>
<section>
- <title>Example POJO</title>
-
- <para>The example POJO classes used for PojoCache demo are:
- <literal>Person</literal> and <literal>Address</literal>. They are located
- under <literal>tests/org/jboss/cache/aop</literal>
- directory. <literal>Person</literal> has attributes of <literal>String
- age, Address addr, List languages</literal>, etc. We will demonstrate that
- once you put the POJO instance in the cache, plain get/set POJO methods
- will be intercepted by the cache.</para>
-
- <para>Here is the snippet of the class definition for
- <literal>Person</literal> and <literal>Address</literal>.</para>
-
- <programlisting>public class Person {
- String name=null;
- int age=0;
- Map hobbies=null;
- Address address=null;
- Set skills;
- List languages;
-
- public String getName() { return name; }
- public void setName(String name) { this.name=name; }
- ...
-}</programlisting>
-
- <programlisting>public class Address {
- String street=null;
- String city=null;
- int zip=0;
-
- public String getStreet() { return street; }
- public void setStreet(String street) { this.street=street; }
- ...
-}</programlisting>
- </section>
-
- <section>
<title>Demo</title>
<para>To run the demo, you will need at least two windows: one to peruse
- the cache contents (plus non-aop operations) and the other to operate the
+ 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
@@ -184,9 +132,6 @@
<itemizedlist>
<listitem>For each
demo example, it'd be best if you re-start the whole setup.</listitem>
- <listitem>While you can modify the cache content on the GUI window and it will show up on the BSH cache
- content (e.g., through <literal>cache.printDetails()</literal>), this won't work on PojoCache demo.
- That is, you can only modify the cache content on the BSH window.</listitem>
</itemizedlist>
<para>The two demo programs to run are:</para>
@@ -196,9 +141,9 @@
<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
- PojoCache GUI. Later on, you can click on a node to view the the
+ 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
- non-AOP cache entries. Since the GUI entry only accepts String 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>
</listitem>
@@ -208,7 +153,7 @@
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, aop.bsh, and aopWithTx.bsh). See the
+ capabilities (e.g., plain.bsh). See the
following for details.</para>
</listitem>
</itemizedlist>
@@ -230,11 +175,10 @@
<programlisting>import org.jboss.cache.*;
show(); // verbose mode for bean shell
-TreeCache tree = new TreeCache();
-PropertyConfigurator config = new PropertyConfigurator(); // configure tree cache. Needs to be in the classpath
-config.configure(tree, "META-INF/replSync-service.xml");
-tree.startService(); // kick start tree cache
-tree.put("/a/b/c", "ben", "me"); // create a cache entry.
+// 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
@@ -242,110 +186,8 @@
content. You can modify the contents from the GUI as well. To create
another node, for example, you can type in the shell:</para>
- <programlisting>tree.put("/a/b/c/d", "JBoss", "Open Source");
-tree.get("/a/b/c/d", "JBoss");</programlisting>
- </section>
-
- <section>
- <title>PojoCache</title>
-
- <para>Once you are in the shell, type
- <literal>sourceRelative("aop.bsh");</literal> to execute the shell script.
- Basically, aop.bsh illustrates the steps to instantiate a cache, configure
- it, and then create entries under it. Here are the snippets:</para>
-
- <programlisting>import org.jboss.cache.PropertyConfigurator;
-import org.jboss.cache.aop.PojoCache;
-import org.jboss.cache.aop.test.Person;
-import org.jboss.cache.aop.test.Address;
-show(); // verbose mode for bean shell
-PojoCache tree = new PojoCache();
-PropertyConfigurator config = new PropertyConfigurator(); // configure tree cache.
-config.configure(tree, "META-INF/replSync-service.xml");
-Person joe = new Person(); // instantiate a Person object named joe
-joe.setName("Joe Black");
-joe.setAge(31);
-Address addr = new Address(); // instantiate a Address object named addr
-addr.setCity("Sunnyvale");
-addr.setStreet("123 Albert Ave");
-addr.setZip(94086); joe.setAddress(addr); // set the address reference
-tree.startService(); // kick start tree cache
-tree.putObject("/aop/joe", joe); // add aop sanctioned object (and sub-objects) into cache.
-// since it is aop-sanctioned, use of plain get/set methods will take care of cache contents automatically.
-joe.setAge(41);</programlisting>
-
- <para>Note the API needed to put the object (and its dependent ones) into
- cache is putObject. Once the second window finishes execution, you should
- see the first GUI window has been populated with entries of
- /aop/joe/address. Click on each tree node will display different values
- associated with that node.</para>
-
- <para>Next step to see AOP in action, you can do plain get/set methods
- without ever worrying about put it in the cache. For example, you can do
- in the shell window joe.setAge(20); and see that GUI gets updated with the
- age field automatically (if not, click away and back will refresh the GUI content).
- Also to demonstrate the object graph replication,
- you can modify Joe's address and see the cache will update it
- automatically. For example, type addr.setCity("San Jose"); in the
- interactive shell, you should see in the GUI that the address got
- modified.</para>
-
- <para>Finally, PojoCache also supports get/set with parameter type of
- Collection classes (i.e., List, Map, and Set). For example, type the
- following in the shell command line:</para>
-
- <programlisting>ArrayList lang = new ArrayList();
-lang.add("Ensligh");
-lang.add("Mandarin");
-joe.setLanguages(lang);</programlisting>
- </section>
-
- <section>
- <title>PojoCache with Transaction</title>
-
- <para>To see TreeCache transaction at work, you start with the same setup
- with last section except you load the bsh of aopWithTx.bsh instead of
- aop.bsh. The additional snippets are:</para>
-
- <programlisting>import org.jboss.cache.PropertyConfigurator;
-import org.jboss.cache.aop.PojoCache;
-import org.jboss.cache.aop.test.Person;
-import org.jboss.cache.aop.test.Address;// Tx imports
-import javax.transaction.UserTransaction; import javax.naming.*;
-import org.jboss.cache.transaction.DummyTransactionManager;
-show(); // verbose mode for bean shell
-// Set up transaction manager
-DummyTransactionManager.getInstance();
-Properties prop = new Properties();
-prop.put(Context.INITIAL_CONTEXT_FACTORY, "org.jboss.cache.transaction.DummyContextFactory");
-UserTransaction tx = (UserTransaction)new InitialContext(prop).lookup("UserTransaction");
-PojoCache tree = new PojoCache();
-PropertyConfigurator config = new PropertyConfigurator(); // configure tree cache.
-config.configure(tree, "META-INF/replSync-service.xml");
-joe = new Person();
-joe.setName("Joe Black");
-joe.setAge(31);
-
-Address addr = new Address();
-addr.setCity("Sunnyvale");
-addr.setStreet("123 Albert Ave");
-addr.setZip(94086);
-joe.setAddress(addr);
-
-tree.startService(); // kick start tree cache
-tree.putObject("/aop/joe", joe); // add aop sanctioned object
-// since it is aop-sanctioned, use of plain get/set methods will take care of cache contents automatically.
-// Also it is transacted
-tx.begin();
-joe.setAge(41);
-joe.getAddress().setZip(95124);
-tx.commit();</programlisting>
-
- <para>In this example, a default dummy transaction manager is used.</para>
-
- <programlisting>tx.begin();
-addr.setZip(95131);
-tx.rollback();</programlisting>
+ <programlisting>tree.put(Fqn.fromString("/a/b/c/d"), "JBoss", "Open Source");
+tree.get(Fqn.fromString("/a/b/c/d"), "JBoss");</programlisting>
</section>
<section>
@@ -356,93 +198,6 @@
<literal>jboss-cache</literal>.</para>
<section>
- <title>Local cache with CacheLoader</title>
-
- <para>This demo shows a local PojoCache with a CacheLoader. We will
- insert a POJO into the cache, and see that the POJO is transparently
- saved using the CacheLoader.</para>
-
- <para>To run this, you have to modify
- <literal>jboss-cache/output/etc/META-INF/oodb-service.xml</literal>:
- change <literal>CacheLoaderConfig</literal> to point to a valid
- directory (create it if it doesn't yet exist):</para>
-
- <programlisting><attribute name="CacheLoaderConfig">
- location=c:\\tmp\\oodb
-</attribute>
-</programlisting>
-
- <para>Then start the beanshell and source <literal>oodb.bsh</literal>
- into it. Note that <literal>oodb.bsh</literal> already contains code to create and retrieve POJO
- from the cache. So remember to comment them out if you decide to create the Person instance yourself.</para>
-
- <programlisting>bela at laptop /cygdrive/c/jboss-cache
-$ ./runShellDemo.sh
-BeanShell 1.3.0 - by Pat Niemeyer (pat at pat.net)
-bsh % sourceRelative("oodb.bsh");
-interceptor chain is:
-class org.jboss.cache.interceptors.CallInterceptor
-class org.jboss.cache.interceptors.CacheLoaderInterceptor
-class org.jboss.cache.interceptors.TransactionInterceptor
-<null>
-bsh %</programlisting>
-
- <para>Next, create an instance of Person, and set its address and other
- fields:</para>
-
- <programlisting>bsh % p=new Person();
-<name=null, age=0, hobbies=, address=null, skills=null, languages=null>
-bsh % p.age=3;
-<3>
-bsh % p.name="Michelle";
-<Michelle>
-bsh % addr=new Address();
-<street=null, city=null, zip=0>
-bsh % addr.city="San Jose";
-<San Jose>
-bsh % addr.zip=95124;
-<95124>
-bsh % addr.street="1704 Almond Blossom Lane";
-<1704 Almond Blossom Lane>
-bsh % p.setAddress(addr);
-bsh % tree.putObject("/person/me", p);
-bsh % p;
-<name=Michelle, age=3, hobbies=, address=street=1704 Almond Blossom Lane, city=San Jose, zip=95124, skills=null, languages=null>
-bsh %</programlisting>
-
- <para>The <literal>Person</literal> object with all of its fields and
- subobjects is now saved. Let's kill beanshell and restart it. At this
- point, because the instance of <literal>Person</literal> we created was
- given the name "p", we can retrieve it again:</para>
-
- <programlisting>bela at laptop /cygdrive/c/jboss-cache
-$ ./runShellDemo.sh
-BeanShell 1.3.0 - by Pat Niemeyer (pat at pat.net)
-bsh % sourceRelative("oodb.bsh");
-interceptor chain is:
-class org.jboss.cache.interceptors.CallInterceptor
-class org.jboss.cache.interceptors.CacheLoaderInterceptor
-class org.jboss.cache.interceptors.TransactionInterceptor
-<null>
-bsh % tree;
-</>
-bsh % p=tree.getObject("/person/me");
-<name=Michelle, age=3, hobbies=, address=street=1704 Almond Blossom Lane, city=San Jose, zip=95124, skills=null, languages=null>
-bsh % tree;
-</p
- /address
->
-bsh %</programlisting>
-
- <para>The interesting thing here is that the cache was initially empty
- ("/"). Only when we loaded "p", did it get populated (lazy loading). You
- can see that the values of "p" are loaded from the datastore where they
- were previously saved.</para>
-
- <para></para>
- </section>
-
- <section>
<title>Replicated cache with shared datastore</title>
<para>The scenario that we'll run in this example is described in the
More information about the jboss-cvs-commits
mailing list