[jboss-cvs] JBossCache/docs/PojoCache/en/modules ...
Ben Wang
bwang at jboss.com
Sun Aug 20 20:36:33 EDT 2006
User: bwang
Date: 06/08/20 20:36:33
Modified: docs/PojoCache/en/modules api.xml architecture.xml
configuration.xml introduction.xml jbossaop.xml
term.xml
Log:
Update doc for 2.0 release.
Revision Changes Path
1.2 +62 -42 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.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- api.xml 27 Apr 2006 07:38:02 -0000 1.1
+++ api.xml 21 Aug 2006 00:36:33 -0000 1.2
@@ -2,7 +2,7 @@
<title>API</title>
- <para>In PojoCache, there are 3 core APIs for
+ <para>In PojoCache, there are 3 core APIs
for pojo management and one
additional one for querying.
@@ -18,18 +18,35 @@
<title>Attachment</title>
<programlisting>
-/*
- * @param fqn The fqn instance to associate with the object in the cache.
- * @param pojo aop-enabled object to be inserted into the cache. If null,
- * it will nullify the fqn node.
- * @throws CacheException
-*/
-Object putObject(Fqn fqn, Object pojo) throws CacheException;
+ /**
+ * Attach a POJO into PojoCache. It will also recursively put any sub-POJO into
+ * the cache system. A POJO can be the following and have the consqeuences when attached:
+ *
+ * It is PojoCacheable, that is, it has been annotated with
+ * {@see org.jboss.cache.aop.annotation.PojoCacheable} annotation (or via XML), and has
+ * been "instrumented" either compile- or load-time. The POJO will be mapped recursively to
+ * the system and fine-grained replication will be performed.
+ *
+ * It is Serializable. The POJO will still be stored in the cache system. However, it is
+ * treated as an "opaque" object per se. That is, the POJO will neither be intercepted
+ * (for fine-grained operation) or object relantionship will be maintained.
+ *
+ * Neither of above. In this case, a user can specify whether it wants this POJO to be
+ * stored (e.g., replicated or persistent). If not, a PojoCacheException will be thrown.
+ *
+ * @param id An id String to identify the object in the cache. To promote concurrency, we
+ * recommend the use of hierarchical String separating by a designated separator. Default
+ * is "/" but it can be set differently via a System property, jbosscache.separator
+ * in the future release. E.g., "ben", or "student/joe", etc.
+ * @param pojo object to be inerted into the cache. If null, it will nullify the fqn node.
+ * @return Existing POJO or null if there is none.
+ * @throws PojoCacheException Throws if there is an error related to the cache operation.
+ */
+ Object attach(String id, Object pojo) throws PojoCacheException;
</programlisting>
<para>
- Calling this Api will put your POJO into the cache management under <literal>fqn</literal>
- where <literal>fqn</literal> is a user-specified fully qualified name (<literal>FQN</literal>)
- to store the node in the underlying cache, e.g., "<literal>/aop/joe</literal>". The
+ Calling this Api will put your POJO into the cache management under <literal>id</literal> String.
+The
<literal>pojo</literal> is the object instance to be managed by <literal>PojoCache</literal>.
</para>
@@ -49,7 +66,7 @@
<literal>pojo</literal>
has sub-objects, e.g., it has fields
that are non-primitive type, this call will issue
- <literal>putObject</literal>
+ <literal>attach</literal>
recursively until all object tree are
traversed (mapping by reachability). In addition, if you put
<literal>pojo</literal>
@@ -72,25 +89,24 @@
<title>Detachment</title>
<programlisting>
-/**
- * Remove aop-enabled object from the cache. After successful call of this API, the returning
- * POJO is no longer managed by the cache.
- *
- * @param fqn Instance that associates with this node.
- * @return Original POJO stored under this node.
- * @throws CacheException
+ /**
+ * Remove POJO object from the cache.
+ *
+ * @param id Is string that associates with this node.
+ * @return Original value object from this node.
+ * @throws PojoCacheException Throws if there is an error related to the cache operation.
*/
-Object removeObject(Fqn fqn) throws CacheException;
+ Object detach(String id) throws PojoCacheException;
</programlisting>
<para>
- This call will detach the POJO from the cache management by removing the contents under fqn
+ This call will detach the POJO from the cache management by removing the contents under id
and return the POJO instance stored there (null if it doesn't exist). After successfully call, any POJO
operation on the returned POJO reference is not intercepted by the cache system anymore. So in essence,
you will use this Api should you decide that the POJO under <literal>fqn</literal> is no longer necessary.
For example, if a POJO is no longer in context, you will need explicitly invoke this Api otherwise it
won't get garbage collected by the VM.
- Note this call will also remove everything stored under <literal>fqn</literal> even if you have put
+ Note this call will also remove everything stored under <literal>id</literal> even if you have put
other plain cache data there.
</para>
</sect1>
@@ -98,19 +114,21 @@
<sect1>
<title>Query</title>
<programlisting>
-/**
- * Retrieve the Pojo from the cache. Return null if object does not exist in the cache.
+
+ /**
+ * Retrieve POJO from the cache system. Return null if object does not exist in the cache.
+ * Note that this operation is fast if there is already a POJO instance attached to the cache.
*
- * @param fqn Instance that associates with this node.
- * @return Current POJO value. Null if does not exist.
- * @throws CacheException
+ * @param id that associates with this node.
+ * @return Current content value. Null if does not exist.
+ * @throws PojoCacheException Throws if there is an error related to the cache operation.
*/
-Object getObject(Fqn fqn) throws CacheException;
+ Object find(String id) throws PojoCacheException;
</programlisting>
<para>
This call will
return the current object content located under
- <literal>fqn</literal>. This method call is useful when you don't have the exact POJO reference.
+ <literal>id</literal>. This method call is useful when you don't have the exact POJO reference.
For example, when you fail over to the
replicated node, you want to get the object reference from the replicated cache instance.
In that case, PojoCache will create a new Java object if it does not exist and
@@ -119,16 +137,18 @@
</para>
<programlisting>
-/**
- * Query all managed pojo objects under the fqn recursively. Note that this will not return the sub-object POJOs,
- * e.g., if Person has a sub-object of Address, it won't return Address pojo. Note also that this operation is
- * not thread-safe now. In addition, it assumes 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.
- * @param fqn The starting place to find all POJOs.
- * @return Map of all POJOs found with (fqn, pojo) pair. Return size of 0, if not found.
- * @throws CacheException
+ /**
+ * Query all managed POJO objects under the id recursively. Note that this will not return
+ * the sub-object POJOs, e.g., if Person has a sub-object of Address, it
+ * won't return Address pojo. Also note also that this operation is not thread-safe
+ * now. In addition, it assumes that once a POJO is found with a id, no more POJO is stored
+ * under the children of the id. That is, we don't mix the id with different POJOs.
+ *
+ * @param id The starting place to find all POJOs.
+ * @return Map of all POJOs found with (id, POJO) pair. Return size of 0, if not found.
+ * @throws PojoCacheException Throws if there is an error related to the cache operation.
*/
-public Map findObjects(Fqn fqn) throws CacheException;
+ Map findAll(String id) throws PojoCacheException;
</programlisting>
<para>
1.6 +114 -30 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.5
retrieving revision 1.6
diff -u -b -r1.5 -r1.6
--- architecture.xml 5 Jul 2006 10:39:30 -0000 1.5
+++ architecture.xml 21 Aug 2006 00:36:33 -0000 1.6
@@ -2,10 +2,72 @@
<title>Architecture</title>
- <para>Following explains the concepts and top-level design
- of PojoCache.</para>
+ <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
+ interceptor feature). Following explains the concepts and top-level design of PojoCache.</para>
<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>,
+ 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:
+<programlisting>
+ <!-- Check id range validity -->
+ <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"/>
+ <!-- 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"/>
+ <!-- Perform parent level node locking -->
+ <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 name="Reentrant" class="org.jboss.cache.pojo.interceptors.MethodReentrancyStopperInterceptor"
+ scope="PER_INSTANCE"/>
+ <!-- Whether to allow non-serializable pojo -->
+ <interceptor name="MarshallNonSerializable" class="org.jboss.cache.pojo.interceptors.CheckNonSerializableInterceptor"
+ scope="PER_INSTANCE">
+ <attribute name="marshallNonSerializable">false</attribute>
+ </interceptor>
+
+ <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>
+
+ <stack name="Detach">
+ <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>
+
+ <stack name="Find">
+ <interceptor-ref name="Start"/>
+ <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>
+
+ </sect1>
+ <sect1>
<title>Dynamic AOP interception</title>
<para>JBossAop provides an API (<literal>appendInterceptor</literal>) to
@@ -14,7 +76,7 @@
will have an associated
<literal>org.jboss.aop.InstanceAdvisor</literal>
instance. During a
- <literal>putObject(FQN fqn, Object pojo)</literal>
+ <literal>attach(String id, Object pojo)</literal>
operation (API explained below), PojoCache will examine to see if
there is already a
<literal>org.jboss.cache.aop.CacheInterceptor</literal>
@@ -37,7 +99,7 @@
the backend cache store. Please note that,
<itemizedlist>
<listitem>
- the filed level interception applies to all access qualifiers.
+ the field level interception applies to all access qualifiers.
That is, regardless whether it is <literal>public</literal>, <literal>protected</literal>, or
<literal>private</literal>
</listitem>
@@ -50,7 +112,7 @@
</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
- <literal>putObject</literal>
+ <literal>attach</literal>
method has been called), Aop will invoke
<literal>CacheInterceptor</literal>
automatically every time there is a
@@ -91,7 +153,7 @@
"prepared" (e.g., a
<literal>Person</literal>
object), during the
- <literal>putObject(Fqn fqn, Object pojo)</literal>
+ <literal>attach(String id, Object pojo)</literal>
operation,
PojoCache will add a
<literal>CacheInterceptor</literal>
@@ -108,7 +170,7 @@
<itemizedlist>
<listitem>
<para>Create a tree node using
- <literal>fqn</literal>, if not yet
+ <literal>id</literal> (internally translated into Cache <literal>fqn</literal>, if not yet
existed.
</para>
</listitem>
@@ -124,7 +186,7 @@
<listitem>
<para>If it is a primitive type, the field value will be stored
under
- <literal>fqn</literal>
+ <literal>id</literal>
with
<literal>(key,
value)</literal>
@@ -141,7 +203,7 @@
<listitem>
<para>If it is a non-primitive type, creates a child
- <literal>FQN</literal>
+ <literal>id</literal>
and then recursively executes another
<literal>pubObject</literal>
until it reaches all primitive
@@ -163,7 +225,7 @@
if (fieldType.isImmediate()) {
immediates.put(field.getName(), value);
} else {
- putObject(new Fqn(fqn, field.getName()), value);
+ _attach(new Fqn(fqn, field.getName()), value);
}</programlisting>
<para>Let's take an example POJO class definition from the Appendix
@@ -172,7 +234,7 @@
object that has
composite non-primitive types (e.g., List and Address). After we execute
the
- <literal>putObject</literal>
+ <literal>attach</literal>
call, the resulting tree node will
schematically look like the cache node in the following figures:
</para>
@@ -181,7 +243,7 @@
Person joe = new Person();
joe.setAddress(new Address());
-cache.putObject("/aop/joe", joe);
+cache.attach("/aop/joe", joe);
</programlisting>
<para>The PojoCache APIs will be explained in fuller details later.
@@ -264,7 +326,7 @@
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.
+tree.attach("/aop/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>
@@ -277,7 +339,7 @@
, configuring, and
starting the cache instance. Then, a user creates the aspectized POJO
that will be put into the cache using
- <literal>putObject()</literal>
+ <literal>attach()</literal>
API.
</para>
@@ -388,13 +450,13 @@
mary.setAddress(addr); // set the address reference
tree.startService(); // kick start tree
-tree.putObject("/aop/joe", joe); // add aop sanctioned object (and sub-objects) into cache.
-tree.putObject("/aop/mary", mary); // add aop sanctioned object (and sub-objects) into cache.
+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.
Address joeAddr = joe.getAddress();
Address maryAddr = mary.getAddress(); // joeAddr and maryAddr should be the same instance
-tree.removeObject("/aop/joe");
+tree.detach("/aop/joe");
maryAddr = mary.getAddress(); // Should still have the address.
</programlisting>
@@ -429,8 +491,8 @@
config.configure(tree, "META-INF/replSync-service.xml");
tree.startService(); // kick start tree
-Person joe = tree.getObject("/aop/joe"); // retrieve the POJO reference.
-Person mary = tree.getObject("/aop/mary"); // retrieve the POJO reference.
+Person joe = tree.find("/aop/joe"); // retrieve the POJO reference.
+Person mary = tree.find("/aop/mary"); // retrieve the POJO reference.
Address joeAddr = joe.getAddress();
Address maryAddr = mary.getAddress(); // joeAddr and maryAddr should be the same instance!!!
@@ -472,11 +534,11 @@
joe.setAge(22); // This is also base class attributes
joe.setYear("Senior"); // This is Student class attribute
-tree.putObject("/aop/student/joe", joe);
+tree.attach("/aop/student/joe", joe);
//...
-joe = (Student)tree.putObject("/aop/student/joe");
+joe = (Student)tree.attach("/aop/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
@@ -509,7 +571,7 @@
</itemizedlist>
To obtain the proxy reference,
users can then use another
- <literal>getObject</literal>
+ <literal>find</literal>
to retrieve this proxy reference and use
this reference to perform POJO operations.
</para>
@@ -521,10 +583,10 @@
list.add("ONE");
list.add("TWO");
-tree.putObject("/aop/list", list);
+tree.attach("/aop/list", list);
list.add("THREE"); // This won't intercept by the cache!
-List proxyList = tree.getObject("/aop/list"; // Note that list is a proxy reference
+List proxyList = tree.find("/aop/list"; // Note that list is a proxy reference
proxyList.add("FOUR"); // This will be intercepted by the cache
</programlisting>
@@ -540,7 +602,7 @@
lang.add("Mandarin");
joe.setLanguages(lang);
// This will map the languages List automatically and swap it out with the proxy reference.
-tree.putObject("/aop/student/joe", joe);
+tree.attach("/aop/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>
@@ -553,7 +615,7 @@
</para>
<para>
- Finally, when you remove a Collection reference from the cache (e.g., via <literal>removeObject</literal>),
+ Finally, when you remove a Collection reference from the cache (e.g., via <literal>detach</literal>),
you still can use the proxy reference since we will update the in-memory copy of that reference during
detachment. Below is a code snippet illustrating this:
</para>
@@ -562,11 +624,11 @@
list.add("ONE");
list.add("TWO");
-tree.putObject("/aop/list", list);
-List proxyList = tree.getObject("/aop/list"); // Note that list is a proxy reference
+tree.attach("/aop/list", list);
+List proxyList = tree.find("/aop/list"); // Note that list is a proxy reference
proxyList.add("THREE"); // This will be intercepted by the cache
-tree.removeObject("/aop/list"); // detach from the cache
+tree.detach("/aop/list"); // detach from the cache
proxyList.add("FOUR"); // proxyList has 4 elements still.
</programlisting>
<sect2>
@@ -591,4 +653,26 @@
</sect2>
</sect1>
+ <sect1>
+ <title>POJO requirement</title>
+ <para>The POJO requirement for PojoCache are:
+ <itemizedlist>
+ <listitem>It does not require to implment <literal>Serializable</literal>, but it does require there is a
+ no-arg constructor declared (can be private). This is needed such that during failover, it has a way
+ to reconstruct the POJO.</listitem>
+ <listitem>There are specific default behaviors for different modifiers as mentioned (<literal>static</literal>,
+ <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)">
+ @org.jboss.cache.aop.annotation.NonTransient
+ </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.
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect1>
+
</chapter>
1.3 +6 -42 JBossCache/docs/PojoCache/en/modules/configuration.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: configuration.xml
===================================================================
RCS file: /cvsroot/jboss/JBossCache/docs/PojoCache/en/modules/configuration.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -b -r1.2 -r1.3
--- configuration.xml 28 Apr 2006 08:37:07 -0000 1.2
+++ configuration.xml 21 Aug 2006 00:36:33 -0000 1.3
@@ -3,12 +3,12 @@
<title>Configuration</title>
- <para>Since PojoCache inherits from TreeCache, the xml configuration
- file attributes are almost identical to that of the latter one. Attributes such
- as replication mode, transaction manager, eviction policy, cache loader,
- and JGroups stack, for example, are still the same. There are two
- differences, however, when using the xml file--- configuring as a MBean
- service and eviction policy.</para>
+ <para>Since PojoCache uses Cache as a delegate for the underlying node replication,
+ transaction,
+ locking, and passivation behavior, user of PojoCache will need to configure the xml
+ for the Cache implementation. In addition, there is another <literal>jboss-aop.xml</literal>
+ for some customized behaviors (if needs to).
+ Finally, how do we deal with the PojoCache bean service?</para>
<sect1>
<title>PojoCache MBean service</title>
@@ -22,40 +22,4 @@
</para>
</sect1>
- <sect1>
- <title>PojoCache eviction policy</title>
-
- <para>PojoCache also provides an eviction policy,
- <literal>org.jboss.cache.aop.eviction.AopLRUPolicy</literal>
- , that is a
- subclass of
- <literal>org.jboss.cache.eviction.LRUPolicy</literal>
- (with
- the same configuration parameters). The reason we need a distinctive
- implementation is because eviction in PojoCache is quite different
- from the regular TreeCache. In the plain cache world, a unit is a FQN
- node, while in the aop world, the concept of a unit is an object (which
- can have multiple nodes and children nodes!).
- </para>
-
- <para>In addition, once a user obtains a POJO reference, everything is
- supposed to be transparent, e.g., cache retrieval and update operations.
- But if an object is evicted, that means there is no
- <literal>CacheInterceptor</literal>
- for the POJO, and the contents are
- not intercepted by the cache. Instead, every operation access will be
- channeled to the in-memory reference. So all operations will succeed but
- then a user has no way of knowing that it is merely updating the
- in-memory reference!
- </para>
-
- <para>To remedy this problem, we currently requires that eviction policy is used in combination of a cache loader
- to persist the data. It can either be fully persistency or passivation (e.g., only persist when it is evicted).
- In this way, when the node is not available it will be retrieved from the persistent store. The downside is that
- the POJO won't be transient, e.g., it is persistent all time unless a specific user-based
- <literal>removeObject</literal> is called.
- </para>
- </sect1>
-
-
</chapter>
\ No newline at end of file
1.3 +123 -113 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.2
retrieving revision 1.3
diff -u -b -r1.2 -r1.3
--- introduction.xml 28 Apr 2006 08:37:07 -0000 1.2
+++ introduction.xml 21 Aug 2006 00:36:33 -0000 1.3
@@ -6,27 +6,38 @@
<title id="s1">Overview</title>
<para>
- The two components in JBossCache, plain cache (implemented as TreeCache) and PojoCache (implemented
- as PojoCache), are both in-memory, transactional,
+ The two components in JBossCache, generic cache (Cache implementation) and POJO cache (
+ PojoCache implementation), are both in-memory, transactional,
replicated, and persistent.
- However, TreeCache is typically used as a plain cache system. That is,
+ However, Cache is used as a generic cache system only. That is,
it directly stores the object references and has a
- <literal>HashMap</literal>-like Api.
- If replication or persistency is turned on, the object will then need to
- implement the
- <literal>Serializable</literal>
- interface. In addition, it has known limitations:
+ <literal>HashMap</literal>-like Api. As a result, it is fairly intuitive and easy to use for
+ local or distributed caching.
+ Nonetheless, it has the following constraints:
<itemizedlist>
- <listitem>Users will have to manage the cache specifically; e.g., when an object is updated, a user will need
+ <listitem>If replication or persistency is needed, the object will then need to
+ implement the <literal>Serializable</literal> interface.
+ <programlisting>public Class Foo implements Serializable</programlisting>
+ </listitem>
+ <listitem>Users will have to manage the cache specifically, e.g., when an object is updated, a user will need
a corresponding
- API call to update the cache content.</listitem>
- <listitem>If the object size is huge, even a single field update would trigger the whole object
- serialization. Thus, it can be
- unnecessarily expensive.</listitem>
+ API call to update the cache content.
+<programlisting>value = new Foo();
+cache.put(fqn, key, value);
+value.update(); // update value
+cache.put(fqn, key, value); // Need to repeat this step again to ask cache to persist or replicate the changes</programlisting>
+ </listitem>
+ <listitem>If the object size is huge, even a single POJO field update would trigger the whole object
+ to serialize. Thus, it can be unnecessarily expensive.
+<programlisting>value = new Foo();
+cache.put(fqn, key, value);
+value.update(); // update value
+cache.put(fqn, key, value); // This replicates the whole Foo instance</programlisting>
+ </listitem>
<listitem>The object structure can not have a graph relationship. That is, the object can not have
sub-objects that are shared (multiple
referenced) or referenced to itself (cyclic). Otherwise, the relationship will be broken upon
- serialization. For example, Figure 1
+ serialization (e.g., when replicate each parent object separately). For example, Figure 1
illustrates this problem during replication.
If we have two
<literal>Person</literal>
@@ -35,7 +46,16 @@
,
upon replication, it will be split into two separate
<literal>Address</literal>
- instances (instead of just one).
+ instances (instead of just one). The following is the code snippet using Cache that illustrates this
+ problem:
+<programlisting>joe = new Person("joe");
+mary = new Person("mary");
+addr = new Address("Taipei");
+joe.setAddress(addr);
+mary.setAddress(addr);
+cache.put("/joe", "person", joe);
+cache.put("/mary", "person", mary);
+</programlisting>
</listitem>
</itemizedlist>
</para>
@@ -52,16 +72,25 @@
<para>PojoCache, on the other hand,
is a
- fine-grained "object-oriented" cache. By "object-oriented", we mean that
+ fine-grained "object-oriented" POJO cache. By "object-oriented", we mean that
PojoCache provides tight integration with the object-oriented Java
language paradigm, specifically,
<itemizedlist>
- <listitem>no need to implement <literal>Serializable</literal> interface for the POJOs.</listitem>
+ <listitem>no need to implement <literal>Serializable</literal> interface for the POJOs. Instead, POJO
+ instrumentation during compile or load time is needed (see later for details).</listitem>
<listitem>
replication (or even persistency)
- is done on a per-field basis (as opposed to the whole object binary level).</listitem>
+ is done on a per-field basis (as opposed to the whole object binary level). This is the fine-grained
+ replication vs. coarse-grained one in a generic cache library like Cache.</listitem>
<listitem> the object relationship and identity are preserved automatically in a distributed,
replicated environment. It enables transparent usage behavior and increases software performance.</listitem>
+ <listitem>Once the POJO is attached to the cache system, all subsquent POJO operation will trigger
+ the replication or persistency automatically.
+<programlisting>POJO pojo = new POJO();
+pojoCache.attach("id", pojo);
+pojo.setName("some pojo"); // This will trigger replication automatically.
+</programlisting>
+ </listitem>
</itemizedlist>
</para>
@@ -70,9 +99,13 @@
<itemizedlist>
<listitem>Declare POJO to be "prepared" (in Aop parlance) either through an external xml file (i.e., <literal>jboss-aop.xml</literal>),
or through annotation inside the POJO. Depending on your preference, you can either pre-instrument your POJO (compile time)
- or have JBossAop do it at load time.</listitem>
- <listitem>Use <literal>putObject</literal> Api to put your POJO under cache management.</listitem>
- <listitem>Operate on POJO directly. Cache will then manage your replication or persistency automatically.</listitem>
+ or have JBoss Aop do it at load time.</listitem>
+ <listitem>Use <literal>attach</literal> api to put your POJO under cache management.</listitem>
+ <listitem>Operate on POJO directly. Cache will then manage your replication or persistency automatically and
+ 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>
</itemizedlist>
</para>
@@ -82,28 +115,29 @@
<para>
<literal>PojoCache</literal>
- also extends the functionality of
- TreeCache to object based. That is, the TreeCache features such as
- transaction, replication, eviction policy, and cache loader, has been extended to POJO level. For example, when you
+ offers similar functionality to that of
+ Cache at POJO level, specifically,
+ 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
- that transaction automatically. When the transaction is either committed or rolled back, your POJO operations will act
+ the transaction automatically. When the transaction is either committed or rolled back, your POJO operations will act
accordingly.
</para>
<para>
Finally, <literal>PojoCache</literal>
- can also be used as a plain
- <literal>TreeCache</literal>
- . For example, a user can use the
- <literal>TreeCache</literal>
+ also provides a way to obtain a
+ <literal>Cache</literal> instance such that caller can
+ operates on just plain cache APIs.
+ For example, a user can use the
+ <literal>Cache</literal>
API
[e.g.,
<literal>get(String fqn)</literal>
and
- <literal>set(String fqn,
+ <literal>put(String fqn,
String key, String value)</literal>
- ] to manage the cache states. Of
- course, users will need to consider the extra cost (albeit slight) in doing this.
+ ] to manage the cache states. Keep in mind again that your POJO is managed as a generic cache system in
+ this case.
</para>
</sect1>
@@ -115,30 +149,33 @@
<itemizedlist>
<listitem>
<para>Fine-grained replication. The replication mode supported is the
- same as that of the TreeCache:
- <literal>LOCAL</literal>
- ,
- <literal>REPL_SYNC</literal>
- , and
- <literal>REPL_ASYNC</literal>. The
- replication level is fine-grained and is done automatically once the POJO is mapped into the
+ same as that of the Cache implementation:
+ <literal>LOCAL</literal>, <literal>REPL_SYNC</literal>, <literal>REPL_ASYNC</literal>,
+ <literal>INVALIDATION_SYNC</literal>, and <literal>INVALIDATION_ASYNC</literal> (see the
+ main <ulink url="TreeCache.html">JBossCache</ulink> reference documentation for details). The
+ replication level is fine-grained and is performed automatically once the POJO is mapped into the
internal cache store. When a POJO field is updated, a replication request
will be sent out only to the node
corresponding to that modified attribute (instead of the whole
object). This can have a potential performance boost during the replication
process; e.g., updating a single key in a big HashMap will only
- replicate the single field instead of the whole map! Please see the
- documentation of
- <ulink url="TreeCache.html">JBossCache</ulink>
- for
- more details on cache mode.
+ replicate the single field instead of the whole map!
</para>
</listitem>
<listitem>
- <para>Transaction. The POJO operation can be transacted once a
- TransactionManager is specified properly. Upon user rollback, it will
- rollback all POJO operations as well. Note that the transaction context
+ <para>Transaction. The POJO operation can participate in a user transaction context.
+ Upon user rollback, it will
+ rollback all POJO operations as well. For example,
+<programlisting>POJO p = new POJO();
+p.setName("old value");
+pojoCache.attach("id", p);
+tx.begin(); // start a user transaction
+p.setName("some pojo");
+txt.rollback(); // this will cause the rollback
+p.getName(); // is "old value"
+</programlisting>
+ Note that the transaction context
only applies to the node level though. That is, in a complex object
graph where you have multiple sub-nodes, only the nodes (or fields)
accessed by a user are under transaction context. To give an example, if I have
@@ -152,20 +189,13 @@
</listitem>
<listitem>
- <para>Eviction policy. PojoCache supports eviction policy that can
- evict the whole POJO object (and any field object references,
- recursively). Currently there is an eviction policy class called
- <literal>org.jboss.cache.aop.eviction.AopLRUPolicy</literal>
- (that is
- sub-class of
- <literal>org.jboss.cache.eviction.LRUPolicy</literal>
- ).
- The configuration parameters are the same as those of the TreeCache
- counterpart. Note that the concept of "Region" in eviction needs to
- be carefully defined at the top of the object FQN level. Otherwise,
- eviction policy will not operate correctly. That is, since "Region" is used to
- define the eviction policy, if you define a "Region" inside a POJO sub-tree, it may
- not be desirable.
+ <para>Passivation. PojoCache supports passivation that can passivate any underlying POJO value. By passivation
+ of a node, we mean when it passivates, the node is evicted from in-memory and stored into a backend
+ cache store of user's choice. When the node is accessed again, it will be retrieved from the store
+ and put into memory.
+ The configuration parameters are the same as those of the Cache
+ counterpart. To configure the passivation, you will need to configure both the eviction policy and
+ cacheloader.
</para>
</listitem>
@@ -176,12 +206,9 @@
<literal>PojoCache</literal>
will
transparently manage the sub-object states as well. During the initial
- <literal>putObject()</literal>
- call,
- <literal>PojoCache</literal>
+ <literal>attach()</literal> call, <literal>PojoCache</literal>
will traverse the object tree and map it accordingly to the internal
- TreeCache nodes. This feature is explained in full details
- later.
+ Cache nodes. This feature is explained in full details later.
</para>
</listitem>
@@ -195,7 +222,7 @@
<listitem>
<para>Automatic support of object identity. In PojoCache, each
- object is uniquely identified by an internal FQN. Client can determine
+ object is uniquely identified by a String id. Client can determine
the object equality through the usual
<literal>equal</literal>
method.
@@ -215,8 +242,7 @@
</para>
<para>Finally, a POJO can be stored under multiple
- <code>Fqn</code>s
- in the cache as well, and its identity is still preserved when retrieved from
+ ids in the cache as well, and its identity is still preserved when retrieved from
both places (after replication).
</para>
</listitem>
@@ -224,27 +250,20 @@
<listitem>
<para>Inheritance relationship. PojoCache preserves the POJO
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>
- call), the attributes in base class
- <literal>Person</literal>
- is
- "aspectized" as well.
+ 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>
+ call), the attributes in base class <literal>Person</literal>
+ is "aspectized" as well.
</para>
</listitem>
<listitem>
<para>Support Collection classes (e.g., List, Set, and Map based
- objects) automatically without declaring them as aop-enabled. That is,
+ objects) automatically without aop instrumentation first. That is,
you can use them either as a plain POJO or a sub-object to POJO
without declaring them as "aspectized". In addition, it supports
- runtime swapping of the proxy reference as well.</para>
+ runtime swapping of the proxy reference as well. Details are described later.</para>
</listitem>
<listitem>
@@ -253,8 +272,7 @@
<literal>aopc</literal>, so-called compile-time mode in JBossAop) and generate
the byte code necessary for AOP system. By pre-compiling the
user-specified POJOs, there is no need for additional declaration file
- (e.g.,
- <literal>jboss-aop.xml</literal>
+ (e.g., <literal>jboss-aop.xml</literal>
) or specifying a JBossAop
system classloader. A user can treat the pre-generated classes as
regular ones and use PojoCache in a non-intrusive way.
@@ -267,21 +285,17 @@
</listitem>
<listitem>
- <para>POJO needs not implement the
- <code>Serializable</code>
- interface.
+ <para>POJO needs not implement the <code>Serializable</code> interface.
</para>
</listitem>
<listitem>
- <para>Support annotation usage. Starting from release 1.2.3,
+ <para>Support annotation usage. Starting from release 2.0,
PojoCache also supports declaration of POJO through annotation
- under JDK1.4. JBossAop provides an annotation precompiler that a user
- can use to pre-process the annotation. As a result, there will be no
- need for
- <literal>jboss-aop.xml</literal>
+ under JDK5.0. As a result, there will be no
+ need for <literal>jboss-aop.xml</literal>
file declaration for POJOs,
- if annotation is preferred. The JDK5.0 annotation will be supported in the next release.
+ if annotation is preferred.
</para>
</listitem>
@@ -298,17 +312,15 @@
<sect1 id="3">
<title>Usage</title>
<para>
- To use PojoCache, it is similar to its TreeCache counter part. Basically, you instantiate a PojoCache
- instance first. Then, you can either configure it programmatically or through an external xml file. Finally, you
- call the cache life cycle method to start the cache. Below is a code snippet that creates and starts the cache
- through an external xml file:
-<programlisting>
- cache_ = new PojoCache();
- PropertyConfigurator config = new PropertyConfigurator(); // configure tree cache.
- config.configure(cache_, "META-INF/replSync-service.xml"); // Search under the classpath
- cache_.start();
- ...
- cache_.stop();
+ To use PojoCache, you obtain the instance from the PojoCacheFactory by supplying a config file that is used
+ 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();
+pcache.attach(id, pojo);
+...
+pcache.stop();
</programlisting>
</para>
</sect1>
@@ -316,10 +328,10 @@
<title>Requirement</title>
<para>
- <literal>PojoCache</literal> is currently supported on both JDK1.4 and JDK50.
- For JDK1.4, it requires the following libraries (in
- addition to jboss-cache.jar and the required libraries for the plain
- TreeCache) to start up:
+ <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
+ Cache) to start up:
</para>
<itemizedlist>
@@ -328,7 +340,7 @@
<itemizedlist>
<listitem>
- jboss-aop.jar. Main JBossAop library.
+ jboss-aop-jdk50.jar. Main JBossAop library.
</listitem>
<listitem>
@@ -345,8 +357,6 @@
</itemizedlist>
</listitem>
</itemizedlist>
- <para>For JDK5.0, in addition to the above libaries, you will need to replace jboss-cache.jar
- with jboss-cache-jdk50.jar and jboss-aop.jar with jboss-aop-jdk50.jar from lib-50 directory.</para>
</sect1>
</chapter>
1.3 +8 -51 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.2
retrieving revision 1.3
diff -u -b -r1.2 -r1.3
--- jbossaop.xml 28 Apr 2006 08:37:07 -0000 1.2
+++ jbossaop.xml 21 Aug 2006 00:36:33 -0000 1.3
@@ -229,12 +229,8 @@
<title>Annotations</title>
<para>
- Annotations are only available in JDK 5.0, but using our annotation compiler
- you can acheive similar functionality with JDK 1.4.2 as well.
- </para>
-
- <para>
- Annotations must map to an annotation type, in JDK 5.0 they are defined as:
+ Annotations are available in JDK 5.0 that must map to an annotation type.
+ In JDK 5.0 they are defined as:
<programlisting>
package com.mypackage;
@@ -245,66 +241,27 @@
int myInteger();
}
</programlisting>
-
- Annotation types for use with the annotation compiler are defined in exactly
- the same way for JDK 1.4.2, with the important difference that '@interface'
- is replaced by 'interface'. i.e. the similar annotation type is a normal
- Java interface:
- <programlisting>
- package com.mypackage;
-
- public interface MyAnnotation
- {
- String myString();
- int myInteger();
- }
- </programlisting>
- </para>
-
- <para>
- The syntax for using annotations in JDK 1.4.2 is almost exactly the same as
- JDK 5.0 annotations except for these subtle differences:
- <itemizedlist>
- <listitem>they are embedded as doclet tags</listitem>
- <listitem>You use a double at sign, i.e. '@@'</listitem>
- <listitem>
- You MUST have a space after the tag name otherwise you will get
- a compilation error. (This is the quirkiness of the QDox doclet compiler
- used to compile the annotations.')
- </listitem>
- <listitem>
- You cannot import the annotation type, you must use the fully
- qualified name of the interface.
- </listitem>
- <listitem>You cannot specify default values for an annotation's value</listitem>
- </itemizedlist>
- </para>
+</para>
<para>
- This example shows an annotated class in JDK 1.4.2:
+ This example shows an annotated class in JDK5.0:
<programlisting>
package com.mypackage;
/**
- * @@com.mypackage.MyAnnotation (myString="class", myInteger=5)
*/
+ @com.mypackage.MyAnnotation (myString="class", myInteger=5)
public class MyClass
{
- /**
- * @@com.mypackage.MyAnnotation (myString="field", myInteger=4)
- */
+ @com.mypackage.MyAnnotation (myString="field", myInteger=4)
private String myField;
- /**
- * @@com.mypackage.MyAnnotation (myString="constructor", myInteger=3)
- */
+ @com.mypackage.MyAnnotation (myString="constructor", myInteger=3)
public MyClass()
{
}
- /**
- * @@com.mypackage.MyAnnotation (myString="method", myInteger=3)
- */
+ @com.mypackage.MyAnnotation (myString="method", myInteger=3)
public int myMethod()
{
}
1.3 +7 -6 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.2
retrieving revision 1.3
diff -u -b -r1.2 -r1.3
--- term.xml 28 Apr 2006 08:37:07 -0000 1.2
+++ term.xml 21 Aug 2006 00:36:33 -0000 1.3
@@ -26,7 +26,7 @@
</varlistentry>
<varlistentry>
- <term>JBossAop</term>
+ <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
@@ -61,13 +61,14 @@
</varlistentry>
<varlistentry>
- <term>TreeCache</term>
+ <term>Cache</term>
<listitem>
<para>
- TreeCache is a component of JBossCache that is a plain cache system. That is, it stores a straight
+ 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 is a sub-class of TreeCache.
+ and persistent. PojoCache currently uses Cache as a delegate for some basic distributed
+ cache functionality such as replication and passivation.
</para>
</listitem>
</varlistentry>
@@ -86,8 +87,8 @@
<listitem>
<para>
Annotation is a new feature in JDK5.0. It introduces metadata along side the Java code that can
- be accessed at runtime. PojoCache currently use both JDK1.4 and JDK50 annotation to support POJO
- instrumentation.
+ be accessed at runtime. PojoCache currently uses JDK50 annotation to support POJO
+ instrumentation (JDK1.4 annotation has been deprecated since release 2.0).
</para>
</listitem>
</varlistentry>
More information about the jboss-cvs-commits
mailing list