[jboss-cvs] JBossCache/docs/PojoCache/en/modules ...
Ben Wang
bwang at jboss.com
Tue Sep 26 12:24:20 EDT 2006
User: bwang
Date: 06/09/26 12:24:20
Modified: docs/PojoCache/en/modules architecture.xml
introduction.xml jbossaop.xml term.xml
Log:
Updated.
Revision Changes Path
1.7 +234 -132 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.6
retrieving revision 1.7
diff -u -b -r1.6 -r1.7
--- architecture.xml 21 Aug 2006 00:36:33 -0000 1.6
+++ architecture.xml 26 Sep 2006 16:24:20 -0000 1.7
@@ -2,37 +2,84 @@
<title>Architecture</title>
- <para>PojoCache uses extensively the JBoss Aop framework to 1) build the interceptor based architecture
- to provide behaviors such as lock, tx, and POJO rollback, 2) intercept POJO field access (via dynamic
+ <para>PojoCache uses extensively the JBoss Aop framework to 1) build the interceptor-based architecture
+ to provide behaviors such as locking and POJO transaction commit and rollback, 2)
+ intercept POJO field access (via dynamic
interceptor feature). Following explains the concepts and top-level design of PojoCache.</para>
+ <para>Following figure is an overview of the PojoCache architecture. From the top, we can see that
+ when a call comes in (e.g., <literal>attach</literal> or <literal>detach</literal>), it will go through
+ the PojoCache interceptor stack first (configured from <literal>pojocache-aop.xml</literal> but is mostly
+ read only). After that, it will store
+ the POJO fields into Cache store and then JGroups (for state replication) as confgiured from a designated
+ <literal>cache-service.xml</literal>. This architecture provides a decoupled framework that by itself
+ is modularized and pluggable (available in the future).</para>
+ <para>Please note that you will need to specify a system property <literal>jboss.aop.path</literal> to set it
+ to the path where <literal>pojocache-aop.xml</literal> resides.</para>
+ <figure>
+ <title>PojoCache architecture overview</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/pojocache_architecture.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
<sect1>
- <title>Interceptor-based architecture</title>
- <para>The JBoss Aop framework provides a rich set of pointcut language for user to create flexible
- interceptor stack per method call. In PojoCache, we have used JBoss Aop to provide customized
- behaviors for each method call, e.g., <literal>attach</literal>, <literal>detach</literal>,
+ <title>PojoCache interceptor stack</title>
+
+ <para>As mentioned, we use JBoss Aop framework to provide a configurable method-based interceptor stack.
+ The JBoss Aop framework provides a rich set of pointcut language for user to create flexible
+ interceptor stack per method call. For example, in our current implementation, we have defined numerous
+ <literal>interceptor</literal> element first and then assemble it within the <literal>stack</literal>
+ element for modularity.
+ </para>
+ <para>
+ In PojoCache, we have provided a customized
+ behaviors for each method call. E.g., <literal>attach</literal>, <literal>detach</literal>,
and <literal>find</literal> would each have their own specific stack for the specific behaviors.
- Following are the stack for each of the API, respectively:
+ Should you need to customize the PojoCache Api behavior, you can implement your own
+ JBoss Aop interceptor
+ and insert it into the respective stack.
+ Following are the stack for each of the API, respectively:</para>
<programlisting>
<!-- Check id range validity -->
- <interceptor name="CheckId" class="org.jboss.cache.pojo.interceptors.CheckIdInterceptor" scope="PER_INSTANCE"/>
+ <interceptor name="CheckId" class="org.jboss.cache.pojo.interceptors.CheckIdInterceptor"
+ scope="PER_INSTANCE"/>
+
<!-- Track Tx undo operation -->
- <interceptor name="Undo" class="org.jboss.cache.pojo.interceptors.PojoTxUndoInterceptor" scope="PER_INSTANCE"/>
- <!-- Begining -->
- <interceptor name="Start" class="org.jboss.cache.pojo.interceptors.PojoBeginInterceptor" scope="PER_INSTANCE"/>
+ <interceptor name="Undo" class="org.jboss.cache.pojo.interceptors.PojoTxUndoInterceptor"
+ scope="PER_INSTANCE"/>
+
+ <!-- Begining of interceptor chain -->
+ <interceptor name="Start" class="org.jboss.cache.pojo.interceptors.PojoBeginInterceptor"
+ scope="PER_INSTANCE"/>
+
<!-- Check if we need a local tx for batch processing -->
- <interceptor name="Tx" class="org.jboss.cache.pojo.interceptors.PojoTxInterceptor" scope="PER_INSTANCE"/>
- <!-- Mockup failed tx for testing -->
- <interceptor name="MockupTx" class="org.jboss.cache.pojo.interceptors.PojoFailedTxMockupInterceptor" scope="PER_INSTANCE"/>
+ <interceptor name="Tx" class="org.jboss.cache.pojo.interceptors.PojoTxInterceptor"
+ scope="PER_INSTANCE"/>
+
+ <!--
+ Mockup failed tx for testing. You will need to set PojoFailedTxMockupInterceptor.setRollback(true)
+ to activate it.
+ -->
+ <interceptor name="MockupTx" class="org.jboss.cache.pojo.interceptors.PojoFailedTxMockupInterceptor"
+ scope="PER_INSTANCE"/>
+
<!-- Perform parent level node locking -->
- <interceptor name="TxLock" class="org.jboss.cache.pojo.interceptors.PojoTxLockInterceptor" scope="PER_INSTANCE"/>
+ <interceptor name="TxLock" class="org.jboss.cache.pojo.interceptors.PojoTxLockInterceptor"
+ scope="PER_INSTANCE"/>
+
<!-- Interceptor to perform Pojo level rollback -->
<interceptor name="TxUndo" class="org.jboss.cache.pojo.interceptors.PojoTxUndoSynchronizationInterceptor"
scope="PER_INSTANCE"/>
- <!-- Interceptor to perform Pojo level rollback -->
+
+ <!-- Interceptor to used to check recursive field interception. -->
<interceptor name="Reentrant" class="org.jboss.cache.pojo.interceptors.MethodReentrancyStopperInterceptor"
scope="PER_INSTANCE"/>
- <!-- Whether to allow non-serializable pojo -->
+
+ <!-- Whether to allow non-serializable pojo. Default is false. -->
<interceptor name="MarshallNonSerializable" class="org.jboss.cache.pojo.interceptors.CheckNonSerializableInterceptor"
scope="PER_INSTANCE">
<attribute name="marshallNonSerializable">false</attribute>
@@ -41,9 +88,7 @@
<stack name="Attach">
<interceptor-ref name="Start"/>
<interceptor-ref name="CheckId"/>
- <interceptor-ref name="MarshallNonSerializable"/>
<interceptor-ref name="Tx"/>
- <interceptor-ref name="MockupTx"/>
<interceptor-ref name="TxLock"/>
<interceptor-ref name="TxUndo"/>
</stack>
@@ -52,7 +97,6 @@
<interceptor-ref name="Start"/>
<interceptor-ref name="CheckId"/>
<interceptor-ref name="Tx"/>
- <interceptor-ref name="MockupTx"/>
<interceptor-ref name="TxLock"/>
<interceptor-ref name="TxUndo"/>
</stack>
@@ -62,23 +106,32 @@
<interceptor-ref name="CheckId"/>
</stack>
</programlisting>
- Note that this
- customized interceptor stack is provided in <literal>jboss-aop.xml</literal> where user can
- also add customed interceptor as well.</para>
+<para>
+ The stack should be mostly self-explanatory. For example, for <literal>Attach</literal> stack,
+ we currently have <literal>Start, CheckId, Tx, TxLock</literal>, and
+ <literal>TxUndo</literal> interceptors. The stack always starts with a
+ <literal>Start</literal> interceptor such that initialization can be done properly.
+ <literal>CheckId</literal> is to ensure the validity of the Id (e.g., it didn't use any internal
+ Id string). Finally, <literal>Tx, TxLock</literal>, and <literal>TxUndo</literal> are handling the
+ the proper transaction locking and rollback behavior (if needed).
+</para><para>
+ Note again that this
+ customized interceptor stack is provided in <literal>pojocache-aop.xml</literal> where user can
+ also add customed interceptor if needs to.</para>
</sect1>
<sect1>
<title>Dynamic AOP interception</title>
- <para>JBossAop provides an API (<literal>appendInterceptor</literal>) to
+ <para>JBoss Aop provides an API (<literal>appendInterceptor</literal>) to
add an interceptor at runtime. PojoCache uses this feature
extensively to provide user transparency. Every "aspectized" POJO class
will have an associated
<literal>org.jboss.aop.InstanceAdvisor</literal>
- instance. During a
+ instance. During an
<literal>attach(String id, Object pojo)</literal>
operation (API explained below), PojoCache will examine to see if
- there is already a
+ there is already an
<literal>org.jboss.cache.aop.CacheInterceptor</literal>
attached. (Note
that a
@@ -106,12 +159,13 @@
<listitem>
we skip interception for field with <literal>final</literal>, <literal>static</literal>,
and <literal>transient</literal> qualifiers. As a result, any field with these 3 qualifiers will not
- be replicated or persisted.
+ be replicated or persisted (although there is Jira issue opened on to make "static" modifier
+ available for replication).
</listitem>
</itemizedlist>
</para>
<para>The figures shown below illustrate operations to perform field read and write.
- Once a POJO is managed by cache (i.e., after a
+ Once a POJO is managed by PojoCache (i.e., after an
<literal>attach</literal>
method has been called), Aop will invoke
<literal>CacheInterceptor</literal>
@@ -146,9 +200,9 @@
</sect1>
<sect1>
- <title>Object mapping by reachability</title>
+ <title>Logical object mapping by reachability</title>
- <para>A complex object by definition is an object that may consist of
+ <para>A complex POJO by definition is an object that may consist of
composite object references. Once a complex object is declared
"prepared" (e.g., a
<literal>Person</literal>
@@ -171,7 +225,7 @@
<listitem>
<para>Create a tree node using
<literal>id</literal> (internally translated into Cache <literal>fqn</literal>, if not yet
- existed.
+ existed).
</para>
</listitem>
@@ -224,31 +278,29 @@
CachedType fieldType = getCachedType(field.getType());
if (fieldType.isImmediate()) {
immediates.put(field.getName(), value);
-} else {
+ } else {
_attach(new Fqn(fqn, field.getName()), value);
+ }
+ ...
}</programlisting>
<para>Let's take an example POJO class definition from the Appendix
section where we have a
<literal>Person</literal>
object that has
- composite non-primitive types (e.g., List and Address). After we execute
- the
- <literal>attach</literal>
- call, the resulting tree node will
- schematically look like the cache node in the following figures:
+ composite non-primitive types (e.g., List and Address).
</para>
<programlisting>
Person joe = new Person();
joe.setAddress(new Address());
-cache.attach("/aop/joe", joe);
+cache.attach("pojo/joe", joe);
</programlisting>
<para>The PojoCache APIs will be explained in fuller details later.
- But notice the illustration of object mapping by reachability in the
- following figure. The fqn <literal>/aop/joe</literal> is associated with the POJO
+ But notice the illustration of object mapping by reachability.
+ The String Id <literal>pojo/joe</literal> is associated with the POJO
<literal>joe</literal>.
Then under that fqn, there are three
children nodes:
@@ -275,7 +327,7 @@
they are non-primitive, they are recursively inserted under the parent
object (<literal>joe</literal>) until all primitive types are reached.
In this way, we have broken down the object graph into a tree view which
- fit into our internal structure nicely. Also note that all the primitive
+ fit into our internal structure. Also note that all the primitive
types will be stored
inside the respective
node's HashMap (e.g.,
@@ -287,16 +339,6 @@
, etc. stored there).
</para>
- <figure>
- <title>Object mapping by reachability</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/map.png"/>
- </imageobject>
- </mediaobject>
- </figure>
-
<para>Here is a code snippet to demonstrate the object mapping by
reachability feature that we just explained. Notice how a
<literal>Person</literal>
@@ -306,39 +348,36 @@
</para>
<programlisting>
-import org.jboss.cache.PropertyConfigurator;
-import org.jboss.cache.aop.PojoCache;
+import org.jboss.cache.pojo.PojoCache;
+import org.jboss.cache.pojo.PojoCacheFactory;
import org.jboss.test.cache.test.standAloneAop.Person;
import org.jboss.test.cache.test.standAloneAop.Address;
-PojoCache tree = new PojoCache();
-PropertyConfigurator config = new PropertyConfigurator(); // configure tree cache.
-config.configure(tree, "META-INF/replSync-service.xml");
+String configFile = "META-INF/replSync-service.xml";
+boolean toStart = false; // Deault is true.
+PojoCache cache = PojoCacheFactory.createInstance(configFile, toStart);
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
+Address addr = new Address(); // instantiate an 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.attach("/aop/joe", joe); // add aop sanctioned object (and sub-objects) into cache.
+cache.start(); // kick start cache cache
+cache.attach("pojo/joe", joe); // add aop sanctioned object (and sub-objects) into cache.
// since it is aspectized, use of plain get/set methods will take care of cache contents automatically.
joe.setAge(41);
</programlisting>
<para>Note that a typical
<literal>PojoCache</literal>
- usage involves
- instantiating the
- <literal>PojoCache</literal>
- , configuring, and
- starting the cache instance. Then, a user creates the aspectized POJO
- that will be put into the cache using
+ usage involves instantiating the <literal>PojoCache</literal>
+ from the <literal>PojoCacheFactory</literal> by passing in the underlying <literal>Cache</literal>
+ configuration. Then, a user creates the aspectized POJO that will be put into PojoCache using
<literal>attach()</literal>
API.
</para>
@@ -356,8 +395,7 @@
addition to the above example will trigger PojoCache to manage the
states for the
<literal>Languages</literal>
- list as well. The following figure illustrates the node structure from the replicated GUI point of view.
- Details of Collection class support will be given later.
+ list as well. Details of Collection class support will be given later.
</para>
<programlisting>
@@ -366,16 +404,84 @@
lang.add("Mandarin");
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>Schematic illustration of List class mapping</title>
+ <title>Object cache mapping II</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/demogui.gif"/>
+ <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>
@@ -424,14 +530,13 @@
</para>
<programlisting>
-import org.jboss.cache.PropertyConfigurator;
-import org.jboss.cache.aop.PojoCache;
+import org.jboss.cache.pojo.PojoCache;
+import org.jboss.cache.pojo.PojoCacheFactory;
import org.jboss.test.cache.test.standAloneAop.Person;
import org.jboss.test.cache.test.standAloneAop.Address;
-PojoCache tree = new PojoCache();
-PropertyConfigurator config = new PropertyConfigurator(); // configure tree cache.
-config.configure(tree, "META-INF/replSync-service.xml");
+String configFile = "META-INF/replSync-service.xml";
+PojoCachecache = PojoCacheFactory.createInstance(configFile); // This will start PojoCache automatically
Person joe = new Person(); // instantiate a Person object named joe
joe.setName("Joe Black");
@@ -449,14 +554,13 @@
joe.setAddress(addr); // set the address reference
mary.setAddress(addr); // set the address reference
-tree.startService(); // kick start tree
-tree.attach("/aop/joe", joe); // add aop sanctioned object (and sub-objects) into cache.
-tree.attach("/aop/mary", mary); // add aop sanctioned object (and sub-objects) into cache.
+cache.attach("pojo/joe", joe); // add aop sanctioned object (and sub-objects) into cache.
+cache.attach("pojo/mary", mary); // add aop sanctioned object (and sub-objects) into cache.
Address joeAddr = joe.getAddress();
Address maryAddr = mary.getAddress(); // joeAddr and maryAddr should be the same instance
-tree.detach("/aop/joe");
+cache.detach("pojo/joe");
maryAddr = mary.getAddress(); // Should still have the address.
</programlisting>
@@ -482,17 +586,15 @@
* Code snippet on cache2 during fail-over
*/
import org.jboss.cache.PropertyConfigurator;
-import org.jboss.cache.aop.PojoCache;
+import org.jboss.cache.pojo.PojoCache;
import org.jboss.test.cache.test.standAloneAop.Person;
import org.jboss.test.cache.test.standAloneAop.Address;
-PojoCache tree = new PojoCache();
-PropertyConfigurator config = new PropertyConfigurator(); // configure tree cache.
-config.configure(tree, "META-INF/replSync-service.xml");
-
-tree.startService(); // kick start tree
-Person joe = tree.find("/aop/joe"); // retrieve the POJO reference.
-Person mary = tree.find("/aop/mary"); // retrieve the POJO reference.
+String configFile = "META-INF/replSync-service.xml";
+PojoCache cache = PojoCacheFactory.createInstance(configFile); // This will start PojoCache automatically
+
+Person joe = cache.find("pojo/joe"); // retrieve the POJO reference.
+Person mary = cache.find("pojo/mary"); // retrieve the POJO reference.
Address joeAddr = joe.getAddress();
Address maryAddr = mary.getAddress(); // joeAddr and maryAddr should be the same instance!!!
@@ -534,11 +636,11 @@
joe.setAge(22); // This is also base class attributes
joe.setYear("Senior"); // This is Student class attribute
-tree.attach("/aop/student/joe", joe);
+cache.attach("pojo/student/joe", joe);
//...
-joe = (Student)tree.attach("/aop/student/joe");
+joe = (Student)cache.attach("pojo/student/joe");
Person person = (Person)joe; // it will be correct here
joe.setYear("Junior"); // will be intercepted by the cache
joe.setName("Joe Black II"); // also intercepted by the cache
@@ -583,10 +685,10 @@
list.add("ONE");
list.add("TWO");
-tree.attach("/aop/list", list);
+cache.attach("pojo/list", list);
list.add("THREE"); // This won't intercept by the cache!
-List proxyList = tree.find("/aop/list"; // Note that list is a proxy reference
+List proxyList = cache.find("pojo/list"; // Note that list is a proxy reference
proxyList.add("FOUR"); // This will be intercepted by the cache
</programlisting>
@@ -602,7 +704,7 @@
lang.add("Mandarin");
joe.setLanguages(lang);
// This will map the languages List automatically and swap it out with the proxy reference.
-tree.attach("/aop/student/joe", joe);
+cache.attach("pojo/student/joe", joe);
ArrayList lang = joe.getLanguages(); // Note that lang is a proxy reference
lang.add("French"); // This will be intercepted by the cache
</programlisting>
@@ -624,11 +726,11 @@
list.add("ONE");
list.add("TWO");
-tree.attach("/aop/list", list);
-List proxyList = tree.find("/aop/list"); // Note that list is a proxy reference
+cache.attach("pojo/list", list);
+List proxyList = cache.find("pojo/list"); // Note that list is a proxy reference
proxyList.add("THREE"); // This will be intercepted by the cache
-tree.detach("/aop/list"); // detach from the cache
+cache.detach("pojo/list"); // detach from the cache
proxyList.add("FOUR"); // proxyList has 4 elements still.
</programlisting>
<sect2>
@@ -665,7 +767,7 @@
field to make it replicatable through the JBoss Aop:
<programlisting>
<annotation-introduction expr="field(* POJO>aTransientField)">
- @org.jboss.cache.aop.annotation.NonTransient
+ @org.jboss.cache.pojo.annotation.NonTransient
</annotation-introduction>
</programlisting>
where you are annotating an original transient field <literal>aTransientField</literal> with a <literal>NonTransient</literal>
1.4 +18 -14 JBossCache/docs/PojoCache/en/modules/introduction.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: introduction.xml
===================================================================
RCS file: /cvsroot/jboss/JBossCache/docs/PojoCache/en/modules/introduction.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -b -r1.3 -r1.4
--- introduction.xml 21 Aug 2006 00:36:33 -0000 1.3
+++ introduction.xml 26 Sep 2006 16:24:20 -0000 1.4
@@ -97,7 +97,8 @@
<para>
In PojoCache, these are the typical development and programming steps:
<itemizedlist>
- <listitem>Declare POJO to be "prepared" (in Aop parlance) either through an external xml file (i.e., <literal>jboss-aop.xml</literal>),
+ <listitem>Declare POJO to be "prepared" (in Aop parlance) either through an external xml file (e.g.,
+ <literal>jboss-aop.xml</literal> or <literal>*-aop.xml</literal> with the name of your choice),
or through annotation inside the POJO. Depending on your preference, you can either pre-instrument your POJO (compile time)
or have JBoss Aop do it at load time.</listitem>
<listitem>Use <literal>attach</literal> api to put your POJO under cache management.</listitem>
@@ -105,7 +106,7 @@
transparently.</listitem>
<listitem>During your business logic, you can detach the POJO from the cache system such that any additional
POJO operation won't be intercepted by the cache. You use detach either for external processing or you
- can mark POJO for VM garbage collection.</listitem>
+ can mark the POJO for VM garbage collection.</listitem>
</itemizedlist>
</para>
@@ -120,14 +121,16 @@
transaction, replication, and passivation. For example, when you
operate on a POJO (say, <literal>pojo.setName()</literal>) under a transaction context, it will participate in
the transaction automatically. When the transaction is either committed or rolled back, your POJO operations will act
- accordingly.
+ accordingly (either commit or rollback).
</para>
<para>
- Finally, <literal>PojoCache</literal>
- also provides a way to obtain a
- <literal>Cache</literal> instance such that caller can
- operates on just plain cache APIs.
+ <literal>PojoCache</literal> currently uses <literal>Cache</literal> as the underlying state replication system
+ for POJO fields. As a result, the overall caching behavior is configured through the core Cache system, e.g.,
+ via <literal>*-service.xml</literal>.
+ Furthermore, it also provides a way to obtain a
+ <literal>Cache</literal> instance directly such that caller can
+ operate on just plain cache APIs.
For example, a user can use the
<literal>Cache</literal>
API
@@ -172,7 +175,7 @@
pojoCache.attach("id", p);
tx.begin(); // start a user transaction
p.setName("some pojo");
-txt.rollback(); // this will cause the rollback
+tx.rollback(); // this will cause the rollback
p.getName(); // is "old value"
</programlisting>
Note that the transaction context
@@ -252,7 +255,7 @@
inheritance hierarchy after the object item is stored in the cache.
For example, if a <literal>Student</literal> class inherits from a
<keycode>Person</keycode> class, once a <literal>Student</literal>
- object is mapped to PojoCache (e.g., <literal>putObject</literal>
+ object is mapped to PojoCache (e.g., <literal>attach</literal>
call), the attributes in base class <literal>Person</literal>
is "aspectized" as well.
</para>
@@ -316,11 +319,12 @@
by the delegating Cache implementation. Once the PojoCache instance is obtained, you can call the cache life
cycle method to start the cache. Below is a code snippet that creates and starts the cache:
<programlisting>String configFile = "replSync-service.xml";
-PojoCache pcache = PojoCacheFactory.createInstance(configFiel);
-pcache.start();
+boolean toStart = false;
+PojoCache pcache = PojoCacheFactory.createInstance(configFiel, toStart);
+pcache.start(); // if toStart above is true, it will starts the cache automatically.
pcache.attach(id, pojo);
...
-pcache.stop();
+pcache.stop(); // stop the cache. This will take PojoCache out of the clustering group, if any, e.g.
</programlisting>
</para>
</sect1>
@@ -330,7 +334,7 @@
<para>
<literal>PojoCache</literal> is currently supported on JDK50 (since release 2.0).
It requires the following libraries (in
- addition to jboss-cache-jdk50.jar and the required libraries for the plain
+ addition to jboss-cache.jar and the required libraries for the plain
Cache) to start up:
</para>
@@ -352,7 +356,7 @@
</listitem>
<listitem>
- qdox.jar. Javadoc parser for annotation.
+ qdox.jar. Javadoc parser for annotation. Needed only for JDK1.4 annotation.
</listitem>
</itemizedlist>
</listitem>
1.4 +44 -0 JBossCache/docs/PojoCache/en/modules/jbossaop.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: jbossaop.xml
===================================================================
RCS file: /cvsroot/jboss/JBossCache/docs/PojoCache/en/modules/jbossaop.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -b -r1.3 -r1.4
--- jbossaop.xml 21 Aug 2006 00:36:33 -0000 1.3
+++ jbossaop.xml 26 Sep 2006 16:24:20 -0000 1.4
@@ -270,5 +270,49 @@
</para>
</sect1>
+ <sect1 id="xml-resolving" revision="1">
+ <title>Resolving XML</title>
+ <para>
+ In JBoss Aop there are two forms of bindings for advices, mixins, and introductions: annotation or XML.
+ JBoss AOP resolves pointcut and advice bindings at runtime. So, bindings are a deployment time thing. How
+ does JBoss AOP find the XML files it needs at runtime? There are a couple of ways.
+ </para>
+ <sect2 id="xml-resolving1" revision="1">
+ <title>Standalone XML Resolving</title>
+ <para>
+ When you are running JBoss AOP outside of the application server there are a few ways that the JBoss AOP
+ framework can resolve XML files.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <literal>jboss.aop.path</literal> This is a system property that is a ';' (Windows) or ':' (Unix)
+ delimited list of XML files and/or directories. If the item in the list is a directory, JBoss AOP
+ will load any xml file in those directories with the filename suffix
+ <literal>-aop.xml</literal>
+ </listitem>
+ <listitem>
+ <literal>META-INF/jboss-aop.xml</literal> Any JAR file in your CLASSPATH that has a
+ <literal>jboss-aop.xml</literal>
+ file in the
+ <literal>META-INF/</literal> will be loaded. JBoss AOP does a
+ <literal>ClassLoader.getResources("META-INF/jboss-aop.xml")</literal> to obtain all these files.
+ </listitem>
+ </itemizedlist>
+ </sect2>
+ <sect2 id="xml-resolving2" revision="1">
+ <title>Application Server XML Resolving</title>
+ <para>
+ When you are running JBoss AOP outside of the application server there are a few ways that the JBoss AOP
+ framework can resolve XML files. One is to place an XML file with the suffix
+ <literal>*-aop.xml</literal>
+ in the deploy directory. The other way is to JAR up your classes and provide a
+ <literal>META-INF/jboss-aop.xml</literal>
+ file in this JAR. This JAR file must be suffixed with
+ <literal>.aop</literal> and placed within the deploy/
+ directory or embedded as a nested archive.
+ </para>
+ </sect2>
+ </sect1>
+
</chapter>
\ No newline at end of file
1.4 +9 -8 JBossCache/docs/PojoCache/en/modules/term.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: term.xml
===================================================================
RCS file: /cvsroot/jboss/JBossCache/docs/PojoCache/en/modules/term.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -b -r1.3 -r1.4
--- term.xml 21 Aug 2006 00:36:33 -0000 1.3
+++ term.xml 26 Sep 2006 16:24:20 -0000 1.4
@@ -29,10 +29,11 @@
<term>JBoss Aop</term>
<listitem>
<para>
- JBossAop is an open-source Aop framework library developed by JBoss. It is 100% Java based and can be run
+ JBoss Aop is an open-source Aop framework library developed by JBoss. It is 100% Java based and can be run
either
as a standalone or inside an application server environment. More details can be found at
- www.jboss.com.
+ www.jboss.com. PojoCache uses JBoss Aop library in two ways. It uses JBoss Aop firstly for its own
+ interceptor-based architecture and secondly to realize the fine-grained replication aspects.
</para>
</listitem>
</varlistentry>
@@ -41,7 +42,7 @@
<term>Dynamic Aop</term>
<listitem>
<para>
- Dynamic Aop is a feature of JBossAop that provides a hook so that a caller can insert event
+ Dynamic Aop is a feature of JBoss Aop that provides a hook so that a caller can insert event
interception on the POJO at runtime. PojoCache currently uses this feature to perform
field level interception.
</para>
@@ -67,8 +68,8 @@
Cache is a component of JBoss Cache that is a generic cache system. That is, it stores a straight
Java object reference and requires an object to be serializable to perform binary-wide replication.
It is Java-based, in-memory, replicated,
- and persistent. PojoCache currently uses Cache as a delegate for some basic distributed
- cache functionality such as replication and passivation.
+ and persistent. PojoCache currently uses Cache as a delegate for POJO field level state replication
+ and passivation.
</para>
</listitem>
</varlistentry>
@@ -97,10 +98,10 @@
<term>Prepare</term>
<listitem>
<para>
- Prepare is a keyword in JBossAop pointcut language used to specify which POJO needs to be
- instrumented. It appears in a <literal>jboss-aop.xml</literal> file. However, if you can
+ Prepare is a keyword in JBoss Aop pointcut language used to specify which POJO needs to be
+ instrumented. It appears in a <literal>pojocache-aop.xml</literal> file. However, if you can
use annotation to specify the POJO instrumentation, there is no
- need for a <literal>jboss-aop.xml</literal> listing. Note that
+ need for a <literal>pojocache-aop.xml</literal> listing. Note that
When a POJO is declared properly either through the xml or annotation, we consider it "aspectized".
</para>
</listitem>
More information about the jboss-cvs-commits
mailing list