/**
    * 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 consequences 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 relationship 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 inserted 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;

As described in the above javadoc, this method "attaches" the passed object to the cache at the specified location ( id ). The passed in object ( pojo ) must have been instrumented (using the @Replicable annotation) or implement the Serializable interface.

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.

If the object has references to other objects, this call will issue attach() 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.

The return value after the call is the previous object under id , 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.