[jboss-cvs] JBossCache/docs/tutorial-pojo/en ...
Manik Surtani
manik at jboss.org
Tue Apr 17 03:44:47 EDT 2007
User: msurtani
Date: 07/04/17 03:44:47
Modified: docs/tutorial-pojo/en master.xml
Log:
updated release date
Revision Changes Path
1.5 +453 -363 JBossCache/docs/tutorial-pojo/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-pojo/en/master.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -b -r1.4 -r1.5
--- master.xml 21 Nov 2006 13:57:42 -0000 1.4
+++ master.xml 17 Apr 2007 07:44:47 -0000 1.5
@@ -3,7 +3,7 @@
<articleinfo>
<title>PojoCache Tutorial</title>
<releaseinfo>Release 2.0.0</releaseinfo>
- <pubdate>January 2007</pubdate>
+ <pubdate>June 2007</pubdate>
<author>
<firstname>Ben</firstname>
<surname>Wang</surname>
@@ -19,9 +19,13 @@
Cache (generic cache) and PojoCache (object-oriented POJO cache).
In this tutorial, we will demonstrate the usage of PojoCache 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">PojoCache</ulink>. There is a separate
- tutorial on Cache.</para>
+ refer to the user manuals for
+ <ulink
+ url="http://labs.jboss.org/portal/jbosscache/docs/index.html">PojoCache
+ </ulink>
+ . There is a separate
+ tutorial on Cache.
+ </para>
</section>
<section>
@@ -49,42 +53,68 @@
<section>
<title>Configuration</title>
- <para>First download the standalone JBoss Cache code from <ulink
- url="http://labs.jboss.org/portal/jbosscache/download/index.html">here</ulink>.
- You will <literal>jboss-cache-pojo-xxx.zip</literal>. Unzip it, and you will get a
+ <para>First download the standalone JBoss Cache code from
+ <ulink
+ url="http://labs.jboss.org/portal/jbosscache/download/index.html">here
+ </ulink>
+ .
+ You will
+ <literal>jboss-cache-pojo-xxx.zip</literal>
+ . Unzip it, and you will get a
root directory (jboss-cache in our
- example).</para>
+ example).
+ </para>
<para>The configuration files are located under the etc directory. You can
modify the behavior of the underlying Cache through editing the various configuration
- files.</para>
+ files.
+ </para>
<itemizedlist>
<listitem>
- <para><literal>log4j.xml</literal>. Logging output. You can turn on logging level or
+ <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>
+ <literal>/tmp/jbosscache.log</literal>
+ ).
+ </para>
</listitem>
<listitem>
- <para><literal>replSync-service.xml</literal>. Cache configuration file (file name
+ <para>
+ <literal>replSync-service.xml</literal>
+ . Cache configuration file (file name
is not fixed. You specify the file to be read in in
- <literal>Configuration</literal>). This settings are for a
+ <literal>Configuration</literal>
+ ). This 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>
+ 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>pojocache-aop.xml</literal>. PojoCache configuration file that contains definition for the
+ <para>
+ <literal>pojocache-aop.xml</literal>
+ . PojoCache configuration file that contains 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>
+ 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>
@@ -93,33 +123,50 @@
<title>Script</title>
<para>The script files that are needed (located under install directory)
- in this tutorial are:</para>
+ in this tutorial are:
+ </para>
<itemizedlist>
<listitem>
- <para><literal>build.sh</literal> (or <literal>build.bat</literal> for DOS/Windows).
+ <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
+ 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>
+ same goes for runDemoShell explained next.
+ </para>
</listitem>
<listitem>
- <para><literal>runDemoShell.sh</literal>. Simple run script that wraps around BeanShell.
+ <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>
+ command line.
+ </para>
</listitem>
<listitem>
- <para><literal>pojocache.bsh</literal>. Java codes that instantiate and configure the aop
+ <para>
+ <literal>pojocache.bsh</literal>
+ . Java codes that instantiate and configure the aop
cache. In addition, it also sets up the example POJO (plain old Java
- object) classes (e.g., Person and Address).</para>
+ object) classes (e.g., Person and Address).
+ </para>
</listitem>
<listitem>
- <para><literal>pojocacheWithTx.bsh</literal>. Same with aop.bsh except it also instantiates a
- transaction context.</para>
+ <para>
+ <literal>pojocacheWithTx.bsh</literal>
+ . Same with aop.bsh except it also instantiates a
+ transaction context.
+ </para>
</listitem>
</itemizedlist>
</section>
@@ -128,19 +175,33 @@
<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/pojo</literal>
- directory. <literal>Person</literal> has attributes of <literal>String
- age, Address addr, List languages</literal>, etc. We will demonstrate that
+ <literal>Person</literal>
+ and
+ <literal>Address</literal>
+ . They are located
+ under
+ <literal>tests/org/jboss/cache/pojo</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>
+ will be intercepted by the cache.
+ </para>
<para>Here is the snippet of the class definition for
- <literal>Person</literal> and <literal>Address</literal> plus the PojoCache annotation.</para>
+ <literal>Person</literal>
+ and
+ <literal>Address</literal>
+ plus the PojoCache annotation.
+ </para>
<programlisting>
- at org.jboss.cache.pojo.annotation.Replicable
-public class Person {
+ @org.jboss.cache.pojo.annotation.Replicable
+ public class Person {
String name=null;
int age=0;
Map hobbies=null;
@@ -151,11 +212,12 @@
public String getName() { return name; }
public void setName(String name) { this.name=name; }
...
-}</programlisting>
+ }
+ </programlisting>
<programlisting>
- at org.jboss.cache.pojo.annotation.Replicable
-public class Address {
+ @org.jboss.cache.pojo.annotation.Replicable
+ public class Address {
String street=null;
String city=null;
int zip=0;
@@ -163,7 +225,8 @@
public String getStreet() { return street; }
public void setStreet(String street) { this.street=street; }
...
-}</programlisting>
+ }
+ </programlisting>
</section>
<section>
@@ -175,28 +238,39 @@
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-pojo-dist.zip). Due to the limitation of the
- GUI, please note that:</para>
+ GUI, please note that:
+ </para>
<itemizedlist>
- <listitem>Do <literal>build.bat compile</literal> command if have not done so yet.</listitem>
+ <listitem>Do
+ <literal>build.bat compile</literal>
+ command if have not done so yet.
+ </listitem>
<listitem>For each
- demo example, it'd be best if you re-start the whole setup.</listitem>
+ 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, this won't work on PojoCache demo.
- That is, you can only modify the cache content on the BSH window.</listitem>
+ That is, you can only modify the cache content on the BSH window.
+ </listitem>
</itemizedlist>
<para>The two demo programs to run are:</para>
<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
+ <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
contents. Note that you can also add/modify the node contents for
non-AOP 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>
+ it is a String type).
+ </para>
</listitem>
<listitem>
@@ -205,7 +279,8 @@
(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., pojocache.bsh, and pojocacheWithTx.bsh). See the
- following for details.</para>
+ following for details.
+ </para>
</listitem>
</itemizedlist>
</section>
@@ -214,55 +289,63 @@
<title>PojoCache</title>
<para>Once you are in the shell, type
- <literal>sourceRelative("pojocache.bsh");</literal> to execute the shell script.
+ <literal>sourceRelative("pojocache.bsh");</literal>
+ to execute the shell script.
Basically, pojocache.bsh illustrates the steps to instantiate a cache, configure
- it, and then create entries under it. Here are the snippets:</para>
+ it, and then create entries under it. Here are the snippets:
+ </para>
-<programlisting>
-import org.jboss.cache.pojo.PojoCacheFactory;
-import org.jboss.cache.pojo.PojoCache;
-import org.jboss.cache.pojo.test.*;
+ <programlisting>
+ import org.jboss.cache.pojo.PojoCacheFactory;
+ import org.jboss.cache.pojo.PojoCache;
+ import org.jboss.cache.pojo.test.*;
-show(); // verbose mode
+ show(); // verbose mode
-String configFile = "META-INF/replSync-service.xml";
-boolean toStart = false;
-cache = PojoCacheFactory.createCache(configFile, toStart);
+ String configFile = "META-INF/replSync-service.xml";
+ boolean toStart = false;
+ cache = PojoCacheFactory.createCache(configFile, toStart);
-joe = new Person();
-joe.setName("Joe Black");
-joe.setAge(31);
+ joe = new Person();
+ joe.setName("Joe Black");
+ joe.setAge(31);
-addr = new Address();
-addr.setCity("Sunnyvale");
-addr.setStreet("123 Albert Ave");
-addr.setZip(94086);
+ addr = new Address();
+ addr.setCity("Sunnyvale");
+ addr.setStreet("123 Albert Ave");
+ addr.setZip(94086);
-joe.setAddress(addr);
+ joe.setAddress(addr);
-cache.start(); // kick start cache
+ cache.start(); // kick start cache
-cache.attach("pojo/joe", joe); // add pojocache sanctioned object
+ cache.attach("pojo/joe", joe); // add pojocache sanctioned object
-// since it is pojocache-sanctioned, use of plain get/set methods will take care of cache content automatically.
-joe.setAge(41);
-</programlisting>
+ // since it is pojocache-sanctioned, use of plain get/set methods will take care of cache content
+ automatically.
+ joe.setAge(41);
+ </programlisting>
<para>Note the API needed to put the object (and its dependent ones) into
cache is attach. Once the second window finishes execution, you should
see the first GUI window has been populated with entries of
joe/address. Click on each tree node will display different values
- associated with that node.</para>
+ associated with that node.
+ </para>
<para>Like we have explained in the reference documentation, PojoCache uses physical "flat-space" mapping
strategy. As a result, you don't see the sub-POJO stored directly under the user-specified node. Instead,
- a <literal>PojoReference</literal> is stored there (Figure 1). You can follow the internal reference and
- click on there to inspect the fields there (Figure 2).</para>
+ a
+ <literal>PojoReference</literal>
+ is stored there (Figure 1). You can follow the internal reference and
+ click on there to inspect the fields there (Figure 2).
+ </para>
<para>For example, to see PojoCache 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.getAddress().setCity("Taipei"); and see that GUI gets updated with the
- age field automatically (if not, click away and back will refresh the GUI content. See Figure 3.)</para>
+ age field automatically (if not, click away and back will refresh the GUI content. See Figure 3.)
+ </para>
<figure>
<title>Gui demo: Joe reference</title>
@@ -296,12 +379,14 @@
<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>
+ following in the shell command line:
+ </para>
<programlisting>ArrayList lang = new ArrayList();
-lang.add("Ensligh");
-lang.add("Mandarin");
-joe.setLanguages(lang);</programlisting>
+ lang.add("Ensligh");
+ lang.add("Mandarin");
+ joe.setLanguages(lang);
+ </programlisting>
</section>
<section>
@@ -309,61 +394,66 @@
<para>To see PojoCache transaction at work, you start with the same setup
with last section except you load the bsh of pojocacheWithTx.bsh (instead of
- pojocache.bsh). The additional snippets are:</para>
+ pojocache.bsh). The additional snippets are:
+ </para>
-<programlisting>
-import org.jboss.cache.pojo.PojoCache;
-import org.jboss.cache.pojo.PojoCacheFactory;
-import org.jboss.cache.pojo.test.*;
-import javax.transaction.UserTransaction;
-import javax.naming.*;
-import org.jboss.cache.transaction.DummyTransactionManager;
+ <programlisting>
+ import org.jboss.cache.pojo.PojoCache;
+ import org.jboss.cache.pojo.PojoCacheFactory;
+ import org.jboss.cache.pojo.test.*;
+ import javax.transaction.UserTransaction;
+ import javax.naming.*;
+ import org.jboss.cache.transaction.DummyTransactionManager;
-show(); // verbose mode
+ show(); // verbose mode
-// Set up transaction manager
-DummyTransactionManager.getInstance();
+ // Set up transaction manager
+ DummyTransactionManager.getInstance();
-prop = new Properties();
-prop.put(Context.INITIAL_CONTEXT_FACTORY,
+ prop = new Properties();
+ prop.put(Context.INITIAL_CONTEXT_FACTORY,
"org.jboss.cache.transaction.DummyContextFactory");
-tx = (UserTransaction)new InitialContext(prop).lookup("UserTransaction");
+ tx = (UserTransaction)new InitialContext(prop).lookup("UserTransaction");
-String configFile = "META-INF/replSync-service.xml";
-boolean toStart = false;
-cache = PojoCacheFactory.createCache(configFile, toStart);
-
-joe = new Person();
-joe.setName("Joe Black");
-joe.setAge(31);
-
-addr = new Address();
-addr.setCity("Sunnyvale");
-addr.setStreet("123 Albert Ave");
-addr.setZip(94086);
-
-joe.setAddress(addr);
-
-cache.start(); // kick start tree cache
-cache.attach("pojo/joe", joe); // add pojocache sanctioned object
-
-// since it is pojocache-sanctioned, use of plain get/set methods will take care of cache content automatically.
-// This is also transacted.
-tx.begin();
-joe.setAge(41);
-tx.commit();
-</programlisting>
+ String configFile = "META-INF/replSync-service.xml";
+ boolean toStart = false;
+ cache = PojoCacheFactory.createCache(configFile, toStart);
+
+ joe = new Person();
+ joe.setName("Joe Black");
+ joe.setAge(31);
+
+ addr = new Address();
+ addr.setCity("Sunnyvale");
+ addr.setStreet("123 Albert Ave");
+ addr.setZip(94086);
+
+ joe.setAddress(addr);
+
+ cache.start(); // kick start tree cache
+ cache.attach("pojo/joe", joe); // add pojocache sanctioned object
+
+ // since it is pojocache-sanctioned, use of plain get/set methods will take care of cache content
+ automatically.
+ // This is also transacted.
+ tx.begin();
+ joe.setAge(41);
+ tx.commit();
+ </programlisting>
<para>Note that, in this example, a default dummy transaction manager is used. You can also try out in the
- Beanshell window as follows:</para>
+ Beanshell window as follows:
+ </para>
<programlisting>tx.begin();
-addr.setZip(95131);
-tx.rollback();</programlisting>
+ addr.setZip(95131);
+ tx.rollback();
+ </programlisting>
</section>
<section>
<title>Conclusion</title>
<para>In this tutorial, we have demonstrated how to run PojoCache fine-grained replication
- example with and without transaction.</para>
+ example with and without transaction.
+ </para>
</section>
</article>
More information about the jboss-cvs-commits
mailing list