/*
 * @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;

Calling this Api will put your POJO into the cache management under fqn where fqn is a user-specified fully qualified name (FQN) to store the node in the underlying cache, e.g., "/aop/joe". The pojo is the object instance to be managed by PojoCache.

The requirement for pojo is that it must have been instrumented or implement the Serializable interface. An object is instrumented by JBossAop if declared either from an xml file or from annotation. More details on this will come later.

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 pojo has sub-objects, e.g., it has fields that are non-primitive type, this call will issue putObject recursively until all object tree are traversed (mapping by reachability). In addition, if you put pojo 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.

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, PojoCache will assign an interceptor for the pojo instance and its sub-objects.