<chapter id="intro">

   <title>Introduction</title>

   <sect1 id="1" revision="1">
      <title id="s1">Overview</title>

      <para>
         The two components in JBossCache, plain cache (implemented as TreeCache) and PojoCache (implemented
         as PojoCache), are both in-memory, transactional,
         replicated, and persistent.
         However, TreeCache is typically used as a plain cache system. That is,
         it directly stores the object references and has a
         <literal>HashMap</literal>-like Api.
         If replication or persistency is turned on, the object will then need to
         implement the
         <literal>Serializable</literal>
         interface. In addition, it has known limitations:
         <itemizedlist>
            <listitem>Users will have to manage the cache specifically;  e.g., when an object is updated, a user will need
               a corresponding
               API call to update the cache content.</listitem>
            <listitem>If the object size is huge, even a single field update would trigger the whole object
               serialization. Thus, it can be
               unnecessarily expensive.</listitem>
            <listitem>The object structure can not have a graph relationship. That is, the object can not have
               sub-objects that are shared (multiple
               referenced) or referenced to itself (cyclic). Otherwise, the relationship will be broken upon
               serialization. For example, Figure 1
               illustrates this problem during replication.
               If we have two
               <literal>Person</literal>
               instances that share the same
               <literal>Address</literal>
               ,
               upon replication, it will be split into two separate
               <literal>Address</literal>
               instances (instead of just one).
            </listitem>
         </itemizedlist>
      </para>

      <figure>
         <title>Illustration of shared objects problem during replication</title>

         <mediaobject>
            <imageobject>
               <imagedata fileref="images/object_split.jpg"/>
            </imageobject>
         </mediaobject>
      </figure>

      <para>PojoCache, on the other hand,
         is a
         fine-grained "object-oriented" cache. By "object-oriented", we mean that
         PojoCache provides tight integration with the object-oriented Java
         language paradigm, specifically,
         <itemizedlist>
            <listitem>no need to implement <literal>Serializable</literal> interface for the POJOs.</listitem>
            <listitem>
            replication (or even persistency)
            is done on a per-field basis (as opposed to the whole object binary level).</listitem>
            <listitem> the object relationship and identity are preserved automatically in a distributed,
            replicated environment. It enables transparent usage behavior and increases software performance.</listitem>
         </itemizedlist>
      </para>

      <para>
         In PojoCache, these are the typical development and programming steps:
         <itemizedlist>
            <listitem>Declare POJO to be "prepared" (in Aop parlance) either through an external xml file (i.e., <literal>jboss-aop.xml</literal>),
            or through annotation inside the POJO. Depending on your preference, you can either pre-instrument your POJO (compile time)
               or have JBossAop do it at load time.</listitem>
            <listitem>Use <literal>putObject</literal> Api to put your POJO under cache management.</listitem>
            <listitem>Operate on POJO directly. Cache will then manage your replication or persistency automatically.</listitem>
         </itemizedlist>
      </para>
      
      <para>
        More details on these steps will be given in later chapters.
      </para>

      <para>
         <literal>PojoCache</literal>
         also extends the functionality of
         TreeCache to object based. That is, the TreeCache features such as
         transaction, replication, eviction policy, and cache loader, has been extended to POJO level. For example, when you
         operate on a POJO (say, <literal>pojo.setName()</literal>) under a transaction context, it will participate in
         that transaction automatically. When the transaction is either committed or rolled back, your POJO operations will act
         accordingly.
      </para>

      <para>
         Finally, <literal>PojoCache</literal>
         can also be used as a plain
         <literal>TreeCache</literal>
         . For example, a user can use the
         <literal>TreeCache</literal>
         API
         [e.g.,
         <literal>get(String fqn)</literal>
         and
         <literal>set(String fqn,
            String key, String value)</literal>
         ] to manage the cache states. Of
         course, users will need to consider the extra cost (albeit slight) in doing this.
      </para>
   </sect1>

   <sect1 id="2" revision="1">
      <title id="s2">Features</title>

      <para>Here are the current features and benefits of PojoCache:</para>

      <itemizedlist>
         <listitem>
            <para>Fine-grained replication. The replication mode supported is the
               same as that of the TreeCache:
               <literal>LOCAL</literal>
               ,
               <literal>REPL_SYNC</literal>
               , and
               <literal>REPL_ASYNC</literal>. The
               replication level is fine-grained and is done automatically once the POJO is mapped into the
               internal cache store. When a POJO field is updated, a replication request
               will be sent out only to the node
               corresponding to that modified attribute (instead of the whole
               object). This can have a potential performance boost during the replication
               process; e.g., updating a single key in a big HashMap will only
               replicate the single field instead of the whole map! Please see the
               documentation of
               <ulink url="TreeCache.html">JBossCache</ulink>
               for
               more details on cache mode.
            </para>
         </listitem>

         <listitem>
            <para>Transaction. The POJO operation can be transacted once a
               TransactionManager is specified properly. Upon user rollback, it will
               rollback all POJO operations as well. Note that the transaction context
               only applies to the node level though. That is, in a complex object
               graph where you have multiple sub-nodes, only the nodes (or fields)
               accessed by a user are under transaction context. To give an example, if I have
            a POJO that has field references to another two POJOs (say, pojo1 and pojo2).
            When pojo1 is modified and under transaction context, pojo2 is not under the same
            transaction context. So you can start another transaction on pojo2 and it will
            succeed.</para>
            <para>In addition, fine-grained operation (replication or persistency) under transaction is batched. That is,
            the update is not performed until the <literal>commit</literal> phase. And if it is rolled back, we will
            simply discard the modifications.</para>
         </listitem>

         <listitem>
            <para>Eviction policy. PojoCache supports eviction policy that can
               evict the whole POJO object (and any field object references,
               recursively). Currently there is an eviction policy class called
               <literal>org.jboss.cache.aop.eviction.AopLRUPolicy</literal>
               (that is
               sub-class of
               <literal>org.jboss.cache.eviction.LRUPolicy</literal>
               ).
               The configuration parameters are the same as those of the TreeCache
               counterpart. Note that the concept of "Region" in eviction needs to
               be carefully defined at the top of the object FQN level. Otherwise,
               eviction policy will not operate correctly. That is, since "Region" is used to
               define the eviction policy, if you define a "Region" inside a POJO sub-tree, it may
               not be desirable.
            </para>
         </listitem>

         <listitem>
            <para>Object cache by reachability, i.e., recursive object mapping
               into the cache store. For example, if a POJO has a reference to
               another advised POJO,
               <literal>PojoCache</literal>
               will
               transparently manage the sub-object states as well. During the initial
               <literal>putObject()</literal>
               call,
               <literal>PojoCache</literal>
               will traverse the object tree and map it accordingly to the internal
               TreeCache nodes. This feature is explained in full details
               later.
            </para>
         </listitem>

         <listitem>
            <para>Object reference handling. In PojoCache, multiple and
               recursive object references are handled automatically. That is, a user
               does not need to declare any object relationship (e.g., one-to-one, or
               one-to-many) to use the cache. Therefore, there is no need to specify
               object relationship via xml file.</para>
         </listitem>

         <listitem>
            <para>Automatic support of object identity. In PojoCache, each
               object is uniquely identified by an internal FQN. Client can determine
               the object equality through the usual
               <literal>equal</literal>
               method.
               For example, an object such as
               <literal>Address</literal>
               may be
               multiple referenced by two
               <literal>Person</literal>s (e.g.,
               <literal>joe</literal>
               and
               <literal>mary</literal>). The objects
               retrieved from
               <literal>joe.getAddress()</literal>
               and
               <literal>mary.getAddress()</literal>
               should be identical.
            </para>

            <para>Finally, a POJO can be stored under multiple
               <code>Fqn</code>s
               in the cache as well, and its identity is still preserved when retrieved from
               both places (after replication).
            </para>
         </listitem>

         <listitem>
            <para>Inheritance relationship. PojoCache preserves the POJO
               inheritance hierarchy after the object item is stored in the cache.
               For example, if a
               <literal>Student</literal>
               class inherits from a
               <keycode>Person</keycode>
               class, once a
               <literal>Student</literal>
               object is mapped to PojoCache (e.g.,
               <literal>putObject</literal>
               call), the attributes in base class
               <literal>Person</literal>
               is
               "aspectized" as well.
            </para>
         </listitem>

         <listitem>
            <para>Support Collection classes (e.g., List, Set, and Map based
               objects) automatically without declaring them as aop-enabled. That is,
               you can use them either as a plain POJO or a sub-object to POJO
               without declaring them as "aspectized". In addition, it supports
               runtime swapping of the proxy reference as well.</para>
         </listitem>

         <listitem>
            <para>Support pre-compiling of POJOs. The latest JBossAop has a
               feature to pre-compile (called
               <literal>aopc</literal>, so-called compile-time mode in JBossAop) and generate
               the byte code necessary for AOP system. By pre-compiling the
               user-specified POJOs, there is no need for additional declaration file
               (e.g.,
               <literal>jboss-aop.xml</literal>
               ) or specifying a JBossAop
               system classloader. A user can treat the pre-generated classes as
               regular ones and use PojoCache in a non-intrusive way.
            </para>

            <para>This provides easy integration to existing Java runtime
               programs, eliminating the need for ad-hoc specification of a system
               class loader, for example. Details will be provided later.
            </para>
         </listitem>

         <listitem>
            <para>POJO needs not implement the
               <code>Serializable</code>
               interface.
            </para>
         </listitem>

         <listitem>
            <para>Support annotation usage. Starting from release 1.2.3,
               PojoCache also supports declaration of POJO through annotation
               under JDK1.4. JBossAop provides an annotation precompiler that a user
               can use to pre-process the annotation. As a result, there will be no
               need for
               <literal>jboss-aop.xml</literal>
               file declaration for POJOs,
               if annotation is preferred. The JDK5.0 annotation will be supported in the next release.
            </para>
         </listitem>

         <listitem>
            <para>Ease of use and transparency. Once a POJO is declared to be
               managed by cache, the POJO object is mapped
               into the cache store behind the scene. Client will have no need to
               manage any object relationship and cache contents
               synchronization.</para>
         </listitem>
      </itemizedlist>
   </sect1>

   <sect1 id="3">
      <title>Usage</title>
      <para>
         To use PojoCache, it is similar to its TreeCache counter part. Basically, you instantiate a PojoCache
         instance first. Then, you can either configure it programmatically or through an external xml file. Finally, you
         call the cache life cycle method to start the cache. Below is a code snippet that creates and starts the cache
         through an external xml file:
