<chapter id="api">

   <title>API</title>

      <para>In PojoCache, there are 3 core APIs for

         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.
      </para>

   <sect1>
      <title>Attachment</title>

<programlisting>
/*
 * @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;
</programlisting>
      <para>
               Calling this Api will put your POJO into the cache management under <literal>fqn</literal>
               where <literal>fqn</literal> is a user-specified fully qualified name (<literal>FQN</literal>)
         to store the node in the underlying cache, e.g., "<literal>/aop/joe</literal>". 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.
            </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.
            </para>

            <para>If
               <literal>pojo</literal>
               has sub-objects, e.g., it has fields
               that are non-primitive type, this call will issue
               <literal>putObject</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>

            <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>
</sect1>
         <sect1>
            <title>Detachment</title>

<programlisting>
/**
 * Remove aop-enabled object from the cache. After successful call of this API, the returning
 * POJO is no longer managed by the cache.
 *
 * @param fqn Instance that associates with this node.
 * @return Original POJO stored under this node.
 * @throws CacheException
 */
Object removeObject(Fqn fqn) throws CacheException;
</programlisting>

            <para>
               This call will detach the POJO from the cache management by removing the contents under fqn
               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.
               Note this call will also remove everything stored under <literal>fqn</literal> even if you have put
               other plain cache data there.
            </para>
         </sect1>

   <sect1>
      <title>Query</title>
<programlisting>
/**
  * Retrieve the Pojo from the cache. Return null if object does not exist in the cache.
  *
  * @param fqn Instance that associates with this node.
  * @return Current POJO value. Null if does not exist.
  * @throws CacheException
  */
Object getObject(Fqn fqn) throws CacheException;
</programlisting>
      <para>
This call will
         return the current object content located under
         <literal>fqn</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
         then add the cache interceptor such that every future access will be
         in sync with the underlying cache store.
      </para>

<programlisting>
/**
 * Query all managed pojo objects under the fqn recursively. Note that this will not return the sub-object POJOs,
 * e.g., if Person has a sub-object of Address, it won't return Address pojo. Note also that this operation is
 * not thread-safe now. 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.
 * @param fqn The starting place to find all POJOs.
 * @return Map of all POJOs found with (fqn, pojo) pair. Return size of 0, if not found.
 * @throws CacheException
 */
public Map findObjects(Fqn fqn) throws CacheException;
</programlisting>

      <para>
This call will return all the managed POJOs under cache with a base Fqn name. It is recursive, meaning that
         it will traverse all the sub-trees to find the POJOs under that base. For example, if you specify
         the fqn to be root, e.g.,
         <code>"/"</code>
         , 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>
   </sect1>


</chapter>
