
$Id: TreeCacheAopObjectGraph.txt 384 2005-08-09 00:24:41Z bwang $


Use cases:

1. Circular reference

a) POJO Link has the following code snippets:
   Class Link {
      String name_;
      Link link_;

      public Link(String name) { name_ = name;}
   }

   Link parent = new Link("parent");
   Link child = new Link("child");
   parent.setLink(child);
   child.setLink(parent);

   cacheAop.putObject("/test", parent);

b) same as (a) except we put both parent and child into the cacheAop first, e.g.,
   cacheAop.putObject("/test/parent", parent);
   cacheAop.putObject("/test/child", child);
   parent.setLink(child);   --> Step a
   child.setLink(parent);   --> Step b

   In this case, step a is treated as a multiple reference (see below) and step b is
   the real circular reference problem.

2. Multiple refernce
   We will use the exisitng classes of Person and Address as an example. Joe and Mary
   is sharing the same address, e.g.

   Person joe = new Person();
   Address addr = new Address();
   joe.setAddress(addr);

   Person mary = new Person();
   mary.setAddress(addr);

   cacheAop.putObject("/person/joe", joe);
   cacheAop.putObject("/person/mary", mary);

Design:

The main issue with TreeCacheAop to handle object graph is that it current doesn't have the
notion of reference. Currently, everything is broken down to "primitive" type and then
put under the children nodes. So they are of copy-by-value semantics. Therefore to
handle the object graph, we will need to introduce the notion of a reference.

The notion of reference can be established by the following.

Every "adviseable" object in TreeCacheAop already has a hidden node called "AOPInstance" 
that stores the transient in-memory object reference.  During replication, the
instance field is not replicated, so when a user does a getObject, it will try to
re-construct the obejct based on the children nodes (of primitive types). Then
the new object reference will be stored under AOPInstance.
 
Therefore, during putObject, if the current object to be store has multiple
references, it will do
   a) re-locate the current object to an JBoss internal tree (called /JBossInternal
      for now.
   b) store the /JBossInternal fqn under the current AOPInsatnce indicating that
      this is a reference and is actually aliasing to the /JBossInternal fqn.

Next is the question of how do I know this object is multiple referenced?

For each "advised" object (i.e., declared under jboss-service.xml), we will implicitly
add a CacheInterceptor. This interceptor can be queried from the Advisor class that
comes with the object.

Therefore, during the pubObject operation, we will query the CacheInterceptor. If it
exists, then we know that this object has been put into the cache and we also determine
that it is multiple referecend. During that stage, we proceed with the case of
multiple referece.

For the case of circular reference, the principle is the same. I.e., we also check
the existence of a CacheIntercptor. Furthermore, the sub-object that we are put under
(e.g., parent.setLink(child)) is a parent fqn, then we determine that it is a circular
reference, indeed. In this case, we simply mark the parent fqn in our AOPInstance.


See NewAopObjectGraph.txt for update.