<programlisting>
   cache_ = new PojoCache();
   PropertyConfigurator config = new PropertyConfigurator(); // configure tree cache.
   config.configure(cache_, "META-INF/replSync-service.xml"); // Search under the classpath
   cache_.start();
   ...
   cache_.stop();
</programlisting>
      </para>
   </sect1>
   <sect1 id="4">
      <title>Requirement</title>

      <para>
         <literal>PojoCache</literal> is currently supported on both JDK1.4 and JDK50.
         For JDK1.4, it requires the following libraries (in
         addition to jboss-cache.jar and the required libraries for the plain
         TreeCache) to start up:
      </para>

      <itemizedlist>
         <listitem>
            <para>Library:</para>

            <itemizedlist>
               <listitem>
                  jboss-aop.jar. Main JBossAop library.
               </listitem>

               <listitem>
                  javassist.jar. Java byte code manipulation library.
               </listitem>

               <listitem>
                  trove.jar. High performance collections for Java.
               </listitem>

               <listitem>
                  qdox.jar. Javadoc parser for annotation.
               </listitem>
            </itemizedlist>
         </listitem>
      </itemizedlist>
      <para>For JDK5.0, in addition to the above libaries, you will need to replace jboss-cache.jar
      with jboss-cache-jdk50.jar and jboss-aop.jar with jboss-aop-jdk50.jar from lib-50 directory.</para>
   </sect1>

</chapter>
