[jboss-cvs] JBossCache/docs/PojoCache/en/modules ...
Ben Wang
bwang at jboss.com
Tue Nov 21 08:21:43 EST 2006
User: bwang
Date: 06/11/21 08:21:43
Modified: docs/PojoCache/en/modules appendix.xml introduction.xml
configuration.xml instrumentation.xml
architecture.xml
Log:
Doc update
Revision Changes Path
1.6 +5 -5 JBossCache/docs/PojoCache/en/modules/appendix.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: appendix.xml
===================================================================
RCS file: /cvsroot/jboss/JBossCache/docs/PojoCache/en/modules/appendix.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -b -r1.5 -r1.6
--- appendix.xml 21 Nov 2006 06:08:20 -0000 1.5
+++ appendix.xml 21 Nov 2006 13:21:42 -0000 1.6
@@ -289,16 +289,16 @@
-->
<!-- If a POJO has PojoCachable annotation, it will be asepctized. -->
- <prepare expr="field(* @org.jboss.cache.pojo.annotation.Replicable->*)" />
+ <prepare expr="field(* $instanceof{@org.jboss.cache.pojo.annotation.Replicable}->*)" />
<!-- Observer and Observable to monitor field modification -->
<bind pointcut="
- set(* @org.jboss.cache.pojo.annotation.Replicable->*)
+ set(* $instanceof{@org.jboss.cache.pojo.annotation.Replicable}->*)
">
<interceptor class="org.jboss.cache.pojo.observable.SubjectInterceptor"/>
</bind>
- <introduction class="@org.jboss.cache.pojo.annotation.Replicable">
+ <introduction class="$instanceof{@org.jboss.cache.pojo.annotation.Replicable}">
<mixin>
<interfaces>org.jboss.cache.pojo.observable.Subject</interfaces>
<class>org.jboss.cache.pojo.observable.SubjectImpl</class>
1.6 +8 -7 JBossCache/docs/PojoCache/en/modules/introduction.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: introduction.xml
===================================================================
RCS file: /cvsroot/jboss/JBossCache/docs/PojoCache/en/modules/introduction.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -b -r1.5 -r1.6
--- introduction.xml 26 Oct 2006 09:01:44 -0000 1.5
+++ introduction.xml 21 Nov 2006 13:21:42 -0000 1.6
@@ -16,7 +16,7 @@
Nonetheless, it has the following constraints:
<itemizedlist>
<listitem>If replication or persistency is needed, the object will then need to
- implement the <literal>Serializable</literal> interface.
+ implement the <literal>Serializable</literal> interface. E.g.,
<programlisting>public Class Foo implements Serializable</programlisting>
</listitem>
<listitem>Users will have to manage the cache specifically, e.g., when an object is updated, a user will need
@@ -179,7 +179,8 @@
p.getName(); // is "old value"
</programlisting>
Note that the transaction context
- only applies to the node level though. That is, in a complex object
+ only applies to the node level though similar to the Java semantics.
+ 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).
@@ -320,7 +321,7 @@
cycle method to start the cache. Below is a code snippet that creates and starts the cache:
<programlisting>String configFile = "replSync-service.xml";
boolean toStart = false;
-PojoCache pcache = PojoCacheFactory.createInstance(configFiel, toStart);
+PojoCache pcache = PojoCacheFactory.createCache(configFiel, toStart);
pcache.start(); // if toStart above is true, it will starts the cache automatically.
pcache.attach(id, pojo);
...
@@ -344,19 +345,19 @@
<itemizedlist>
<listitem>
- jboss-aop-jdk50.jar. Main JBossAop library.
+ pojocache.jar. Main PojoCache library.
</listitem>
<listitem>
- javassist.jar. Java byte code manipulation library.
+ jboss-aop-jdk50.jar. Main JBossAop library.
</listitem>
<listitem>
- trove.jar. High performance collections for Java.
+ javassist.jar. Java byte code manipulation library.
</listitem>
<listitem>
- qdox.jar. Javadoc parser for annotation. Needed only for JDK1.4 annotation.
+ trove.jar. High performance collections for Java.
</listitem>
</itemizedlist>
</listitem>
1.6 +6 -3 JBossCache/docs/PojoCache/en/modules/configuration.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: configuration.xml
===================================================================
RCS file: /cvsroot/jboss/JBossCache/docs/PojoCache/en/modules/configuration.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -b -r1.5 -r1.6
--- configuration.xml 29 Sep 2006 09:46:30 -0000 1.5
+++ configuration.xml 21 Nov 2006 13:21:42 -0000 1.6
@@ -68,13 +68,17 @@
</programlisting>
</para>
+ <para>Another way to support multiple regions in eviction is to use Marshalling. When the Cache
+ use marshalling, it has the side effect of placing all internal data under that specific region.
+ As a result, the whole region will be passivated and activated at the same time.</para>
</sect1>
<sect1>
<title>PojoCache configuration xml</title>
<para>PojoCache supplies a <literal>pojocache-aop.xml</literal> that is required to be set via a
- system property: <literal>jboss.aop.path</literal> during compile- or load-time. The file now consists
+ system property: <literal>jboss.aop.path</literal> during compile- or load-time, or placed in
+ the user's classpath. The file now consists
of interceptor stack specification and annotations for POJO instrumentation. It is listed fully in the
Appendix section. Note that the file should be read mostly. So no need to modify it now unless you
are customizing the interceptor chain, e.g.</para>
@@ -83,8 +87,7 @@
<sect1>
<title>PojoCache MBean service</title>
- <para>PojoCache can expose the MBean attributes by setting the flag <literal>useMBean</literal>
- in the cache config xml.
+ <para>TODO... This section needs to be filled in when the new JMX aspect is introduced.
</para>
</sect1>
1.6 +25 -25 JBossCache/docs/PojoCache/en/modules/instrumentation.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: instrumentation.xml
===================================================================
RCS file: /cvsroot/jboss/JBossCache/docs/PojoCache/en/modules/instrumentation.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -b -r1.5 -r1.6
--- instrumentation.xml 21 Nov 2006 06:08:20 -0000 1.5
+++ instrumentation.xml 21 Nov 2006 13:21:42 -0000 1.6
@@ -17,15 +17,16 @@
<para>As for the second step, either we can ask JBoss Aop to do load-time
(through a special class loader, so-called load-time mode) or compile-time
instrumentation (use of an aopc pre-compiler, so-called precompiled
- mode). Read can read the JBoss Aop introduction chapter for more details.</para>
+ mode). Reader can read the JBoss Aop introduction chapter for more details.</para>
<sect1>
<title>XML descriptor</title>
<para>To declare a POJO via XML configuration file, you will need a
- <literal>META-INF/jboss-aop.xml</literal>
+ <literal>META-INF/jboss-aop.xml</literal> (or in the PojoCache case, it is
+ the equivalent <literal>pojocache-service.xml</literal>
file located under the class
- path or a <literal>xxx-aop.xml</literal> listed in the <literal>jboss.aop.path</literal> system
+ path or listed in the <literal>jboss.aop.path</literal> system
property. JBoss AOP framework will read this file during startup to make
necessary byte code manipulation for advice and introduction. Or you
can pre-compile it using a pre-compiler called
@@ -66,21 +67,32 @@
<literal>Address</literal>
are provided in the Appendix section. But here
is the snippet for
- <literal>META-INF/jboss-aop.xml</literal>
+ <literal>pojocache-aop.xml</literal>
:
</para>
<programlisting>
<aop>
- <prepare expr="field(* org.jboss.test.cache.test.standAloneAop.Address->*)" />
- <prepare expr="field(* $instanceof{org.jboss.test.cache.test.standAloneAop.Person}->*)" />
+ <prepare expr="field(* $instanceof{@org.jboss.cache.pojo.annotation.Replicable}->*)" />
</aop>
</programlisting>
+ and then notice the annotation @Replicable used in the <literal>Person</literal> and
+ <literal>Address</literal> POJOs. Also note that @Replicable is now inheritant. For example,
+ sub-class of <literal>Person</literal> such as <literal>Student</literal> will also
+ be aspectized by JBoss Aop as well. If you want to stop this inheritance behavior,
+ you can simply remove the
+ <literal>$instanceof</literal> declaration in the prepare statement, e.g.,
+ <programlisting>
+ <aop>
+ <prepare expr="field(* @org.jboss.cache.pojo.annotation.Replicable->*)" />
+ </aop>
+ </programlisting>
+
<para>Detailed semantics of
- <literal>jboss-aop.xml</literal>
+ <literal>pojocache-aop.xml</literal> (or equivalently <literal>pojocache-aop.xml</literal>)
can again
- be found in JBossAop. But above statements basically declare all field
+ be found in JBoss Aop. But above statements basically declare all field
read and write operations in classes
<code>Address</code>
and
@@ -125,10 +137,8 @@
<listitem>
We don't intercept field modifiers of
- <literal>static</literal>
- ,
<literal>final</literal>
- , and
+ and
<literal>transient</literal>
though. That is, field with these modifiers are not stored in cache and is not replicated either. If
you don't want your field to be managed by the cache, you can declare them with these modifiers, e.g.,
@@ -153,7 +163,7 @@
<literal>resources</literal>
directory. For
reference, here is annotation definition from
- <literal>pojocache-aop.xml</literal>
+ <literal>pojocache-aop.xml</literal> again
:
<programlisting>
<aop>
@@ -165,17 +175,7 @@
</para>
- <para>Here is two code snippets that illustrate the declaration of
- both types:</para>
-
-
-<programlisting>
- @org.jboss.cache.pojo.annotation.Replicable
- public class Address {...}
-</programlisting>
-
-The above declaration will instrument the class <literal>Address</literal>, and
-
+ <para>Here is a code snippet that illustrate the declaration:</para>
<programlisting>
@org.jboss.cache.pojo.annotation.Replicable
public class Person {...}
@@ -195,7 +195,7 @@
<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>PojoCacheable</code>. However, the field will need to implement the <code>Serializable</code>
+ <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.
@@ -241,7 +241,7 @@
(<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>jboss-aop.xml</literal>
+ <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.
1.10 +12 -12 JBossCache/docs/PojoCache/en/modules/architecture.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: architecture.xml
===================================================================
RCS file: /cvsroot/jboss/JBossCache/docs/PojoCache/en/modules/architecture.xml,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -b -r1.9 -r1.10
--- architecture.xml 26 Oct 2006 09:01:44 -0000 1.9
+++ architecture.xml 21 Nov 2006 13:21:42 -0000 1.10
@@ -15,7 +15,7 @@
<literal>cache-service.xml</literal>. This architecture provides a decoupled framework that by itself
is modularized and pluggable (available in the future).</para>
<para>Please note that you will need to specify a system property <literal>jboss.aop.path</literal> to set it
- to the path where <literal>pojocache-aop.xml</literal> resides.</para>
+ to the path where <literal>pojocache-aop.xml</literal> resides or put it in your classpath.</para>
<figure>
<title>PojoCache architecture overview</title>
@@ -157,10 +157,10 @@
<literal>private</literal>
</listitem>
<listitem>
- we skip interception for field with <literal>final</literal>, <literal>static</literal>,
- and <literal>transient</literal> qualifiers. As a result, any field with these 3 qualifiers will not
- be replicated or persisted (although there is Jira issue opened on to make "static" modifier
- available for replication).
+ we skip interception for field with <literal>final</literal>, and <literal>transient</literal> qualifiers. As a result, any field with these 3 qualifiers will not
+ be replicated or persisted. Note that since Release 2.0, "static" field modifier will
+ be replicated by default. If user doesn't want to replicate the static field, she can
+ annotate the field with "@Transient" annotation to skip the replication.
</listitem>
</itemizedlist>
</para>
@@ -355,7 +355,7 @@
String configFile = "META-INF/replSync-service.xml";
boolean toStart = false; // Deault is true.
-PojoCache cache = PojoCacheFactory.createInstance(configFile, toStart);
+PojoCache cache = PojoCacheFactory.createCache(configFile, toStart);
Person joe = new Person(); // instantiate a Person object named joe
joe.setName("Joe Black");
@@ -458,7 +458,7 @@
import org.jboss.test.cache.test.standAloneAop.Address;
String configFile = "META-INF/replSync-service.xml";
-PojoCache cache = PojoCacheFactory.createInstance(configFile); // This will start PojoCache automatically
+PojoCache cache = PojoCacheFactory.createCache(configFile); // This will start PojoCache automatically
Person joe = new Person(); // instantiate a Person object named joe
joe.setName("Joe Black");
@@ -513,7 +513,7 @@
import org.jboss.test.cache.test.standAloneAop.Address;
String configFile = "META-INF/replSync-service.xml";
-PojoCache cache = PojoCacheFactory.createInstance(configFile); // This will start PojoCache automatically
+PojoCache cache = PojoCacheFactory.createCache(configFile); // This will start PojoCache automatically
Person joe = cache.find("pojo/joe"); // retrieve the POJO reference.
Person mary = cache.find("pojo/mary"); // retrieve the POJO reference.
@@ -573,7 +573,7 @@
<title>Physical object cache mapping model</title>
<para>The previous sections describe the logical object mapping model. In this section, we will explain
the physical mapping model, that is, how do we map the POJO into internal core <literal>Cache</literal>
- for transaction state replication.</para>
+ for transactional state replication.</para>
<para>Starting in release 2.0, we have adopted a so-called "flat space" mapping approach. That is, whenever a
POJO attachment is called with a specified String id, we would create an instance of
@@ -803,12 +803,12 @@
<listitem>It does not require to implement <literal>Serializable</literal>, but it does require there is a
no-arg constructor declared (can be private). This is needed such that during failover, it has a way
to reconstruct the POJO.</listitem>
- <listitem>There are specific default behaviors for different modifiers as mentioned (<literal>static</literal>,
- <literal>transient</literal>, and <literal>final</literal>). However, the user can override the <literal>transient</literal>
+ <listitem>There are specific default behaviors for different modifiers as mentioned (
+ <literal>transient</literal> and <literal>final</literal>). However, the user can override the <literal>transient</literal>
field to make it replicatable through the JBoss Aop:
<programlisting>
<annotation-introduction expr="field(* POJO->aTransientField)">
- @org.jboss.cache.pojo.annotation.NonTransient
+ @org.jboss.cache.pojo.annotation.Serializable
</annotation-introduction>
</programlisting>
where you are annotating an original transient field <literal>aTransientField</literal> with a <literal>NonTransient</literal>
More information about the jboss-cvs-commits
mailing list