Author: jason.greene(a)jboss.com Date: 2008-11-14 11:19:25 -0500 (Fri, 14 Nov 2008) New Revision: 7141 Added: pojo/tags/3.0.0.GA/ pojo/tags/3.0.0.GA/pom.xml pojo/tags/3.0.0.GA/src/main/docbook/faq/en/master.xml pojo/tags/3.0.0.GA/src/main/docbook/tutorial/en/master.xml Removed: pojo/tags/3.0.0.GA/pom.xml pojo/tags/3.0.0.GA/src/main/docbook/faq/en/master.xml pojo/tags/3.0.0.GA/src/main/docbook/tutorial/en/master.xml Log: Tag 3.0.0.GA Copied: pojo/tags/3.0.0.GA (from rev 7137, pojo/trunk) Deleted: pojo/tags/3.0.0.GA/pom.xml =================================================================== --- pojo/trunk/pom.xml 2008-11-14 14:10:27 UTC (rev 7137) +++ pojo/tags/3.0.0.GA/pom.xml 2008-11-14 16:19:25 UTC (rev 7141) @@ -1,307 +0,0 @@ -<?xml version="1.0"?> -<project xmlns="http://maven.apache.org/POM/4.0.0" - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> - <modelVersion>4.0.0</modelVersion> - <properties> - <jbosscache-pojo-version>3.0.0.CR3</jbosscache-pojo-version> - <jbosscache-core-version>3.0.0.CR3</jbosscache-core-version> - <jboss.aop.version>2.0.0.GA</jboss.aop.version> - </properties> - <parent> - <groupId>org.jboss.cache</groupId> - <artifactId>jbosscache-common-parent</artifactId> - <version>1.1</version> - </parent> - <groupId>org.jboss.cache</groupId> - <artifactId>jbosscache-pojo</artifactId> - <version>${jbosscache-pojo-version}</version> - <name>JBoss Cache - POJO Edition</name> - <description>JBoss Cache - POJO Edition</description> - <packaging>jar</packaging> - <dependencies> - <dependency> - <groupId>org.jboss.aop</groupId> - <artifactId>jboss-aop</artifactId> - <version>${jboss.aop.version}</version> - </dependency> - <dependency> - <groupId>org.jboss.cache</groupId> - <artifactId>jbosscache-core</artifactId> - <version>${jbosscache-core-version}</version> - </dependency> - <dependency> - <groupId>org.jboss.cache</groupId> - <artifactId>jbosscache-core</artifactId> - <version>${jbosscache-core-version}</version> - <type>test-jar</type> - <scope>test</scope> - </dependency> - <dependency> - <groupId>commons-logging</groupId> - <artifactId>commons-logging</artifactId> - <version>1.1.1</version> - </dependency> - <dependency> - <groupId>net.jcip</groupId> - <artifactId>jcip-annotations</artifactId> - <version>1.0</version> - <optional>true</optional> - </dependency> - - <dependency> - <groupId>org.jboss.logging</groupId> - <artifactId>jboss-logging-log4j</artifactId> - <version>2.0.5.GA</version> - <scope>test</scope> - </dependency> - </dependencies> - <build> - <plugins> - <plugin> - <groupId>org.apache.maven.plugins</groupId> - <artifactId>maven-javadoc-plugin</artifactId> - <executions> - <execution> - <phase>package</phase> - <goals> - <goal>javadoc</goal> - </goals> - <configuration> - <aggregate>${jbosscache.reports.aggregate}</aggregate> - <links> - <link>http://java.sun.com/j2se/1.5.0/docs/api/</link> - <link>http://java.sun.com/javaee/5/docs/api/</link> - <link>http://labs.jboss.org/file-access/default/members/jbosscache/free... - </links> - </configuration> - </execution> - </executions> - </plugin> - <plugin> - <artifactId>maven-assembly-plugin</artifactId> - <version>2.2-beta-1</version> - <executions> - <execution> - <id>assemble</id> - <phase>install</phase> - <goals> - <goal>attached</goal> - </goals> - <configuration> - <descriptors> - <descriptor>assembly/bin.xml</descriptor> - <descriptor>assembly/doc.xml</descriptor> - <descriptor>assembly/all.xml</descriptor> - </descriptors> - <finalName>${artifactId}-${jbosscache-pojo-version}</finalName> - <outputDirectory>target/distribution</outputDirectory> - <workDirectory>target/assembly/work</workDirectory> - </configuration> - </execution> - </executions> - </plugin> - <plugin> - <groupId>org.apache.maven.plugins</groupId> - <artifactId>maven-surefire-plugin</artifactId> - <version>2.3</version> - <configuration> - <systemProperties> - <property> - <name>bind.address</name> - <value>127.0.0.1</value> - </property> - <property> - <name>java.net.preferIPv4Stack</name> - <value>true</value> - </property> - <property> - <name>jgroups.stack</name> - <value>udp</value> - </property> - </systemProperties> - <groups>functional</groups> - <forkMode>always</forkMode> - <argLine>-Djboss.aop.path=${basedir}/src/main/resources/META-INF/pojocache-aop.xml -javaagent:${settings.localRepository}/org/jboss/aop/jboss-aop/${jboss.aop.version}/jboss-aop-${jboss.aop.version}.jar</argLine> - <!-- Warning, this does not work right on 2.4-SNAPSHOT, (see SUREFIRE-349) --> - <!-- This seems to fail in some cases on 2.3 as well, disable for now --> - <useSystemClassLoader>true</useSystemClassLoader> - <redirectTestOutputToFile>false</redirectTestOutputToFile> - <trimStackTrace>false</trimStackTrace> - </configuration> - </plugin> - <!-- the docbook generation plugin for the user guide --> - <plugin> - <groupId>org.jboss.maven.plugins</groupId> - <artifactId>maven-jdocbook-plugin</artifactId> - <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> - <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--> - <execution> - <id>userguide_en</id> - <phase>package</phase> - <goals> - <goal>resources</goal> - <goal>generate</goal> - </goals> - <configuration> - <sourceDocumentName>master.xml</sourceDocumentName> - <sourceDirectory>${basedir}/src/main/docbook/userguide/en</sourceDirectory> - <imageResource> - <directory>${basedir}/src/main/docbook/images</directory> - </imageResource> - <cssResource> - <directory>${basedir}/src/main/docbook/css</directory> - </cssResource> - <targetDirectory>${basedir}/target/docbook/userguide_en</targetDirectory> - <formats> - <format> - <formatName>pdf</formatName> - <stylesheetResource>classpath:/xslt/org/jboss/main-pdf.xsl</stylesheetResource> - <finalName>userguide_en.pdf</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> - </options> - </configuration> - </execution> - - <!-- The Tutorial --> - <execution> - <id>tutorial_en</id> - <phase>package</phase> - <goals> - <goal>resources</goal> - <goal>generate</goal> - </goals> - <configuration> - <sourceDocumentName>master.xml</sourceDocumentName> - <sourceDirectory>${basedir}/src/main/docbook/tutorial/en</sourceDirectory> - <imageResource> - <directory>${basedir}/src/main/docbook/images</directory> - </imageResource> - <cssResource> - <directory>${basedir}/src/main/docbook/css</directory> - </cssResource> - <targetDirectory>${basedir}/target/docbook/tutorial_en</targetDirectory> - <formats> - <format> - <formatName>pdf</formatName> - <stylesheetResource>classpath:/xslt/org/jboss/main-pdf.xsl</stylesheetResource> - <finalName>tutorial_en.pdf</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> - </options> - </configuration> - </execution> - - <!-- the FAQs --> - <execution> - <id>faq_en</id> - <phase>package</phase> - <goals> - <goal>resources</goal> - <goal>generate</goal> - </goals> - <configuration> - <sourceDocumentName>master.xml</sourceDocumentName> - <sourceDirectory>${basedir}/src/main/docbook/faq/en</sourceDirectory> - <imageResource> - <directory>${basedir}/src/main/docbook/images</directory> - </imageResource> - <cssResource> - <directory>${basedir}/src/main/docbook/css</directory> - </cssResource> - <targetDirectory>${basedir}/target/docbook/faq_en</targetDirectory> - <formats> - <format> - <formatName>pdf</formatName> - <stylesheetResource>classpath:/xslt/org/jboss/main-pdf.xsl</stylesheetResource> - <finalName>faq_en.pdf</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> - </options> - </configuration> - </execution> - </executions> - </plugin> - </plugins> - </build> - - <!-- basic JBoss repository so that the common parent POM in jbosscache-support can be found --> - <repositories> - <repository> - <id>snapshots.jboss.org</id> - <url>http://snapshots.jboss.org/maven2</url> - </repository> - <repository> - <id>repository.jboss.org</id> - <url>http://repository.jboss.org/maven2</url> - </repository> - </repositories> -</project> Copied: pojo/tags/3.0.0.GA/pom.xml (from rev 7140, pojo/trunk/pom.xml) =================================================================== --- pojo/tags/3.0.0.GA/pom.xml (rev 0) +++ pojo/tags/3.0.0.GA/pom.xml 2008-11-14 16:19:25 UTC (rev 7141) @@ -0,0 +1,307 @@ +<?xml version="1.0"?> +<project xmlns="http://maven.apache.org/POM/4.0.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> + <modelVersion>4.0.0</modelVersion> + <properties> + <jbosscache-pojo-version>3.0.0.GA</jbosscache-pojo-version> + <jbosscache-core-version>3.0.0.GA</jbosscache-core-version> + <jboss.aop.version>2.0.0.GA</jboss.aop.version> + </properties> + <parent> + <groupId>org.jboss.cache</groupId> + <artifactId>jbosscache-common-parent</artifactId> + <version>1.1</version> + </parent> + <groupId>org.jboss.cache</groupId> + <artifactId>jbosscache-pojo</artifactId> + <version>${jbosscache-pojo-version}</version> + <name>JBoss Cache - POJO Edition</name> + <description>JBoss Cache - POJO Edition</description> + <packaging>jar</packaging> + <dependencies> + <dependency> + <groupId>org.jboss.aop</groupId> + <artifactId>jboss-aop</artifactId> + <version>${jboss.aop.version}</version> + </dependency> + <dependency> + <groupId>org.jboss.cache</groupId> + <artifactId>jbosscache-core</artifactId> + <version>${jbosscache-core-version}</version> + </dependency> + <dependency> + <groupId>org.jboss.cache</groupId> + <artifactId>jbosscache-core</artifactId> + <version>${jbosscache-core-version}</version> + <type>test-jar</type> + <scope>test</scope> + </dependency> + <dependency> + <groupId>commons-logging</groupId> + <artifactId>commons-logging</artifactId> + <version>1.1.1</version> + </dependency> + <dependency> + <groupId>net.jcip</groupId> + <artifactId>jcip-annotations</artifactId> + <version>1.0</version> + <optional>true</optional> + </dependency> + + <dependency> + <groupId>org.jboss.logging</groupId> + <artifactId>jboss-logging-log4j</artifactId> + <version>2.0.5.GA</version> + <scope>test</scope> + </dependency> + </dependencies> + <build> + <plugins> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-javadoc-plugin</artifactId> + <executions> + <execution> + <phase>package</phase> + <goals> + <goal>javadoc</goal> + </goals> + <configuration> + <aggregate>${jbosscache.reports.aggregate}</aggregate> + <links> + <link>http://java.sun.com/j2se/1.5.0/docs/api/</link> + <link>http://java.sun.com/javaee/5/docs/api/</link> + <link>http://labs.jboss.org/file-access/default/members/jbosscache/free... + </links> + </configuration> + </execution> + </executions> + </plugin> + <plugin> + <artifactId>maven-assembly-plugin</artifactId> + <version>2.2-beta-1</version> + <executions> + <execution> + <id>assemble</id> + <phase>install</phase> + <goals> + <goal>attached</goal> + </goals> + <configuration> + <descriptors> + <descriptor>assembly/bin.xml</descriptor> + <descriptor>assembly/doc.xml</descriptor> + <descriptor>assembly/all.xml</descriptor> + </descriptors> + <finalName>${artifactId}-${jbosscache-pojo-version}</finalName> + <outputDirectory>target/distribution</outputDirectory> + <workDirectory>target/assembly/work</workDirectory> + </configuration> + </execution> + </executions> + </plugin> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-surefire-plugin</artifactId> + <version>2.3</version> + <configuration> + <systemProperties> + <property> + <name>bind.address</name> + <value>127.0.0.1</value> + </property> + <property> + <name>java.net.preferIPv4Stack</name> + <value>true</value> + </property> + <property> + <name>jgroups.stack</name> + <value>udp</value> + </property> + </systemProperties> + <groups>functional</groups> + <forkMode>always</forkMode> + <argLine>-Djboss.aop.path=${basedir}/src/main/resources/META-INF/pojocache-aop.xml -javaagent:${settings.localRepository}/org/jboss/aop/jboss-aop/${jboss.aop.version}/jboss-aop-${jboss.aop.version}.jar</argLine> + <!-- Warning, this does not work right on 2.4-SNAPSHOT, (see SUREFIRE-349) --> + <!-- This seems to fail in some cases on 2.3 as well, disable for now --> + <useSystemClassLoader>true</useSystemClassLoader> + <redirectTestOutputToFile>false</redirectTestOutputToFile> + <trimStackTrace>false</trimStackTrace> + </configuration> + </plugin> + <!-- the docbook generation plugin for the user guide --> + <plugin> + <groupId>org.jboss.maven.plugins</groupId> + <artifactId>maven-jdocbook-plugin</artifactId> + <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> + <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--> + <execution> + <id>userguide_en</id> + <phase>package</phase> + <goals> + <goal>resources</goal> + <goal>generate</goal> + </goals> + <configuration> + <sourceDocumentName>master.xml</sourceDocumentName> + <sourceDirectory>${basedir}/src/main/docbook/userguide/en</sourceDirectory> + <imageResource> + <directory>${basedir}/src/main/docbook/images</directory> + </imageResource> + <cssResource> + <directory>${basedir}/src/main/docbook/css</directory> + </cssResource> + <targetDirectory>${basedir}/target/docbook/userguide_en</targetDirectory> + <formats> + <format> + <formatName>pdf</formatName> + <stylesheetResource>classpath:/xslt/org/jboss/main-pdf.xsl</stylesheetResource> + <finalName>userguide_en.pdf</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> + </options> + </configuration> + </execution> + + <!-- The Tutorial --> + <execution> + <id>tutorial_en</id> + <phase>package</phase> + <goals> + <goal>resources</goal> + <goal>generate</goal> + </goals> + <configuration> + <sourceDocumentName>master.xml</sourceDocumentName> + <sourceDirectory>${basedir}/src/main/docbook/tutorial/en</sourceDirectory> + <imageResource> + <directory>${basedir}/src/main/docbook/images</directory> + </imageResource> + <cssResource> + <directory>${basedir}/src/main/docbook/css</directory> + </cssResource> + <targetDirectory>${basedir}/target/docbook/tutorial_en</targetDirectory> + <formats> + <format> + <formatName>pdf</formatName> + <stylesheetResource>classpath:/xslt/org/jboss/main-pdf.xsl</stylesheetResource> + <finalName>tutorial_en.pdf</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> + </options> + </configuration> + </execution> + + <!-- the FAQs --> + <execution> + <id>faq_en</id> + <phase>package</phase> + <goals> + <goal>resources</goal> + <goal>generate</goal> + </goals> + <configuration> + <sourceDocumentName>master.xml</sourceDocumentName> + <sourceDirectory>${basedir}/src/main/docbook/faq/en</sourceDirectory> + <imageResource> + <directory>${basedir}/src/main/docbook/images</directory> + </imageResource> + <cssResource> + <directory>${basedir}/src/main/docbook/css</directory> + </cssResource> + <targetDirectory>${basedir}/target/docbook/faq_en</targetDirectory> + <formats> + <format> + <formatName>pdf</formatName> + <stylesheetResource>classpath:/xslt/org/jboss/main-pdf.xsl</stylesheetResource> + <finalName>faq_en.pdf</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> + </options> + </configuration> + </execution> + </executions> + </plugin> + </plugins> + </build> + + <!-- basic JBoss repository so that the common parent POM in jbosscache-support can be found --> + <repositories> + <repository> + <id>snapshots.jboss.org</id> + <url>http://snapshots.jboss.org/maven2</url> + </repository> + <repository> + <id>repository.jboss.org</id> + <url>http://repository.jboss.org/maven2</url> + </repository> + </repositories> +</project> Deleted: pojo/tags/3.0.0.GA/src/main/docbook/faq/en/master.xml =================================================================== --- pojo/trunk/src/main/docbook/faq/en/master.xml 2008-11-14 14:10:27 UTC (rev 7137) +++ pojo/tags/3.0.0.GA/src/main/docbook/faq/en/master.xml 2008-11-14 16:19:25 UTC (rev 7141) @@ -1,665 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "../../../../docbook-support/support/docbook-dtd/docbookx.dtd" - > -<article class="faq" lang="en"> - <articleinfo> - <title>Frequently Asked Questions about POJO Cache</title> - <releaseinfo>Release 3.0.0.CR3</releaseinfo> - <pubdate>November 2008</pubdate> - - <author> - <firstname>Ben</firstname> - <surname>Wang</surname> - <email&gt;ben.wang(a)jboss.com&lt;/email&gt; - </author> - <author> - <firstname>Scott</firstname> - <surname>Marlow</surname> - <email&gt;smarlow(a)novell.com&lt;/email&gt; - </author> - <author> - <firstname>Jason</firstname> - <surname>Greene</surname> - <email&gt;jason.greene(a)jboss.com&lt;/email&gt; - </author> - </articleinfo> - - <para>These are frequently asked questions regarding POJO Cache.</para> - - <qandaset defaultlabel="qanda"> - <title>General Information</title> - - <qandaentry> - <question id="a49"> - <para>What is POJO Cache?</para> - </question> - - <answer> - <para>POJO Cache is a fine-grained field-level replicated and - transactional POJO (plain old Java object) cache. By POJO, we mean - that the cache: 1) automatically manages object mapping and - relationship for a client under both local and replicated cache - mode, 2) provides support for inheritance relationship between - "aspectized" POJOs. By leveraging the dynamic AOP in JBossAop, it is - able to map a complex object into the cache store, preserve and - manage the object relationship behind the scene. During replication - mode, it performs fine-granularity (i.e., on a per-field basis) - update, and thus has the potential to boost cache performance and - minimize network traffic. - </para> - - <para>From a user perspective, once your POJO is managed by the - cache, all cache operations are transparent. Therefore, all the - usual in-VM POJO method semantics are still preserved, providing - ease of use. For example, if a POJO has been put in POJO Cache (by - calling - <literal>attach</literal> - , for example), then any POJO get/set - method will be - intercepted by POJO Cache to provide the data from the - cache. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="a1"> - <para>What is the relationship between Core Cache and POJO Cache?</para> - </question> - - <answer> - <para>Cores Cache is a traditional generic distributed cache system. - POJO Cache uses Core Cache as the underlying distributed state system to achieve object caching. - As a result, all the replication aspects are configured with the Cache configuration XML. - Additionally, POJO Cache also has API to expose the Cache interface (via - <literal>getCache()</literal> - API). - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="a52"> - <para>What is the difference between Core Cache and - POJO Cache? - </para> - </question> - - <answer> - <para>Think of POJO Cache as a Cache on steroids. :-) - Seriously, both are cache stores-- one is a generic cache and the other other one POJO Cache. - However, while Cache only - provides pure object reference storage (e.g., - <literal>put(FQN fqn, - Object key, Object value) - </literal> - ), POJO Cache goes beyond that - and performs fine-grained field level replication object mapping and - relationship management for a user behind the scenes. As a result, - if you have complex object systems that you would like to cache, you - can have POJO Cache manage it for you. You simply treat your - object systems as they are residing in-memory, e.g., use your - regular POJO methods without worrying about cache management. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="a521"> - <para>How does POJO Cache work then?</para> - </question> - - <answer> - <para>POJO Cache uses the JBoss AOP project to perform field level - interception. This allows POJO Cache to monitor changes to your object model, and react - accordingly. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="a522"> - <para>What's changed between 1.x and 2.x release then?</para> - </question> - - <answer> - <para>Starting in 2.0 release, we have a separate library for POJO Cache, - <literal>pojocache.jar</literal> - that - is extra to the core - <literal>jboss-cache.jar</literal> - . Since we uses Cache as a delegate, user - will need to have a regular xml to configure the core Cache functionality (e.g., replication and locking - aspect). In addition, there is also the - <literal>pojocache-aop.xml</literal> - that specifies the POJO Cache - interceptor stack (that can be left as default). - </para> - <para>Additionally, here are the changed features: - <itemizedlist> - <listitem> - <para>New APIs. It replaces - <literal>putObject, removeObject, and get</literal> - with - <literal>attach, detach, and find</literal> - . - </para> - </listitem> - <listitem> - <para>New POJO based events that a user can subscribe to.</para> - </listitem> - <listitem> - <para>New configuration pojocache-aop.xml specifically for POJO Cache, in addition to - the regular cache-service.xml for the delegating Cache. - </para> - </listitem> - <listitem> - <para>New package namespace ( - <literal>org.jboss.cache.pojo)</literal> - for POJO Cache. - The previous - <literal>org.jboss.cache.aop</literal> - space has been deprecated. - </para> - </listitem> - </itemizedlist> - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="a53"> - <para>How do you use POJO Cache?</para> - </question> - - <answer> - <para>In order to use POJO Cache, you will need to:</para> - - <itemizedlist> - <listitem> - <para>Annotate your POJOt with @Replicable. - </para> - </listitem> - <listitem> - <para>Instrument your POJO. This can be done at load-time using special JVM arguments (prefered), or at compile time using the - AOP precompiler tool (aopc). See the user guide for more specific details on instrumentation. - </para> - </listitem> - </itemizedlist> - </answer> - </qandaentry> - - <qandaentry> - <question id="a541"> - <para>What is the JDK version required to run POJO Cache 2.x?</para> - </question> - - <answer> - <para>POJO Cache 2.x requires Java 5 or newer.</para> - </answer> - </qandaentry> - - <qandaentry> - <question id="a542"> - <para>Can I run POJO Cache as a standalone mode?</para> - </question> - - <answer> - <para>Yes, same as the Core Cache library, you can run POJO Cache either as a standalone or - inside an application server. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="a543"> - <para>What is the JBoss AS recommended version to run POJO Cache 2.x?</para> - </question> - - <answer> - <para>POJO Cache can be run either in AS4.0.5 (and up) and 5.0. But either way, it will require - JDK5.0 though. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="a56"> - <para>Can I pre-compile objects used in POJO Cache, so that I don't have to provide an AOP descriptor? - </para> - </question> - - <answer> - <para>Yes. The AOP library included with POJO Cache has a pre-compiler called - <literal>aopc</literal> that can be used to instrument objects in advance. However, - this is not the recommended approach, since your classes become tied to a specific AOP version. - See the instrumentation chapter in the user guide for more information. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="a561"> - <para>In POJO Cache 2.x release, do I still need - <literal>annoc</literal> - ? - </para> - </question> - - <answer> - <para>No. POJO Cache 2.x requires JDK 5, and recommends load-time instrumentation. Alternatively the offline aopc tool may be used. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="a57"> - <para>How do I use aopc on multiple module directories?</para> - </question> - - <answer> - <para>In aopc, you specify the src path for a specific directory. To - pre-compile multiple ones, you will need to invoke aopc multiple - times. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="a57a"> - <para>Does POJO Cache provide a listener/event model for catching changes?</para> - </question> - - <answer> - <para>Yes. See the javadoc for PojoCache.addListener() and @PojoCacheListener. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="a58"> - <para>What's in the - <literal>pojocaches-aop.xml</literal> - configuration? - </para> - </question> - - <answer> - <para> - These descriptors are necessary for instrumentation. However, you typically do not need to touch them since they include a rule - which matches the classes with an @Replicable annotation. Therefore, all you need to do, is just - annotate your class with @Replicable. Advanced users may decide to customize them with special AOP prepare statements that match - classes which do not have @Replicable. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="a58a"> - <para>What's the difference between - <literal>jboss-aop.xml</literal> - <literal>pojocache-aop.xml</literal> - ? - </para> - </question> - - <answer> - <para> - <literal>pojocache-aop.xml</literal> - is essentially a - <literal>jboss-aop.xml</literal> - , - except it is used specifically for POJO Cache. The analogy is similar to JBoss' own - MBean service file - <literal>jboss-service.xml</literal> - , for example. So in our documentation, - we will use these two terms interchangeably. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="a59"> - <para>Can I use annotations instead of editing the AOP XML descriptors?</para> - </question> - - <answer> - <para>Yes, in release 2.0, we recommend you use the @Replicable annotation, and don't bother with editing the AOP files. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="a60"> - <para>Is there a problem with using a custom AOP descriptor over the provided annotations?</para> - </question> - - <answer> - <para>The only real benefit to a custom AOP descriptor is if you can't easily add the annotation to the class source (it's not under your control). - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="a61"> - <para>What are the - <literal&gt;(a)org.jboss.cache.pojo.annotation.Transient&lt;/literal&gt; - and - <literal&gt;(a)org.jboss.cache.pojo.annotation.Serializable&lt;/literal&gt; - field level annotations? - </para> - </question> - - <answer> - <para>In 2.0, we also offer two additional field-level annotations. The first one, - <literal&gt;(a)org.jboss.cache.pojo.Transient&lt;/literal&gt; - , - when applied has the same effect as declaring a field - <literal>transient</literal> - . POJO Cache - won't put this field under management. - </para> - <para>The second one, - <literal&gt;(a)org.jboss.cache.pojo.Serializable&lt;/literal&gt; - when applied, - will cause POJO Cache to - treat the field as a Serializable object even when it is - <literal&gt;(a)org.jboss.cache.pojo.Replicable&lt;/literal&gt; - . - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="a62"> - <para>Why do you recommend load-time over compile-time instrumentation?</para> - </question> - - <answer> - <para> The major problem with compile-time instrumentation is that it adds a binary dependency on your class files to whatever - version of JBoss AOP that was used to run aopc. Once this has been done, the class may not work with a future version of - JBoss AOP (although the AOP team tries to ensure binary compatibility across minor revisions). Load-time doesn't have - this problem since the class is instrumented only in memory, and only when it is loaded. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="a63"> - <para>Is it possible to store the same object multiple times but - with different Fqn paths? Like /foo/byName and /foo/byId ? - </para> - </question> - - <answer> - <para>Yes, you can use POJO Cache to do that. It supports the - notion of multiple object references. POJO Cache manages the unique object - through association of the dynamic cache interceptor. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="a64"> - <para>Do I have to instrument my objects? - </para> - </question> - - <answer> - <para> You can also attach objects that implement - <literal>Serializable</literal>. However, you lose field-level replication and object identity preservation. - This is really only supported as a compatibility measure. It is definately worth useing instrumentation. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="a65"> - <para>Will POJO Cache intercept changes made from Java Reflection?</para> - </question> - - <answer> - <para>Yes and No. Since POJO Cache intercepts field changes, any method - of an object that has been annotated with @Replicable will be handled properly when called with reflection. - However, modifying fields using reflection is not currently supported. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="a66"> - <para>When I declare my POJO to be "aspectized", what happens to the - fields with transient, static, and final modifiers? - </para> - </question> - - <answer> - <para>POJO Cache currently will ignore the fields with these - modifiers. That is, it won't put these fields into the cache (and - thus no replication either). - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="a67"> - <para>What are those keys such as - <literal>JBoss:internal:class</literal> - and - <literal>PojoInstance</literal> - ? - </para> - </question> - - <answer> - <para>They are for internal use only. Users should ignore these keys - and values in the node hashmap. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="a68"> - <para>What about Collection classes? Do I need to declare them - "prepared"? - </para> - </question> - - <answer> - <para>No. Since the Collection classes such as - <literal>ArrayList</literal> - are java util classes, aop by default - won't instrument these classes. Instead, POJO Cache will generate - a dynamic class proxy for the Collection classes (upon the - <literal>attach</literal> - call is invoked). The proxy will - delegate the operations to a cache interceptor that implements the - actual Collection classes APIs. That is, the system classes won't be - invoked when used in POJO Cache. - </para> - - <para>Internally, the cache interceptor implements the APIs by - direct interaction with respect to the underlying cache store. Note - that this can have implications in performance for certain APIs. For - example, both - <literal>ArrayList</literal> - and - <literal>LinkedList</literal> - will have the same implementation. - Plan is currently underway to optimize these APIs. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="a69"> - <para>How do I use - <literal>List</literal> - , - <literal>Set</literal> - , - and - <literal>Map</literal> with POJO Cache? - </para> - </question> - - <answer> - <para>POJO Cache supports all classes that implement - <literal>List</literal> - , - <literal>Set</literal> - , and - <literal>Map</literal> - without instrumentation. This is done using a dynamic proxy. Here is an example using - <literal>ArrayList</literal>: - </para> - - <programlisting role="JAVA"><![CDATA[ - ArrayList list = new ArrayList(); - list.add("first"); - - cache.attach("/list/test", list); // Put the list under the 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> - </answer> - </qandaentry> - - <qandaentry> - <question id="a70"> - <para>What is the proper way of assigning two different keys with - Collection class object? - </para> - </question> - - <answer> - <para>Let's say you want to assign a - <literal>List</literal> - object - under two different names, you will need to use the class proxy to - insert the second time to ensure both are managed by the cache. Here - is the code snippet. - </para> - - <programlisting role="JAVA"><![CDATA[ - ArrayList list = new ArrayList(); - list.add("first"); - - 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 - - cache.attach("/list_alias", myList); // Note you will need to use the proxy here!! - myList.remove("second"); - ]]></programlisting> - </answer> - </qandaentry> - - <qandaentry> - <question id="a71"> - <para>OK, so I know I am supposed to use proxy when manipulating the - Collection classes once they are managed by the cache. But what - happens to POJOs that share the Collection objects, e.g., a - <literal>List</literal> - instance that is shared by two objects?? - </para> - </question> - - <answer> - <para>POJOss that share Collection instance references will be - handled by the cache automatically. That is, when you ask the Cache - to manage it, the Cache will dynamically swap out the regular - Collection references with the dynamic proxy ones. As a result, it - is transparent to you. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="a72"> - <para>What happens when my instrumented object contains collections? - </para> - </question> - - <answer> - <para>When an object is passed to - <literal>attach</literal> - , it will recursively map the field - members into the cache store as well. If the field member is of a - Collection class (e.g., List, Set, or Map), POJO Cache will first - map the collection into cache. Then, it will swap out - the field reference with an corresponding proxy reference. - </para> - - <para>This is necessary so that an internal update on the field - member will be intercepted by the cache. - </para> - </answer> - </qandaentry> - - - <qandaentry> - <question id="a73"> - <para>What are the limitations of using Java Collections in POJO Cache?</para> - </question> - <answer> - <para> - List, Set, and Map are supported; however, these APIs do not stipulate - of constraints like whether a null key or value is allowed. Therefore the behavior of an attached collection may differ - slightly from the originals Java implementation. The behavior implemented by POJO Cache follows - java.util.HashSet for any Set type, java.util.ArrayList for any List type, and java.util.HashMap for any Map type.s - </para> - </answer> - </qandaentry> - </qandaset> - - - <qandaset defaultlabel="qanda"> - <title>Passiviation and eviction</title> - <qandaentry> - <question id="a80"> - <para>Can I use eviction to evict a POJO from the memory?</para> - </question> - <answer> - <para>In 2.0 release, we removed the POJO-based eviction policy since it has always been - problematic in earlier release. You can, however, use the standard Core Cache eviction system to - evict the data that backs the POJO. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question id="a81"> - <para>Is passivation supported?</para> - </question> - <answer> - <para>Yes, in order to reduce memory consumption, you can use the passivation feature that comes with - Core Cache. Passivation uses the combination of eviction and a cache loader such that when the - items are old, it will be evicted from memory and store in a cache store (can be DB or file). Next time, - when the item needs to be accessed again, we will retrieve it from the cache store. - </para> - </answer> - </qandaentry> - </qandaset> - - <qandaset defaultlabel="qanda"> - <title>Troubleshooting</title> - <qandaentry> - <question id="a90"> - <para>I am having problems getting POJO Cache to work, where can I get information on troubleshooting?</para> - </question> - <answer> - <para>Troubleshooting section can be found in the following - <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=PojoCacheTroubleshooti... link</ulink> - . - </para> - </answer> - </qandaentry> - </qandaset> -</article> Copied: pojo/tags/3.0.0.GA/src/main/docbook/faq/en/master.xml (from rev 7140, pojo/trunk/src/main/docbook/faq/en/master.xml) =================================================================== --- pojo/tags/3.0.0.GA/src/main/docbook/faq/en/master.xml (rev 0) +++ pojo/tags/3.0.0.GA/src/main/docbook/faq/en/master.xml 2008-11-14 16:19:25 UTC (rev 7141) @@ -0,0 +1,665 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "../../../../docbook-support/support/docbook-dtd/docbookx.dtd" + > +<article class="faq" lang="en"> + <articleinfo> + <title>Frequently Asked Questions about POJO Cache</title> + <releaseinfo>Release 3.0.0</releaseinfo> + <pubdate>November 2008</pubdate> + + <author> + <firstname>Ben</firstname> + <surname>Wang</surname> + <email&gt;ben.wang(a)jboss.com&lt;/email&gt; + </author> + <author> + <firstname>Scott</firstname> + <surname>Marlow</surname> + <email&gt;smarlow(a)novell.com&lt;/email&gt; + </author> + <author> + <firstname>Jason</firstname> + <surname>Greene</surname> + <email&gt;jason.greene(a)jboss.com&lt;/email&gt; + </author> + </articleinfo> + + <para>These are frequently asked questions regarding POJO Cache.</para> + + <qandaset defaultlabel="qanda"> + <title>General Information</title> + + <qandaentry> + <question id="a49"> + <para>What is POJO Cache?</para> + </question> + + <answer> + <para>POJO Cache is a fine-grained field-level replicated and + transactional POJO (plain old Java object) cache. By POJO, we mean + that the cache: 1) automatically manages object mapping and + relationship for a client under both local and replicated cache + mode, 2) provides support for inheritance relationship between + "aspectized" POJOs. By leveraging the dynamic AOP in JBossAop, it is + able to map a complex object into the cache store, preserve and + manage the object relationship behind the scene. During replication + mode, it performs fine-granularity (i.e., on a per-field basis) + update, and thus has the potential to boost cache performance and + minimize network traffic. + </para> + + <para>From a user perspective, once your POJO is managed by the + cache, all cache operations are transparent. Therefore, all the + usual in-VM POJO method semantics are still preserved, providing + ease of use. For example, if a POJO has been put in POJO Cache (by + calling + <literal>attach</literal> + , for example), then any POJO get/set + method will be + intercepted by POJO Cache to provide the data from the + cache. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question id="a1"> + <para>What is the relationship between Core Cache and POJO Cache?</para> + </question> + + <answer> + <para>Cores Cache is a traditional generic distributed cache system. + POJO Cache uses Core Cache as the underlying distributed state system to achieve object caching. + As a result, all the replication aspects are configured with the Cache configuration XML. + Additionally, POJO Cache also has API to expose the Cache interface (via + <literal>getCache()</literal> + API). + </para> + </answer> + </qandaentry> + + <qandaentry> + <question id="a52"> + <para>What is the difference between Core Cache and + POJO Cache? + </para> + </question> + + <answer> + <para>Think of POJO Cache as a Cache on steroids. :-) + Seriously, both are cache stores-- one is a generic cache and the other other one POJO Cache. + However, while Cache only + provides pure object reference storage (e.g., + <literal>put(FQN fqn, + Object key, Object value) + </literal> + ), POJO Cache goes beyond that + and performs fine-grained field level replication object mapping and + relationship management for a user behind the scenes. As a result, + if you have complex object systems that you would like to cache, you + can have POJO Cache manage it for you. You simply treat your + object systems as they are residing in-memory, e.g., use your + regular POJO methods without worrying about cache management. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question id="a521"> + <para>How does POJO Cache work then?</para> + </question> + + <answer> + <para>POJO Cache uses the JBoss AOP project to perform field level + interception. This allows POJO Cache to monitor changes to your object model, and react + accordingly. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question id="a522"> + <para>What's changed between 1.x and 2.x release then?</para> + </question> + + <answer> + <para>Starting in 2.0 release, we have a separate library for POJO Cache, + <literal>pojocache.jar</literal> + that + is extra to the core + <literal>jboss-cache.jar</literal> + . Since we uses Cache as a delegate, user + will need to have a regular xml to configure the core Cache functionality (e.g., replication and locking + aspect). In addition, there is also the + <literal>pojocache-aop.xml</literal> + that specifies the POJO Cache + interceptor stack (that can be left as default). + </para> + <para>Additionally, here are the changed features: + <itemizedlist> + <listitem> + <para>New APIs. It replaces + <literal>putObject, removeObject, and get</literal> + with + <literal>attach, detach, and find</literal> + . + </para> + </listitem> + <listitem> + <para>New POJO based events that a user can subscribe to.</para> + </listitem> + <listitem> + <para>New configuration pojocache-aop.xml specifically for POJO Cache, in addition to + the regular cache-service.xml for the delegating Cache. + </para> + </listitem> + <listitem> + <para>New package namespace ( + <literal>org.jboss.cache.pojo)</literal> + for POJO Cache. + The previous + <literal>org.jboss.cache.aop</literal> + space has been deprecated. + </para> + </listitem> + </itemizedlist> + </para> + </answer> + </qandaentry> + + <qandaentry> + <question id="a53"> + <para>How do you use POJO Cache?</para> + </question> + + <answer> + <para>In order to use POJO Cache, you will need to:</para> + + <itemizedlist> + <listitem> + <para>Annotate your POJOt with @Replicable. + </para> + </listitem> + <listitem> + <para>Instrument your POJO. This can be done at load-time using special JVM arguments (prefered), or at compile time using the + AOP precompiler tool (aopc). See the user guide for more specific details on instrumentation. + </para> + </listitem> + </itemizedlist> + </answer> + </qandaentry> + + <qandaentry> + <question id="a541"> + <para>What is the JDK version required to run POJO Cache 3.x?</para> + </question> + + <answer> + <para>POJO Cache 3.x requires Java 5 or newer.</para> + </answer> + </qandaentry> + + <qandaentry> + <question id="a542"> + <para>Can I run POJO Cache as a standalone mode?</para> + </question> + + <answer> + <para>Yes, same as the Core Cache library, you can run POJO Cache either as a standalone or + inside an application server. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question id="a543"> + <para>What is the JBoss AS recommended version to run POJO Cache 3.x?</para> + </question> + + <answer> + <para>POJO Cache can be run either in AS4.0.5 (and up) and 5.0. But either way, it will require + JDK5.0 though. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question id="a56"> + <para>Can I pre-compile objects used in POJO Cache, so that I don't have to provide an AOP descriptor? + </para> + </question> + + <answer> + <para>Yes. The AOP library included with POJO Cache has a pre-compiler called + <literal>aopc</literal> that can be used to instrument objects in advance. However, + this is not the recommended approach, since your classes become tied to a specific AOP version. + See the instrumentation chapter in the user guide for more information. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question id="a561"> + <para>In the POJO Cache 2.x and 3.x releases, do I still need + <literal>annoc</literal> + ? + </para> + </question> + + <answer> + <para>No. POJO Cache 2.x and 3.x requires JDK 5, and recommends load-time instrumentation. Alternatively the offline aopc tool may be used. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question id="a57"> + <para>How do I use aopc on multiple module directories?</para> + </question> + + <answer> + <para>In aopc, you specify the src path for a specific directory. To + pre-compile multiple ones, you will need to invoke aopc multiple + times. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question id="a57a"> + <para>Does POJO Cache provide a listener/event model for catching changes?</para> + </question> + + <answer> + <para>Yes. See the javadoc for PojoCache.addListener() and @PojoCacheListener. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question id="a58"> + <para>What's in the + <literal>pojocaches-aop.xml</literal> + configuration? + </para> + </question> + + <answer> + <para> + These descriptors are necessary for instrumentation. However, you typically do not need to touch them since they include a rule + which matches the classes with an @Replicable annotation. Therefore, all you need to do, is just + annotate your class with @Replicable. Advanced users may decide to customize them with special AOP prepare statements that match + classes which do not have @Replicable. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question id="a58a"> + <para>What's the difference between + <literal>jboss-aop.xml</literal> + <literal>pojocache-aop.xml</literal> + ? + </para> + </question> + + <answer> + <para> + <literal>pojocache-aop.xml</literal> + is essentially a + <literal>jboss-aop.xml</literal> + , + except it is used specifically for POJO Cache. The analogy is similar to JBoss' own + MBean service file + <literal>jboss-service.xml</literal> + , for example. So in our documentation, + we will use these two terms interchangeably. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question id="a59"> + <para>Can I use annotations instead of editing the AOP XML descriptors?</para> + </question> + + <answer> + <para>Yes, in release 2.0 and 3.0, we recommend you use the @Replicable annotation, and don't bother with editing the AOP files. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question id="a60"> + <para>Is there a problem with using a custom AOP descriptor over the provided annotations?</para> + </question> + + <answer> + <para>The only real benefit to a custom AOP descriptor is if you can't easily add the annotation to the class source (it's not under your control). + </para> + </answer> + </qandaentry> + + <qandaentry> + <question id="a61"> + <para>What are the + <literal&gt;(a)org.jboss.cache.pojo.annotation.Transient&lt;/literal&gt; + and + <literal&gt;(a)org.jboss.cache.pojo.annotation.Serializable&lt;/literal&gt; + field level annotations? + </para> + </question> + + <answer> + <para>In 2.0, we also offer two additional field-level annotations. The first one, + <literal&gt;(a)org.jboss.cache.pojo.Transient&lt;/literal&gt; + , + when applied has the same effect as declaring a field + <literal>transient</literal> + . POJO Cache + won't put this field under management. + </para> + <para>The second one, + <literal&gt;(a)org.jboss.cache.pojo.Serializable&lt;/literal&gt; + when applied, + will cause POJO Cache to + treat the field as a Serializable object even when it is + <literal&gt;(a)org.jboss.cache.pojo.Replicable&lt;/literal&gt; + . + </para> + </answer> + </qandaentry> + + <qandaentry> + <question id="a62"> + <para>Why do you recommend load-time over compile-time instrumentation?</para> + </question> + + <answer> + <para> The major problem with compile-time instrumentation is that it adds a binary dependency on your class files to whatever + version of JBoss AOP that was used to run aopc. Once this has been done, the class may not work with a future version of + JBoss AOP (although the AOP team tries to ensure binary compatibility across minor revisions). Load-time doesn't have + this problem since the class is instrumented only in memory, and only when it is loaded. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question id="a63"> + <para>Is it possible to store the same object multiple times but + with different Fqn paths? Like /foo/byName and /foo/byId ? + </para> + </question> + + <answer> + <para>Yes, you can use POJO Cache to do that. It supports the + notion of multiple object references. POJO Cache manages the unique object + through association of the dynamic cache interceptor. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question id="a64"> + <para>Do I have to instrument my objects? + </para> + </question> + + <answer> + <para> You can also attach objects that implement + <literal>Serializable</literal>. However, you lose field-level replication and object identity preservation. + This is really only supported as a compatibility measure. It is definately worth useing instrumentation. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question id="a65"> + <para>Will POJO Cache intercept changes made from Java Reflection?</para> + </question> + + <answer> + <para>Yes and No. Since POJO Cache intercepts field changes, any method + of an object that has been annotated with @Replicable will be handled properly when called with reflection. + However, modifying fields using reflection is not currently supported. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question id="a66"> + <para>When I declare my POJO to be "aspectized", what happens to the + fields with transient, static, and final modifiers? + </para> + </question> + + <answer> + <para>POJO Cache currently will ignore the fields with these + modifiers. That is, it won't put these fields into the cache (and + thus no replication either). + </para> + </answer> + </qandaentry> + + <qandaentry> + <question id="a67"> + <para>What are those keys such as + <literal>JBoss:internal:class</literal> + and + <literal>PojoInstance</literal> + ? + </para> + </question> + + <answer> + <para>They are for internal use only. Users should ignore these keys + and values in the node hashmap. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question id="a68"> + <para>What about Collection classes? Do I need to declare them + "prepared"? + </para> + </question> + + <answer> + <para>No. Since the Collection classes such as + <literal>ArrayList</literal> + are java util classes, aop by default + won't instrument these classes. Instead, POJO Cache will generate + a dynamic class proxy for the Collection classes (upon the + <literal>attach</literal> + call is invoked). The proxy will + delegate the operations to a cache interceptor that implements the + actual Collection classes APIs. That is, the system classes won't be + invoked when used in POJO Cache. + </para> + + <para>Internally, the cache interceptor implements the APIs by + direct interaction with respect to the underlying cache store. Note + that this can have implications in performance for certain APIs. For + example, both + <literal>ArrayList</literal> + and + <literal>LinkedList</literal> + will have the same implementation. + Plan is currently underway to optimize these APIs. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question id="a69"> + <para>How do I use + <literal>List</literal> + , + <literal>Set</literal> + , + and + <literal>Map</literal> with POJO Cache? + </para> + </question> + + <answer> + <para>POJO Cache supports all classes that implement + <literal>List</literal> + , + <literal>Set</literal> + , and + <literal>Map</literal> + without instrumentation. This is done using a dynamic proxy. Here is an example using + <literal>ArrayList</literal>: + </para> + + <programlisting role="JAVA"><![CDATA[ + ArrayList list = new ArrayList(); + list.add("first"); + + cache.attach("/list/test", list); // Put the list under the 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> + </answer> + </qandaentry> + + <qandaentry> + <question id="a70"> + <para>What is the proper way of assigning two different keys with + Collection class object? + </para> + </question> + + <answer> + <para>Let's say you want to assign a + <literal>List</literal> + object + under two different names, you will need to use the class proxy to + insert the second time to ensure both are managed by the cache. Here + is the code snippet. + </para> + + <programlisting role="JAVA"><![CDATA[ + ArrayList list = new ArrayList(); + list.add("first"); + + 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 + + cache.attach("/list_alias", myList); // Note you will need to use the proxy here!! + myList.remove("second"); + ]]></programlisting> + </answer> + </qandaentry> + + <qandaentry> + <question id="a71"> + <para>OK, so I know I am supposed to use proxy when manipulating the + Collection classes once they are managed by the cache. But what + happens to POJOs that share the Collection objects, e.g., a + <literal>List</literal> + instance that is shared by two objects?? + </para> + </question> + + <answer> + <para>POJOss that share Collection instance references will be + handled by the cache automatically. That is, when you ask the Cache + to manage it, the Cache will dynamically swap out the regular + Collection references with the dynamic proxy ones. As a result, it + is transparent to you. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question id="a72"> + <para>What happens when my instrumented object contains collections? + </para> + </question> + + <answer> + <para>When an object is passed to + <literal>attach</literal> + , it will recursively map the field + members into the cache store as well. If the field member is of a + Collection class (e.g., List, Set, or Map), POJO Cache will first + map the collection into cache. Then, it will swap out + the field reference with an corresponding proxy reference. + </para> + + <para>This is necessary so that an internal update on the field + member will be intercepted by the cache. + </para> + </answer> + </qandaentry> + + + <qandaentry> + <question id="a73"> + <para>What are the limitations of using Java Collections in POJO Cache?</para> + </question> + <answer> + <para> + List, Set, and Map are supported; however, these APIs do not stipulate + of constraints like whether a null key or value is allowed. Therefore the behavior of an attached collection may differ + slightly from the originals Java implementation. The behavior implemented by POJO Cache follows + java.util.HashSet for any Set type, java.util.ArrayList for any List type, and java.util.HashMap for any Map type.s + </para> + </answer> + </qandaentry> + </qandaset> + + + <qandaset defaultlabel="qanda"> + <title>Passiviation and eviction</title> + <qandaentry> + <question id="a80"> + <para>Can I use eviction to evict a POJO from the memory?</para> + </question> + <answer> + <para>In 2.0 release, we removed the POJO-based eviction policy since it has always been + problematic in earlier release. You can, however, use the standard Core Cache eviction system to + evict the data that backs the POJO. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question id="a81"> + <para>Is passivation supported?</para> + </question> + <answer> + <para>Yes, in order to reduce memory consumption, you can use the passivation feature that comes with + Core Cache. Passivation uses the combination of eviction and a cache loader such that when the + items are old, it will be evicted from memory and store in a cache store (can be DB or file). Next time, + when the item needs to be accessed again, we will retrieve it from the cache store. + </para> + </answer> + </qandaentry> + </qandaset> + + <qandaset defaultlabel="qanda"> + <title>Troubleshooting</title> + <qandaentry> + <question id="a90"> + <para>I am having problems getting POJO Cache to work, where can I get information on troubleshooting?</para> + </question> + <answer> + <para>Troubleshooting section can be found in the following + <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=PojoCacheTroubleshooti... link</ulink> + . + </para> + </answer> + </qandaentry> + </qandaset> +</article> Deleted: pojo/tags/3.0.0.GA/src/main/docbook/tutorial/en/master.xml =================================================================== --- pojo/trunk/src/main/docbook/tutorial/en/master.xml 2008-11-14 14:10:27 UTC (rev 7137) +++ pojo/tags/3.0.0.GA/src/main/docbook/tutorial/en/master.xml 2008-11-14 16:19:25 UTC (rev 7141) @@ -1,401 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<article lang="en"> - <articleinfo> - <title>PojoCache Tutorial</title> - <releaseinfo>Release 3.0.0</releaseinfo> - <pubdate>November 2008</pubdate> - <author> - <firstname>Ben</firstname> - <surname>Wang</surname> - <email&gt;ben.wang(a)jboss.com&lt;/email&gt; - </author> - <author> - <firstname>Galder</firstname> - <surname>Zamarreño</surname> - <email&gt;galder.zamarreno(a)jboss.com&lt;/email&gt; - </author> - </articleinfo> - - <section> - <title>Introduction</title> - - <para>PojoCache is an in-memory, transactional, and replicated POJO (plain old Java object) cache system that - allows users to operate on a POJO transparently without active user management of either replication or - persistency aspects. This tutorial focuses on the usage of the PojoCache API. - </para> - <para>For details of configuration, usage and APIs, please refer to the - <ulink url="http://labs.jboss.org/portal/jbosscache/docs/index.html"&g... manual</ulink>. - </para> - </section> - - <section> - <title>What You Will Learn</title> - - <itemizedlist> - <listitem> - <para>PojoCache creation and modification</para> - </listitem> - - <listitem> - <para>Replication of POJO fields</para> - </listitem> - - <listitem> - <para>Using Collections in PojoCache</para> - </listitem> - - <listitem> - <para>Transactions</para> - </listitem> - - </itemizedlist> - </section> - - <section> - <title>Configuration</title> - - <para>First download the JBoss Cache 2.x distribution from - <ulink url="http://labs.jboss.org/portal/jbosscache/download/index.html&quo... download page</ulink> - . You probably want the - <literal>JBossCache-pojo-2.X.Y.zip</literal> - distribution. Unzip it, and you will get a directory containing the distribution, such as - <literal>JBossCache-pojo-2.X.Y</literal> - . - For the sake of this tutorial, I will refer to this as - <literal>PojoCache</literal> - . - </para> - - <para>The configuration files are located under the - <literal>PojoCache/etc</literal> - directory. You can modify the behavior of the underlying cache through editing the various configuration files. - </para> - - <itemizedlist> - <listitem> - <para> - <literal>log4j.xml</literal> - . Logging output. You can enable logging, specify log levels or change the name and path to the log file. - </para> - </listitem> - - <listitem> - <para> - <literal>META-INF/replSync-service.xml</literal> - . Cache configuration file used for this tutorial. - </para> - </listitem> - - <listitem> - <para> - <literal>pojocache-aop.xml</literal> - . PojoCache configuration file that contains, amongst other things, the annotation to use on POJOs so - that they're aspectised. For more information, please the PojoCache - <ulink url="http://labs.jboss.org/portal/jbosscache/docs/index.html"&g... manual</ulink> - . - </para> - </listitem> - </itemizedlist> - </section> - - <section> - <title>Script</title> - - <para>The only script needed for this tutorial is the - <literal>PojoCache/build.xml</literal> - ant script. - </para> - </section> - - <section> - <title>Example POJOs</title> - - <para>The example POJO classes used for PojoCache demo are: - <literal>org.jboss.cache.pojo.test.Person</literal> - and - <literal>org.jboss.cache.pojo.test.Address</literal> - . They are located - under - <literal>tests/functional</literal> - directory.The demo will demonstrate that once a POJO has been attached to the cache, plain get/set POJO methods - will be intercepted by the cache. - </para> - - <para>Here is the snippet of the class definition for - <literal>Person</literal> - and - <literal>Address</literal> - with the - <literal>Replicable</literal> - annotation. - </para> - - <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 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> - - <section> - <title>Running The Demo GUI</title> - - <para> - The demo is run by calling the ant script (via the driver) with the - <literal>run.demo</literal> - target. E.g., - </para> - - <para> - <literal>ant run.demo</literal> - </para> - <para> - This will cause a GUI window to appear, giving you a tree view of the cache in the top pane and a BeanShell - view of the JVM in the lower pane. - </para> - <para> - The BeanShell view is preset with the following variables: - <itemizedlist> - <listitem> - <literal>cache</literal> - - a reference to the PojoCache interface, used by the GUI instance. - </listitem> - <listitem> - <literal>transactionManager</literal> - - a reference to the registered transaction manager. - </listitem> - </itemizedlist> - The references made available to the BeanShell window point to the same cache instance used by the tree view in - the GUI above. - </para> - - <para> - To run the demo as a replicated demo, it is useful to start another command line window and run the ant script - again as you did above. Now you will have two cache instances running in two separate GUIs, replicating state - to each other. - </para> - - </section> - - <section> - <title>Tutorials</title> - It is recommended that you shut down and restart the demo GUI for each of the following tutorials, to ensure - clean caches every time. To inspect POJO attribute changes via GUI, please refer to the PojoCache - <ulink - url="http://labs.jboss.org/portal/jbosscache/docs/index.html"&g... manual - </ulink> - to understand how the POJOs are mapped internally in the cache. - - <section> - <title>PojoCache API, POJO manipulation, and Replication</title> - <para> - For this tutorial, start two instance of the demo GUI. In this tutorial, we will: - - <itemizedlist> - <listitem>Attach POJOs to the cache and see them being replicated.</listitem> - <listitem>After attaching, manipulate the POJOs and see the individual changes replicated.</listitem> - <listitem>Retrieve POJOs from the cache, manipulate them and see the changes replicated.</listitem> - <listitem>Create POJOs that share a common POJO and the consequences of changes to this.</listitem> - <listitem>Detach POJOs from the cache.</listitem> - <listitem>After detaching, manipulates the POJOs and see how the values in the cache are unchanged.</listitem> - </itemizedlist> - - </para> - - <orderedlist> - <listitem>In the 1st GUI instance, create a POJO, i.e. a Person with an Address: - <programlisting role="JAVA"><![CDATA[ - joe = new Person(); - joe.setName("Joe Black"); - joe.setAge(31); - - addr = new Address(); - addr.setCity("Sunnyvale"); - addr.setStreet("123 Albert Ave"); - addr.setZip(94086); - - joe.setAddress(addr); - ]]></programlisting> - </listitem> - - <listitem>Attach the POJO to the cache: - <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 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 role="JAVA"><![CDATA[ - joe = cache.find("pojo/joe"); - - mary = new Person(); - mary.setName("Mary White"); - mary.setAge(30); - - mary.setAddress(joe.getAddress()); - ]]></programlisting> - </listitem> - - <listitem>Attach the new POJO to the cache: - <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 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 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 role="JAVA"><![CDATA[ - joe.setName("Joe White"); - ]]></programlisting> - </listitem> - - </orderedlist> - - </section> - - <section> - <title>Collections</title> - <para> - For this tutorial, start two instances of the demo GUI. In this tutorial, we will: - - <itemizedlist> - <listitem>Attach a POJO to the cache and see it being replicated.</listitem> - <listitem>Set a Collection attribute in this POJO</listitem> - <listitem>Manipulate this Collection attribute and see the changes visible in the GUI and being replicated</listitem> - <listitem>Detach a POJO from the cache.</listitem> - </itemizedlist> - - </para> - - <orderedlist> - <listitem>In the 1st GUI instance, create a POJO with a Collection attribute: - <programlisting role="JAVA"><![CDATA[ - joe = new Person(); - joe.setName("Joe Black"); - - lang = new ArrayList(); - lang.add("Spanish"); - - joe.setLanguages(lang); - ]]></programlisting> - </listitem> - - <listitem>Attach the POJO to the cache: - <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 role="JAVA"><![CDATA[ - proxyLang = joe.getLanguages(); - proxyLang.add("English"); - ]]></programlisting> - </listitem> - - <listitem>Detach the pojo from the cache: - <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 role="JAVA"><![CDATA[ - proxyLang.add("French"); - ]]></programlisting> - </listitem> - - </orderedlist> - </section> - </section> - - <section> - <title>Transactions</title> - <para> - For this tutorial, start two instances instance of the demo GUI. Repeat the exercises in the previous - tutorial, only starting transactions before attaching/detaching nodes or modiying the POJOs. This will depict - how replication only occurs on transaction boundaries. Try rolling back a few transactions as well, to see how - nothing gets replicated in these cases. - </para> - </section> - -</article> Copied: pojo/tags/3.0.0.GA/src/main/docbook/tutorial/en/master.xml (from rev 7140, pojo/trunk/src/main/docbook/tutorial/en/master.xml) =================================================================== --- pojo/tags/3.0.0.GA/src/main/docbook/tutorial/en/master.xml (rev 0) +++ pojo/tags/3.0.0.GA/src/main/docbook/tutorial/en/master.xml 2008-11-14 16:19:25 UTC (rev 7141) @@ -0,0 +1,401 @@ +<?xml version="1.0" encoding="UTF-8"?> +<article lang="en"> + <articleinfo> + <title>PojoCache Tutorial</title> + <releaseinfo>Release 3.0.0</releaseinfo> + <pubdate>November 2008</pubdate> + <author> + <firstname>Ben</firstname> + <surname>Wang</surname> + <email&gt;ben.wang(a)jboss.com&lt;/email&gt; + </author> + <author> + <firstname>Galder</firstname> + <surname>Zamarreño</surname> + <email&gt;galder.zamarreno(a)jboss.com&lt;/email&gt; + </author> + </articleinfo> + + <section> + <title>Introduction</title> + + <para>PojoCache is an in-memory, transactional, and replicated POJO (plain old Java object) cache system that + allows users to operate on a POJO transparently without active user management of either replication or + persistency aspects. This tutorial focuses on the usage of the PojoCache API. + </para> + <para>For details of configuration, usage and APIs, please refer to the + <ulink url="http://labs.jboss.org/portal/jbosscache/docs/index.html"&g... manual</ulink>. + </para> + </section> + + <section> + <title>What You Will Learn</title> + + <itemizedlist> + <listitem> + <para>PojoCache creation and modification</para> + </listitem> + + <listitem> + <para>Replication of POJO fields</para> + </listitem> + + <listitem> + <para>Using Collections in PojoCache</para> + </listitem> + + <listitem> + <para>Transactions</para> + </listitem> + + </itemizedlist> + </section> + + <section> + <title>Configuration</title> + + <para>First download the JBoss Cache 3.x distribution from + <ulink url="http://labs.jboss.org/portal/jbosscache/download/index.html&quo... download page</ulink> + . You probably want the + <literal>JBossCache-pojo-3.X.Y.zip</literal> + distribution. Unzip it, and you will get a directory containing the distribution, such as + <literal>JBossCache-pojo-3.X.Y</literal> + . + For the sake of this tutorial, I will refer to this as + <literal>PojoCache</literal> + . + </para> + + <para>The configuration files are located under the + <literal>PojoCache/etc</literal> + directory. You can modify the behavior of the underlying cache through editing the various configuration files. + </para> + + <itemizedlist> + <listitem> + <para> + <literal>log4j.xml</literal> + . Logging output. You can enable logging, specify log levels or change the name and path to the log file. + </para> + </listitem> + + <listitem> + <para> + <literal>META-INF/replSync-service.xml</literal> + . Cache configuration file used for this tutorial. + </para> + </listitem> + + <listitem> + <para> + <literal>pojocache-aop.xml</literal> + . PojoCache configuration file that contains, amongst other things, the annotation to use on POJOs so + that they're aspectised. For more information, please the PojoCache + <ulink url="http://labs.jboss.org/portal/jbosscache/docs/index.html"&g... manual</ulink> + . + </para> + </listitem> + </itemizedlist> + </section> + + <section> + <title>Script</title> + + <para>The only script needed for this tutorial is the + <literal>PojoCache/build.xml</literal> + ant script. + </para> + </section> + + <section> + <title>Example POJOs</title> + + <para>The example POJO classes used for PojoCache demo are: + <literal>org.jboss.cache.pojo.test.Person</literal> + and + <literal>org.jboss.cache.pojo.test.Address</literal> + . They are located + under + <literal>tests/functional</literal> + directory.The demo will demonstrate that once a POJO has been attached to the cache, plain get/set POJO methods + will be intercepted by the cache. + </para> + + <para>Here is the snippet of the class definition for + <literal>Person</literal> + and + <literal>Address</literal> + with the + <literal>Replicable</literal> + annotation. + </para> + + <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 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> + + <section> + <title>Running The Demo GUI</title> + + <para> + The demo is run by calling the ant script (via the driver) with the + <literal>run.demo</literal> + target. E.g., + </para> + + <para> + <literal>ant run.demo</literal> + </para> + <para> + This will cause a GUI window to appear, giving you a tree view of the cache in the top pane and a BeanShell + view of the JVM in the lower pane. + </para> + <para> + The BeanShell view is preset with the following variables: + <itemizedlist> + <listitem> + <literal>cache</literal> + - a reference to the PojoCache interface, used by the GUI instance. + </listitem> + <listitem> + <literal>transactionManager</literal> + - a reference to the registered transaction manager. + </listitem> + </itemizedlist> + The references made available to the BeanShell window point to the same cache instance used by the tree view in + the GUI above. + </para> + + <para> + To run the demo as a replicated demo, it is useful to start another command line window and run the ant script + again as you did above. Now you will have two cache instances running in two separate GUIs, replicating state + to each other. + </para> + + </section> + + <section> + <title>Tutorials</title> + It is recommended that you shut down and restart the demo GUI for each of the following tutorials, to ensure + clean caches every time. To inspect POJO attribute changes via GUI, please refer to the PojoCache + <ulink + url="http://labs.jboss.org/portal/jbosscache/docs/index.html"&g... manual + </ulink> + to understand how the POJOs are mapped internally in the cache. + + <section> + <title>PojoCache API, POJO manipulation, and Replication</title> + <para> + For this tutorial, start two instance of the demo GUI. In this tutorial, we will: + + <itemizedlist> + <listitem>Attach POJOs to the cache and see them being replicated.</listitem> + <listitem>After attaching, manipulate the POJOs and see the individual changes replicated.</listitem> + <listitem>Retrieve POJOs from the cache, manipulate them and see the changes replicated.</listitem> + <listitem>Create POJOs that share a common POJO and the consequences of changes to this.</listitem> + <listitem>Detach POJOs from the cache.</listitem> + <listitem>After detaching, manipulates the POJOs and see how the values in the cache are unchanged.</listitem> + </itemizedlist> + + </para> + + <orderedlist> + <listitem>In the 1st GUI instance, create a POJO, i.e. a Person with an Address: + <programlisting role="JAVA"><![CDATA[ + joe = new Person(); + joe.setName("Joe Black"); + joe.setAge(31); + + addr = new Address(); + addr.setCity("Sunnyvale"); + addr.setStreet("123 Albert Ave"); + addr.setZip(94086); + + joe.setAddress(addr); + ]]></programlisting> + </listitem> + + <listitem>Attach the POJO to the cache: + <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 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 role="JAVA"><![CDATA[ + joe = cache.find("pojo/joe"); + + mary = new Person(); + mary.setName("Mary White"); + mary.setAge(30); + + mary.setAddress(joe.getAddress()); + ]]></programlisting> + </listitem> + + <listitem>Attach the new POJO to the cache: + <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 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 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 role="JAVA"><![CDATA[ + joe.setName("Joe White"); + ]]></programlisting> + </listitem> + + </orderedlist> + + </section> + + <section> + <title>Collections</title> + <para> + For this tutorial, start two instances of the demo GUI. In this tutorial, we will: + + <itemizedlist> + <listitem>Attach a POJO to the cache and see it being replicated.</listitem> + <listitem>Set a Collection attribute in this POJO</listitem> + <listitem>Manipulate this Collection attribute and see the changes visible in the GUI and being replicated</listitem> + <listitem>Detach a POJO from the cache.</listitem> + </itemizedlist> + + </para> + + <orderedlist> + <listitem>In the 1st GUI instance, create a POJO with a Collection attribute: + <programlisting role="JAVA"><![CDATA[ + joe = new Person(); + joe.setName("Joe Black"); + + lang = new ArrayList(); + lang.add("Spanish"); + + joe.setLanguages(lang); + ]]></programlisting> + </listitem> + + <listitem>Attach the POJO to the cache: + <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 role="JAVA"><![CDATA[ + proxyLang = joe.getLanguages(); + proxyLang.add("English"); + ]]></programlisting> + </listitem> + + <listitem>Detach the pojo from the cache: + <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 role="JAVA"><![CDATA[ + proxyLang.add("French"); + ]]></programlisting> + </listitem> + + </orderedlist> + </section> + </section> + + <section> + <title>Transactions</title> + <para> + For this tutorial, start two instances instance of the demo GUI. Repeat the exercises in the previous + tutorial, only starting transactions before attaching/detaching nodes or modiying the POJOs. This will depict + how replication only occurs on transaction boundaries. Try rolling back a few transactions as well, to see how + nothing gets replicated in these cases. + </para> + </section> + +</article>