7:19 p.m.
Author: jason.greene(a)jboss.com
Date: 2008-03-11 19:19:01 -0400 (Tue, 11 Mar 2008)
New Revision: 5416
Modified:
pojo/branches/2.1/pom.xml
pojo/branches/2.1/src/main/docbook/faq/en/master.xml
pojo/branches/2.1/src/main/docbook/tutorial/en/master.xml
pojo/branches/2.1/src/main/docbook/userguide/en/master.xml
pojo/branches/2.1/src/main/docbook/userguide/en/modules/api.xml
pojo/branches/2.1/src/main/docbook/userguide/en/modules/appendix.xml
pojo/branches/2.1/src/main/docbook/userguide/en/modules/architecture.xml
pojo/branches/2.1/src/main/docbook/userguide/en/modules/configuration.xml
pojo/branches/2.1/src/main/docbook/userguide/en/modules/instrumentation.xml
pojo/branches/2.1/src/main/docbook/userguide/en/modules/introduction.xml
Log:
Merge docbook changes
Modified: pojo/branches/2.1/pom.xml
===================================================================
--- pojo/branches/2.1/pom.xml 2008-03-11 23:10:40 UTC (rev 5415)
+++ pojo/branches/2.1/pom.xml 2008-03-11 23:19:01 UTC (rev 5416)
@@ -147,12 +147,33 @@
<version>2.0.0</version>
<extensions>true</extensions>
<dependencies>
- <dependency>
- <groupId>org.jboss.cache</groupId>
- <artifactId>jbosscache-doc-xslt-support</artifactId>
- <version>1.0</version>
- </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-->
@@ -176,20 +197,20 @@
<formats>
<format>
<formatName>pdf</formatName>
-
<stylesheetResource>classpath:/standard/fopdf.xsl</stylesheetResource>
+
<stylesheetResource>classpath:/xslt/org/jboss/main-pdf.xsl</stylesheetResource>
<finalName>userguide_en.pdf</finalName>
</format>
- <format>
- <formatName>html</formatName>
-
<stylesheetResource>classpath:/standard/html_chunk.xsl</stylesheetResource>
- <finalName>index.html</finalName>
- </format>
- <format>
- <formatName>html_single</formatName>
-
<stylesheetResource>classpath:/standard/html.xsl</stylesheetResource>
- <finalName>index.html</finalName>
- </format>
- </formats>
+ <format>
+ <formatName>html</formatName>
+
<stylesheetResource>classpath:/xslt/org/jboss/main-html.xsl</stylesheetResource>
+ <finalName>index.html</finalName>
+ </format>
+ <format>
+ <formatName>html_single</formatName>
+
<stylesheetResource>classpath:/xslt/org/jboss/nochunk-html.xsl</stylesheetResource>
+ <finalName>index.html</finalName>
+ </format>
+ </formats>
<options>
<xincludeSupported>false</xincludeSupported>
</options>
@@ -217,19 +238,19 @@
<formats>
<format>
<formatName>pdf</formatName>
-
<stylesheetResource>classpath:/standard/fopdf.xsl</stylesheetResource>
+
<stylesheetResource>classpath:/xslt/org/jboss/main-pdf.xsl</stylesheetResource>
<finalName>tutorial_en.pdf</finalName>
</format>
- <format>
- <formatName>html</formatName>
-
<stylesheetResource>classpath:/standard/html_chunk.xsl</stylesheetResource>
- <finalName>index.html</finalName>
- </format>
- <format>
- <formatName>html_single</formatName>
-
<stylesheetResource>classpath:/standard/html.xsl</stylesheetResource>
- <finalName>index.html</finalName>
- </format>
+ <format>
+ <formatName>html</formatName>
+
<stylesheetResource>classpath:/xslt/org/jboss/main-html.xsl</stylesheetResource>
+ <finalName>index.html</finalName>
+ </format>
+ <format>
+ <formatName>html_single</formatName>
+
<stylesheetResource>classpath:/xslt/org/jboss/nochunk-html.xsl</stylesheetResource>
+ <finalName>index.html</finalName>
+ </format>
</formats>
<options>
<xincludeSupported>false</xincludeSupported>
@@ -258,19 +279,19 @@
<formats>
<format>
<formatName>pdf</formatName>
-
<stylesheetResource>classpath:/standard/fopdf.xsl</stylesheetResource>
+
<stylesheetResource>classpath:/xslt/org/jboss/main-pdf.xsl</stylesheetResource>
<finalName>faq_en.pdf</finalName>
</format>
- <format>
- <formatName>html</formatName>
-
<stylesheetResource>classpath:/standard/html_chunk.xsl</stylesheetResource>
- <finalName>index.html</finalName>
- </format>
- <format>
- <formatName>html_single</formatName>
-
<stylesheetResource>classpath:/standard/html.xsl</stylesheetResource>
- <finalName>index.html</finalName>
- </format>
+ <format>
+ <formatName>html</formatName>
+
<stylesheetResource>classpath:/xslt/org/jboss/main-html.xsl</stylesheetResource>
+ <finalName>index.html</finalName>
+ </format>
+ <format>
+ <formatName>html_single</formatName>
+
<stylesheetResource>classpath:/xslt/org/jboss/nochunk-html.xsl</stylesheetResource>
+ <finalName>index.html</finalName>
+ </format>
</formats>
<options>
<xincludeSupported>false</xincludeSupported>
Modified: pojo/branches/2.1/src/main/docbook/faq/en/master.xml
===================================================================
--- pojo/branches/2.1/src/main/docbook/faq/en/master.xml 2008-03-11 23:10:40 UTC (rev
5415)
+++ pojo/branches/2.1/src/main/docbook/faq/en/master.xml 2008-03-11 23:19:01 UTC (rev
5416)
@@ -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/branches/2.1/src/main/docbook/tutorial/en/master.xml
===================================================================
--- pojo/branches/2.1/src/main/docbook/tutorial/en/master.xml 2008-03-11 23:10:40 UTC (rev
5415)
+++ pojo/branches/2.1/src/main/docbook/tutorial/en/master.xml 2008-03-11 23:19:01 UTC (rev
5416)
@@ -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/branches/2.1/src/main/docbook/userguide/en/master.xml
===================================================================
--- pojo/branches/2.1/src/main/docbook/userguide/en/master.xml 2008-03-11 23:10:40 UTC
(rev 5415)
+++ pojo/branches/2.1/src/main/docbook/userguide/en/master.xml 2008-03-11 23:19:01 UTC
(rev 5416)
@@ -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/branches/2.1/src/main/docbook/userguide/en/modules/api.xml
===================================================================
--- pojo/branches/2.1/src/main/docbook/userguide/en/modules/api.xml 2008-03-11 23:10:40
UTC (rev 5415)
+++ pojo/branches/2.1/src/main/docbook/userguide/en/modules/api.xml 2008-03-11 23:19:01
UTC (rev 5416)
@@ -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/branches/2.1/src/main/docbook/userguide/en/modules/appendix.xml
===================================================================
--- pojo/branches/2.1/src/main/docbook/userguide/en/modules/appendix.xml 2008-03-11
23:10:40 UTC (rev 5415)
+++ pojo/branches/2.1/src/main/docbook/userguide/en/modules/appendix.xml 2008-03-11
23:19:01 UTC (rev 5416)
@@ -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/branches/2.1/src/main/docbook/userguide/en/modules/architecture.xml
===================================================================
--- pojo/branches/2.1/src/main/docbook/userguide/en/modules/architecture.xml 2008-03-11
23:10:40 UTC (rev 5415)
+++ pojo/branches/2.1/src/main/docbook/userguide/en/modules/architecture.xml 2008-03-11
23:19:01 UTC (rev 5416)
@@ -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/branches/2.1/src/main/docbook/userguide/en/modules/configuration.xml
===================================================================
--- pojo/branches/2.1/src/main/docbook/userguide/en/modules/configuration.xml 2008-03-11
23:10:40 UTC (rev 5415)
+++ pojo/branches/2.1/src/main/docbook/userguide/en/modules/configuration.xml 2008-03-11
23:19:01 UTC (rev 5416)
@@ -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/branches/2.1/src/main/docbook/userguide/en/modules/instrumentation.xml
===================================================================
--- pojo/branches/2.1/src/main/docbook/userguide/en/modules/instrumentation.xml 2008-03-11
23:10:40 UTC (rev 5415)
+++ pojo/branches/2.1/src/main/docbook/userguide/en/modules/instrumentation.xml 2008-03-11
23:19:01 UTC (rev 5416)
@@ -1,320 +1,328 @@
+<?xml version="1.0" encoding="UTF-8"?>
<chapter id="instrumentation">
+ <title>Instrumentation</title>
- <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 this chapter, we explain how to instrument (or
"aspectize") the
- POJOs via JBoss Aop. There are two steps needed by JBoss Aop: 1) POJO
- declaration, 2) instrumentation. But depends on the instrumentation
- mode that you are using, you may not need to pre-process your POJO at all. That
is,
- if you use JDK5.0 (required) and load-time mode, then all you need to do is
- annotating your POJO (or declare it in a xml file). This makes your PojoCache
- programming nearly transparent.</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>For the first step, since we are using the dynamic Aop feature, a
- POJO is only required to be declared "prepare". Basically, there are
two
- ways to do this: either via explicit xml or annotation.</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>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). Reader can read the JBoss Aop introduction chapter for more
details.</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>
+ </note>
- <sect1>
- <title>XML descriptor</title>
+ <sect1>
+ <title>Load-time instrumentation</title>
- <para>To declare a POJO via XML configuration file, you will need a
- <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 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
- <literal>aopc</literal>
- such that you won't need the XML file during load time. JBoss Aop
- provides a so-called
- <literal>pointcut</literal>
- language where it
- consists of a regular expression set to specify the interception
- points (or
- <literal>jointpoint</literal>
- in aop parlance). The
- jointpoint can be constructor, method call, or field. You will need to
- declare any of your POJO to be "prepared" so that AOP framework
knows
- to start intercepting either method, field, or constructor invocations
- using the dynamic Aop.
- </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>
- <para>For PojoCache, we only allow all the
- fields (both read and write) to be intercepted. That is, we don't
care
- for the method level interception since it is the state that we are
- interested in. So you should
- only need to change your POJO class name. For details of the pointcut
- language, please refer to JBoss Aop.</para>
+ <orderedlist>
+ <listitem>
+ <para>The <literal>jboss.aop.path</literal> system property set
to the
+ location of <literal>pojocache-aop.xml</literal></para>
+ </listitem>
- <para>The standalone
- <literal>JBoss Cache</literal>
- distribution
- package provides an example declaration for the tutorial classes,
- namely,
- <literal>Person</literal>
- and
- <literal>Address</literal>
- .
- Detailed class declaration for
- <literal>Person</literal>
- and
- <literal>Address</literal>
- are provided in the Appendix section. But here
- is the snippet for
- <literal>pojocache-aop.xml</literal>
- :
- </para>
+ <listitem>
+ <para>A javaagent argument which includes
+ <emphasis>jboss-aop-jdk50.jar</emphasis></para>
+ </listitem>
+ </orderedlist>
-<programlisting>
-<aop>
- <prepare expr="field(*
$instanceof{(a)org.jboss.cache.pojo.annotation.Replicable}-&gt;*)" />
-</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>These requirements lead to the following example ant task:</para>
+ <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>Detailed semantics of
- <literal>pojocache-aop.xml</literal> (or equivalently
<literal>pojocache-aop.xml</literal>)
- can again
- be found in JBoss Aop. But above statements basically declare all field
- read and write operations in classes
- <code>Address</code>
- and
- <code>Person</code>
- will be "prepared" (or "aspectized"). Note
- that:
- </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>
- <itemizedlist>
- <listitem>
- The wildcard at the end of the expression signifies all fields in the
POJO
- </listitem>
+ <sect1>
+ <title>Compile-time instrumentation</title>
- <listitem>
- You can potentially replace specific class name with wildcard that
includes all the POJOs inside the
- same package space
- </listitem>
+ <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>
- <listitem>
- The
+ <orderedlist>
+ <listitem>
+ <para>The <literal>aoppath</literal> option must point to the
location
+ of pojocache-aop.xml</para>
+ </listitem>
- <code>instanceof</code>
+ <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>
+ </listitem>
+ </orderedlist>
- operator declares any sub-type or sub-class of the specific POJO will
also be "aspectized". For
- example, if a
- <code>Student</code>
- class is a subclass of
- <code>Person</code>
- , JBossAop will automatically instrument it as well!
- </listitem>
+ <para>The following is an example ant task which performs compile-time
+ instrumentation:</para>
- <listitem>
- We intercept the field of all access levels (i.e.,
- <literal>private</literal>
- ,
- <literal>protected</literal>
- ,
- <literal>public</literal>
- , etc.) The main reason being that we consider all fields as stateful
data. However, we can relax this
- requirement in the future if there is a use case for it.
- </listitem>
+ <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>
+ </sect1>
- <listitem>
- We don't intercept field modifiers of
- <literal>final</literal>
- 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.,
- transient.
- </listitem>
- </itemizedlist>
- </sect1>
+ <sect1>
+ <title>Understanding the provided AOP descriptor</title>
- <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>
+ <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>
- <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
- :
-<programlisting>
-<aop>
- <prepare expr="field(*
@org.jboss.cache.pojo.annotation.Replicable->*)" />
-</aop>
-</programlisting>
- Basically, it simply states that any annotation
- with both marker interfaces will be "aspectized" accordingly.
- </para>
+ <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
+ 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>
- <para>Here is a code snippet that illustrate the
declaration:</para>
-<programlisting>
-(a)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>
+ <sect1>
+ <title>Annotation</title>
- <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>(a)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>(a)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:
-<programlisting>
+ <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>
+ <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>
+
+
+
+ <para>Here is a code snippet that illustrate the declaration:</para>
+
+
+
+ <programlisting role="JAVA"><![CDATA[
+(a)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>(a)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;
+ @Transient
+ Resource resource;
+
// specialAddress is treated as a Serializable object but still has object
relationship
- @Serializable SpecialAddress specialAddress;
+ @Serializable
+ SpecialAddress specialAddress;
+
// other state variables
}
-</programlisting>
- Then when we do:
-<programlisting>
+ ]]></programlisting><para>Then when we
do:</para><programlisting role="JAVA"><![CDATA[
Gadget gadget = new Gadget();
Resource resource = new Resource();
- SepcialAddress specialAddress = new SpecialAddress();
+ SpecialAddress specialAddress = new SpecialAddress();
// setters
gadget.setResource(resource);
gadget.setSpecialAddress(specialAddress);
- cache1.putObject("/gadget", gadget); // put into PojoCache management
+ // put into PojoCache management
+ cache1.putObject("/gadget", gadget);
- 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.
+ // 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>
- </para>
- </sect2>
+ ]]></programlisting>
+ </sect2>
+ </sect1>
- </sect1>
+ <sect1>
+ <title>Weaving</title>
- <sect1>
- <title>Weaving</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>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>
- 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>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>
- <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.
-<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>
- </sect2>
+ <sect2>
+ <title>Ant target for running load-time instrumentation using
+ specialized class loader</title>
- <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>
- <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>
+ <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>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/classes.png"/>
- </imageobject>
- </mediaobject>
- </figure>
+ <sect2>
+ <title>Ant target for aopc</title>
- </sect2>
- </sect1>
+ <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>
-</chapter>
+ <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>
+ </sect1>
+</chapter>
\ No newline at end of file
Modified: pojo/branches/2.1/src/main/docbook/userguide/en/modules/introduction.xml
===================================================================
--- pojo/branches/2.1/src/main/docbook/userguide/en/modules/introduction.xml 2008-03-11
23:10:40 UTC (rev 5415)
+++ pojo/branches/2.1/src/main/docbook/userguide/en/modules/introduction.xml 2008-03-11
23:19:01 UTC (rev 5416)
@@ -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>