[jbosscache-commits] JBoss Cache SVN: r6994 - pojo/trunk/src/main/docbook/userguide/en/modules.

[jbosscache-commits at lists.jboss.org]

Author: jason.greene at jboss.com
Date: 2008-10-21 18:28:54 -0400 (Tue, 21 Oct 2008)
New Revision: 6994

Modified:
   pojo/trunk/src/main/docbook/userguide/en/modules/architecture.xml
Log:
Merge doc update


Modified: pojo/trunk/src/main/docbook/userguide/en/modules/architecture.xml
===================================================================
--- pojo/trunk/src/main/docbook/userguide/en/modules/architecture.xml	2008-10-21 22:25:24 UTC (rev 6993)
+++ pojo/trunk/src/main/docbook/userguide/en/modules/architecture.xml	2008-10-21 22:28:54 UTC (rev 6994)
@@ -486,4 +486,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[
+ at 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 Team(); 
+     cache.attach("/team/1", team);
+     
+     team.setMember(0, "John");
+     team.setMember(1, "Joe");
+   }
+}    
+]]></programlisting>
+      </sect1>
 </chapter>