[jboss-cvs] JBossCache/docs/PojoCache/en/modules ...
Jason Thomas Greene
jgreene at jboss.com
Wed Aug 1 00:51:19 EDT 2007
User: jgreene
Date: 07/08/01 00:51:19
Modified: docs/PojoCache/en/modules api.xml architecture.xml
configuration.xml introduction.xml term.xml
Removed: docs/PojoCache/en/modules jbossaop.xml
Log:
Update docs. Still alot more work to do here, but it's a start
Revision Changes Path
1.5 +32 -58 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.4
retrieving revision 1.5
diff -u -b -r1.4 -r1.5
--- api.xml 26 Oct 2006 09:01:44 -0000 1.4
+++ api.xml 1 Aug 2007 04:51:18 -0000 1.5
@@ -1,12 +1,11 @@
<chapter id="api">
<title>API Overview</title>
- <para>In this section, we will discuss an overview of the PojoCache APIs including the
- PojoCacheFactory class.</para>
+ <para>This section provides a brief overview of the POJO Cache APIs. Please consult the javadoc for the full API.</para>
<sect1>
- <title>PojoCacheFactory API</title>
- <para>PojoCacheFactory provides couple of static methods to instantiate and obtain a PojoCache instance.</para>
+ <title>PojoCacheFactory Class</title>
+ <para>PojoCacheFactory provides a 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.
@@ -44,13 +43,11 @@
<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.
+ <title>PojoCache Interface</title>
+ <para>
+ <literal>PojoCache</literal> is the main interface for POJO Cache operations.
+ Since most of the cache interaction is performed against the application domain model,
+ there are only a few methods on this interface.
</para>
<sect2>
@@ -84,44 +81,29 @@
Object attach(String id, Object pojo) throws PojoCacheException;
</programlisting>
<para>
- 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>
-
- <para>
- The requirement for <literal>pojo</literal> is that it must have been instrumented or implement the
- <literal>Serializable</literal> interface. An object is instrumented by JBossAop if declared either
- from an xml file or from annotation. More details on this will come later.
+ As described in the above javadoc, this method "attaches" the passed object to the cache
+ at the specified location (<literal>id</literal>).
+ The passed in object (<literal>pojo</literal>) must have been instrumented (using the <literal>@Replicable</literal> annotation)
+ or implement the <literal>Serializable</literal> interface.
</para>
<para>
- When the POJO is only serializable, PojoCache will simply treat it as an opaque "primitive" type. That is,
- it will simply store it without mapping the object's field into cache. Replication is done on the object wide
- level and therefore no fine-grained replication can be obtained.
+ If the object is not instrumented, but serializable, POJO Cache will simply treat it as an opaque "primitive" type. That is,
+ it will simply store it without mapping the object's fields into the cache. Replication is done on the object wide
+ level and therefore it will not be fine-grained.
</para>
- <para>If
- <literal>pojo</literal>
- has sub-objects, e.g., it has fields
- that are non-primitive type, this call will issue
- <literal>attach</literal>
- recursively until all object tree are
- traversed (mapping by reachability). In addition, if you put
- <literal>pojo</literal>
- in multiple
- times, it will simply returns the original object reference right
- away. Furthermore, if this POJO has been referenced multiple times, e.g., referenced from other
- POJO or circular reference, this Api will handle the appropriate reference counting.
+ <para>If the object has references to other objects, this call will issue
+ <literal>attach()</literal> calls
+ recursively until the entire object graph is
+ traversed. In addition, object identity and object references are preserved. So both circular and multiply referenced objects
+ are mapped as expected.
</para>
- <para>The return value after the call is the existing object under fqn
- (if any). As a result, a successful call will replace that old value
- with pojo instance, if it exists. Note that a user will only need to
- issue this call once for each POJO (think of it as attaching POJO to cache management). Once it is executed,
- <literal>PojoCache</literal>
- will assign an interceptor for the
- pojo instance and its sub-objects.
+ <para>The return value after the call is the previous object under <literal>id</literal>, if any. As a result, a successful call i
+ will replace that old value with the new instance. Note that a user will only need to
+ issue this call once for each top-level object. Further calls can be made directly on the graph, and they will be mapped as
+ expected.
</para>
</sect2>
<sect2>
@@ -139,12 +121,9 @@
</programlisting>
<para>
- 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.
+ This call will detach the POJO from the cache by removing the contents under <literal>id</literal>
+ and return the POJO instance stored there (null if it doesn't exist). If successful, further operations against
+ this object will not affect the cache.
Note this call will also remove everything stored under <literal>id</literal> even if you have put
other plain cache data there.
</para>
@@ -170,7 +149,7 @@
<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
+ In this case, PojoCache will create a new Java object if it does not exist and
then add the cache interceptor such that every future access will be
in sync with the underlying cache store.
</para>
@@ -198,11 +177,6 @@
, then it will return all the
managed POJOs under the cache.
</para>
- <para>
- Note also that this operation is currently not thread-safe. 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.
- </para>
</sect2>
</sect1>
1.12 +109 -440 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.11
retrieving revision 1.12
diff -u -b -r1.11 -r1.12
--- architecture.xml 18 Jul 2007 17:40:48 -0000 1.11
+++ architecture.xml 1 Aug 2007 04:51:18 -0000 1.12
@@ -2,22 +2,15 @@
<title>Architecture</title>
- <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>POJO Cache internally uses the JBoss Aop framework to both intercept object field access, and
+ to provide an internal interceptor stack for centralizing common behavior (e.g. locking, transactions). </para>
- <para>Following figure is an overview of the PojoCache architecture. From the top, we can see that
+ <para>The following figure is a simple overview of the POJO Cache architecture. From the top, it can be can seen 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 configured 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 or put it in your classpath.</para>
+ the POJO Cache interceptor stack first. After that, it will store the object's fields into the underlying Core Cache,
+ which will be replicated (if enabled) using JGroups.</para>
<figure>
- <title>PojoCache architecture overview</title>
+ <title>POJO Cache architecture overview</title>
<mediaobject>
<imageobject>
@@ -27,22 +20,12 @@
</figure>
<sect1>
- <title>PojoCache interceptor stack</title>
+ <title>POJO Cache 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.
- 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>
+ <para>As mentioned, the JBoss Aop framework is used to provide a configurable interceptor stack.
+ In the current implementation, the main POJO Cache methods have their own independant stack. These are specified in <literal>META-INF/pojocache-aop.xml</literal>
+ In most cases, this file should be left alone, although advanced users may wish to add their own interceptors.
+ The Following is the default configuration:</para>
<programlisting>
<!-- Check id range validity -->
<interceptor name="CheckId" class="org.jboss.cache.pojo.interceptors.CheckIdInterceptor"
@@ -107,77 +90,47 @@
</stack>
</programlisting>
<para>
- The stack should be mostly self-explanatory. For example, for <literal>Attach</literal> stack,
+ The stack should be self-explanatory. For example, for the <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 customized interceptor if needs to.</para>
-
+</para>
</sect1>
<sect1>
- <title>Dynamic AOP interception</title>
+ <title>Field interception</title>
- <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 an
- <literal>attach(String id, Object pojo)</literal>
- operation (API explained below), PojoCache will examine to see if
- there is already an
- <literal>org.jboss.cache.aop.CacheInterceptor</literal>
- attached. (Note
- that a
- <literal>CacheInterceptor</literal>
- is the entrance of
- PojoCache to dynamically manage cache contents.) If it has not, one
- will be added to
- <literal>InstanceAdvisor</literal>
- object. Afterward,
- any POJO field modification will invoke the corresponding
- <literal>CacheInterceptor</literal>
- instance. Below is a schematic
- illustration of this process.
- </para>
-
- <para>JBossAop has the capability to intercept both method level call and field level read write. From the
- perspective of PojoCache, field level interception is the appropriate mechanism to synchronize with
- the back-end cache store. Please note that,
+ <para>POJO Cache currently uses JBoss AOP to intercept field operations. If a class has been properly instrumented (by either
+ using the <literal>@Replicable</literal> annotation, or if the object has already been advised by JBoss AOP), then a cache
+ interceptor is added during an <literal>attach()</literal> call.
+ Afterward, any field modification will invoke the corresponding <literal>CacheFieldInterceptor</literal>
+ instance. Below is a schematic illustration of this process.
+ </para>
+
+ <para>Only fields, and not methods are intercepted, since this is the most efficient and accurate way to gaurantee the same data is visible on all nodes in the cluster. Further, this allows for objects that do not conform to the JavaBean specficiation to be replicable.
+ There are two important aspects of field interception:
<itemizedlist>
<listitem>
- 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>
+ All access qualifiers are intercepted. In other words, all <literal>private</literal>, all <literal>protected</literal>, all default, and all <literal>public</literal> fields will be intercepted.
</listitem>
<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.
+ Any field with <literal>final</literal>, <literal>static</literal>, and/or <literal>transient</literal> qualifiers, <emphasis role="bold">will be skipped</emphasis>. Therefore, they will not be replicated, passivated, or manipulated in any way by POJO Cache.
</listitem>
</itemizedlist>
</para>
-<para>The figures shown below illustrate operations to perform field read and write.
- Once a POJO is managed by PojoCache (i.e., after an
- <literal>attach</literal>
- method has been called), Aop will invoke
- <literal>CacheInterceptor</literal>
- automatically every time there is a
- field read or write. However, you should see the difference between
- these figures. While field write operation will go to cache first and,
- then, invoke the in-memory update, the field read invocation does not
- involve in-memory reference at all. This is because the value in cache
- and memory should have been synchronized during write operation. As a
- result, the field value from the cache is returned.
+<para>The figure below illustrates both field read and write operations.
+ Once an POJO is managed by POJO Cache (i.e., after an
+ <literal>attach()</literal>
+ method has been called), JBoss Aop will invoke the
+ <literal>CacheFieldInterceptor</literal> every time a class operates on a field. The cache is always consulted, since it is in control
+ of the mapped data (i.e. it gaurantess the state changes made by other nodes in the cluster are visible). Afterwords, the in-memmory copy is
+ updated. This is mainly to allow transaction rollbacks to restore the previous state of the object.
</para>
<figure>
- <title>Dynamic AOP interception for field write</title>
+ <title>POJO Cache field interception</title>
<mediaobject>
<imageobject>
@@ -185,255 +138,24 @@
</imageobject>
</mediaobject>
</figure>
-
- <figure>
- <title>Dynamic AOP Interception for field read</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/get.png"/>
- </imageobject>
- </mediaobject>
- </figure>
</sect1>
- <sect1>
- <title>Logical object mapping by reachability</title>
-
- <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>
- object), during the
- <literal>attach(String id, Object pojo)</literal>
- operation,
- PojoCache will add a
- <literal>CacheInterceptor</literal>
- instance to
- the
- <literal>InstanceAdvisor</literal>
- associated with that object, as
- we have discussed above. In addition, the cache will map recursively the
- primitive object fields into the corresponding cache nodes.
- </para>
-
- <para>The mapping rule is as follows:</para>
-
- <itemizedlist>
- <listitem>
- <para>Create a tree node using
- <literal>id</literal> (internally translated into Cache <literal>fqn</literal>, if not yet
- existed).
- </para>
- </listitem>
-
- <listitem>
- <para>Go through all the fields (say, with an association
- <literal>java.lang.reflect.Field</literal>
- type field) in
- POJO,
- </para>
-
- <itemizedlist>
- <listitem>
- <para>If it is a primitive type, the field value will be stored
- under
- <literal>id</literal>
- with
- <literal>(key,
- value)</literal>
- pair of
- <literal>(field.getName(),
- field.getValue()).</literal>
- The following are primitive types
- supported now:
- <literal>String, Boolean, Double, Float, Integer,
- Long, Short, Character.</literal>
-
- </para>
- </listitem>
-
- <listitem>
- <para>If it is a non-primitive type, creates a child
- <literal>id</literal>
- and then recursively executes another
- <literal>pubObject</literal>
- until it reaches all primitive
- types.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </itemizedlist>
-
- <para>Following is a code snippet that illustrates this mapping
- process</para>
-
-<programlisting>
-for (Iterator i = type.getFields().iterator(); i.hasNext();) {
- Field field = (Field) i.next();
- Object value = field.get(obj);
- CachedType fieldType = getCachedType(field.getType());
- if (fieldType.isImmediate()) {
- immediates.put(field.getName(), value);
- } 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).
- </para>
-
-<programlisting>
-Person joe = new Person();
-joe.setAddress(new Address());
-
-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.
- The String Id <literal>pojo/joe</literal> is associated with the POJO
- <literal>joe</literal>.
- Then under that fqn, there are three
- children nodes:
- <literal>addr,</literal>
-
- <literal>skills,</literal>
- and
- <literal>languages.</literal>
- If you look at the
- <literal>Person</literal>
- class declaration, you will find that
- <literal>addr</literal>
- is an
- <literal>Address</literal>
- class,
- <literal>skills</literal>
- is a
- <literal>Set</literal>
- , and
- <literal>languages</literal>
- is a
- <literal>List</literal>
- type. Since
- 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. Also note that all the primitive
- types will be stored
- inside the respective
- node's HashMap (e.g.,
- <literal>addr</literal>
- will have
- <literal>Zip</literal>
- ,
- <literal>Street</literal>
- , etc. stored there).
- </para>
-
- <para>Here is a code snippet to demonstrate the object mapping by
- reachability feature that we just explained. Notice how a
- <literal>Person</literal>
- object
- (e.g., <literal>joe</literal>) that has complex object references will
- be mapped into the underlying cache store as explained above.
- </para>
-
-<programlisting>
-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;
-
-String configFile = "META-INF/replSync-service.xml";
-boolean toStart = false; // Deault is true.
-PojoCache cache = PojoCacheFactory.createCache(configFile, toStart);
-
-Person joe = new Person(); // instantiate a Person object named joe
-joe.setName("Joe Black");
-joe.setAge(41);
-
-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
-
-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>
- 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>
-
- <para>In addition, PojoCache also supports get/set with parameter
- type of some
- <literal>Collection</literal>
- classes (i.e.,
- <literal>List</literal>
- ,
- <literal>Map</literal>
- , and
- <literal>Set</literal>
- ) automatically. For example, the following code snippet in
- addition to the above example will trigger PojoCache to manage the
- states for the
- <literal>Languages</literal>
- list as well. Details of Collection class support will be given later.
- </para>
-
-<programlisting>
-ArrayList lang = new ArrayList();
-lang.add("Ensligh");
-lang.add("Mandarin");
-joe.setLanguages(lang);
-</programlisting>
-</sect1>
<sect1>
<title>Object relationship management</title>
- <para>Like we have mentioned, traditional cache system does not support object relationship
- management during serialization (be it to the persistent data store or
- replicated to the other in-memory nodes.) Examples of object
- relationship are like an address object is shared by members of the
- household, and a child-parent relationship. All these relationship will
- be lost once the objects are replicated or persisted. As a result, explicit mapping
- will be needed outside of the cache system to express the object
- relationship. PojoCache, in contrast, can manage object relationship
- transparently for users.</para>
-
- <para>During the mapping process, we will check whether any of its
- associated object is multiple or circular referenced. A reference
- counting mechanism has been implemented associating with the
- <literal>CacheInterceptor</literal>. If a new object created in the cache referenced to another
- POJO, a referenced <literal>fqn</literal> will be stored there to redirect any query and update
- to the original node.
+ <para>As previously mentioned, unlike a traditional cache system, POJO Cache preserves object identity. This allows
+ for any type of object relationship available in the Java language to be transparently handled. </para>
+
+ <para>During the mapping process, all object references are checked to see if they are already stored in the cache. If already stored, instead of duplicating the data, a reference to the original object is written in the cache. All referenced objects are reference counted, so they will be removed once they are no longer referenced.
</para>
<para>To look at one example, let's say that multiple
<literal>Person</literal>s ("joe" and "mary")
objects can own the same
<literal>Address</literal>
- (e.g., a household). Graphically, here is
- what it will look like in the tree nodes. Like we have covered in the previous section on the mapping by
- reachability, the POJO will map recursively into the cache. However, when we detect a multiple reference
- (in this case, the <literal>Address</literal>), we will keep track of the reference counting for the sub-object
- <literal>addr.</literal>
+ (e.g., a household). The following diagram is a graphical representation of the pysical cache data.
+ As can be seen, the "San Jose" address is only stored once.
</para>
<figure>
@@ -484,9 +206,9 @@
maryAddr = mary.getAddress(); // Should still have the address.
</programlisting>
- <para>Notice that after we remove
+ <para>If
<literal>joe</literal>
- instance from
+ is removed from
the cache,
<literal>mary</literal>
should still have reference the same
@@ -495,11 +217,11 @@
</para>
<para>To further illustrate this relationship management, let's examine the Java code under a replicated
- environment. Imagine that we have two separate cache instances in the cluster now (<literal>cache1</literal>
- and <literal>cache2</literal>). Let's say, on the first cache instance, we put both <literal>joe</literal>
- and <literal>mary</literal> under cache management as above. Then, we failover to <literal>cache2.</literal>
+ environment. Imagine two separate cache instances in the cluster now (<literal>cache1</literal>
+ and <literal>cache2</literal>). On the first cache instance, both <literal>joe</literal>
+ and <literal>mary</literal> are attached as above. Then, the application fails over to <literal>cache2.</literal>
Here is the code
- snippet:
+ snippet for <literal>cache2</literal> (assume the objects were already attached):
</para>
<programlisting>
/**
@@ -511,10 +233,10 @@
import org.jboss.test.cache.test.standAloneAop.Address;
String configFile = "META-INF/replSync-service.xml";
-PojoCache cache = PojoCacheFactory.createCache(configFile); // This will start PojoCache automatically
+PojoCache cache2 = PojoCacheFactory.createCache(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.
+Person joe = cache2.find("pojo/joe"); // retrieve the POJO reference.
+Person mary = cache2.find("pojo/mary"); // retrieve the POJO reference.
Address joeAddr = joe.getAddress();
Address maryAddr = mary.getAddress(); // joeAddr and maryAddr should be the same instance!!!
@@ -522,26 +244,24 @@
maryAddr = mary.getAddress().setZip(95123);
int zip = joeAddr.getAddress().getZip(); // Should be 95123 as well instead of 94086!
</programlisting>
-
-
</sect1>
<sect1>
- <title>Object inheritance hierarchy</title>
+ <title>Object Inheritance</title>
- <para>PojoCache preserves the POJO object inheritance hierarchy
- automatically. For example, if a
+ <para>POJO Cache preserves the inheritance hierarchy of all attached objects.
+ For example, if a
<literal>Student</literal>
extends
<literal>Person</literal>
with an additional field
- <literal>year</literal>
- (see POJO definition in the Appendix section), then once
+ <literal>year</literal>,
+ then once
<literal>Student</literal>
is put into the cache, all the class
attributes of
<literal>Person</literal>
- can be managed as well.
+ are mapped to the cache as well.
</para>
<para>Following is a code snippet that illustrates how the inheritance
@@ -570,30 +290,28 @@
<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 transactional 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.
+ the physical mapping model, that is, how do we map the POJO into Core Cache
+ for transactional state replication. However, it should be noted that the physical structure of the cache
+ is purely an internal implementation detail, it should not be treated as an API as it may change in future
+ releases. This information is provided solely to aid in better understanding the mapping process in POJO Cache.</para>
+
+ <para>When an object is first attached in POJO Cache, the Core Cache node representation is created in a special internal
+ area. The <literal>Id</literal> fqn that is passed to <literal>attach()</literal> is used to create an empty node that
+ references the internal node. Future references to the same object will point to the same internal node location, and that
+ node will remain until all such references have been removed (detached).
</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
+ <para>The example below demonstrates the mapping of the <literal>Person</literal> object under id "pojo/joe" and
+ "pojo/mary" as metioned in previous sections. It 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 highlight 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
+ For clarity, multiple snapshots were taken to highlight the mapping process.</para><para>
+ The first figure illustrates the first step of the mapping approach. From the bottom of the figure,
+ it can be seen 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
+ <literal>/__JBossInternal__/5c4o12-lpaf5g-esl49n5e-1-esl49n5o-2</literal>. That is, under the user-specified
Id string, we store only an indirect reference to the internal 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>
+ <literal>Mary</literal> has a similar reference.</para>
<figure>
<title>Object cache mapping for <literal>Joe</literal></title>
@@ -614,7 +332,7 @@
</mediaobject>
</figure>
- <para>Then by clicking on the referenced internal node (from the following figure), we can see that the
+ <para>Then by clicking on the referenced internal node (from the following figure), it can seen 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
@@ -639,12 +357,12 @@
</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
+ <para>Under the <literal>/__JBossInternal__/5c4o12-lpaf5g-esl49n5e-1-esl49n5o-2</literal>, it can be seen that
+ there is an <literal>Address</literal> node. 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
+ Then by the same token, the <literal>Address</literal> node under
+ <literal>/__JBossInternal__/5c4o12-lpaf5g-esl49n5e-1-esl49na0-4</literal> 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>
@@ -667,8 +385,8 @@
</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>Street</literal>,
+ <para>Finally, the <literal>/__JBossInternal__/5c4o12-lpaf5g-esl49n5e-1-esl49ngs-3</literal> node
+ contains the various various primitive fields of <literal>Address</literal>, e.g., <literal>Street</literal>,
<literal>Zip</literal>, and <literal>City</literal>. This is illustrated in the following figure.</para>
<figure>
<title>Object cache mapping: Address fields</title>
@@ -679,45 +397,34 @@
</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>
+ <title>Collection Mapping</title>
- <para>The POJO classes that inherit from
- <literal>Set</literal>
- ,
- <literal>List</literal>
- , and
- <literal>Map</literal>
- are treated as
- "aspectized" automatically. That is, users need not declare them
- "prepared" in the xml configuration file or via annotation.
- Since we are not allowed to instrument the Java system library, we will use a
- proxy approach instead. That is, when we encounter any Collection instance, we will:
+ <para>Due to current Java limitations, Collection classes that implement
+ <literal>Set</literal>, <literal>List</literal>, and <literal>Map</literal>
+ are substituted with a Java proxy. That is, whenever POJO Cache encounters
+ any Collection instance, it will:
<itemizedlist>
<listitem>
Create a Collection proxy instance and place it in the cache (instead of the original reference).
The mapping of the Collection elements will still be carried out recursively as expected.
</listitem>
<listitem>
- If the Collection instance is a sub-object, e.g., inside another POJO, we will swap out the original reference
- with the new proxy one to promote transparent usage.
+ If the Collection instance is referenced from another object, POJO Cache will swap out the original reference
+ with the new proxy, so that operations performed by the refering object will be picked up by the cache.
</listitem>
</itemizedlist>
- To obtain the proxy reference,
- users can then use another
- <literal>find</literal>
- to retrieve this proxy reference and use
- this reference to perform POJO operations.
+
+ The drawback to this approach is that the calling application must re-get any collection references that were attached. Otherwise,
+ the cache will not be aware of future changes. If the collection is referenced from another object, then the calling app can obtain
+ the proxy by using the publishing mechanism provided by the object (e.g. Person.getHobbies()).
+
+ If, however, the collection is directly attached to the cache, then a subsequent <literal>find()</literal> call will need to be made
+ to retrieve the proxy.
</para>
- <para>Here is a code snippet that illustrates the usage of a Collection proxy reference:
+ <para>The following code snippet illustrates obtaining a direct Collection proxy reference:
</para>
<programlisting>
List list = new ArrayList();
@@ -732,33 +439,24 @@
</programlisting>
<para>
- Here is another snippet to illustrate the dynamic swapping of the Collection reference when it
- is embedded inside another object:
+ This snippet illustrates obtaining the proxy reference from a refering object:
</para>
<programlisting>
Person joe = new Person();
joe.setName("Joe Black"); // This is base class attributes
-ArrayList lang = new ArrayList();
+List lang = new ArrayList();
lang.add("English");
lang.add("Mandarin");
joe.setLanguages(lang);
// This will map the languages List automatically and swap it out with the proxy reference.
cache.attach("pojo/student/joe", joe);
-ArrayList lang = joe.getLanguages(); // Note that lang is a proxy reference
+lang = joe.getLanguages(); // Note that lang is now a proxy reference
lang.add("French"); // This will be intercepted by the cache
</programlisting>
- <para>As you can see,
- <literal>getLanguages</literal>
- simply returns the
- field reference that has been swapped out for the proxy reference
- counterpart.
- </para>
-
<para>
- 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:
+ Finally, when a Collection is removed from the cache (e.g., via <literal>detach</literal>),
+ you still can use the proxy reference. POJO Cache will just redirect the call back to the in-memory copy. See below:
</para>
<programlisting>
List list = new ArrayList();
@@ -773,47 +471,18 @@
proxyList.add("FOUR"); // proxyList has 4 elements still.
</programlisting>
<sect2>
- <title>Limitation</title>
- <para>Use of Collection class in PojoCache helps you to track fine-grained changes
- in your collection fields automatically. However, current implementation has the follow
- limitation that we plan to address soon.</para>
- <para>Currently, we only support a limited implementation of Collection classes. That is,
- we support APIs in List, Set, and Map. However, since the APIs do not stipulate
- of constraints like NULL key or value, it makes mapping of user instance to our proxy tricky.
- For example, ArrayList would allow NULL value and some other implementation would not.
- The Set interface maps to java.util.HashSet implementation. The List interface maps
- to java.util.ArrayList implementation. The Map interface maps to java.util.HashMap
- implementation.
- </para>
- <para>Another related issue is the expected performance. For example, the current implementation is ordered, so
- that makes insert/delete from the Collection slow. Performance between Set, Map and List collections also vary.
- Adding items to a Set is slower than a List or Map, since Set does not allow duplicate entries.</para>
- <para>As of PojoCache 2.0, HashMap keys must be serializable.
- Prior to PojoCache 2.0, HashMap keys were converted to String.
- This was fixed as you couldn't get the key back in its original form. See issue JBCACHE-399 for more details.</para>
- </sect2>
- </sect1>
-
- <sect1>
- <title>POJO requirement</title>
- <para>The POJO requirement for PojoCache are:
+ <title>Limitations</title>
+ <para>The current implementation has the following
+ limitations with collections:</para>
<itemizedlist>
- <listitem>It does not require to implement <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>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.pojo.annotation.Serializable
- </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>Only List, Set and Map are supported. Also it should be noted that the Java Collection API does not
+ fully describe the behavior of implementations, so the cache versions may differ slightly from the common Java implementations (e.g. handling of NULL)
+ </listitem>
+ <listitem>As of PojoCache 2.0, HashMap keys must be serializable.
+ Prior to PojoCache 2.0, HashMap keys were converted to String.
+ This was fixed as you couldn't get the key back in its original form. See issue JBCACHE-399 for more details.
</listitem>
</itemizedlist>
- </para>
+ </sect2>
</sect1>
-
</chapter>
1.8 +31 -34 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.7
retrieving revision 1.8
diff -u -b -r1.7 -r1.8
--- configuration.xml 6 Jun 2007 19:50:07 -0000 1.7
+++ configuration.xml 1 Aug 2007 04:51:18 -0000 1.8
@@ -3,34 +3,33 @@
<title>Configuration and Deployment</title>
- <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>pojocache-aop.xml</literal>
- for some customized behaviors (if needed).</para>
+ <para>Since POJO Cache uses Core Cache for the underlying node replication, transaction,
+ locking, and passivation behavior, the configuration is mostly the same.</para>
<section>
<title>Cache configuration xml file</title>
- <para>When a user obtains a PojoCache instance from the PojoCacheFactory, it is required that the
- user pass in a <literal>org.jboss.cache.config.Configuration</literal> object, or more typically
- a String indicating the location on the classpath or filesystem of an xml configuration file.
- PojoCacheFactory will parse the xml to create a <literal>Configuration</literal>. PojoCache will simply
- pass this <literal>Configuration</literal> to the underlying Cache implementation.
- As a result, any state replication aspects can be configured in this file, along with cache
- passivation. For details on the configuration xml, please see the "Configuration" chapter in the
+ <para>When a PojoCache instance is obtained from a PojoCacheFactory, it is required that the
+ either a <literal>org.jboss.cache.config.Configuration</literal> object is passed, or more typically
+ a String indicating the location on the classpath or filesystem of an xml configuration file is provided.
+ In the latter case, PojoCacheFactory will parse the xml to create a <literal>Configuration</literal>.
+ PojoCache will simply pass the resulting <literal>Configuration</literal> to the underlying Core Cache
+ implementation.
+
+ For details on the configuration please see the "Configuration" chapter in the
the JBoss Cache User Guide.</para>
</section>
<section>
- <title>Passivation configuration</title>
- <para>A user can also configure the underlying Cache to enable passivation. Passivation is a feature
- needed to keep the VM memory compact. In JBoss Cache, it is done via a combination of an eviction
+ <title>Passivation</title>
+ <para>A common use-case is to configure the underlying Core Cache to enable passivation. Passivation is a feature
+ used to reduce cache memory usage by evicting stale data that can later be reloaded.
+ In JBoss Cache, it is done via a combination of an eviction
policy and a cache loader. That is, when a node is evicted from the Cache's in-memory store, it will
be stored in a persistent store by the cache loader. When the node is requested again, it will be loaded
from the persistent store and stored into memory.
</para>
- <para>There is a restriction, however. Since we use the "flat space" physical POJO mapping, there are
- two places that have POJO information. One is under the regular String ID that the user specifies, and
+ <para>There is a restriction, however. Since POJO Cache maps object data into an internal area, there are
+ two places that have object information. One is under the regular String ID that the user specifies, and
the other is located under <code>/__JBossInternal__</code>. Therefore, to maintain consistentency,
when you specify the eviction region, you can only specify one global (i.e., <code>/_default_</code>)
region. This way, when the nodes associated with a POJO are passivated, they will do so across the whole
@@ -77,26 +76,25 @@
</programlisting>
</para>
<para>Another way to support multiple regions in eviction is to use region-based marshalling.
- See the "Architecture" chapter in the JBoss Cache User Guide for more on region-based marshalling.
- When the Cache uses region-based marshalling, it has the side effect of placing all internal data
- under the specific region. As a result, if you configure eviction regions whose root Fqns match
- your marshalling regions, the whole region will be passivated and activated at the same time.</para>
+ See the "Architecture" chapter in the JBoss Cache User Guide for more information on region-based marshalling.
+ When the Cache uses region-based marshalling, POJO Cache will store internal node data on the region that is
+ specified. This allows for a more flexible eviction policy. </para>
</section>
<section>
- <title>PojoCache configuration xml</title>
- <para>PojoCache supplies a <literal>pojocache-aop.xml</literal> that is required to be set via a
+ <title>AOP Configuration</title>
+ <para>POJO Cache supplies a <literal>pojocache-aop.xml</literal> that is required to be set via a
system property: <literal>jboss.aop.path</literal> during compile- or load-time, or placed in
the user's classpath. The file now consists
- of interceptor stack specification and annotations for POJO instrumentation. It is listed fully in the
- Appendix section. Note that the file should be read mostly. So no need to modify it now unless you
- are customizing the interceptor chain, e.g.</para>
+ of the interceptor stack specification, as well as annotations for POJO instrumentation. It is listed fully in the
+ Appendix section. Note that the file should not normally need to be modified. Only an advanced use-case
+ would require changes.</para>
</section>
<section>
<title>Deployment Options</title>
- <para>There are a number of ways to deploy your PojoCache:</para>
+ <para>There are a number of ways to deploy POJO Cache:</para>
<section>
<title>Programatic Deployment</title>
@@ -133,8 +131,7 @@
</para>
<para>
- It is possible to deploy a PojoCache 2.0 instance in JBoss AS 4.x
- (at least in 4.2.0.GA; other AS releases are completely untested).
+ It is possible, to deploy a POJO Cache 2.0 instance in JBoss AS 4.x
However, the significant API changes between the 2.x and 1.x releases
mean none of the standard AS 4.x clustering services (e.g.
http session replication) that rely on the 1.x API will work with
@@ -254,12 +251,12 @@
<para>
An interesting thing to note in the above example is the difference
- between PojoCache and a plain Cache in the use of a factory to
+ between POJO Cache and a plain Cache in the use of a factory to
create the cache. (See the "Deploying JBoss Cache" chapter in the
JBoss Cache User Guide for the comparable plain Cache example.) The
PojoCacheFactory exposes static methods for creating a PojoCache;
as a result there is no need to add a separate <literal>bean</literal>
- element for the factory. Plain Cache's
+ element for the factory. Core Cache's
<literal>DefaultCacheFactory</literal> creates caches from a singleton
instance, requiring a bit more boilerplate in the config file.
</para>
@@ -267,9 +264,9 @@
</section>
<section id="jmx.mbeans">
- <title>PojoCache MBeans</title>
+ <title>POJO Cache MBeans</title>
<para>
- PojoCache provides an MBean that can be registered with your environment's JMX server to allow access
+ POJO Cache provides an MBean that can be registered with your environment's JMX server to allow access
to the cache instance via JMX. This MBean is the <literal>org.jboss.cache.pojo.jmx.PojoCacheJmxWrapper</literal>.
It is a StandardMBean, so it's MBean interface is <literal>org.jboss.cache.pojo.jmx.PojoCacheJmxWrapperMBean</literal>.
This MBean can be used to:
1.7 +71 -181 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.6
retrieving revision 1.7
diff -u -b -r1.6 -r1.7
--- introduction.xml 21 Nov 2006 13:21:42 -0000 1.6
+++ introduction.xml 1 Aug 2007 04:51:18 -0000 1.7
@@ -6,37 +6,35 @@
<title id="s1">Overview</title>
<para>
- The two components in JBossCache, generic cache (Cache implementation) and POJO cache (
- PojoCache implementation), are both in-memory, transactional,
- replicated, and persistent.
- 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. As a result, it is fairly intuitive and easy to use for
- local or distributed caching.
- Nonetheless, it has the following constraints:
+ JBoss Cache consists of two components, Core Cache, and POJO Cache. Core Cache provides efficient
+ memory storage, transactions, replication, eviction, persistent storage, and many other
+ "core" features you would expect from a distributed cache.
+
+ The Core Cache API is tree based. Data is arranged on the tree using nodes that each offer a map
+ of attributes. This map-like API is intuitive and easy to use for caching data, but just like the
+ Java Collection API, it operates only off of simple and serializable types.
+ Therefore, it has the following constraints:
<itemizedlist>
- <listitem>If replication or persistency is needed, the object will then need to
+ <listitem>If replication or persistence is needed, the object will then need to
implement the <literal>Serializable</literal> interface. E.g.,
<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>If the object is mutable, any field change will require a successive put operation on the cache:
<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>Java serialization always writes the entire object, even if only one field was changed. Therefore, large objects
+ can have significant overhead, especially if they are updated frequently:
+<programlisting>thousand = new ThousandFieldObject();
+cache.put(fqn, key, thousand);
+thousand.setField1("blah"); // Only one field was modified
+cache.put(fqn, key, thousand); // Replicates 1000 fields</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
+ references to objects that are shared (multiple
+ referenced) or to itself (cyclic). Otherwise, the relationship will be broken upon
serialization (e.g., when replicate each parent object separately). For example, Figure 1
illustrates this problem during replication.
If we have two
@@ -70,22 +68,17 @@
</mediaobject>
</figure>
- <para>PojoCache, on the other hand,
- is a
- fine-grained "object-oriented" POJO cache. By "object-oriented", we mean that
- PojoCache provides tight integration with the object-oriented Java
- language paradigm, specifically,
+ <para>POJO Cache attempts to address these issues by building a layer on top of Core Cache which transparently maps
+ normal Java object model operations to individual Node operations on the cache.
+
+ This offers the following improvements:
<itemizedlist>
- <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). 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 subsequent POJO operation will trigger
- the replication or persistency automatically.
+ <listitem>Objects do not need to implement <literal>Serializable</literal> interface. Instead they are instrumented,
+ allowing POJO Cache to intercept individual operations.</listitem>
+ <listitem>Replication is fine-grained. Only modified fields are replicated, and they can be optionally batched in a transaction. </listitem>
+ <listitem>Object identity is preserved, so graphs and cyclical references are allowed.</listitem>
+ <listitem>Once attached to the cache, all subsequent object operationis will trigger a cache operation (like replication)
+ automatically:
<programlisting>POJO pojo = new POJO();
pojoCache.attach("id", pojo);
pojo.setName("some pojo"); // This will trigger replication automatically.
@@ -95,18 +88,12 @@
</para>
<para>
- In PojoCache, these are the typical development and programming steps:
+ In POJO Cache, these are the typical development and programming steps:
<itemizedlist>
- <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>
- <listitem>Operate on POJO directly. Cache will then manage your replication or persistency automatically and
+ <listitem>Annotate your object with <literal>@Replicable</literal></listitem>
+ <listitem>Use <literal>attach()</literal> to put your POJO under cache management.</listitem>
+ <listitem>Operate on the object directly. The cache will then manage the replication or persistence 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 the POJO for VM garbage collection.</listitem>
</itemizedlist>
</para>
@@ -115,32 +102,7 @@
</para>
<para>
- <literal>PojoCache</literal>
- 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
- the transaction automatically. When the transaction is either committed or rolled back, your POJO operations will act
- accordingly (either commit or rollback).
- </para>
-
- <para>
- <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
- [e.g.,
- <literal>get(String fqn)</literal>
- and
- <literal>put(String fqn,
- String key, String value)</literal>
- ] to manage the cache states. Keep in mind again that your POJO is managed as a generic cache system in
- this case.
+ Since POJO Cache is a layer on-top of Core Cache, all features available in Core Cache are also available in POJO Cache. Furthermore, you can obtain an instance to the underlying Core Cache by calling <literal>PojoCache.getCache()</literal>. This is useful for resusing the same cache instance to store custom data, along with the POJO model.
</para>
</sect1>
@@ -151,14 +113,14 @@
<itemizedlist>
<listitem>
- <para>Fine-grained replication. The replication mode supported is the
- same as that of the Cache implementation:
+ <para>Fine-grained replication. The replication modes supported are the
+ same as that of Core Cache:
<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
+ main JBoss Cache 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
+ will be sent out only to the key
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
@@ -167,9 +129,8 @@
</listitem>
<listitem>
- <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,
+ <para>Transactions. All attached objects participate in a user transaction context.
+ If a rollback occurs, the previous internal field state of the object will be restored:
<programlisting>POJO p = new POJO();
p.setName("old value");
pojoCache.attach("id", p);
@@ -177,138 +138,67 @@
p.setName("some pojo");
tx.rollback(); // this will cause the rollback
p.getName(); // is "old value"
-</programlisting>
- Note that the transaction context
- only applies to the node level though similar to the Java semantics.
- 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
- a POJO that has field references to another two POJOs (say, pojo1 and pojo2).
- When pojo1 is modified and under transaction context, pojo2 is not under the same
- transaction context. So you can start another transaction on pojo2 and it will
- succeed.</para>
- <para>In addition, fine-grained operation (replication or persistency) under transaction is batched. That is,
- the update is not performed until the <literal>commit</literal> phase. And if it is rolled back, we will
- simply discard the modifications.</para>
+</programlisting></para>
+ <para>In addition, operations under a transaction is batched. That is,
+ the update is not performed until the <literal>commit</literal> phase. Further, if replication is enabled, other nodes will not see the changes until the transaction has completed successfully. </para>
</listitem>
<listitem>
- <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.
+ <para>Passivation. POJO Cache supports the same passivation provided by Core Cache. When a node mapped by POJO Cache has reached a configured threshold, it is evicted from memory and stored using a cache loader. When the node is accessed again, it will be retrieved from the cache loader 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.
+ cache loader.
</para>
</listitem>
<listitem>
<para>Object cache by reachability, i.e., recursive object mapping
- into the cache store. For example, if a POJO has a reference to
- another advised POJO,
- <literal>PojoCache</literal>
- will
- transparently manage the sub-object states as well. During the initial
- <literal>attach()</literal> call, <literal>PojoCache</literal>
- will traverse the object tree and map it accordingly to the internal
- Cache nodes. This feature is explained in full details later.
+ into the cache store. On attach, <literal>POJO Cache</literal>
+ will attach all referenced objects as well. This feature is explained in more detail later.
</para>
</listitem>
<listitem>
- <para>Object reference handling. In PojoCache, multiple and
- recursive object references are handled automatically. That is, a user
+ <para>Natural Object Relationships. Java references are preserved as they were written. That is, a user
does not need to declare any object relationship (e.g., one-to-one, or
- one-to-many) to use the cache. Therefore, there is no need to specify
- object relationship via xml file.</para>
+ one-to-many) to use the cache.</para>
</listitem>
<listitem>
- <para>Automatic support of object identity. In PojoCache, each
- object is uniquely identified by a String id. Client can determine
- the object equality through the usual
- <literal>equal</literal>
- method.
- For example, an object such as
- <literal>Address</literal>
- may be
- multiple referenced by two
- <literal>Person</literal>s (e.g.,
- <literal>joe</literal>
- and
- <literal>mary</literal>). The objects
- retrieved from
- <literal>joe.getAddress()</literal>
- and
- <literal>mary.getAddress()</literal>
- should be identical.
- </para>
-
- <para>Finally, a POJO can be stored under multiple
- ids in the cache as well, and its identity is still preserved when retrieved from
- both places (after replication).
+ <para>Object Identity. Object identity is preserved. Not only can a cached object be compared
+ using <literal>equals()</literal>, but the comparison operator, <literal>==</literal>, can be
+ used as well. For example, an object such as
+ <literal>Address</literal> may be multiple referenced by two
+ <literal>Person</literal>s (e.g., <literal>joe</literal> and <literal>mary</literal>).
+ The objects retrieved from <literal>joe.getAddress()</literal> and <literal>mary.getAddress()</literal>
+ should be identicali, when when retrieved from a different node in the cluster then that which attached them.
</para>
</listitem>
<listitem>
- <para>Inheritance relationship. PojoCache preserves the POJO
- inheritance hierarchy after the object item is stored in the cache.
+ <para>Inheritance. POJO Cache preserves the inheritance hierarchy of any object 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>attach</literal>
- call), the attributes in base class <literal>Person</literal>
- is "aspectized" as well.
+ object is mapped to POJO Cache (e.g., <literal>attach</literal>
+ call), the fields in the base class <literal>Person</literal>
+ are mapped as well.
</para>
</listitem>
<listitem>
- <para>Support Collection classes (e.g., List, Set, and Map based
- 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. Details are described later.</para>
- </listitem>
-
- <listitem>
- <para>Support pre-compiling of POJOs. The latest JBossAop has a
- feature to pre-compile (called
- <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>
- ) 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.
- </para>
-
- <para>This provides easy integration to existing Java runtime
- programs, eliminating the need for ad-hoc specification of a system
- class loader, for example. Details will be provided later.
- </para>
- </listitem>
-
- <listitem>
- <para>POJO needs not implement the <code>Serializable</code> interface.
- </para>
+ <para>Collections. Java Collection types (e.g. List, Set, and Map) are transparently mapped using Java proxies.
+ Details are described later.</para>
</listitem>
<listitem>
- <para>Support annotation usage. Starting from release 2.0,
- PojoCache also supports declaration of POJO through annotation
- 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.
+ <para>Annotation based. Starting from release 2.0, JDK 5 annotations are used to indicate that an object should
+ be instrumented for use under POJO Cache (once attached).
</para>
</listitem>
<listitem>
- <para>Ease of use and transparency. Once a POJO is declared to be
- managed by cache, the POJO object is mapped
- into the cache store behind the scene. Client will have no need to
- manage any object relationship and cache contents
- synchronization.</para>
+ <para>Transparent. Once a POJO is attached to the cache, subsequent object model changes are transparently handled.
+ No further API calls are required.</para>
</listitem>
</itemizedlist>
</sect1>
@@ -316,7 +206,7 @@
<sect1 id="3">
<title>Usage</title>
<para>
- To use PojoCache, you obtain the instance from the PojoCacheFactory by supplying a config file that is used
+ To use POJO Cache, 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";
@@ -330,12 +220,12 @@
</para>
</sect1>
<sect1 id="4">
- <title>Requirement</title>
+ <title>Requirements</title>
<para>
- <literal>PojoCache</literal> is currently supported on JDK50 (since release 2.0).
+ <literal>POJO Cache</literal> is currently supported on JDK 5 (since release 2.0).
It requires the following libraries (in
- addition to jboss-cache.jar and the required libraries for the plain
+ addition to jboss-cache.jar and the required libraries for Core
Cache) to start up:
</para>
@@ -345,11 +235,11 @@
<itemizedlist>
<listitem>
- pojocache.jar. Main PojoCache library.
+ pojocache.jar. Main POJO Cache library.
</listitem>
<listitem>
- jboss-aop-jdk50.jar. Main JBossAop library.
+ jboss-aop-jdk50.jar. Main JBoss Aop library.
</listitem>
<listitem>
1.5 +5 -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.4
retrieving revision 1.5
diff -u -b -r1.4 -r1.5
--- term.xml 26 Sep 2006 16:24:20 -0000 1.4
+++ term.xml 1 Aug 2007 04:51:19 -0000 1.5
@@ -62,14 +62,13 @@
</varlistentry>
<varlistentry>
- <term>Cache</term>
+ <term>Core Cache</term>
<listitem>
<para>
- 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 POJO field level state replication
- and passivation.
+ Core Cache is a tree-structured, clustered, transactional cache. Simple and Serializable java types
+ are stored as key/value pairs on nodes within the tree using a collection-like API. It also provides
+ a number of configurable aspects such as node locking strategies, data isolation, eviction, and so on.
+ POJO Cache leverages Core Cache as the underlying data-store in order to provide the same capabilities.
</para>
</listitem>
</varlistentry>
More information about the jboss-cvs-commits
mailing list