4:52 p.m.
Author: manik.surtani(a)jboss.com
Date: 2008-03-09 17:52:37 -0400 (Sun, 09 Mar 2008)
New Revision: 5405
Modified:
pojo/trunk/pom.xml
pojo/trunk/src/main/docbook/faq/en/master.xml
pojo/trunk/src/main/docbook/tutorial/en/master.xml
pojo/trunk/src/main/docbook/userguide/en/master.xml
pojo/trunk/src/main/docbook/userguide/en/modules/api.xml
pojo/trunk/src/main/docbook/userguide/en/modules/appendix.xml
pojo/trunk/src/main/docbook/userguide/en/modules/architecture.xml
pojo/trunk/src/main/docbook/userguide/en/modules/configuration.xml
pojo/trunk/src/main/docbook/userguide/en/modules/instrumentation.xml
pojo/trunk/src/main/docbook/userguide/en/modules/introduction.xml
Log:
1. Updated docbook program listings to enable syntax highlighting.
2. Updated pom.xml to use latest JBoss.org look and feel.
Modified: pojo/trunk/pom.xml
===================================================================
--- pojo/trunk/pom.xml 2008-03-08 11:57:27 UTC (rev 5404)
+++ pojo/trunk/pom.xml 2008-03-09 21:52:37 UTC (rev 5405)
@@ -147,18 +147,33 @@
<version>2.0.0</version>
<extensions>true</extensions>
<dependencies>
- <dependency>
- <groupId>org.jboss</groupId>
- <artifactId>jbossorg-docbook-xslt</artifactId>
- <version>1.0.0</version>
- </dependency>
- <dependency>
- <groupId>org.jboss</groupId>
- <artifactId>jbossorg-jdocbook-style</artifactId>
- <version>1.0.0</version>
- <type>jdocbook-style</type>
- </dependency>
- </dependencies>
+ <dependency>
+ <groupId>org.jboss</groupId>
+ <artifactId>jbossorg-docbook-xslt</artifactId>
+ <version>1.1.0-SNAPSHOT</version>
+ </dependency>
+ <dependency>
+ <groupId>org.jboss</groupId>
+ <artifactId>jbossorg-jdocbook-style</artifactId>
+ <version>1.1.0-SNAPSHOT</version>
+ <type>jdocbook-style</type>
+ </dependency>
+ <dependency>
+ <groupId>com.uwyn</groupId>
+ <artifactId>jhighlight</artifactId>
+ <version>1.0</version>
+ </dependency>
+ <dependency>
+ <groupId>de.java2html</groupId>
+ <artifactId>java2html</artifactId>
+ <version>5.0</version>
+ </dependency>
+ <dependency>
+ <groupId>org.richfaces.docs</groupId>
+ <artifactId>highlight</artifactId>
+ <version>3.1.4.GA</version>
+ </dependency>
+ </dependencies>
<executions>
<!-- The User Guide-->
Modified: pojo/trunk/src/main/docbook/faq/en/master.xml
===================================================================
--- pojo/trunk/src/main/docbook/faq/en/master.xml 2008-03-08 11:57:27 UTC (rev 5404)
+++ pojo/trunk/src/main/docbook/faq/en/master.xml 2008-03-09 21:52:37 UTC (rev 5405)
@@ -584,17 +584,18 @@
proxy class.
</para>
- <programlisting>ArrayList list = new ArrayList();
- list.add("first");
+ <programlisting role="JAVA"><![CDATA[
+ ArrayList list = new ArrayList();
+ list.add("first");
- cache.attach("list/test", list); // Put the list under the aop
cache
- list.add("second"); // Won't work since AOP intercepts the
dynamic proxy not the original POJO.
+ cache.attach("list/test", list); // Put the list under the aop cache
+ list.add("second"); // Won't work since AOP intercepts the dynamic proxy
not the original POJO.
- ArrayList myList = (List)cache.find("list/test"); // we are
getting a dynamic proxy instead
- myList.add("second"); // it works now
- myList.add("third");
- myList.remove("third");
- </programlisting>
+ ArrayList myList = (List)cache.find("list/test"); // we are getting a
dynamic proxy instead
+ myList.add("second"); // it works now
+ myList.add("third");
+ myList.remove("third");
+ ]]></programlisting>
</answer>
</qandaentry>
@@ -614,17 +615,18 @@
is the code snippet.
</para>
- <programlisting>ArrayList list = new ArrayList();
- list.add("first");
+ <programlisting role="JAVA"><![CDATA[
+ ArrayList list = new ArrayList();
+ list.add("first");
- cache.attach("list", list); // Put the list under the aop cache
+ cache.attach("list", list); // Put the list under the aop cache
- ArrayList myList = (List)cache.find("list"); // we are getting a
dynamic proxy instead
- myList.add("second"); // it works now
+ ArrayList myList = (List)cache.find("list"); // we are getting a dynamic
proxy instead
+ myList.add("second"); // it works now
- cache.attach("list_alias", myList); // Note you will need to use
the proxy here!!
- myList.remove("second");
- </programlisting>
+ cache.attach("list_alias", myList); // Note you will need to use the proxy
here!!
+ myList.remove("second");
+ ]]></programlisting>
</answer>
</qandaentry>
Modified: pojo/trunk/src/main/docbook/tutorial/en/master.xml
===================================================================
--- pojo/trunk/src/main/docbook/tutorial/en/master.xml 2008-03-08 11:57:27 UTC (rev 5404)
+++ pojo/trunk/src/main/docbook/tutorial/en/master.xml 2008-03-09 21:52:37 UTC (rev 5405)
@@ -130,30 +130,64 @@
annotation.
</para>
- <programlisting><![CDATA[
- @org.jboss.cache.pojo.annotation.Replicable
- public class Person {
- ...
- public String getName() { return name; }
- public void setName(String name) { this.name=name; }
- ...
- public List<String> getLanguages() { return languages; }
- public void setLanguages(List<String> languages) { this.languages =
languages; }
- ...
- public Address getAddress() { return address; }
- public void setAddress(Address address) { this.address = address; }
- ...
+ <programlisting role="JAVA"><![CDATA[
+(a)org.jboss.cache.pojo.annotation.Replicable
+public class Person
+{
+ ...
+ public String getName()
+ {
+ return name;
}
+
+ public void setName(String name)
+ {
+ this.name=name;
+ }
+
+ // ...
+
+ public List<String> getLanguages()
+ {
+ return languages;
+ }
+
+ public void setLanguages(List<String> languages)
+ {
+ this.languages = languages;
+ }
+
+ // ...
+
+ public Address getAddress()
+ {
+ return address;
+ }
+
+ public void setAddress(Address address)
+ {
+ this.address = address;
+ }
+
+ // ...
+}
]]></programlisting>
- <programlisting><![CDATA[
- @org.jboss.cache.pojo.annotation.Replicable
- public class Address {
- ...
- public String getStreet() { return street; }
- public void setStreet(String street) { this.street=street; }
- ...
+ <programlisting role="JAVA"><![CDATA[
+(a)org.jboss.cache.pojo.annotation.Replicable
+public class Address
+{
+ // ...
+ public String getStreet()
+ {
+ return street;
}
+ public void setStreet(String street)
+ {
+ this.street=street;
+ }
+ // ...
+}
]]></programlisting>
</section>
@@ -224,8 +258,7 @@
<orderedlist>
<listitem>In the 1st GUI instance, create a POJO, i.e. a Person with an
Address:
- <programlisting><![CDATA[
-
+ <programlisting role="JAVA"><![CDATA[
joe = new Person();
joe.setName("Joe Black");
joe.setAge(31);
@@ -236,31 +269,25 @@
addr.setZip(94086);
joe.setAddress(addr);
-
]]></programlisting>
</listitem>
<listitem>Attach the POJO to the cache:
- <programlisting><![CDATA[
-
+ <programlisting role="JAVA"><![CDATA[
cache.attach("pojo/joe", joe);
-
]]></programlisting>
</listitem>
<listitem>Change attributes of the POJO and see the individual changes
being propagated to the 2nd
cache GUI:
- <programlisting><![CDATA[
-
+ <programlisting role="JAVA"><![CDATA[
joe.setAge(41);
-
]]></programlisting>
</listitem>
<listitem>In the 2nd GUI instance, get a reference to the Person in the
cache and create a second Person
with the existing Person's Address:
- <programlisting><![CDATA[
-
+ <programlisting role="JAVA"><![CDATA[
joe = cache.find("pojo/joe");
mary = new Person();
@@ -268,44 +295,35 @@
mary.setAge(30);
mary.setAddress(joe.getAddress());
-
]]></programlisting>
</listitem>
<listitem>Attach the new POJO to the cache:
- <programlisting><![CDATA[
-
+ <programlisting role="JAVA"><![CDATA[
cache.attach("pojo/mary", mary);
-
]]></programlisting>
</listitem>
<listitem>Now, change either Person's Address and see how the
change applies to both POJOs and has been
propagated to the other cache, visible in the 1st GUI instance:
- <programlisting><![CDATA[
-
+ <programlisting role="JAVA"><![CDATA[
mary.getAddress().setZip(95000);
-
]]></programlisting>
</listitem>
<listitem>Still in the 2nd GUI instance, detach the POJOs from the
cache and see how the POJOs are no longer
visible:
- <programlisting><![CDATA[
-
+ <programlisting role="JAVA"><![CDATA[
cache.detach("pojo/joe");
cache.detach("pojo/mary");
-
]]></programlisting>
</listitem>
<listitem>Finally, in any of GUI instances, change some attributes of
the POJO and see these changes have
no effect in the cache:
- <programlisting><![CDATA[
-
+ <programlisting role="JAVA"><![CDATA[
joe.setName("Joe White");
-
]]></programlisting>
</listitem>
@@ -329,8 +347,7 @@
<orderedlist>
<listitem>In the 1st GUI instance, create a POJO with a Collection
attribute:
- <programlisting><![CDATA[
-
+ <programlisting role="JAVA"><![CDATA[
joe = new Person();
joe.setName("Joe Black");
@@ -338,41 +355,32 @@
lang.add("Spanish");
joe.setLanguages(lang);
-
]]></programlisting>
</listitem>
<listitem>Attach the POJO to the cache:
- <programlisting><![CDATA[
-
+ <programlisting role="JAVA"><![CDATA[
cache.attach("pojo/joe", joe);
-
]]></programlisting>
</listitem>
<listitem>Get a proxy reference to the Collection and add a new element
to it:
- <programlisting><![CDATA[
-
+ <programlisting role="JAVA"><![CDATA[
proxyLang = joe.getLanguages();
- proxyLang.add("English");
-
+ proxyLang.add("English");
]]></programlisting>
</listitem>
<listitem>Detach the pojo from the cache:
- <programlisting><![CDATA[
-
+ <programlisting role="JAVA"><![CDATA[
cache.detach("pojo/joe");
-
]]></programlisting>
</listitem>
<listitem>Use the proxy reference to the Collection to add another
element and see how this does not get
added to the cache:
- <programlisting><![CDATA[
-
+ <programlisting role="JAVA"><![CDATA[
proxyLang.add("French");
-
]]></programlisting>
</listitem>
Modified: pojo/trunk/src/main/docbook/userguide/en/master.xml
===================================================================
--- pojo/trunk/src/main/docbook/userguide/en/master.xml 2008-03-08 11:57:27 UTC (rev
5404)
+++ pojo/trunk/src/main/docbook/userguide/en/master.xml 2008-03-09 21:52:37 UTC (rev
5405)
@@ -75,18 +75,18 @@
inside the available page width. These lines have been broken up. A '\'
at the end of a
line means that a break has been introduced to fit in the page, with the
following lines
indented. So:
+ </para>
<programlisting>
Let's pretend to have an extremely \
long line that \
does not fit
This one is short
</programlisting>
- Is really:
+ <para>Is really:</para>
<programlisting>
Let's pretend to have an extremely long line that does not fit
This one is short
</programlisting>
- </para>
</preface>
Modified: pojo/trunk/src/main/docbook/userguide/en/modules/api.xml
===================================================================
--- pojo/trunk/src/main/docbook/userguide/en/modules/api.xml 2008-03-08 11:57:27 UTC (rev
5404)
+++ pojo/trunk/src/main/docbook/userguide/en/modules/api.xml 2008-03-09 21:52:37 UTC (rev
5405)
@@ -6,39 +6,38 @@
<sect1>
<title>PojoCacheFactory Class</title>
<para>PojoCacheFactory provides a couple of static methods to instantiate and
obtain a PojoCache instance.</para>
-<programlisting>
- /**
- * 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.
- * @return PojoCache
- */
- public static PojoCache createInstance(String config);
+<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.
+ * @return PojoCache
+ */
+public static PojoCache createInstance(String config);
- /**
- * Create a PojoCache instance.
- * @param config A configuration string that represents the file name that is used to
- * configure the underlying Cache instance.
- * @param start If true, it will start the cache life cycle.
- * @return PojoCache
- */
- public static PojoCache createInstance(String config, boolean start);
+/**
+ * Create a PojoCache instance.
+ * @param config A configuration string that represents the file name that is used to
+ * configure the underlying Cache instance.
+ * @param start If true, it will start the cache life cycle.
+ * @return PojoCache
+ */
+public static PojoCache createInstance(String config, boolean start);
- /**
- * Create a PojoCache instance.
- * @param config A configuration object that is used to configure the underlying Cache
instance.
- * @param start If true, it will start the cache life cycle.
- * @return PojoCache
- */
- public static PojoCache createInstance(Configuration config, boolean start);
-</programlisting>
+/**
+ * Create a PojoCache instance.
+ * @param config A configuration object that is used to configure the underlying Cache
instance.
+ * @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:
-<programlisting>
+ we can do:</para>
+<programlisting role="JAVA"><![CDATA[
String configFile = "META-INF/replSync-service.xml";
PojoCache cache = PojoCacheFactory.createInstance(configFile);
-</programlisting>
- </para>
+]]></programlisting>
</sect1>
@@ -53,7 +52,7 @@
<sect2>
<title>Attachment</title>
-<programlisting>
+<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:
@@ -79,7 +78,7 @@
* @throws PojoCacheException Throws if there is an error related to the cache
operation.
*/
Object attach(String id, Object pojo) throws PojoCacheException;
-</programlisting>
+]]></programlisting>
<para>
As described in the above javadoc, this method "attaches" the
passed object to the cache
at the specified location (<literal>id</literal>).
@@ -109,7 +108,7 @@
<sect2>
<title>Detachment</title>
-<programlisting>
+<programlisting role="JAVA"><![CDATA[
/**
* Remove POJO object from the cache.
*
@@ -118,7 +117,7 @@
* @throws PojoCacheException Throws if there is an error related to the cache
operation.
*/
Object detach(String id) throws PojoCacheException;
-</programlisting>
+]]></programlisting>
<para>
This call will detach the POJO from the cache by removing the contents
under <literal>id</literal>
@@ -131,8 +130,7 @@
<sect2>
<title>Query</title>
-<programlisting>
-
+<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.
@@ -142,7 +140,7 @@
* @throws PojoCacheException Throws if there is an error related to the cache
operation.
*/
Object find(String id) throws PojoCacheException;
-</programlisting>
+]]></programlisting>
<para>
This call will
return the current object content located under
@@ -154,7 +152,7 @@
in sync with the underlying cache store.
</para>
-<programlisting>
+<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
@@ -167,7 +165,7 @@
* @throws PojoCacheException Throws if there is an error related to the cache
operation.
*/
Map findAll(String id) throws PojoCacheException;
-</programlisting>
+]]></programlisting>
<para>
This call will return all the managed POJOs under cache with a base Fqn name. It is
recursive, meaning that
Modified: pojo/trunk/src/main/docbook/userguide/en/modules/appendix.xml
===================================================================
--- pojo/trunk/src/main/docbook/userguide/en/modules/appendix.xml 2008-03-08 11:57:27 UTC
(rev 5404)
+++ pojo/trunk/src/main/docbook/userguide/en/modules/appendix.xml 2008-03-09 21:52:37 UTC
(rev 5405)
@@ -15,7 +15,7 @@
) along with the annotation.
</para>
- <programlisting>
+<programlisting role="JAVA"><![CDATA[
@org.jboss.cache.pojo.annotation.Replicable
public class Person {
String name=null;
@@ -42,16 +42,18 @@
public List getLanguages() { return languages; }
public void setLanguages(List languages) { this.languages = languages; }
-}</programlisting>
+}]]></programlisting>
- <programlisting>public class Student extends Person {
+ <programlisting role="JAVA"><![CDATA[
+public class Student extends Person {
String year=null;
public String getYear() { return year; }
public void setYear(String year) { this.year=year; }
-}</programlisting>
+}
+]]></programlisting>
- <programlisting>
+<programlisting role="JAVA"><![CDATA[
@org.jboss.cache.pojo.annotation.Replicable
public class Address {
String street=null;
@@ -60,8 +62,9 @@
public String getStreet() { return street; }
public void setStreet(String street) { this.street=street; }
- ...
-}</programlisting>
+ // ...
+}
+]]></programlisting>
</sect1>
<sect1 id="xml" revision="1">
@@ -70,8 +73,7 @@
<para>
Below is a sample xml configuration for Cache that you can use for PojoCache
creation.
</para>
- <programlisting>
- <![CDATA[
+<programlisting role="XML"><![CDATA[
<?xml version="1.0" encoding="UTF-8" ?>
<server>
@@ -150,8 +152,7 @@
</mbean>
</server>
-]]>
- </programlisting>
+]]></programlisting>
</sect1>
@@ -159,9 +160,9 @@
<sect1 id="xml-pojo" revision="1">
<title>PojoCache configuration xml</title>
<para>Attached is a full listing for
<literal>pojocache-aop.xml</literal>.</para>
-<programlisting>
- <?xml version="1.0" encoding="UTF-8"?>
- <!--
+<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)
@@ -173,137 +174,137 @@
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.
- -->
- <aop>
+ -->
+ <aop>
- <!--
+ <!--
This defines the PojoCache 2.0 interceptor stack. Unless necessary, don't
modify the stack here!
- -->
+ -->
- <!-- Check id range validity -->
- <interceptor name="CheckId"
class="org.jboss.cache.pojo.interceptors.CheckIdInterceptor"
- scope="PER_INSTANCE"/>
+ <!-- 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"/>
+ <!-- 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"/>
+ <!-- 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"/>
+ <!-- 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"/>
+ -->
+ <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"/>
+ <!-- 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 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"/>
+ <!-- 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"
+ <!-- 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>
+ 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>
+ <!-- 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="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>
+ <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>
+ <!-- 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.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.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.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>
+ <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;*)" />
+ <!-- If a POJO has PojoCachable annotation, it will be asepctized. -->
+ <prepare expr="field(*
$instanceof{(a)org.jboss.cache.pojo.annotation.Replicable}->*)" />
- <!-- 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>
+ <!-- Observer and Observable to monitor field modification -->
+ <bind pointcut="
+ set(* $instanceof{(a)org.jboss.cache.pojo.annotation.Replicable}->*)
+ ">
+ <interceptor
class="org.jboss.cache.pojo.observable.SubjectInterceptor"/>
+ </bind>
- <introduction
class="$instanceof{(a)org.jboss.cache.pojo.annotation.Replicable}"&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>
+ <introduction
class="$instanceof{(a)org.jboss.cache.pojo.annotation.Replicable}">
+ <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>
-</programlisting>
+]]></programlisting>
</sect1>
</chapter>
Modified: pojo/trunk/src/main/docbook/userguide/en/modules/architecture.xml
===================================================================
--- pojo/trunk/src/main/docbook/userguide/en/modules/architecture.xml 2008-03-08 11:57:27
UTC (rev 5404)
+++ pojo/trunk/src/main/docbook/userguide/en/modules/architecture.xml 2008-03-09 21:52:37
UTC (rev 5405)
@@ -26,69 +26,69 @@
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>
- <!-- Check id range validity -->
- <interceptor name="CheckId"
class="org.jboss.cache.pojo.interceptors.CheckIdInterceptor"
- scope="PER_INSTANCE"/>
+<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"/>
+ <!-- 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"/>
+ <!-- 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"/>
+ <!-- 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"/>
+ -->
+ <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"/>
+ <!-- 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 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"/>
+ <!-- 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>
+ <!-- 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="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="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>
+ <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
@@ -171,7 +171,7 @@
<para>In the following code snippet, we show programmatically the object
sharing example.
</para>
-<programlisting>
+<programlisting role="JAVA"><![CDATA[
import org.jboss.cache.pojo.PojoCache;
import org.jboss.cache.pojo.PojoCacheFactory;
import org.jboss.test.cache.test.standAloneAop.Person;
@@ -204,7 +204,7 @@
cache.detach("pojo/joe");
maryAddr = mary.getAddress(); // Should still have the address.
-</programlisting>
+]]></programlisting>
<para>If
<literal>joe</literal>
@@ -223,7 +223,7 @@
Here is the code
snippet for <literal>cache2</literal> (assume the objects were
already attached):
</para>
-<programlisting>
+<programlisting role="JAVA"><![CDATA[
/**
* Code snippet on cache2 during fail-over
*/
@@ -243,7 +243,7 @@
maryAddr = mary.getAddress().setZip(95123);
int zip = joeAddr.getAddress().getZip(); // Should be 95123 as well instead of 94086!
-</programlisting>
+]]></programlisting>
</sect1>
<sect1>
@@ -268,7 +268,7 @@
behavior of a POJO is maintained. Again, no special configuration is
needed.</para>
-<programlisting>
+<programlisting role="JAVA"><![CDATA[
import org.jboss.test.cache.test.standAloneAop.Student;
Student joe = new Student(); // Student extends Person class
@@ -284,7 +284,7 @@
Person person = (Person)joe; // it will be correct here
joe.setYear("Junior"); // will be intercepted by the cache
joe.setName("Joe Black II"); // also intercepted by the cache
-</programlisting>
+]]></programlisting>
</sect1>
<sect1>
@@ -426,7 +426,7 @@
<para>The following code snippet illustrates obtaining a direct Collection
proxy reference:
</para>
-<programlisting>
+<programlisting role="JAVA"><![CDATA[
List list = new ArrayList();
list.add("ONE");
list.add("TWO");
@@ -436,29 +436,30 @@
List proxyList = cache.find("pojo/list"; // Note that list is a proxy
reference
proxyList.add("FOUR"); // This will be intercepted by the cache
-</programlisting>
+]]></programlisting>
<para>
This snippet illustrates obtaining the proxy reference from a refering
object:
</para>
-<programlisting>
+<programlisting role="JAVA"><![CDATA[
Person joe = new Person();
joe.setName("Joe Black"); // This is base class attributes
List lang = new ArrayList();
lang.add("English");
lang.add("Mandarin");
joe.setLanguages(lang);
+
// This will map the languages List automatically and swap it out with the proxy
reference.
cache.attach("pojo/student/joe", joe);
lang = joe.getLanguages(); // Note that lang is now a proxy reference
lang.add("French"); // This will be intercepted by the cache
-</programlisting>
+]]></programlisting>
<para>
Finally, when a Collection is removed from the cache (e.g., via
<literal>detach</literal>),
you still can use the proxy reference. POJO Cache will just redirect the
call back to the in-memory copy. See below:
</para>
-<programlisting>
+<programlisting role="JAVA"><![CDATA[
List list = new ArrayList();
list.add("ONE");
list.add("TWO");
@@ -469,7 +470,7 @@
cache.detach("pojo/list"); // detach from the cache
proxyList.add("FOUR"); // proxyList has 4 elements still.
-</programlisting>
+]]></programlisting>
<sect2>
<title>Limitations</title>
<para>The current implementation has the following
Modified: pojo/trunk/src/main/docbook/userguide/en/modules/configuration.xml
===================================================================
--- pojo/trunk/src/main/docbook/userguide/en/modules/configuration.xml 2008-03-08 11:57:27
UTC (rev 5404)
+++ pojo/trunk/src/main/docbook/userguide/en/modules/configuration.xml 2008-03-09 21:52:37
UTC (rev 5405)
@@ -38,9 +38,8 @@
<para>
Below is a snippet from a cache configuration xml
illustrating how the eviction policy along with cache loader can be configured.
Please note that this is
- simply an aspect of the underlying Cache. That is, PojoCache layer is agnostic
to this behavior.
-<programlisting>
- <![CDATA[
+ simply an aspect of the underlying Cache. That is, PojoCache layer is agnostic
to this behavior.</para>
+<programlisting role="XML"><![CDATA[
<attribute name="EvictionPolicyConfig">
<config>
<attribute name="wakeUpIntervalSeconds">5</attribute>
@@ -72,9 +71,7 @@
</cacheloader>
</config>
</attribute>
-]]>
-</programlisting>
- </para>
+]]></programlisting>
<para>Another way to support multiple regions in eviction is to use
region-based marshalling.
See the "Architecture" chapter in the JBoss Cache User Guide for more
information on region-based marshalling.
When the Cache uses region-based marshalling, POJO Cache will store internal node
data on the region that is
@@ -158,16 +155,14 @@
the cache:
</para>
- <programlisting>
- <![CDATA[
- MBeanServer server = MBeanServerLocator.locateJBoss();
- ObjectName on = new ObjectName("jboss.cache:service=PojoCache");
- PojoCacheJmxWrapperMBean cacheWrapper =
- (PojoCacheJmxWrapperMBean) MBeanServerInvocationHandler.newProxyInstance(server,
on,
- PojoCacheJmxWrapperMBean.class, false);
- PojoCache cache = cacheWrapper.getPojoCache();
- ]]>
- </programlisting>
+ <programlisting role="JAVA"><![CDATA[
+ MBeanServer server = MBeanServerLocator.locateJBoss();
+ ObjectName on = new ObjectName("jboss.cache:service=PojoCache");
+ PojoCacheJmxWrapperMBean cacheWrapper =
+ (PojoCacheJmxWrapperMBean) MBeanServerInvocationHandler.newProxyInstance(server,
on,
+ PojoCacheJmxWrapperMBean.class, false);
+ PojoCache cache = cacheWrapper.getPojoCache();
+ ]]></programlisting>
<para>The MBeanServerLocator class is a helper to find the (only) JBoss
MBean server inside the current JVM. The
@@ -220,8 +215,7 @@
installation, you can find several more examples.
</para>
- <programlisting>
- <![CDATA[
+ <programlisting role="XML"><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<deployment xmlns="urn:jboss:bean-deployer:2.0">
@@ -246,8 +240,7 @@
</bean>
</deployment>
-]]>
- </programlisting>
+]]></programlisting>
<para>
An interesting thing to note in the above example is the difference
@@ -320,30 +313,30 @@
and pass it to the <literal>PojoCacheJmxWrapper</literal>
constructor.
</para>
- <programlisting>
- // Build but don't start the cache
- // (although it would work OK if we started it)
- PojoCache cache =
PojoCacheFactory.createCache("cache-configuration.xml", false);
-
- PojoCacheJmxWrapperMBean wrapper = new PojoCacheJmxWrapper(cache);
- MBeanServer server = getMBeanServer(); // however you do it
- ObjectName on = new ObjectName("jboss.cache:service=PojoCache");
- server.registerMBean(wrapper, on);
-
- // Invoking lifecycle methods on the wrapper results
- // in a call through to the cache
- wrapper.create();
- wrapper.start();
-
- ... use the cache
-
- ... on application shutdown
-
- // Invoking lifecycle methods on the wrapper results
- // in a call through to the cache
- wrapper.stop();
- wrapper.destroy();
- </programlisting>
+ <programlisting role="JAVA"><![CDATA[
+ // Build but don't start the cache
+ // (although it would work OK if we started it)
+ PojoCache cache = PojoCacheFactory.createCache("cache-configuration.xml",
false);
+
+ PojoCacheJmxWrapperMBean wrapper = new PojoCacheJmxWrapper(cache);
+ MBeanServer server = getMBeanServer(); // however you do it
+ ObjectName on = new ObjectName("jboss.cache:service=PojoCache");
+ server.registerMBean(wrapper, on);
+
+ // Invoking lifecycle methods on the wrapper results
+ // in a call through to the cache
+ wrapper.create();
+ wrapper.start();
+
+ ... use the cache
+
+ ... on application shutdown
+
+ // Invoking lifecycle methods on the wrapper results
+ // in a call through to the cache
+ wrapper.stop();
+ wrapper.destroy();
+ ]]></programlisting>
<para>
Alternatively, build a <literal>Configuration</literal> object
@@ -351,29 +344,28 @@
will construct the <literal>PojoCache</literal>:
</para>
- <programlisting>
- Configuration config = buildConfiguration(); // whatever it does
-
- PojoCacheJmxWrapperMBean wrapper = new PojoCacheJmxWrapper(config);
- MBeanServer server = getMBeanServer(); // however you do it
- ObjectName on = new ObjectName("jboss.cache:service=TreeCache");
- server.registerMBean(wrapper, on);
-
- // Call to wrapper.create() will build the Cache if one wasn't injected
- wrapper.create();
- wrapper.start();
-
- // Now that it's built, created and started, get the cache from the
wrapper
- PojoCache cache = wrapper.getPojoCache();
-
- ... use the cache
-
- ... on application shutdown
-
- wrapper.stop();
- wrapper.destroy();
-
- </programlisting>
+<programlisting role="JAVA"><![CDATA[
+ Configuration config = buildConfiguration(); // whatever it does
+
+ PojoCacheJmxWrapperMBean wrapper = new PojoCacheJmxWrapper(config);
+ MBeanServer server = getMBeanServer(); // however you do it
+ ObjectName on = new ObjectName("jboss.cache:service=TreeCache");
+ server.registerMBean(wrapper, on);
+
+ // Call to wrapper.create() will build the Cache if one wasn't injected
+ wrapper.create();
+ wrapper.start();
+
+ // Now that it's built, created and started, get the cache from the wrapper
+ PojoCache cache = wrapper.getPojoCache();
+
+ // ... use the cache
+
+ // ... on application shutdown
+
+ wrapper.stop();
+ wrapper.destroy();
+ ]]></programlisting>
</section>
<section>
@@ -399,8 +391,7 @@
annotation on the <literal>PojoCacheJmxWrapper</literal> bean:
</para>
- <programlisting>
- <![CDATA[
+<programlisting role="XML"><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<deployment xmlns="urn:jboss:bean-deployer:2.0">
@@ -440,8 +431,7 @@
</bean>
</deployment>
-]]>
- </programlisting>
+]]></programlisting>
<para>
As discussed in the <link
linkend="jmx.registration.programatic">Programatic Registration</link>
@@ -449,8 +439,7 @@
creating and starting the PojoCache if it is provided with a
<literal>Configuration</literal>:
</para>
- <programlisting>
- <![CDATA[
+ <programlisting role="XML"><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<deployment xmlns="urn:jboss:bean-deployer:2.0">
@@ -478,8 +467,7 @@
</bean>
</deployment>
-]]>
- </programlisting>
+]]></programlisting>
</section>
</section>
Modified: pojo/trunk/src/main/docbook/userguide/en/modules/instrumentation.xml
===================================================================
--- pojo/trunk/src/main/docbook/userguide/en/modules/instrumentation.xml 2008-03-08
11:57:27 UTC (rev 5404)
+++ pojo/trunk/src/main/docbook/userguide/en/modules/instrumentation.xml 2008-03-09
21:52:37 UTC (rev 5405)
@@ -52,11 +52,13 @@
<para>These requirements lead to the following example ant task:</para>
- <programlisting><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> </programlisting>
+ <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>
+]]></programlisting>
<para>Once the JVM is executed in this manner, any class with the
<literal>@Replicable</literal> annotation will be instrumented when it
is
@@ -86,16 +88,18 @@
<para>The following is an example ant task which performs compile-time
instrumentation:</para>
- <para><programlisting><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>In this example, once the aopc
target
+ <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>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>
@@ -113,7 +117,9 @@
which matches any class (or subclass) using the annotation. This is shown
in the following snippet:</para>
- <programlisting><prepare expr="field(*
$instanceof{(a)org.jboss.cache.pojo.annotation.Replicable}-&gt;*)"/&gt;
</programlisting>
+ <programlisting role="XML"><![CDATA[
+<prepare expr="field(*
$instanceof{(a)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
@@ -145,11 +151,12 @@
<literal>pojocache-aop.xml</literal> under the
<literal>resources</literal> directory. For reference, here is
annotation definition from <literal>pojocache-aop.xml</literal> again
:
- <programlisting>
- <aop> <prepare expr="field(*
- @org.jboss.cache.pojo.annotation.Replicable->*)"
- /> </aop>
- </programlisting> Basically, it simply states that any annotation
+ </para>
+ <programlisting role="XML"><![CDATA[
+<aop>
+ <prepare
expr="field(*(a)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>
@@ -158,10 +165,10 @@
- <programlisting>
- @org.jboss.cache.pojo.annotation.Replicable public class
- Person {...}
- </programlisting>
+ <programlisting role="JAVA"><![CDATA[
+(a)org.jboss.cache.pojo.annotation.Replicable public class
+Person {...}
+ ]]></programlisting>
The above declaration will instrument the class
@@ -196,34 +203,42 @@
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: <programlisting>
- 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> Then when we do: <programlisting>
- Gadget gadget = new Gadget(); Resource resource =
- new Resource(); SepcialAddress specialAddress = new
- SpecialAddress();
+ annotations. Assuming that you have a Gadget class: </para>
+ <programlisting role="JAVA"><![CDATA[
+public class Gadget
+{
+ // resource won't be replicated
+ @Transient
+ Resource resource;
- // setters gadget.setResource(resource);
- gadget.setSpecialAddress(specialAddress);
+ // specialAddress is treated as a Serializable object but still has object
relationship
+ @Serializable
+ SpecialAddress specialAddress;
- cache1.putObject("/gadget", gadget); // put into
- PojoCache management
+ // 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();
- Gadget g2 = (Gadget)cache2.getObject("/gadget"); //
- retrieve it from another cache instance
- g2.getResource(); // This is should be null because
- of @Transient tag so it is not replicated.
+ // setters
+ gadget.setResource(resource);
+ gadget.setSpecialAddress(specialAddress);
- SepcialAddress d2 = g2.getSpecialAddress();
- d2.setName("inet"); // This won't get replicated
- automatically because of @Serializable tag
- ge.setSpecialAddress(d2); // Now this will.
- </programlisting></para>
+ // 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>
@@ -240,14 +255,17 @@
<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.
- <programlisting>
- <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></para>
+ </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>
<sect2>
<title>Ant target for running load-time instrumentation using
@@ -255,23 +273,21 @@
<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. <programlisting>
- <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></para>
+ <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>
@@ -281,20 +297,18 @@
target. Running this target will do compile-time weaving of the POJO
classes specified.</para>
- <programlisting>
- <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>
+ <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
Modified: pojo/trunk/src/main/docbook/userguide/en/modules/introduction.xml
===================================================================
--- pojo/trunk/src/main/docbook/userguide/en/modules/introduction.xml 2008-03-08 11:57:27
UTC (rev 5404)
+++ pojo/trunk/src/main/docbook/userguide/en/modules/introduction.xml 2008-03-09 21:52:37
UTC (rev 5405)
@@ -14,23 +14,30 @@
of attributes. This map-like API is intuitive and easy to use for caching data,
but just like the
Java Collection API, it operates only off of simple and serializable types.
Therefore, it has the following constraints:
+ </para>
<itemizedlist>
<listitem>If replication or persistence is needed, the object will then
need to
implement the <literal>Serializable</literal> interface. E.g.,
- <programlisting>public Class Foo implements
Serializable</programlisting>
+ <programlisting role="JAVA"><![CDATA[
+public Class Foo implements Serializable
+]]></programlisting>
</listitem>
<listitem>If the object is mutable, any field change will require a
successive put operation on the cache:
-<programlisting>value = new Foo();
+<programlisting role="JAVA"><![CDATA[
+value = new Foo();
cache.put(fqn, key, value);
value.update(); // update value
-cache.put(fqn, key, value); // Need to repeat this step again to ask cache to persist or
replicate the changes</programlisting>
+cache.put(fqn, key, value); // Need to repeat this step again to ask cache to persist or
replicate the changes
+]]></programlisting>
</listitem>
<listitem>Java serialization always writes the entire object, even if
only one field was changed. Therefore, large objects
can have significant overhead, especially if they are updated
frequently:
-<programlisting>thousand = new ThousandFieldObject();
+<programlisting role="JAVA"><![CDATA[
+thousand = new ThousandFieldObject();
cache.put(fqn, key, thousand);
thousand.setField1("blah"); // Only one field was modified
-cache.put(fqn, key, thousand); // Replicates 1000 fields</programlisting>
+cache.put(fqn, key, thousand); // Replicates 1000 fields
+]]></programlisting>
</listitem>
<listitem>The object structure can not have a graph relationship. That
is, the object can not have
references to objects that are shared (multiple
@@ -46,18 +53,19 @@
<literal>Address</literal>
instances (instead of just one). The following is the code snippet using
Cache that illustrates this
problem:
-<programlisting>joe = new Person("joe");
+<programlisting role="JAVA"><![CDATA[
+joe = new Person("joe");
mary = new Person("mary");
addr = new Address("Taipei");
joe.setAddress(addr);
mary.setAddress(addr);
cache.put("/joe", "person", joe);
cache.put("/mary", "person", mary);
-</programlisting>
+]]></programlisting>
</listitem>
</itemizedlist>
- </para>
+
<figure>
<title>Illustration of shared objects problem during
replication</title>
@@ -71,7 +79,7 @@
<para>POJO Cache attempts to address these issues by building a layer on top
of Core Cache which transparently maps
normal Java object model operations to individual Node operations on the cache.
- This offers the following improvements:
+ This offers the following improvements:</para>
<itemizedlist>
<listitem>Objects do not need to implement
<literal>Serializable</literal> interface. Instead they are instrumented,
allowing POJO Cache to intercept individual operations.</listitem>
@@ -79,13 +87,13 @@
<listitem>Object identity is preserved, so graphs and cyclical
references are allowed.</listitem>
<listitem>Once attached to the cache, all subsequent object operationis
will trigger a cache operation (like replication)
automatically:
-<programlisting>POJO pojo = new POJO();
+<programlisting role="JAVA"><![CDATA[
+POJO pojo = new POJO();
pojoCache.attach("id", pojo);
pojo.setName("some pojo"); // This will trigger replication automatically.
-</programlisting>
+]]></programlisting>
</listitem>
</itemizedlist>
- </para>
<para>
In POJO Cache, these are the typical development and programming steps:
@@ -129,16 +137,17 @@
</listitem>
<listitem>
- <para>Transactions. All attached objects participate in a user
transaction context.
+ Transactions. All attached objects participate in a user transaction
context.
If a rollback occurs, the previous internal field state of the object will
be restored:
-<programlisting>POJO p = new POJO();
+<programlisting role="JAVA"><![CDATA[
+POJO p = new POJO();
p.setName("old value");
pojoCache.attach("id", p);
tx.begin(); // start a user transaction
p.setName("some pojo");
tx.rollback(); // this will cause the rollback
p.getName(); // is "old value"
-</programlisting></para>
+]]></programlisting>
<para>In addition, operations under a transaction is batched. That is,
the update is not performed until the <literal>commit</literal>
phase. Further, if replication is enabled, other nodes will not see the changes until the
transaction has completed successfully. </para>
</listitem>
@@ -208,16 +217,16 @@
<para>
To use POJO Cache, you obtain the instance from the PojoCacheFactory by
supplying a config file that is used
by the delegating Cache implementation. Once the PojoCache instance is obtained,
you can call the cache life
- cycle method to start the cache. Below is a code snippet that creates and starts
the cache:
-<programlisting>String configFile = "replSync-service.xml";
+ cycle method to start the cache. Below is a code snippet that creates and starts
the cache:</para>
+<programlisting role="JAVA"><![CDATA[
+String configFile = "replSync-service.xml";
boolean toStart = false;
PojoCache pcache = PojoCacheFactory.createCache(configFiel, toStart);
pcache.start(); // if toStart above is true, it will starts the cache automatically.
pcache.attach(id, pojo);
-...
+// ...
pcache.stop(); // stop the cache. This will take PojoCache out of the clustering group,
if any, e.g.
-</programlisting>
- </para>
+]]></programlisting>
</sect1>
<sect1 id="4">
<title>Requirements</title>