[jboss-cvs] JBossCache/docs/PojoCache/en/modules ...
Ben Wang
bwang at jboss.com
Wed Sep 27 00:56:44 EDT 2006
User: bwang
Date: 06/09/27 00:56:44
Modified: docs/PojoCache/en/modules api.xml architecture.xml
Log:
Updated.
Revision Changes Path
1.3 +54 -14 JBossCache/docs/PojoCache/en/modules/api.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: api.xml
===================================================================
RCS file: /cvsroot/jboss/JBossCache/docs/PojoCache/en/modules/api.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -b -r1.2 -r1.3
--- api.xml 21 Aug 2006 00:36:33 -0000 1.2
+++ api.xml 27 Sep 2006 04:56:44 -0000 1.3
@@ -1,20 +1,59 @@
<chapter id="api">
- <title>API</title>
+ <title>API Overview</title>
+ <para>In this section, we will discuss an overview of the PojoCache APIs including the
+ PojoCacheFactory class.</para>
- <para>In PojoCache, there are 3 core APIs
+ <sect1>
+ <title>PojoCacheFactory API</title>
+ <para>PojoCacheFactory provides couple of static methods to instantiate and obtain a PojoCache instance.</para>
+<programlisting>
+ /**
+ * Create a PojoCache instance. Note that this will start the cache life cycle automatically.
+ * @param config A configuration string that represents the file name that is used to
+ * configure the underlying Cache instance.
+ * @return PojoCache
+ */
+ public static PojoCache createInstance(String config);
+
+ /**
+ * Create a PojoCache instance.
+ * @param config A configuration string that represents the file name that is used to
+ * configure the underlying Cache instance.
+ * @param start If true, it will start the cache life cycle.
+ * @return PojoCache
+ */
+ public static PojoCache createInstance(String config, boolean start);
+
+ /**
+ * Create a PojoCache instance.
+ * @param config A configuration object that is used to configure the underlying Cache instance.
+ * @param start If true, it will start the cache life cycle.
+ * @return PojoCache
+ */
+ public static PojoCache createInstance(Configuration config, boolean start);
+</programlisting>
+ <para>For example, to obtain a PojoCache instance and start the cache lifecycle automaticaly,
+ we can do:
+<programlisting>
+ String configFile = "META-INF/replSync-service.xml";
+ PojoCache cache = PojoCacheFactory.createInstance(configFile);
+</programlisting>
+ </para>
+ </sect1>
- for pojo management and one
- additional one for querying.
- They will be fully discussed here.
- Note that we have stressed that the management aspect of these APIs. This is because
- we expect
- most of the time, you only use these APIs to attach, detach, and retrieve the POJO from the cache system. After
+
+ <sect1>
+ <title>PojoCache API</title>
+ <para>In PojoCache, there are 3 core APIs for pojo management and one additional one for querying.
+ They will be fully discussed here. Note that we have stressed that the management aspect of these APIs.
+ This is because we expect most of the time, you only use these APIs to attach, detach, and
+ retrieve the POJO from the cache system. After
that, a user should operate on that POJO reference directly without worrying about replication and/or
persistency aspects.
</para>
- <sect1>
+ <sect2>
<title>Attachment</title>
<programlisting>
@@ -84,8 +123,8 @@
will assign an interceptor for the
pojo instance and its sub-objects.
</para>
-</sect1>
- <sect1>
+</sect2>
+ <sect2>
<title>Detachment</title>
<programlisting>
@@ -109,9 +148,9 @@
Note this call will also remove everything stored under <literal>id</literal> even if you have put
other plain cache data there.
</para>
- </sect1>
+ </sect2>
- <sect1>
+ <sect2>
<title>Query</title>
<programlisting>
@@ -164,7 +203,8 @@
that once a pojo is found with a fqn, no more pojo is stored under the children of the fqn. That is,
we don't mixed the fqn with different POJOs.
</para>
- </sect1>
+ </sect2>
+</sect1>
</chapter>
1.8 +125 -84 JBossCache/docs/PojoCache/en/modules/architecture.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: architecture.xml
===================================================================
RCS file: /cvsroot/jboss/JBossCache/docs/PojoCache/en/modules/architecture.xml,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -b -r1.7 -r1.8
--- architecture.xml 26 Sep 2006 16:24:20 -0000 1.7
+++ architecture.xml 27 Sep 2006 04:56:44 -0000 1.8
@@ -359,7 +359,7 @@
Person joe = new Person(); // instantiate a Person object named joe
joe.setName("Joe Black");
-joe.setAge(31);
+joe.setAge(41);
Address addr = new Address(); // instantiate an Address object named addr
addr.setCity("Sunnyvale");
@@ -405,84 +405,6 @@
joe.setLanguages(lang);
</programlisting>
</sect1>
- <sect1>
- <title>Physical object cache mapping model</title>
- <para>The previous section describes the logical object mapping model. In this section, we will explain
- the physical mapping model, that is, how do we map the POJO into internal core <literal>Cache</literal>.
- Again, keep in mind that we use Cache as a state replication aspect.</para>
-
- <para>Starting in release 2.0, we have adopted a so-called "flat space" mapping approach. That is, whenever a
- POJO attachment is called with a specified String id, we would create an instance of
- <literal>PojoReference</literal> first and stored under the String id region. <literal>PojoRefernce</literal>
- in turns contains a reference to an internal location where the real POJO mapping is held. If this POJO
- is of complex type, e.g., it has sub-types, this "flat space" mapping process will be executed recursively.
- </para>
-
- <para>For example, let's take the mapping of the <literal>Person</literal> POJO under id "pojo/joe".
- Keep in mind that a "Person" object would have sub-objects (such as <literal>Address</literal>)
- that we need to recursively map. This example is created from a two node replication group where
- one node is a Beanshell window and the other node is a Swing Gui window (shown here).
- The following figure illustrates the first step of the mapping process. From the bottom figure,
- we can see that
- the <literal>PojoReference</literal> under <literal>pojo/joe</literal> is pointing to an internal location
- (<literal>/__JBossInternal__/5c4o12-ywds1o-eskgh9iw-1-eskgh9iw-2</literal>).</para>
- <figure>
- <title>Object cache mapping I.</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/gui1.png"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>Then by clicking on the referenced internal node (from the following figure), we can see that the
- primitive fields for <literal>Person</literal> are stored. E.g., <literal>Age</literal> is
- <literal>41</literal> and
- <literal>Name</literal> is <literal>Joe Black</literal>.
- </para>
- <figure>
- <title>Object cache mapping II</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/gui1a.png"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>Under the <literal>/__JBossInternal__/5c4o12-ywds1o-eskgh9iw-1-eskgh9iw-2</literal>, we can see that
- there is an <literal>Address</literal> node, since <literal>Address</literal> is by itself a POJO. Clicking
- on the <literal>Address</literal> node shows that it references another internal location:
- <literal>/__JBossInternal__/5c4o12-ywds1o-eskgh9iw-1-eskgh9oh-3</literal> as shown in the following figure.</para>
- <figure>
- <title>Object cache mapping III</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/gui2.png"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>Then clicking on the <literal>/__JBossInternal__/5c4o12-ywds1o-eskgh9iw-1-eskgh9oh-3</literal> node
- again, we can see the primitive fields are stored there, e.g., <literal>Stree</literal>,
- <literal>Zip</literal>, and <literal>City</literal>. This is illustrated in the following figure.</para>
- <figure>
- <title>Object cache mapping IV</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/gui3.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>The above example give you a flavor of the "flat space" mapping approach. The biggest advantage for
- this approach is when a sub-POJO is multiple referenced. In this case, the reference is so-called canonical in
- that all references have a logical <literal>PojoReference</literal> that points to the real one. Of course,
- the downside is if we don't have any objection relationship then the "flat space" mapping will incure the
- overhead of additional mapping into the PojoCache internal region.</para>
- </sect1>
<sect1>
<title>Object relationship management</title>
@@ -536,11 +458,11 @@
import org.jboss.test.cache.test.standAloneAop.Address;
String configFile = "META-INF/replSync-service.xml";
-PojoCachecache = PojoCacheFactory.createInstance(configFile); // This will start PojoCache automatically
+PojoCache cache = PojoCacheFactory.createInstance(configFile); // This will start PojoCache automatically
Person joe = new Person(); // instantiate a Person object named joe
joe.setName("Joe Black");
-joe.setAge(31);
+joe.setAge(41);
Person mary = new Person(); // instantiate a Person object named mary
mary.setName("Mary White");
@@ -648,6 +570,125 @@
</sect1>
<sect1>
+ <title>Physical object cache mapping model</title>
+ <para>The previous sections describe the logical object mapping model. In this section, we will explain
+ the physical mapping model, that is, how do we map the POJO into internal core <literal>Cache</literal>
+ for transaction state replication.</para>
+
+ <para>Starting in release 2.0, we have adopted a so-called "flat space" mapping approach. That is, whenever a
+ POJO attachment is called with a specified String id, we would create an instance of
+ <literal>PojoReference</literal> first and stored under the String id region. <literal>PojoRefernce</literal>
+ in turns contains a reference to an internal location where the real POJO mapping is held. If this POJO
+ is of complex type, e.g., it has sub-types, this "flat space" mapping process will be executed recursively.
+ </para>
+
+ <para>For example, let's take the mapping of the <literal>Person</literal> POJO under id "pojo/joe" and
+ "pojo/mary" illustrated in the previous sections.
+ Keep in mind that a "Person" object would have sub-objects (such as <literal>Address</literal>)
+ that we need to recursively map. This example is created from a two node replication group where
+ one node is a Beanshell window and the other node is a Swing Gui window (shown here).
+ For clarity, we have created couple snapshots to hightlight the mapping process.</para><para>
+ The following figure illustrates the first step of the mapping approach. From the bottom of the figure,
+ we can see that
+ the <literal>PojoReference</literal> field under <literal>pojo/joe</literal> is pointing to an
+ internal location,
+ <literal>/__JBossInternal__/5c4o12-lpaf5g-esl49n5e-1-esl49n5o-2</literal>. That is, under user-specified
+ Id string, we store only an indirect reference to the intneral area. Please note that
+ <literal>Mary</literal> has a similar reference. (Note that the <literal>_lock_</literal> is used
+ to control POJO level transaction locking and is considered internal.)</para>
+ <figure>
+ <title>Object cache mapping for <literal>Joe</literal></title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/guiJoe.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <figure>
+ <title>Object cache mapping for <literal>Mary</literal></title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/guiMary.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Then by clicking on the referenced internal node (from the following figure), we can see that the
+ primitive fields for <literal>Joe</literal> are stored there. E.g., <literal>Age</literal> is
+ <literal>41</literal> and
+ <literal>Name</literal> is <literal>Joe Black</literal>. And similarly for <literal>Mary</literal> as
+ well.
+ </para>
+ <figure>
+ <title>Object cache mapping for internal node <literal>Joe</literal></title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/guiJoeInternal.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <figure>
+ <title>Object cache mapping for internal node <literal>Mary</literal></title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/guiMaryInternal.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Under the <literal>/__JBossInternal__/5c4o12-lpaf5g-esl49n5e-1-esl49n5o-2</literal>, we can see that
+ there is an <literal>Address</literal> node, since <literal>Address</literal> is by itself a POJO. Clicking
+ on the <literal>Address</literal> node shows that it references another internal location:
+ <literal>/__JBossInternal__/5c4o12-lpaf5g-esl49n5e-1-esl49ngs-3</literal> as shown in the following figure.
+ Then by the same token, when your click <literal>Address</literal> under
+ <literal>/__JBossInternal__/5c4o12-lpaf5g-esl49n5e-1-esl49na0-4</literal>, it points to the same
+ address reference. That is, both <literal>Joe</literal> and <literal>Mary</literal> share the same
+ <literal>Address</literal> reference.</para>
+ <figure>
+ <title>Object cache mapping: Joe's internal address</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/guiJoeAddress.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <figure>
+ <title>Object cache mapping: Mary's internal address</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/guiMaryAddress.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Finally, clicking on the <literal>/__JBossInternal__/5c4o12-lpaf5g-esl49n5e-1-esl49ngs-3</literal> node
+ again, we can see the primitive fields are stored there, e.g., <literal>Stree</literal>,
+ <literal>Zip</literal>, and <literal>City</literal>. This is illustrated in the following figure.</para>
+ <figure>
+ <title>Object cache mapping: Address fields</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/guiAddress.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>The above example give you a flavor of the "flat space" mapping approach. The biggest advantage for
+ this approach is when a sub-POJO is multiple referenced. In this case, the reference is so-called canonical in
+ that all references have a logical <literal>PojoReference</literal> that points to the real one. Of course,
+ the downside is if we don't have any objection relationship then the "flat space" mapping will incur the
+ overhead of additional mapping into the PojoCache internal region.</para>
+ </sect1>
+
+ <sect1>
<title>Collection class proxy</title>
<para>The POJO classes that inherit from
@@ -686,7 +727,7 @@
list.add("TWO");
cache.attach("pojo/list", list);
-list.add("THREE"); // This won't intercept by the cache!
+list.add("THREE"); // This won't be intercepted by the cache!
List proxyList = cache.find("pojo/list"; // Note that list is a proxy reference
proxyList.add("FOUR"); // This will be intercepted by the cache
@@ -766,9 +807,9 @@
<literal>transient</literal>, and <literal>final</literal>). However, the user can override the <literal>transient</literal>
field to make it replicatable through the JBoss Aop:
<programlisting>
- <annotation-introduction expr="field(* POJO>aTransientField)">
+ <annotation-introduction expr="field(* POJO->aTransientField)">
@org.jboss.cache.pojo.annotation.NonTransient
- </annotation-introduction>
+ </annotation-introduction>
</programlisting>
where you are annotating an original transient field <literal>aTransientField</literal> with a <literal>NonTransient</literal>
that causes that transient field to be replicated.
More information about the jboss-cvs-commits
mailing list