[jbosscache-commits] JBoss Cache SVN: r6595 - in pojo/branches/2.2/src/main/docbook: userguide/en and 1 other directories.
jbosscache-commits at lists.jboss.org
jbosscache-commits at lists.jboss.org
Thu Aug 21 15:21:04 EDT 2008
Author: jason.greene at 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">users 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">the 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">users 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">user 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>@org.jboss.cache.annotation.Replicable</literal>
+ 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>@org.jboss.cache.annotation.Transient</literal> 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>@org.jboss.cache.annotation.Serializable</literal>
+ 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{@org.jboss.cache.pojo.annotation.Replicable}->*)"/>
-]]></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="field(*@org.jboss.cache.pojo.annotation.Replicable->*)"/>
-</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[
- at 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>@org.jboss.cache.pojo.annotation.Transient</code> . 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{@org.jboss.cache.pojo.annotation.Replicable}->*)"/>
]]></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
More information about the jbosscache-commits
mailing list