Author: jason.greene(a)jboss.com Date: 2008-08-21 20:15:38 -0400 (Thu, 21 Aug 2008) New Revision: 6596 Modified: pojo/branches/2.2/src/main/docbook/userguide/en/master.xml pojo/branches/2.2/src/main/docbook/userguide/en/modules/appendix.xml pojo/branches/2.2/src/main/docbook/userguide/en/modules/architecture.xml Log: Update docs Add array section 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 19:21:04 UTC (rev 6595) +++ pojo/branches/2.2/src/main/docbook/userguide/en/master.xml 2008-08-22 00:15:38 UTC (rev 6596) @@ -18,8 +18,8 @@ <bookinfo> <title>POJO Cache</title> <subtitle>User Documentation</subtitle> - <releaseinfo>Release 2.1.0.GA</releaseinfo> - <pubdate>March 2008</pubdate> + <releaseinfo>Release 2.2.0.GA</releaseinfo> + <pubdate>October 2008</pubdate> <author> <firstname>Ben</firstname> Modified: pojo/branches/2.2/src/main/docbook/userguide/en/modules/appendix.xml =================================================================== --- pojo/branches/2.2/src/main/docbook/userguide/en/modules/appendix.xml 2008-08-21 19:21:04 UTC (rev 6595) +++ pojo/branches/2.2/src/main/docbook/userguide/en/modules/appendix.xml 2008-08-22 00:15:38 UTC (rev 6596) @@ -161,149 +161,29 @@ <title>PojoCache configuration xml</title> <para>Attached is a full listing for <literal>pojocache-aop.xml</literal>.</para> <programlisting role="XML"><![CDATA[ - <?xml version="1.0" encoding="UTF-8"?> - <!-- - This is the PojoCache configuration file that specifies: - 1. Interceptor stack for API - 2. Annotation binding for POJO (via "prepare" element) +<aop> + <!-- If a POJO has a Replicable annotation, it will be asepectized. --> - Basically, this is a variant of jboss-aop.xml. Note that - except for the customization of interceptor stack, you should - not need to modify this file. - - To run PojoCache, you will need to define a system property: - jboss.aop.path that contains the path to this file such that JBoss Aop - can locate it. + <!-- + Supports inheritance and polymorphism. It can either be a concrete class + or an interface. All sub-classes or interface implementors will be instrumeneted. --> - <aop> + <prepare expr="field(* $instanceof{(a)org.jboss.cache.pojo.annotation.Replicable}-&gt;*)&quot; /> - <!-- - This defines the PojoCache 2.0 interceptor stack. Unless necessary, don't modify the stack here! - --> + <!-- Work around that ensures annotated classes which do not access fields are instrumented --> + <introduction expr=&quot;class($instanceof{(a)org.jboss.cache.pojo.annotation.Replicable})&quot;/&gt; - <!-- Check id range validity --> - <interceptor name="CheckId" class="org.jboss.cache.pojo.interceptors.CheckIdInterceptor" - scope="PER_INSTANCE"/> - - <!-- Track Tx undo operation --> - <interceptor name="Undo" class="org.jboss.cache.pojo.interceptors.PojoTxUndoInterceptor" - scope="PER_INSTANCE"/> - - <!-- Begining of interceptor chain --> - <interceptor name="Start" class="org.jboss.cache.pojo.interceptors.PojoBeginInterceptor" - scope="PER_INSTANCE"/> - - <!-- Check if we need a local tx for batch processing --> - <interceptor name="Tx" class="org.jboss.cache.pojo.interceptors.PojoTxInterceptor" - scope="PER_INSTANCE"/> - - <!-- - Mockup failed tx for testing. You will need to set PojoFailedTxMockupInterceptor.setRollback(true) - to activate it. - --> - <interceptor name="MockupTx" class="org.jboss.cache.pojo.interceptors.PojoFailedTxMockupInterceptor" - scope="PER_INSTANCE"/> - - <!-- Perform parent level node locking --> - <interceptor name="TxLock" class="org.jboss.cache.pojo.interceptors.PojoTxLockInterceptor" - scope="PER_INSTANCE"/> - - <!-- Interceptor to perform Pojo level rollback --> - <interceptor name="TxUndo" class="org.jboss.cache.pojo.interceptors.PojoTxUndoSynchronizationInterceptor" - scope="PER_INSTANCE"/> - - <!-- Interceptor to used to check recursive field interception. --> - <interceptor name="Reentrant" class="org.jboss.cache.pojo.interceptors.MethodReentrancyStopperInterceptor" - scope="PER_INSTANCE"/> - - <!-- Whether to allow non-serializable pojo. Default is false. --> - <interceptor name="MarshallNonSerializable" - class="org.jboss.cache.pojo.interceptors.CheckNonSerializableInterceptor" - scope="PER_INSTANCE"> - <attribute name="marshallNonSerializable">false</attribute> - </interceptor> - - <!-- This defines the stack macro --> - <stack name="Attach"> - <interceptor-ref name="Start"/> - <interceptor-ref name="CheckId"/> - <interceptor-ref name="MarshallNonSerializable"/> - <interceptor-ref name="Tx"/> - <!-- NOTE: You can comment this out during production although leaving it here is OK. --> - <interceptor-ref name="MockupTx"/> - <interceptor-ref name="TxLock"/> - <interceptor-ref name="TxUndo"/> - </stack> - - <stack name="Detach"> - <interceptor-ref name="Start"/> - <interceptor-ref name="CheckId"/> - <interceptor-ref name="Tx"/> - <!-- NOTE: You can comment this out during production although leaving it here is OK. --> - <interceptor-ref name="MockupTx"/> - <interceptor-ref name="TxLock"/> - <interceptor-ref name="TxUndo"/> - </stack> - - <stack name="Find"> - <interceptor-ref name="Start"/> - <interceptor-ref name="CheckId"/> - </stack> - - <!-- - The following section should be READ-ONLY!! It defines the annotation binding to the stack. - --> - - <!-- This binds the jointpoint to specific in-memory operations. Currently in PojoUtil. --> - <bind pointcut="execution(* - @org.jboss.cache.pojo.annotation.Reentrant->toString())"> - <interceptor-ref name="Reentrant"/> - </bind> - - <bind pointcut="execution(* - org.jboss.cache.pojo.PojoUtil->@org.jboss.cache.pojo.annotation.TxUndo(..))"> - <interceptor-ref name="Undo"/> - </bind> - - <bind pointcut="execution(* org.jboss.cache.pojo.impl.PojoCacheImpl->@org.jboss.cache.pojo.annotation.Attach(..))"> - <stack-ref name="Attach"/> - </bind> - - <bind pointcut="execution(* org.jboss.cache.pojo.impl.PojoCacheImpl->@org.jboss.cache.pojo.annotation.Detach(..))"> - <stack-ref name="Detach"/> - </bind> - - <bind pointcut="execution(* org.jboss.cache.pojo.impl.PojoCacheImpl->@org.jboss.cache.pojo.annotation.Find(..))"> - <stack-ref name="Find"/> - </bind> - - - <!-- - Following is declaration for JDK50 annotation. You use the specific annotation on your - POJO such that it can be instrumented. Idea is user will then need only to annotate like: - @org.jboss.cache.pojo.annotation.Replicable - in his POJO. There will be no need of jboss-aop.xml from user's side. - --> - - <!-- If a POJO has PojoCachable annotation, it will be asepctized. --> - <prepare expr="field(* $instanceof{(a)org.jboss.cache.pojo.annotation.Replicable}-&gt;*)&quot; /> - - <!-- Observer and Observable to monitor field modification --> - <bind pointcut=" - set(* $instanceof{(a)org.jboss.cache.pojo.annotation.Replicable}-&gt;*) - "> - <interceptor class="org.jboss.cache.pojo.observable.SubjectInterceptor"/> - </bind> - - <introduction class=&quot;$instanceof{(a)org.jboss.cache.pojo.annotation.Replicable}&quot;&gt; - <mixin> - <interfaces>org.jboss.cache.pojo.observable.Subject</interfaces> - <class>org.jboss.cache.pojo.observable.SubjectImpl</class> - <construction>new org.jboss.cache.pojo.observable.SubjectImpl(this)</construction> - </mixin> - </introduction> - </aop> - + <!-- Array support --> + <!-- Comment entire section to disable --> + <arrayreplacement expr=&quot;class($instanceof{(a)org.jboss.cache.pojo.annotation.Replicable})&quot;/&gt; + <interceptor name="pojocache-array" class="org.jboss.cache.pojo.interceptors.dynamic.ArrayInterceptor"/> + <introduction expr=&quot;class($instanceof{(a)org.jboss.cache.pojo.annotation.Replicable})&quot;&gt; + <interfaces>org.jboss.cache.pojo.impl.ArrayInterceptable</interfaces> + </introduction> + <arraybind name="pojocache-array" type="READ_WRITE"> + <interceptor-ref name="pojocache-array"/> + </arraybind> +</aop> ]]></programlisting> </sect1> </chapter> Modified: pojo/branches/2.2/src/main/docbook/userguide/en/modules/architecture.xml =================================================================== --- pojo/branches/2.2/src/main/docbook/userguide/en/modules/architecture.xml 2008-08-21 19:21:04 UTC (rev 6595) +++ pojo/branches/2.2/src/main/docbook/userguide/en/modules/architecture.xml 2008-08-22 00:15:38 UTC (rev 6596) @@ -19,86 +19,6 @@ </mediaobject> </figure> - <sect1> - <title>POJO Cache interceptor stack</title> - - <para>As mentioned, the JBoss Aop framework is used to provide a configurable interceptor stack. - In the current implementation, the main POJO Cache methods have their own independant stack. These are specified in <literal>META-INF/pojocache-aop.xml</literal> - In most cases, this file should be left alone, although advanced users may wish to add their own interceptors. - The Following is the default configuration:</para> -<programlisting role="XML"><![CDATA[ - <!-- Check id range validity --> - <interceptor name="CheckId" class="org.jboss.cache.pojo.interceptors.CheckIdInterceptor" - scope="PER_INSTANCE"/> - - <!-- Track Tx undo operation --> - <interceptor name="Undo" class="org.jboss.cache.pojo.interceptors.PojoTxUndoInterceptor" - scope="PER_INSTANCE"/> - - <!-- Begining of interceptor chain --> - <interceptor name="Start" class="org.jboss.cache.pojo.interceptors.PojoBeginInterceptor" - scope="PER_INSTANCE"/> - - <!-- Check if we need a local tx for batch processing --> - <interceptor name="Tx" class="org.jboss.cache.pojo.interceptors.PojoTxInterceptor" - scope="PER_INSTANCE"/> - - <!-- - Mockup failed tx for testing. You will need to set PojoFailedTxMockupInterceptor.setRollback(true) - to activate it. - --> - <interceptor name="MockupTx" class="org.jboss.cache.pojo.interceptors.PojoFailedTxMockupInterceptor" - scope="PER_INSTANCE"/> - - <!-- Perform parent level node locking --> - <interceptor name="TxLock" class="org.jboss.cache.pojo.interceptors.PojoTxLockInterceptor" - scope="PER_INSTANCE"/> - - <!-- Interceptor to perform Pojo level rollback --> - <interceptor name="TxUndo" class="org.jboss.cache.pojo.interceptors.PojoTxUndoSynchronizationInterceptor" - scope="PER_INSTANCE"/> - - <!-- Interceptor to used to check recursive field interception. --> - <interceptor name="Reentrant" class="org.jboss.cache.pojo.interceptors.MethodReentrancyStopperInterceptor" - scope="PER_INSTANCE"/> - - <!-- Whether to allow non-serializable pojo. Default is false. --> - <interceptor name="MarshallNonSerializable" class="org.jboss.cache.pojo.interceptors.CheckNonSerializableInterceptor" - scope="PER_INSTANCE"> - <attribute name="marshallNonSerializable">false</attribute> - </interceptor> - - <stack name="Attach"> - <interceptor-ref name="Start"/> - <interceptor-ref name="CheckId"/> - <interceptor-ref name="Tx"/> - <interceptor-ref name="TxLock"/> - <interceptor-ref name="TxUndo"/> - </stack> - - <stack name="Detach"> - <interceptor-ref name="Start"/> - <interceptor-ref name="CheckId"/> - <interceptor-ref name="Tx"/> - <interceptor-ref name="TxLock"/> - <interceptor-ref name="TxUndo"/> - </stack> - - <stack name="Find"> - <interceptor-ref name="Start"/> - <interceptor-ref name="CheckId"/> - </stack> -]]></programlisting> -<para> - The stack should be self-explanatory. For example, for the <literal>Attach</literal> stack, - we currently have <literal>Start, CheckId, Tx, TxLock</literal>, and - <literal>TxUndo</literal> interceptors. The stack always starts with a - <literal>Start</literal> interceptor such that initialization can be done properly. - <literal>CheckId</literal> is to ensure the validity of the Id (e.g., it didn't use any internal - Id string). Finally, <literal>Tx, TxLock</literal>, and <literal>TxUndo</literal> are handling the - the proper transaction locking and rollback behavior (if needed). -</para> - </sect1> <sect1> <title>Field interception</title> @@ -116,7 +36,7 @@ All access qualifiers are intercepted. In other words, all <literal>private</literal>, all <literal>protected</literal>, all default, and all <literal>public</literal> fields will be intercepted. </listitem> <listitem> - Any field with <literal>final</literal>, <literal>static</literal>, and/or <literal>transient</literal> qualifiers, <emphasis role="bold">will be skipped</emphasis>. Therefore, they will not be replicated, passivated, or manipulated in any way by POJO Cache. + Any field with <literal>static</literal>, and/or <literal>transient</literal> qualifiers, <emphasis role="bold">will be skipped</emphasis>. Therefore, they will not be replicated, passivated, or manipulated in any way by POJO Cache. </listitem> </itemizedlist> </para> @@ -416,12 +336,9 @@ </listitem> </itemizedlist> - The drawback to this approach is that the calling application must re-get any collection references that were attached. Otherwise, - the cache will not be aware of future changes. If the collection is referenced from another object, then the calling app can obtain - the proxy by using the publishing mechanism provided by the object (e.g. Person.getHobbies()). - - If, however, the collection is directly attached to the cache, then a subsequent <literal>find()</literal> call will need to be made - to retrieve the proxy. + The drawback to this approach is that the calling application must re-get any collection references that were directly attached. Otherwise, + the cache will not be aware of future changes. However, if the collection is referenced from an attached object, then this is transparently + handled. More specifically, the attached object will see the proxy instead of the original. </para> <para>The following code snippet illustrates obtaining a direct Collection proxy reference: @@ -486,4 +403,51 @@ </itemizedlist> </sect2> </sect1> + <sect1> + <title>Array Mapping</title> + + <para>As of 2.2, array fields of any attached object are updated transparently, provided that the array + is written/read from a class marked with <literal>@Replicable</literal>. If this is the case, only + the indexes of the array that are modified are replicated. However, if the array is passed externally + to a class that is not marked as <literal>@Replicable</literal>, then the changes will not be noticed. For this + reason, it is recommended to abstract access to the array where possible (i.e. setItem(item, index)). + If an external, non-replicable class needs access to the array, then it is recommended to pass a copy, + and add a method to the container object that reapplies the changes. Also, due to JVM limitations, + an array can not be monitored if it is directly attached to the cache (i.e. a first class object). POJO + Cache still allows this, but they are treated as a serializable type. As with other serializable type, + they must be reattached after every change. + </para> + + <para>The following code snippet illustrates accessing a replicated array through abstraction: + </para> +<programlisting role="JAVA"><![CDATA[ +@Replicable public class Team +{ + private String[] members = new String[10]; + + public String getMember(int index) + { + return members[index]; + } + + public void setMember(int index, String member) + { + members[index] = member; + } +} + +public class SomeExternalClass +{ + ... + public void someMethod() + { + Team team = new Tesam(); + cache.attach("/team/1", team); + + team.setMember(0, "John"); + team.setMember(1, "Joe"); + } +} +]]></programlisting> + </sect1> </chapter>