PojoCache (currently implemented PojoCache as a sub-class of TreeCache) is a fine-grained field-level replicated and transactional POJO (plain old Java object) cache. By POJO, we mean that the cache: 1) automatically manages object mapping and relationship for a client under both local and replicated cache mode, 2) provides support for inheritance relationship between "aspectized" POJOs. By leveraging the dynamic AOP in JBossAop, it is able to map a complex object into the cache store, preserve and manage the object relationship behind the scene. During replication mode, it performs fine-granularity (i.e., on a per-field basis) update, and thus has the potential to boost cache performance and minimize network traffic.

From a user perspective, once your POJO is managed by the cache, all cache operations are transparent. Therefore, all the usual in-VM POJO method semantics are still preserved, providing ease of use. For example, if a POJO has been put in PojoCache (by calling putObject, for example), then any get/set method will be intercepted by PojoCache to provide the data from the cache.

Since release 1.4, we have created a new class called PojoCache (to better reflect the cache nature). The old implementation TreeCacheAop has been deprecated.

Yes. PojoCache extends TreeCache so it has all the same features TreeCache such as cache mode, transaction isolation level, and eviction policy.

Think of PojoCache as a TreeCache on steroids. :-) Seriously, both are cache stores-- one is a generic cache and the other other one POJO Cache. However, while TreeCache only provides pure object reference storage (e.g., put(FQN fqn, Object key, Object value) ), PojoCache goes beyond that and performs fine-grained field level replication object mapping and relationship management for a user behind the scenes. As a result, if you have complex object systems that you would like to cache, you can have PojoCache manage it for you. You simply treat your object systems as they are residing in-memory, e.g., use your regular POJO methods without worrying about cache management. Furthermore, this is true in replication mode as well.

Starting from release 1.3, depends on the JDK you use, it has slightly different steps. But in general, in order to use PojoCache, you will need to:

So if you use JDK50, for example, with annotation and load-time instrumentation, then you won't need any pre-processing step to use PojoCache. For a full example, please refer to the distro examples directory. There are numerous PojoCache examples that uses different options.

Yes and no. Yes, since JBossAop can also be back-ported to 3.2.x (see JBossAop wiki for details). However, it will take some effort. Therefore, the recommended JBoss version is 4.x to run PojoCache.

Yes. It is almost the same as TreeCache MBean. The only difference is the object name and the class name. E.g., instead of

<mbean code="org.jboss.cache.TreeCache"
                     name="jboss.cache:service=TreeCache">

you will have:

<mbean code="org.jboss.cache.aop.PojoCache"
                     name="jboss.cache:service=PojoCache">

in the xml configuration file.

Yes. The latest versions of JBossCache have a pre-compiler option called aopc . You can use this option to pre-compile your "aspectized" POJO. Once the classes have been byte code generated, they can be treated as regular class files, i.e., you will not need to include any jboss-aop.xml that specifies the advisable POJO and to specify the JBossAop system class loader.

For an example of how to use aopc , please see 1) tools directory for PojoCacheTasks14.xml and PojoCacheTasks50.xml. Both contain Ant tasks that you can import to your regular project for annoc and aopc . In addition, please also check out the examples directory for concrete examples.

In aopc, you specify the src path for a specific directory. To pre-compile multiple ones, you will need to invoke aopc multiple times.

jboss-aop.xml is needed for POJO instrumentation. In jboss-aop.xml , you can declare your POJO (e.g., Person ) to be "prepared", a JBossAop term to denote that the object will be "aspectized" by the system. After this declaration, JBossAop will invoke any interceptor that associates with this POJO. PojoCache will dynamically add an org.jboss.cache.aop.CacheInterceptor to this POJO to perform object mapping and relationship management.

Note that to add your POJO, you should declare all the fields to be "prepared" as in the example.

Yes, starting with JBossCache 1.3, you can use annotation to instrument your POJO for both JDK1.4 and 1.5. Check the documentation for details.

It really depends on your organization environment, I'd say, since this can be turned into a hot debate. Having said that, I feel strongly that POJO annotation is well suited for PojoCache. This is because once you specify the annotation, you'd probably change it rarely since there is no parameters to tune, for example.

Starting in 1.4, we also offer two additional field-level annotations. The first one, @Transient , when applied has the same effect as declaring a field transient . PojoCache won't put this field under management.

The second one, @Serializable when applied, will cause PojoCache to treat the field as a Serializable object even when it is @PojoCacheable .

Again it depends. But my preference is to do compile-time instrumentation via aopc. I prefer this approach because it is easier to debug (at least at the development stage). In addition, once I generate the new class, there is no more steps needed.

Yes, you can use PojoCache to do that. It supports the notion of object reference. PojoCache manages the unique object through association of the dynamic cache interceptor.

Not necessarily. If there is an object that you don't need the cache to manage for you, you can leave it out of the declaration. The cache will treat this object as a "primitive" type. However, the object will need to implement Serializable interface for replication.

No. The update via reflection will not be intercepted in JBossAop and therefore PojoCache will not be able to perform the necessary synchronization.

PojoCache currently will ignore the fields with these modifiers. That is, it won't put these fields into the cache (and thus no replication either).

They are for internal use only. Users should ignore these keys and values in the node hashmap.

No. Since the Collection classes such as ArrayList are java util classes, aop by default won't instrument these classes. Instead, PojoCache will generate a dynamic class proxy for the Collection classes (upon the putObject call is invoked). The proxy will delegate the operations to a cache interceptor that implements the actual Collection classes APIs. That is, the system classes won't be invoked when used in PojoCache.

Internally, the cache interceptor implements the APIs by direct interaction with respect to the underlying cache store. Note that this can have implications in performance for certain APIs. For example, both ArrayList and LinkedList will have the same implementation. Plan is currently underway to optimize these APIs.

PojoCache supports classes extending from List , Set , and Map without users to declare them "aspectized". It is done via a dynamic proxy. Here is a code snippet to use an ArrayList proxy class.

ArrayList list = new ArrayList();
                  list.add("first");

                  cache.putObject("/list/test", list); // Put the list under the aop cache
                  list.add("second"); // Won't work since AOP intercepts the dynamic proxy not the original POJO.

                  ArrayList myList = (List)cache.getObject("/list/test"); // we are getting a dynamic proxy instead
                  myList.add("second"); // it works now
                  myList.add("third");
                  myList.remove("third");
               

Let's say you want to assign a List object under two different names, you will need to use the class proxy to insert the second time to ensure both are managed by the cache. Here is the code snippet.

ArrayList list = new ArrayList();
                  list.add("first");

                  cache.putObject("/list", list); // Put the list under the aop cache

                  ArrayList myList = (List)cache.getObject("/list"); // we are getting a dynamic proxy instead
                  myList.add("second"); // it works now

                  cache.putObject("/list_alias", myList); // Note you will need to use the proxy here!!
                  myList.remove("second");
               

Pojos that share Collection instance references will be handled by the cache automatically. That is, when you ask the Cache to manage it, the Cache will dynamically swap out the regular Collection references with the dynamic proxy ones. As a result, it is transparent to the users.

When a user puts a POJO into the cache through the call putObject , it will recursively map the field members into the cache store as well. When the field member is of a Collection class (e.g., List, Set, or Map), PojoCache will first map the collection into cache. Then, it will swap out dynamically the field reference with an corresponding proxy reference.

This is necessary so that an internal update on the field member will be intercepted by the cache.

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.

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.

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.

As mentioned in the reference doc, PojoCache has the following advantages:

And here are some cases that you may not want to use PojoCache: