[jboss-cvs] JBossCache/docs/tutorial-pojo/en ...
Galder Zamarreno
galder.zamarreno at jboss.com
Wed May 16 08:33:59 EDT 2007
User: gzamarreno
Date: 07/05/16 08:33:59
Modified: docs/tutorial-pojo/en master.xml
Log:
[JBCACHE-1000] JBossCache tutorial demo has been refactored to accomodate PojoCache one so that it uses the same embedded beanshell. PojoCache tutorial has been rewritten to have more similarities with JBossCache one, and has been extended with a section on Collections. Person and Address fields have been made private to promote encapsulation. Person no has a setLanguages(List<String>) to be consistent with get operation. This required fixing the ReplicatedPutWithBulkRemoveTest.
Revision Changes Path
1.6 +266 -327 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.5
retrieving revision 1.6
diff -u -b -r1.5 -r1.6
--- master.xml 17 Apr 2007 07:44:47 -0000 1.5
+++ master.xml 16 May 2007 12:33:59 -0000 1.6
@@ -9,27 +9,27 @@
<surname>Wang</surname>
<email>ben.wang at jboss.com</email>
</author>
+ <author>
+ <firstname>Galder</firstname>
+ <surname>Zamarreño</surname>
+ <email>galder.zamarreno at jboss.com</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 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>PojoCache is an in-memory, transactional, and replicated POJO (plain old Java object) cache system that
+ allows users to operate on a POJO transparently without active user management of either replication or
+ persistency aspects. This tutorial focuses on the usage of the PojoCache API.
+ </para>
+ <para>For details of configuration, usage and APIs, please refer to the
+ <ulink url="http://labs.jboss.org/portal/jbosscache/docs/index.html">users manual</ulink>.
</para>
</section>
<section>
- <title>Scope</title>
+ <title>What You Will Learn</title>
<itemizedlist>
<listitem>
@@ -37,83 +37,62 @@
</listitem>
<listitem>
- <para>Replication</para>
+ <para>Replication of POJO fields</para>
</listitem>
<listitem>
- <para>Transaction</para>
+ <para>Using Collections in PojoCache</para>
</listitem>
<listitem>
- <para>Cache loader</para>
+ <para>Transactions</para>
</listitem>
+
</itemizedlist>
</section>
<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>
+ <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-pojo-2.X.Y.zip</literal>
+ distribution. Unzip it, and you will get a directory containing the distribution, such as
+ <literal>JBossCache-pojo-2.X.Y</literal>
+ .
+ For the sake of this tutorial, I will refer to this as
+ <literal>PojoCache</literal>
.
- You will
- <literal>jboss-cache-pojo-xxx.zip</literal>
- . 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 the underlying Cache through editing the various configuration
- files.
+ <para>The configuration files are located under the
+ <literal>PojoCache/etc</literal>
+ directory. You can modify the behavior of the underlying cache through 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>
- ).
+ . 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 in
- <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.
+ <literal>META-INF/replSync-service.xml</literal>
+ . Cache configuration file used for this tutorial.
</para>
</listitem>
<listitem>
<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.
+ . PojoCache configuration file that contains, amongst other things, the annotation to use on POJOs so
+ that they're aspectised. For more information, please the PojoCache
+ <ulink url="http://labs.jboss.org/portal/jbosscache/docs/index.html">users manual</ulink>
+ .
</para>
</listitem>
</itemizedlist>
@@ -122,73 +101,28 @@
<section>
<title>Script</title>
- <para>The script files that are needed (located under install directory)
- in this tutorial are:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
+ <para>The only script needed for this tutorial is the
+ <literal>PojoCache/build.xml</literal>
+ ant script and the accompanying
+ driver scripts (
<literal>build.sh</literal>
- (or
+ for Unix and
<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.
+ for Windows).
</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>
- </listitem>
-
- <listitem>
- <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>
- </listitem>
-
- <listitem>
- <para>
- <literal>pojocacheWithTx.bsh</literal>
- . Same with aop.bsh except it also instantiates a
- transaction context.
- </para>
- </listitem>
- </itemizedlist>
</section>
<section>
- <title>Example POJO</title>
+ <title>Example POJOs</title>
<para>The example POJO classes used for PojoCache demo are:
- <literal>Person</literal>
+ <literal>org.jboss.cache.pojo.test.Person</literal>
and
- <literal>Address</literal>
+ <literal>org.jboss.cache.pojo.test.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
+ <literal>tests/functional</literal>
+ directory.The demo will demonstrate that once a POJO has been attached to the cache, plain get/set POJO methods
will be intercepted by the cache.
</para>
@@ -196,115 +130,106 @@
<literal>Person</literal>
and
<literal>Address</literal>
- plus the PojoCache annotation.
+ with the
+ <literal>Replicable</literal>
+ annotation.
</para>
- <programlisting>
+ <programlisting><![CDATA[
@org.jboss.cache.pojo.annotation.Replicable
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; }
...
+ public List<String> getLanguages() { return languages; }
+ public void setLanguages(List<String> languages) { this.languages = languages; }
+ ...
+ public Address getAddress() { return address; }
+ public void setAddress(Address address) { this.address = address; }
+ ...
}
- </programlisting>
+ ]]></programlisting>
- <programlisting>
+ <programlisting><![CDATA[
@org.jboss.cache.pojo.annotation.Replicable
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>
+ ]]></programlisting>
</section>
<section>
- <title>Demo</title>
+ <title>Running The Demo GUI</title>
- <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-pojo-dist.zip). Due to the limitation of the
- GUI, please note that:
+ <para>
+ The demo is run by calling the ant script (via the driver) with the
+ <literal>run.demo.pojocache</literal>
+ target. E.g.,
</para>
- <itemizedlist>
- <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>
- <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>
- </itemizedlist>
-
- <para>The two demo programs to run are:</para>
+ <para>
+ <literal>./build.sh run.demo.pojocache</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>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>
+ <literal>cache</literal>
+ - a reference to the PojoCache interface, used by the GUI instance.
</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., pojocache.bsh, and pojocacheWithTx.bsh). See the
- following for details.
- </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>PojoCache</title>
+ <title>Tutorials</title>
+ It is recommended that you shut down and restart the demo GUI for each of the following tutorials, to ensure
+ clean caches every time. To inspect POJO attribute changes via GUI, please refer to the PojoCache
+ <ulink
+ url="http://labs.jboss.org/portal/jbosscache/docs/index.html">user manual
+ </ulink>
+ to understand how the POJOs are mapped internally in the cache.
- <para>Once you are in the shell, type
- <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>
+ <section>
+ <title>PojoCache API, POJO manipulation, and Replication</title>
+ <para>
+ For this tutorial, start two instance of the demo GUI. In this tutorial, we will:
- <programlisting>
- import org.jboss.cache.pojo.PojoCacheFactory;
- import org.jboss.cache.pojo.PojoCache;
- import org.jboss.cache.pojo.test.*;
+ <itemizedlist>
+ <listitem>Attach POJOs to the cache and see them being replicated.</listitem>
+ <listitem>After attaching, manipulate the POJOs and see the individual changes replicated.</listitem>
+ <listitem>Retrieve POJOs from the cache, manipulate them and see the changes replicated.</listitem>
+ <listitem>Create POJOs that share a common POJO and the consequences of changes to this.</listitem>
+ <listitem>Detach POJOs from the cache.</listitem>
+ <listitem>After detaching, manipulates the POJOs and see how the values in the cache are unchanged.</listitem>
+ </itemizedlist>
- show(); // verbose mode
+ </para>
- String configFile = "META-INF/replSync-service.xml";
- boolean toStart = false;
- cache = PojoCacheFactory.createCache(configFile, toStart);
+ <orderedlist>
+ <listitem>In the 1st GUI instance, create a POJO, i.e. a Person with an Address:
+ <programlisting><![CDATA[
joe = new Person();
joe.setName("Joe Black");
@@ -317,143 +242,157 @@
joe.setAddress(addr);
- cache.start(); // kick start cache
+ ]]></programlisting>
+ </listitem>
+
+ <listitem>Attach the POJO to the cache:
+ <programlisting><![CDATA[
- cache.attach("pojo/joe", joe); // add pojocache sanctioned object
+ cache.attach("pojo/joe", joe);
+
+ ]]></programlisting>
+ </listitem>
+
+ <listitem>Change attributes of the POJO and see the individual changes being propagated to the 2nd
+ cache GUI:
+ <programlisting><![CDATA[
- // 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>
-
- <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>
-
- <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>
-
- <figure>
- <title>Gui demo: Joe reference</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/demoJoe.png"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <figure>
- <title>Gui demo: Address reference</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/demoAddressInternal.png"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <figure>
- <title>Gui demo: Address</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/demoAddress.png"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <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>
+ ]]></programlisting>
+ </listitem>
+
+ <listitem>In the 2nd GUI instance, get a reference to the Person in the cache and create a second Person
+ with the existing Person's Address:
+ <programlisting><![CDATA[
+
+ joe = cache.find("pojo/joe");
+
+ mary = new Person();
+ mary.setName("Mary White");
+ mary.setAge(30);
+
+ mary.setAddress(joe.getAddress());
+
+ ]]></programlisting>
+ </listitem>
+
+ <listitem>Attach the new POJO to the cache:
+ <programlisting><![CDATA[
+
+ cache.attach("pojo/mary", mary);
+
+ ]]></programlisting>
+ </listitem>
+
+ <listitem>Now, change either Person's Address and see how the change applies to both POJOs and has been
+ propagated to the other cache, visible in the 1st GUI instance:
+ <programlisting><![CDATA[
+
+ mary.getAddress().setZip(95000);
+
+ ]]></programlisting>
+ </listitem>
+
+
+ <listitem>Still in the 2nd GUI instance, detach the POJOs from the cache and see how the POJOs are no longer
+ visible:
+ <programlisting><![CDATA[
+
+ cache.detach("pojo/joe");
+ cache.detach("pojo/mary");
+
+ ]]></programlisting>
+ </listitem>
+
+ <listitem>Finally, in any of GUI instances, change some attributes of the POJO and see these changes have
+ no effect in the cache:
+ <programlisting><![CDATA[
+
+ joe.setName("Joe White");
+
+ ]]></programlisting>
+ </listitem>
+
+ </orderedlist>
+
</section>
<section>
- <title>PojoCache with Transaction</title>
+ <title>Collections</title>
+ <para>
+ For this tutorial, start two instances of the demo GUI. In this tutorial, we will:
- <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>
-
- <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
-
- // Set up transaction manager
- DummyTransactionManager.getInstance();
-
- prop = new Properties();
- prop.put(Context.INITIAL_CONTEXT_FACTORY,
- "org.jboss.cache.transaction.DummyContextFactory");
- tx = (UserTransaction)new InitialContext(prop).lookup("UserTransaction");
-
- String configFile = "META-INF/replSync-service.xml";
- boolean toStart = false;
- cache = PojoCacheFactory.createCache(configFile, toStart);
+ <itemizedlist>
+ <listitem>Attach a POJO to the cache and see it being replicated.</listitem>
+ <listitem>Set a Collection attribute in this POJO</listitem>
+ <listitem>Manipulate this Collection attribute and see the changes visible in the GUI and being replicated</listitem>
+ <listitem>Detach a POJO from the cache.</listitem>
+ </itemizedlist>
+
+ </para>
+
+ <orderedlist>
+ <listitem>In the 1st GUI instance, create a POJO with a Collection attribute:
+ <programlisting><![CDATA[
joe = new Person();
joe.setName("Joe Black");
- joe.setAge(31);
- addr = new Address();
- addr.setCity("Sunnyvale");
- addr.setStreet("123 Albert Ave");
- addr.setZip(94086);
+ lang = new ArrayList();
+ lang.add("Spanish");
- joe.setAddress(addr);
+ joe.setLanguages(lang);
+
+ ]]></programlisting>
+ </listitem>
- cache.start(); // kick start tree cache
- cache.attach("pojo/joe", joe); // add pojocache sanctioned object
+ <listitem>Attach the POJO to the cache:
+ <programlisting><![CDATA[
- // 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>
+ cache.attach("pojo/joe", joe);
- <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>
+ ]]></programlisting>
+ </listitem>
- <programlisting>tx.begin();
- addr.setZip(95131);
- tx.rollback();
- </programlisting>
+ <listitem>Get a proxy reference to the Collection and add a new element to it:
+ <programlisting><![CDATA[
+
+ proxyLang = joe.getLanguages();
+ proxyLang.add("English");
+
+ ]]></programlisting>
+ </listitem>
+
+ <listitem>Detach the pojo from the cache:
+ <programlisting><![CDATA[
+
+ cache.detach("pojo/joe");
+
+ ]]></programlisting>
+ </listitem>
+
+ <listitem>Use the proxy reference to the Collection to add another element and see how this does not get
+ added to the cache:
+ <programlisting><![CDATA[
+
+ proxyLang.add("French");
+
+ ]]></programlisting>
+ </listitem>
+
+ </orderedlist>
</section>
+ </section>
+
<section>
- <title>Conclusion</title>
- <para>In this tutorial, we have demonstrated how to run PojoCache fine-grained replication
- example with and without transaction.
+ <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 attaching/detaching nodes or modiying the POJOs. 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>
+
</article>
More information about the jboss-cvs-commits
mailing list