Author: jason.greene(a)jboss.com Date: 2008-08-21 15:21:04 -0400 (Thu, 21 Aug 2008) New Revision: 6595 Modified: pojo/branches/2.2/src/main/docbook/tutorial/en/master.xml pojo/branches/2.2/src/main/docbook/userguide/en/master.xml pojo/branches/2.2/src/main/docbook/userguide/en/modules/api.xml pojo/branches/2.2/src/main/docbook/userguide/en/modules/instrumentation.xml Log: Sync 2.2 docs with 2.1 changes Modified: pojo/branches/2.2/src/main/docbook/tutorial/en/master.xml =================================================================== --- pojo/branches/2.2/src/main/docbook/tutorial/en/master.xml 2008-08-21 17:33:17 UTC (rev 6594) +++ pojo/branches/2.2/src/main/docbook/tutorial/en/master.xml 2008-08-21 19:21:04 UTC (rev 6595) @@ -1,9 +1,9 @@ <?xml version="1.0" encoding="UTF-8"?> <article lang="en"> <articleinfo> - <title>PojoCache Tutorial</title> - <releaseinfo>Release 2.0.0</releaseinfo> - <pubdate>June 2007</pubdate> + <title>POJO Cache Tutorial</title> + <releaseinfo>Release 2.1.0</releaseinfo> + <pubdate>March 2008</pubdate> <author> <firstname>Ben</firstname> <surname>Wang</surname> @@ -19,9 +19,9 @@ <section> <title>Introduction</title> - <para>PojoCache is an in-memory, transactional, and replicated POJO (plain old Java object) cache system that + <para>POJO Cache is an in-memory, transactional, and replicated POJO (plain old Java object) cache system that allows users to operate on a POJO transparently without active user management of either replication or - persistency aspects. This tutorial focuses on the usage of the PojoCache API. + persistency aspects. This tutorial focuses on the usage of the POJO Cache API. </para> <para>For details of configuration, usage and APIs, please refer to the <ulink url="http://labs.jboss.org/portal/jbosscache/docs/index.html"&g... manual</ulink>. @@ -33,7 +33,7 @@ <itemizedlist> <listitem> - <para>PojoCache creation and modification</para> + <para>POJO Cache creation and modification</para> </listitem> <listitem> @@ -41,7 +41,7 @@ </listitem> <listitem> - <para>Using Collections in PojoCache</para> + <para>Using Collections in POJO Cache</para> </listitem> <listitem> @@ -57,17 +57,17 @@ <para>First download the JBoss Cache 2.x distribution from <ulink url="http://labs.jboss.org/portal/jbosscache/download/index.html&quo... download page</ulink> . You probably want the - <literal>JBossCache-pojo-2.X.Y.zip</literal> + <literal>jbosscache-pojo-2.X.Y.zip</literal> distribution. Unzip it, and you will get a directory containing the distribution, such as - <literal>JBossCache-pojo-2.X.Y</literal> + <literal>jbosscache-pojo-2.X.Y</literal> . For the sake of this tutorial, I will refer to this as - <literal>PojoCache</literal> + <literal>POJO Cache</literal> . </para> <para>The configuration files are located under the - <literal>PojoCache/etc</literal> + <literal>jbosscache-pojo/etc</literal> directory. You can modify the behavior of the underlying cache through editing the various configuration files. </para> @@ -89,8 +89,8 @@ <listitem> <para> <literal>pojocache-aop.xml</literal> - . PojoCache configuration file that contains, amongst other things, the annotation to use on POJOs so - that they're aspectised. For more information, please the PojoCache + . POJO Cache configuration file that contains, amongst other things, the annotation to use on POJOs so + that they're aspectised. For more information, please the POJO Cache <ulink url="http://labs.jboss.org/portal/jbosscache/docs/index.html"&g... manual</ulink> . </para> @@ -102,7 +102,7 @@ <title>Script</title> <para>The only script needed for this tutorial is the - <literal>PojoCache/build.xml</literal> + <literal>jbosscache-pojo/build.xml</literal> ant script. </para> </section> @@ -110,7 +110,7 @@ <section> <title>Example POJOs</title> - <para>The example POJO classes used for PojoCache demo are: + <para>The example POJO classes used for POJO Cache demo are: <literal>org.jboss.cache.pojo.test.Person</literal> and <literal>org.jboss.cache.pojo.test.Address</literal> @@ -212,7 +212,7 @@ <itemizedlist> <listitem> <literal>cache</literal> - - a reference to the PojoCache interface, used by the GUI instance. + - a reference to the POJO Cache interface, used by the GUI instance. </listitem> <listitem> <literal>transactionManager</literal> @@ -234,14 +234,14 @@ <section> <title>Tutorials</title> It is recommended that you shut down and restart the demo GUI for each of the following tutorials, to ensure - clean caches every time. To inspect POJO attribute changes via GUI, please refer to the PojoCache + clean caches every time. To inspect POJO attribute changes via GUI, please refer to the POJO Cache <ulink url="http://labs.jboss.org/portal/jbosscache/docs/index.html"&g... manual </ulink> to understand how the POJOs are mapped internally in the cache. <section> - <title>PojoCache API, POJO manipulation, and Replication</title> + <title>POJO Cache API, POJO manipulation, and Replication</title> <para> For this tutorial, start two instance of the demo GUI. In this tutorial, we will: Modified: pojo/branches/2.2/src/main/docbook/userguide/en/master.xml =================================================================== --- pojo/branches/2.2/src/main/docbook/userguide/en/master.xml 2008-08-21 17:33:17 UTC (rev 6594) +++ pojo/branches/2.2/src/main/docbook/userguide/en/master.xml 2008-08-21 19:21:04 UTC (rev 6595) @@ -18,8 +18,8 @@ <bookinfo> <title>POJO Cache</title> <subtitle>User Documentation</subtitle> - <releaseinfo>Release 2.0.0</releaseinfo> - <pubdate>July 2007</pubdate> + <releaseinfo>Release 2.1.0.GA</releaseinfo> + <pubdate>March 2008</pubdate> <author> <firstname>Ben</firstname> Modified: pojo/branches/2.2/src/main/docbook/userguide/en/modules/api.xml =================================================================== --- pojo/branches/2.2/src/main/docbook/userguide/en/modules/api.xml 2008-08-21 17:33:17 UTC (rev 6594) +++ pojo/branches/2.2/src/main/docbook/userguide/en/modules/api.xml 2008-08-21 19:21:04 UTC (rev 6595) @@ -1,13 +1,21 @@ +<?xml version="1.0" encoding="UTF-8"?> <chapter id="api"> - <title>API Overview</title> - <para>This section provides a brief overview of the POJO Cache APIs. Please consult the javadoc for the full API.</para> + <para> + This section provides a brief overview of the POJO Cache APIs. + Please consult the javadoc for the full API. + </para> + <sect1> <title>PojoCacheFactory Class</title> - <para>PojoCacheFactory provides a couple of static methods to instantiate and obtain a PojoCache instance.</para> -<programlisting role="JAVA"><![CDATA[ -/** + + <para> + PojoCacheFactory provides a couple of static methods to + instantiate and obtain a PojoCache instance. + </para> + + <programlisting role="JAVA"><![CDATA[/** * Create a PojoCache instance. Note that this will start the cache life cycle automatically. * @param config A configuration string that represents the file name that is used to * configure the underlying Cache instance. @@ -30,30 +38,31 @@ * @param start If true, it will start the cache life cycle. * @return PojoCache */ -public static PojoCache createInstance(Configuration config, boolean start); -]]></programlisting> - <para>For example, to obtain a PojoCache instance and start the cache lifestyle automatically, - we can do:</para> -<programlisting role="JAVA"><![CDATA[ - String configFile = "META-INF/replSync-service.xml"; - PojoCache cache = PojoCacheFactory.createInstance(configFile); -]]></programlisting> - </sect1> +public static PojoCache createInstance(Configuration config, boolean start);]]></programlisting> + <para> + For example, to obtain a PojoCache instance and start the cache + lifestyle automatically, we can do: + </para> + <programlisting role="JAVA"><![CDATA[String configFile = "META-INF/replSync-service.xml"; +PojoCache cache = PojoCacheFactory.createInstance(configFile);]]> + </programlisting> + </sect1> <sect1> <title>PojoCache Interface</title> + <para> - <literal>PojoCache</literal> is the main interface for POJO Cache operations. - Since most of the cache interaction is performed against the application domain model, - there are only a few methods on this interface. + <literal>PojoCache</literal> + is the main interface for POJO Cache operations. Since most of the + cache interaction is performed against the application domain + model, there are only a few methods on this interface. </para> <sect2> <title>Attachment</title> -<programlisting role="JAVA"><![CDATA[ - /** + <programlisting role="JAVA"><![CDATA[/** * 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: * @@ -72,66 +81,84 @@ * @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. + * 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; -]]></programlisting> + Object attach(String id, Object pojo) throws PojoCacheException;]]></programlisting> + <para> - As described in the above javadoc, this method "attaches" the passed object to the cache - at the specified location (<literal>id</literal>). - The passed in object (<literal>pojo</literal>) must have been instrumented (using the <literal>@Replicable</literal> annotation) - or implement the <literal>Serializable</literal> interface. + As described in the above javadoc, this method "attaches" the + passed object to the cache at the specified location ( + <literal>id</literal> + ). The passed in object ( + <literal>pojo</literal> + ) must have been instrumented (using the + <literal>@Replicable</literal> + annotation) or implement the + <literal>Serializable</literal> + interface. </para> <para> - 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 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. </para> - <para>If the object has references to other objects, this call will issue - <literal>attach()</literal> 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. + <para> + If the object has references to other objects, this call will + issue + <literal>attach()</literal> + 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. </para> - <para>The return value after the call is the previous object under <literal>id</literal>, 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 + <para> + The return value after the call is the previous object under + <literal>id</literal> + , 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. </para> </sect2> + <sect2> <title>Detachment</title> -<programlisting role="JAVA"><![CDATA[ - /** + <programlisting role="JAVA"><![CDATA[/** * Remove POJO object from the cache. * * @param id Is string that associates with this node. * @return Original value object from this node. * @throws PojoCacheException Throws if there is an error related to the cache operation. */ - Object detach(String id) throws PojoCacheException; -]]></programlisting> + Object detach(String id) throws PojoCacheException;]]></programlisting> <para> - This call will detach the POJO from the cache by removing the contents under <literal>id</literal> - and return the POJO instance stored there (null if it doesn't exist). If successful, further operations against - this object will not affect the cache. - Note this call will also remove everything stored under <literal>id</literal> even if you have put - other plain cache data there. + This call will detach the POJO from the cache by removing the + contents under + <literal>id</literal> + and return the POJO instance stored there (null if it doesn't + exist). If successful, further operations against this object + will not affect the cache. Note this call will also remove + everything stored under + <literal>id</literal> + even if you have put other plain cache data there. </para> </sect2> <sect2> <title>Query</title> -<programlisting role="JAVA"><![CDATA[ - /** + + <programlisting role="JAVA"><![CDATA[/** * Retrieve POJO from the cache system. Return null if object does not exist in the cache. * Note that this operation is fast if there is already a POJO instance attached to the cache. * @@ -139,21 +166,21 @@ * @return Current content value. Null if does not exist. * @throws PojoCacheException Throws if there is an error related to the cache operation. */ - Object find(String id) throws PojoCacheException; -]]></programlisting> + Object find(String id) throws PojoCacheException;]]></programlisting> + <para> -This call will - return the current object content located under - <literal>id</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 this 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. + This call will return the current object content located under + <literal>id</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 this 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 role="JAVA"><![CDATA[ - /** + <programlisting role="JAVA"><![CDATA[/** * Query all managed POJO objects under the id 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. Also note also that this operation is not thread-safe @@ -164,19 +191,110 @@ * @return Map of all POJOs found with (id, POJO) pair. Return size of 0, if not found. * @throws PojoCacheException Throws if there is an error related to the cache operation. */ - Map findAll(String id) throws PojoCacheException; -]]></programlisting> + Map findAll(String id) throws PojoCacheException;]]></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., + 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. + , then it will return all the managed POJOs under the cache. </para> </sect2> - </sect1> + <sect1> + <title>POJO Annotations</title> + + <para> + There are currently three annotations that can be used on attached + objects in POJO Cache: + <literal>@Replicable</literal> + , + <literal>@Transient</literal> + , and + <literal>@Serializable</literal> + . All of which affect how the annotated object is replicated. + </para> + + <sect2> + <title>@Replicable annotation</title> + + <para> + The + <literal&gt;(a)org.jboss.cache.annotation.Replicable&lt;/literal&gt; + annotation is used to mark classes for instrumentation. Once + instrumented, individual field changes can be replicated + separately. See the instrumentation chapter for more information + on this process. + </para> + + <para> + The following example will replicate changes to resource and + name separately: + </para> + + <programlisting role="JAVA"><![CDATA[@Replicable +public class Gadget +{ + private Resource resource; + private String name; +}]]> </programlisting> + </sect2> + + <sect2> + <title>@Transient annotation</title> + + <para> + The <literal&gt;(a)org.jboss.cache.annotation.Transient&lt;/literal&gt; annotation is used to + indicate that a field should not be replicable. This allows + non-transient fields to be included in normal Java serialization + output, but not when replicated by POJO Cache. + </para> + + <para> + The following object will not replicate changes to resource. + </para> + + <programlisting role="JAVA"><![CDATA[@Replicable +public class Gadget +{ + // resource won't be replicated + @Transient + private Resource resource; +} ]]></programlisting> + + </sect2> + + <sect2> + <title>@Serializable annotation</title> + + <para> + The + <literal&gt;(a)org.jboss.cache.annotation.Serializable&lt;/literal&gt; + annotation indicates a field should be treated as a serialized + attribute. This, of course, requires that the type of the field + implement + <literal>Serializable</literal> + . If the marked field type has an @Replicable annotation, it + will be ignored. + <literal></literal> + </para> + + <programlisting role="JAVA"><![CDATA[@Replicable +public class Gadget +{ + // resource won't be replicated + @Transient + private Resource resource; + + // serialized even if SpecialAddress is @Replicable + @Serializable + private SpecialAddress specialAddress; + + // other state variables +}]]> </programlisting> + </sect2> + </sect1> </chapter> Modified: pojo/branches/2.2/src/main/docbook/userguide/en/modules/instrumentation.xml =================================================================== --- pojo/branches/2.2/src/main/docbook/userguide/en/modules/instrumentation.xml 2008-08-21 17:33:17 UTC (rev 6594) +++ pojo/branches/2.2/src/main/docbook/userguide/en/modules/instrumentation.xml 2008-08-21 19:21:04 UTC (rev 6595) @@ -2,94 +2,136 @@ <chapter id="instrumentation"> <title>Instrumentation</title> - <para>In order to store an object in POJO Cache, it must be either - instrumented or made serializable. Instrumentation is the most optimal - approach since it preserves object identity and provides field granular - replication. POJO Cache currently uses the JBoss AOP project to provide - instrumentation, so the same processes described in the AOP documentation - are used with POJO Cache.</para> + <para> + In order to store an object in POJO Cache, it must be either + instrumented or made serializable. Instrumentation is the most + optimal approach since it preserves object identity and provides + field granular replication. POJO Cache currently uses the JBoss AOP + project to provide instrumentation, so the same processes described + in the AOP documentation are used with POJO Cache. + </para> - <para>The primary input to JBoss AOP is the AOP binding file, which is - responsible for specifying which classes should be instrumented. POJO Cache - provides a binding file, <literal>pojocache-aop.xml</literal> , which - matches all classes that have been annotated with the - <literal>@Replicable</literal> annotation. Advanced users may choose to - alter this definition to instrument classes in other various interesting - ways. However, it is recommended to just stick with the default annotation - binding.</para> + <para> + The primary input to JBoss AOP is the AOP binding file, which is + responsible for specifying which classes should be instrumented. + POJO Cache provides a binding file, + <literal>pojocache-aop.xml</literal> + , which matches all classes that have been annotated with the + <literal>@Replicable</literal> + annotation. Advanced users may choose to alter this definition to + instrument classes in other various interesting ways. However, it is + recommended to just stick with the default annotation binding. + </para> - <para>The instrumentation process can be executed at either load-time, or - compile-time. Load-time instrumentation uses a Java agent to intercept and - modify classes as they are loaded; whereas compile-time instrumentation - requires running <literal>aopc</literal> as part of the compilation - process.</para> + <para> + The instrumentation process can be executed at either load-time, or + compile-time. Load-time instrumentation uses a Java agent to + intercept and modify classes as they are loaded; whereas + compile-time instrumentation requires running + <literal>aopc</literal> + as part of the compilation process. + </para> <note> - <para>Load-time is the recommended approach, since compile-time - instrumentation adds hard dependencies to the weaved bytecode which ties - the output to a particular version of JBoss AOP.</para> + <para> + Load-time is the recommended approach, since compile-time + instrumentation adds hard dependencies to the weaved bytecode + which ties the output to a particular version of JBoss AOP. + </para> </note> <sect1> <title>Load-time instrumentation</title> - <para>Load-time instrumentation uses a Java agent to intercept all classes - loaded by the JVM. As they are loaded JBoss AOP instruments them, allowing - POJO Cache to monitor field changes. To enable load time instrumentation - the JVM must be started with the following specified:</para> + <para> + Load-time instrumentation uses a Java agent to intercept all + classes loaded by the JVM. As they are loaded JBoss AOP + instruments them, allowing POJO Cache to monitor field changes. To + enable load time instrumentation the JVM must be started with the + following specified: + </para> <orderedlist> <listitem> - <para>The <literal>jboss.aop.path</literal> system property set to the - location of <literal>pojocache-aop.xml</literal></para> + <para> + The + <literal>jboss.aop.path</literal> + system property set to the location of + <literal>pojocache-aop.xml</literal> + </para> </listitem> <listitem> - <para>A javaagent argument which includes - <emphasis>jboss-aop-jdk50.jar</emphasis></para> + <para> + A javaagent argument which includes + <emphasis>jboss-aop-jdk50.jar</emphasis> + </para> </listitem> </orderedlist> - <para>These requirements lead to the following example ant task:</para> + <para> + These requirements lead to the following example ant task: + </para> - <programlisting role="XML"><![CDATA[ -<java classname="Foo" fork="yes"> + <programlisting role="XML"><![CDATA[<java classname="Foo" fork="yes"> <jvmarg value="-javaagent:lib/jboss-aop.jar"/> <jvmarg value="-Djboss.aop.path=etc/META-INF/pojocache-aop.xml"/> <classpath refid="test.classpath"/> -</java> +</java>]]></programlisting> + + <para> + There is also a + <emphasis>pojo-run</emphasis> + command line script in the POJO Cache distribution that passes the + proper arguments to the JVM for you. + </para> + + <programlisting role="XML"><![CDATA[$ pojo-run -classpath myclasses org.foo.Bar ]]></programlisting> - <para>Once the JVM is executed in this manner, any class with the - <literal>@Replicable</literal> annotation will be instrumented when it is - loaded.</para> + <para> + Once the JVM is executed in this manner, any class with the + <literal>@Replicable</literal> + annotation will be instrumented when it is loaded. + </para> </sect1> <sect1> <title>Compile-time instrumentation</title> - <para>While load-time is the preffered approach, it is also possible to - instrument classes at compile-time. To do this, the aopc tool is used, - with the following requirements:</para> + <para> + While load-time is the preferred approach, it is also possible to + instrument classes at compile-time. To do this, the aopc tool is + used, with the following requirements: + </para> <orderedlist> <listitem> - <para>The <literal>aoppath</literal> option must point to the location - of pojocache-aop.xml</para> + <para> + The + <literal>aoppath</literal> + option must point to the location of pojocache-aop.xml + </para> </listitem> <listitem> - <para>The <literal>src</literal> option must point to the location of - your class files that are to be instrumented. This is typically the - output folder of a <literal>javac</literal> run.</para> + <para> + The + <literal>src</literal> + option must point to the location of your class files that are + to be instrumented. This is typically the output folder of a + <literal>javac</literal> + run. + </para> </listitem> </orderedlist> - <para>The following is an example ant task which performs compile-time - instrumentation:</para> + <para> + The following is an example ant task which performs compile-time + instrumentation: + </para> - <programlisting role="XML"><![CDATA[ -<taskdef name="aopc" classname="org.jboss.aop.ant.AopC" classpathref="aop.classpath"/> + <programlisting role="XML"><![CDATA[<taskdef name="aopc" classname="org.jboss.aop.ant.AopC" classpathref="aop.classpath"/> <target name="aopc" depends="compile" description="Precompile aop class"> <aopc compilerclasspathref="aop.classpath" verbose="true"> <src path="${build}"/> @@ -98,231 +140,47 @@ <classpath path="${build}"/> <classpath refid="lib.classpath"/> </aopc> -</target> -]]></programlisting><para>In this example, once the aopc target - is executeed the clasess in the build directory are modified. They can - then be packaged in a jar and loaded using the normal Java - mechanisms.</para> - </sect1> +</target>]]></programlisting> - <sect1> - <title>Understanding the provided AOP descriptor</title> - - <para>The advanced user might decide to alter the provided AOP descritor. - In order to do this, it is important to understand the reaons behind what - is provided, and what is required by POJO Cache. Previous sections have - mentioned that any class with the <literal>@Replicable</literal> - annotation will be instrumented. This happens, because the provided AOP - descriptor, <literal>pojocache-aop.xml</literal>, has a perpare statement - which matches any class (or subclass) using the annotation. This is shown - in the following snippet:</para> - - <programlisting role="XML"><![CDATA[ -<prepare expr="field(* $instanceof{(a)org.jboss.cache.pojo.annotation.Replicable}-&gt;*)&quot;/&gt; -]]></programlisting> - - <para>More specifically, any code which accesses a field on a class which - has been annotated with <literal>@Replicable</literal>, will be - instrumented: The "field" pointcut in the expression matches both read and - write operations. The wildcard "*" indicates that all java protection - modes are intercepted (private, package, protected, public). The - <literal>$instanceof</literal> expression refers to any annotation that - subclasses <literal>@Replicable</literal>. Finally, the ending wildcard - allows the matched field to have any name.</para> - </sect1> - - <sect1> - <title>Annotation</title> - - <para>Annotation is a new feature in Java 5.0 that when declared can - contain metadata at compile and run time. It is well suited for aop - declaration since there will be no need for external metadata xml - descriptor.</para> - - <sect2> - - - <title>POJO annotation for instrumentation</title> - - - - <para>To support annotation (in order to simplify user's development - effort), the JBoss Cache distribution ships with a - <literal>pojocache-aop.xml</literal> under the - <literal>resources</literal> directory. For reference, here is - annotation definition from <literal>pojocache-aop.xml</literal> again : + <para> + In this example, once the aopc target is executed the classes in + the build directory are modified. They can then be packaged in a + jar and loaded using the normal Java mechanisms. </para> - <programlisting role="XML"><![CDATA[ -<aop> - <prepare expr=&quot;field(*(a)org.jboss.cache.pojo.annotation.Replicable-&gt;*)&quot;/&gt; -</aop> - ]]></programlisting><para>Basically, it simply states that any annotation - with both marker interfaces will be "aspectized" accordingly.</para> - - - - <para>Here is a code snippet that illustrate the declaration:</para> - - - - <programlisting role="JAVA"><![CDATA[ -(a)org.jboss.cache.pojo.annotation.Replicable public class -Person {...} - ]]></programlisting> - - The above declaration will instrument the class - - <literal>Person</literal> - - and all of its sub-classes. That is, if - - <literal>Student</literal> - - sub-class from - - <literal>Personal</literal> - - , then it will get instrumented automatically without further annotation declaration. - </sect2> - - <sect2> - <title>JDK5.0 field level annotations</title> - - <para>In Release 2.0, we have added two additional field level - annotations for customized behavior. The first one is - <code&gt;(a)org.jboss.cache.pojo.annotation.Transient&lt;/code&gt; . When applied - to a field variable, it has the same effect as the Java language - <code>transient</code> keyword. That is, PojoCache won't put this field - into cache management (and therefore no replication).</para> - - <para>The second one is <code> - @org.jboss.cache.pojo.annotation.Serializable </code> , when applied to - a field variable, PojoCache will treat this variable as - <code>Serializable</code> , even when it is <code>Replicable</code> . - However, the field will need to implement the <code>Serializable</code> - interface such that it can be replicated.</para> - - <para>Here is a code snippet that illustrates usage of these two - annotations. Assuming that you have a Gadget class: </para> - <programlisting role="JAVA"><![CDATA[ -public class Gadget -{ - // resource won't be replicated - @Transient - Resource resource; - - // specialAddress is treated as a Serializable object but still has object relationship - @Serializable - SpecialAddress specialAddress; - - // other state variables -} - ]]></programlisting><para>Then when we do:</para><programlisting role="JAVA"><![CDATA[ - Gadget gadget = new Gadget(); - Resource resource = new Resource(); - SpecialAddress specialAddress = new SpecialAddress(); - - // setters - gadget.setResource(resource); - gadget.setSpecialAddress(specialAddress); - - // put into PojoCache management - cache1.putObject("/gadget", gadget); - - // retrieve it from another cache instance - Gadget g2 = (Gadget) cache2.getObject("/gadget"); - - // This is should be null because of @Transient tag so it is not replicated. - g2.getResource(); - - SepcialAddress d2 = g2.getSpecialAddress(); - d2.setName("inet"); // This won't get replicated automatically because of @Serializable tag - ge.setSpecialAddress(d2); // Now this will. - ]]></programlisting> - </sect2> </sect1> <sect1> - <title>Weaving</title> + <title>Understanding the provided AOP descriptor</title> - <para>As already mentioned, a user can use the aop precompiler ( - <literal>aopc</literal> ) to precompile the POJO classes such that, during - runtime, there is no additional system class loader needed. The - precompiler will read in <literal>pojocache-aop.xml</literal> and weave - the POJO byte code at compile time. This is a convenient feature to make - the aop less intrusive.</para> + <para> + The advanced user might decide to alter the provided AOP + descriptor. In order to do this, it is important to understand the + reasons behind what is provided, and what is required by POJO + Cache. Previous sections have mentioned that any class with the + <literal>@Replicable</literal> + annotation will be instrumented. This happens, because the + provided AOP descriptor, + <literal>pojocache-aop.xml</literal> + , has a prepare statement which matches any class (or subclass) + using the annotation. This is shown in the following snippet: + </para> - <para>Below is an Ant snippet that defines the library needed for the - various Ant targets that we are listing here. User can refer to the - <literal>build.xml</literal> in the distribution for full details. - </para> - <programlisting role="XML"><![CDATA[ -<path id="aop.classpath"> - <fileset dir="${lib}"> - <include name="**/*.jar" /> - <exclude name="**/jboss-cache.jar" /> - <exclude name="**/j*unit.jar" /> - <exclude name="**/bsh*.jar" /> - </fileset> -</path> + <programlisting role="XML"><![CDATA[<prepare expr="field(* $instanceof{(a)org.jboss.cache.pojo.annotation.Replicable}-&gt;*)&quot;/&gt; ]]></programlisting> - <sect2> - <title>Ant target for running load-time instrumentation using - specialized class loader</title> - - <para>In JDK5.0, you can use the <code>javaagent</code> option that does - not require a separate Classloader. Here are the ant snippet from - <code>one-test-pojo</code> , for example.</para> - <programlisting role="XML"><![CDATA[ -<target name="one.test.pojo" depends="compile" description="run one junit test case."> - <junit printsummary="yes" timeout="${junit.timeout}" fork="yes"> - <jvmarg value="-Djboss.aop.path=${output}/resources/pojocache-aop.xml"/> - <jvmarg value="-javaagent:${lib}/jboss-aop-jdk50.jar"/> - <classpath path="${output}/etc" /> - <sysproperty key="log4j.configuration" value="file:${output}/etc/log4j.xml" /> - <classpath refid="lib.classpath"/> - <classpath refid="build.classpath"/> - <formatter type="xml" usefile="true"/> - <test name="${test}" todir="${reports}"/> - </junit> -</target> - ]]></programlisting> - </sect2> - - <sect2> - <title>Ant target for aopc</title> - - <para>Below is the code snippet for the <literal>aopc</literal> Ant - target. Running this target will do compile-time weaving of the POJO - classes specified.</para> - - <programlisting role="XML"><![CDATA[ -<taskdef name="aopc" classname="org.jboss.aop.ant.AopC" classpathref="aop.classpath"/> -<target name="aopc" depends="compile" description="Precompile aop class"> - <aopc compilerclasspathref="aop.classpath" verbose="true"> - <src path="${build}"/> - <include name="org/jboss/cache/aop/test/**/*.class"/> - <aoppath path="${output}/resources/pojocache-aop.xml"/> - <classpath path="${build}"/> - <classpath refid="lib.classpath"/> - </aopc> -</target> - ]]></programlisting> - - <para>Below is a snapshot of files that are generated when aopc is - applied. Notice that couple extra classes have been generated because of - <literal>aopc</literal> .</para> - - <figure> - <title>Classes generated after aopc</title> - - <mediaobject> - <imageobject> - <imagedata fileref="images/classes.png" /> - </imageobject> - </mediaobject> - </figure> - </sect2> + <para> + More specifically, any code which accesses a field on a class + which has been annotated with + <literal>@Replicable</literal> + , will be instrumented: The "field" pointcut in the expression + matches both read and write operations. The wildcard "*" indicates + that all java protection modes are intercepted (private, package, + protected, public). The + <literal>$instanceof</literal> + expression refers to any annotation that subclasses + <literal>@Replicable</literal> + . Finally, the ending wildcard allows the matched field to have + any name. + </para> </sect1> </chapter> \ No newline at end of file