Author: manik.surtani(a)jboss.com Date: 2008-03-09 17:54:23 -0400 (Sun, 09 Mar 2008) New Revision: 5406 Modified: core/trunk/pom.xml core/trunk/src/main/docbook/faq/en/master.xml core/trunk/src/main/docbook/tutorial/en/master.xml core/trunk/src/main/docbook/userguide/en/modules/basic_api.xml core/trunk/src/main/docbook/userguide/en/modules/cache_loaders.xml core/trunk/src/main/docbook/userguide/en/modules/configuration.xml core/trunk/src/main/docbook/userguide/en/modules/configuration_reference.xml core/trunk/src/main/docbook/userguide/en/modules/deployment.xml core/trunk/src/main/docbook/userguide/en/modules/eviction_policies.xml core/trunk/src/main/docbook/userguide/en/modules/replication.xml core/trunk/src/main/docbook/userguide/en/modules/transactions.xml Log: Updated pom.xml to use latest JBoss.org LnF and updated program listings in docs Modified: core/trunk/pom.xml =================================================================== --- core/trunk/pom.xml 2008-03-09 21:52:37 UTC (rev 5405) +++ core/trunk/pom.xml 2008-03-09 21:54:23 UTC (rev 5406) @@ -164,14 +164,29 @@ <dependency> <groupId>org.jboss</groupId> <artifactId>jbossorg-docbook-xslt</artifactId> - <version>1.0.0</version> + <version>1.1.0-SNAPSHOT</version> </dependency> <dependency> <groupId>org.jboss</groupId> <artifactId>jbossorg-jdocbook-style</artifactId> - <version>1.0.0</version> + <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> Modified: core/trunk/src/main/docbook/faq/en/master.xml =================================================================== --- core/trunk/src/main/docbook/faq/en/master.xml 2008-03-09 21:52:37 UTC (rev 5405) +++ core/trunk/src/main/docbook/faq/en/master.xml 2008-03-09 21:54:23 UTC (rev 5406) @@ -150,8 +150,9 @@ JBoss Cache has an active community of developers and contributors. The project was founded by Bela Ban and is currently led by Manik Surtani. Jason Greene is the lead for the PojoCache subsystem, and other - contributors both past and present include Ben Wang, Harald Gliebe, Brian Stansberry, Galder Zamarreno - and Elias Ross. + contributors both past and present include Ben Wang, Harald Gliebe, Brian Stansberry, Vladimir + Blagojevic, + Mircea Markus, Jimmy Wilson, Galder Zamarreño and Elias Ross. </para> </answer> </qandaentry> @@ -1066,37 +1067,38 @@ </para> <programlisting role="JAVA"> - import org.jboss.invocation.MarshalledValue; + <![CDATA[ +import org.jboss.invocation.MarshalledValue; - public class CacheService - { - private Cache cache; +public class CacheService +{ + private Cache cache; - public Object get(Fqn fqn, String key) - { - return getUnMarshalledValue(cache.get(fqn, key)); - } + public Object get(Fqn fqn, String key) + { + return getUnMarshalledValue(cache.get(fqn, key)); + } - public Object set(Fqn fqn, String key, Object value) - { - cache.put(fqn, key, getMarshalledValue(value)); - return value; // only if successful - } + public Object set(Fqn fqn, String key, Object value) + { + cache.put(fqn, key, getMarshalledValue(value)); + return value; // only if successful + } - ... + ... - private Object getUnMarshalledValue(object value) - { - // assuming we use the calling thread context classloader - return ((MarshalledValue)value).get(); - } + private Object getUnMarshalledValue(object value) + { + // assuming we use the calling thread context classloader + return ((MarshalledValue)value).get(); + } - private Object getMarshalledValue(Object value) - { - return new MarshalledValue(value); - } - } - </programlisting> + private Object getMarshalledValue(Object value) + { + return new MarshalledValue(value); + } +} +]]></programlisting> </answer> </qandaentry> Modified: core/trunk/src/main/docbook/tutorial/en/master.xml =================================================================== --- core/trunk/src/main/docbook/tutorial/en/master.xml 2008-03-09 21:52:37 UTC (rev 5405) +++ core/trunk/src/main/docbook/tutorial/en/master.xml 2008-03-09 21:54:23 UTC (rev 5406) @@ -172,95 +172,66 @@ <listitem>Remove nodes under the root node, both individually and recursively.</listitem> <listitem>Add and remove data from nodes.</listitem> </itemizedlist> + </para> - <orderedlist> - <listitem>Set up the Fqns you need. In the BeanShell pane, create 3 Fqn variables: - <programlisting role="JAVA"><![CDATA[ - + <para>1. Set up the Fqns you need. In the BeanShell pane, create 3 Fqn variables:</para> + <programlisting role="JAVA"><![CDATA[ childFqn1 = Fqn.fromString("/child1"); childFqn2 = Fqn.fromString("/child2"); childFqn3 = Fqn.fromString("/child2/child3"); - ]]></programlisting> - </listitem> - <listitem> - Create child nodes under the root node. - <programlisting role="JAVA"><![CDATA[ - + <para>2. Create child nodes under the root node.</para> + <programlisting role="JAVA"><![CDATA[ child1 = root.addChild(childFqn1); child2 = root.addChild(childFqn2); child3 = root.addChild(childFqn3); - ]]></programlisting> - </listitem> - <listitem> - Query the nodes - <programlisting role="JAVA"><![CDATA[ + <para>3. Query the nodes.</para> + <programlisting role="JAVA"><![CDATA[ root.hasChild(childFqn1); // should return true child2.hasChild(childFqn3.getLastElement()); // should return true child3.getParent(); // should return child2 child2.getParent(); // should return root - ]]></programlisting> - </listitem> - - <listitem> - Put some data in the nodes. - <programlisting role="JAVA"><![CDATA[ - + <para>4. Put some data in the nodes. By selecting the nodes in the tree view, you should see the contents of + each node. + </para> + <programlisting role="JAVA"><![CDATA[ child1.put("key1", "value1"); child1.put("key2", "value2"); child2.put("key3", "value3"); child2.put("key4", "value4"); child3.put("key5", "value5"); child3.put("key6", "value6"); - ]]></programlisting> - By selecting the nodes in the tree view, you should see the contents of each node. - </listitem> + <para>5. Query some of the data.</para> - <listitem> - Query some of the data. - - <programlisting role="JAVA"><![CDATA[ - + <programlisting role="JAVA"><![CDATA[ child1.getKeys(); child2.getData(); - ]]></programlisting> - </listitem> + <para>6. Remove some data in the nodes.</para> - <listitem> - Remove some data in the nodes. - - <programlisting role="JAVA"><![CDATA[ - + <programlisting role="JAVA"><![CDATA[ child1.remove("key1"); child2.remove("key3"); child3.clearData(); - ]]></programlisting> - </listitem> - <listitem> - Delete nodes + <para>7. Delete nodes</para> - <programlisting role="JAVA"><![CDATA[ - + <programlisting role="JAVA"><![CDATA[ root.removeChild(childFqn1); // will also remove any data held under child1 root.removeChild(childFqn2); // will recursively remove child3 as well. - ]]></programlisting> - </listitem> - </orderedlist> - + <para> In addition to the above, you should refer to the <literal>Cache</literal> and @@ -292,15 +263,13 @@ replication only occurs on transaction boundaries. Try rolling back a few transactions as well, to see how nothing gets replicated in these cases. Below is the sample code for managing transactions: - <programlisting role="JAVA"><![CDATA[ - + </para> + <programlisting role="JAVA"><![CDATA[ tm = cache.getTransactionManager(); tm.begin(); - //do the operations here - tm.commit();//tm.rollback(); - + // do operations here + tm.commit(); // tm.rollback(); ]]></programlisting> - </para> </section> </section> Modified: core/trunk/src/main/docbook/userguide/en/modules/basic_api.xml =================================================================== --- core/trunk/src/main/docbook/userguide/en/modules/basic_api.xml 2008-03-09 21:52:37 UTC (rev 5405) +++ core/trunk/src/main/docbook/userguide/en/modules/basic_api.xml 2008-03-09 21:54:23 UTC (rev 5406) @@ -90,10 +90,10 @@ a cache, using the default configuration values: </para> - <programlisting role="JAVA"> - CacheFactory factory = DefaultCacheFactory.getInstance(); - Cache cache = factory.createCache(); - </programlisting> + <programlisting role="JAVA"><![CDATA[ + CacheFactory factory = DefaultCacheFactory.getInstance(); + Cache cache = factory.createCache(); + ]]></programlisting> <para>Here we tell the <literal>CacheFactory</literal> @@ -101,26 +101,26 @@ parse a configuration file on the classpath: </para> - <programlisting role="JAVA"> - CacheFactory factory = DefaultCacheFactory.getInstance(); - Cache cache = factory.createCache("cache-configuration.xml"); - </programlisting> + <programlisting role="JAVA"><![CDATA[ + CacheFactory factory = DefaultCacheFactory.getInstance(); + Cache cache = factory.createCache("cache-configuration.xml"); + ]]></programlisting> <para>Here we configure the cache from a file, but want to programatically change a configuration element. So, we tell the factory not to start the cache, and instead do it ourselves: </para> - <programlisting role="JAVA"> - CacheFactory factory = DefaultCacheFactory.getInstance(); - Cache cache = factory.createCache("cache-configuration.xml", false); - Configuration config = cache.getConfiguration(); - config.setClusterName(this.getClusterName()); + <programlisting role="JAVA"><![CDATA[ + CacheFactory factory = DefaultCacheFactory.getInstance(); + Cache cache = factory.createCache("cache-configuration.xml", false); + Configuration config = cache.getConfiguration(); + config.setClusterName(this.getClusterName()); - // Have to create and start cache before using it - cache.create(); - cache.start(); - </programlisting> + // Have to create and start cache before using it + cache.create(); + cache.start(); + ]]></programlisting> </section> @@ -135,42 +135,42 @@ in the cache and then do some simple reads and writes to that node. </para> - <programlisting role="JAVA"> - // Let's get ahold of the root node. - Node rootNode = cache.getRoot(); + <programlisting role="JAVA"><![CDATA[ + // Let's get ahold of the root node. + Node rootNode = cache.getRoot(); - // Remember, JBoss Cache stores data in a tree structure. - // All nodes in the tree structure are identified by Fqn objects. - Fqn peterGriffinFqn = Fqn.fromString("/griffin/peter"); + // Remember, JBoss Cache stores data in a tree structure. + // All nodes in the tree structure are identified by Fqn objects. + Fqn peterGriffinFqn = Fqn.fromString("/griffin/peter"); - // Create a new Node - Node peterGriffin = rootNode.addChild(peterGriffinFqn); + // Create a new Node + Node peterGriffin = rootNode.addChild(peterGriffinFqn); - // let's store some data in the node - peterGriffin.put("isCartoonCharacter", Boolean.TRUE); - peterGriffin.put("favouriteDrink", new Beer()); + // let's store some data in the node + peterGriffin.put("isCartoonCharacter", Boolean.TRUE); + peterGriffin.put("favouriteDrink", new Beer()); - // some tests (just assume this code is in a JUnit test case) - assertTrue(peterGriffin.get("isCartoonCharacter")); - assertEquals(peterGriffinFqn, peterGriffin.getFqn()); - assertTrue(rootNode.hasChild(peterGriffinFqn)); + // some tests (just assume this code is in a JUnit test case) + assertTrue(peterGriffin.get("isCartoonCharacter")); + assertEquals(peterGriffinFqn, peterGriffin.getFqn()); + assertTrue(rootNode.hasChild(peterGriffinFqn)); - Set keys = new HashSet(); - keys.add("isCartoonCharacter"); - keys.add("favouriteDrink"); + Set keys = new HashSet(); + keys.add("isCartoonCharacter"); + keys.add("favouriteDrink"); - assertEquals(keys, peterGriffin.getKeys()); + assertEquals(keys, peterGriffin.getKeys()); - // let's remove some data from the node - peterGriffin.remove("favouriteDrink"); + // let's remove some data from the node + peterGriffin.remove("favouriteDrink"); - assertNull(peterGriffin.get("favouriteDrink"); + assertNull(peterGriffin.get("favouriteDrink"); - // let's remove the node altogether - rootNode.removeChild(peterGriffinFqn); + // let's remove the node altogether + rootNode.removeChild(peterGriffinFqn); - assertFalse(rootNode.hasChild(peterGriffinFqn)); - </programlisting> + assertFalse(rootNode.hasChild(peterGriffinFqn)); + ]]></programlisting> <para> The @@ -181,23 +181,23 @@ as an argument: </para> - <programlisting role="JAVA"> - Fqn peterGriffinFqn = Fqn.fromString("/griffin/peter"); + <programlisting role="JAVA"><![CDATA[ + Fqn peterGriffinFqn = Fqn.fromString("/griffin/peter"); - cache.put(peterGriffinFqn, "isCartoonCharacter", Boolean.TRUE); - cache.put(peterGriffinFqn, "favouriteDrink", new Beer()); + cache.put(peterGriffinFqn, "isCartoonCharacter", Boolean.TRUE); + cache.put(peterGriffinFqn, "favouriteDrink", new Beer()); - assertTrue(peterGriffin.get(peterGriffinFqn, "isCartoonCharacter")); - assertTrue(cache.getRootNode().hasChild(peterGriffinFqn)); + assertTrue(peterGriffin.get(peterGriffinFqn, "isCartoonCharacter")); + assertTrue(cache.getRootNode().hasChild(peterGriffinFqn)); - cache.remove(peterGriffinFqn, "favouriteDrink"); + cache.remove(peterGriffinFqn, "favouriteDrink"); - assertNull(cache.get(peterGriffinFqn, "favouriteDrink"); + assertNull(cache.get(peterGriffinFqn, "favouriteDrink"); - cache.removeNode(peterGriffinFqn); + cache.removeNode(peterGriffinFqn); - assertFalse(cache.getRootNode().hasChild(peterGriffinFqn)); - </programlisting> + assertFalse(cache.getRootNode().hasChild(peterGriffinFqn)); + ]]></programlisting> </section> <section id="basic_api.fqn"> @@ -243,35 +243,29 @@ most commonly used approaches to creating an Fqn: </para> - <programlisting role="JAVA"> - <![CDATA[ - // Create an Fqn pointing to node 'Joe' under parent node 'Smith' - // under the 'people' section of the tree + <programlisting role="JAVA"><![CDATA[ + // Create an Fqn pointing to node 'Joe' under parent node 'Smith' + // under the 'people' section of the tree - // Parse it from a String - Fqn<String> abc = Fqn.fromString("/people/Smith/Joe/"); + // Parse it from a String + Fqn<String> abc = Fqn.fromString("/people/Smith/Joe/"); - // Build it directly. A bit more efficient to construct than parsing - String[] strings = new String[] { "people", "Smith", "Joe" }; - Fqn<String> abc = new Fqn<String>(strings); + // Build it directly. Marginally more efficient to construct than parsing + String[] strings = new String[] { "people", "Smith", "Joe" }; + Fqn<String> abc = new Fqn<String>(strings); - // Here we want to use types other than String - Object[] objs = new Object[]{ "accounts", "NY", new Integer(12345) }; - Fqn<Object> acctFqn = new Fqn<Object>(objs); - ]]> - </programlisting> + // Here we want to use types other than String + Object[] objs = new Object[]{ "accounts", "NY", new Integer(12345) }; + Fqn<Object> acctFqn = new Fqn<Object>(objs); + ]]></programlisting> <para>Note that</para> - <para> - <programlisting role="JAVA"><![CDATA[Fqn<String> f = new Fqn<String>("/a/b/c");]]></programlisting> - </para> + <programlisting role="JAVA"><![CDATA[Fqn<String> f = new Fqn<String>("/a/b/c");]]></programlisting> <para>is <emphasis>not</emphasis> the same as </para> - <para> - <programlisting role="JAVA"><![CDATA[Fqn<String> f = Fqn.fromString("/a/b/c");]]></programlisting> - </para> + <programlisting role="JAVA"><![CDATA[Fqn<String> f = Fqn.fromString("/a/b/c");]]></programlisting> <para> The former will result in an Fqn with a single element, called "/a/b/c" @@ -287,7 +281,9 @@ <para> The JBoss Cache API in the 1.x releases included many overloaded - convenience methods that took a string in the "/a/b/c" format in place + convenience methods that took a string in the + <literal>/a/b/c</literal> + format in place of an <literal>Fqn</literal> . In the interests of API simplicity, no @@ -305,10 +301,10 @@ resources like the JGroups channel are properly cleaned up. </para> - <programlisting role="JAVA"> - cache.stop(); - cache.destroy(); - </programlisting> + <programlisting role="JAVA"><![CDATA[ + cache.stop(); + cache.destroy(); + ]]></programlisting> <para> Not also that a cache that has had @@ -589,8 +585,8 @@ </para> <para> Example: - <programlisting role="JAVA"><![CDATA[ - + </para> + <programlisting role="JAVA"><![CDATA[ @CacheListener public class MyListener { @@ -620,9 +616,7 @@ log("An event on node " + ne.getFqn() + " has occured"); } } - ]]></programlisting> - </para> </section> <section> Modified: core/trunk/src/main/docbook/userguide/en/modules/cache_loaders.xml =================================================================== --- core/trunk/src/main/docbook/userguide/en/modules/cache_loaders.xml 2008-03-09 21:52:37 UTC (rev 5405) +++ core/trunk/src/main/docbook/userguide/en/modules/cache_loaders.xml 2008-03-09 21:54:23 UTC (rev 5406) @@ -147,9 +147,7 @@ details. </para> - <programlisting role="XML"> - <![CDATA[ - + <programlisting role="XML"><![CDATA[ ... <!-- Cache loader config block --> @@ -213,8 +211,7 @@ </config> </attribute> -]]> - </programlisting> +]]></programlisting> <para>The <literal>class</literal> @@ -800,9 +797,7 @@ configuration. </para> - <para> - <programlisting role="XML"> - <![CDATA[ + <programlisting role="XML"><![CDATA[ <attribute name="CacheLoaderConfiguration"> <config> <passivation>false</passivation> @@ -834,16 +829,13 @@ </cacheloader> </config> </attribute> -]]> - </programlisting> - </para> +]]></programlisting> <para>As an alternative to configuring the entire JDBC connection, the name of an existing data source can be given: </para> - <programlisting role="XML"> - <![CDATA[ + <programlisting role="XML"><![CDATA[ <attribute name="CacheLoaderConfiguration"> <config> <passivation>false</passivation> @@ -862,13 +854,11 @@ </cacheloader> </config> </attribute> -]]> - </programlisting> +]]></programlisting> <para>Cconfiguration example for a cache loader using c3p0 JDBC connection pooling:</para> - <programlisting role="XML"> - <![CDATA[ + <programlisting role="XML"><![CDATA[ <attribute name="CacheLoaderConfiguration"> <config> <passivation>false</passivation> @@ -903,8 +893,7 @@ </cacheloader> </config> </attribute> -]]> - </programlisting> +]]></programlisting> </section> </section> @@ -952,8 +941,7 @@ <para>The configuration looks as follows:</para> - <programlisting role="XML"> - <![CDATA[ + <programlisting role="XML"><![CDATA[ <attribute name="CacheLoaderConfiguration"> <config> <cacheloader> @@ -967,8 +955,7 @@ </cacheloader> </config> </attribute> -]]> - </programlisting> +]]></programlisting> <para>This means this instance of JBoss Cache will delegate all load and store requests to the remote TcpCacheServer running on Modified: core/trunk/src/main/docbook/userguide/en/modules/configuration.xml =================================================================== --- core/trunk/src/main/docbook/userguide/en/modules/configuration.xml 2008-03-09 21:52:37 UTC (rev 5405) +++ core/trunk/src/main/docbook/userguide/en/modules/configuration.xml 2008-03-09 21:54:23 UTC (rev 5406) @@ -64,8 +64,7 @@ <para> Here is a simple example configuration file: </para> - <programlisting role="XML"> - <![CDATA[ + <programlisting role="XML"><![CDATA[ <?xml version="1.0" encoding="UTF-8"?> <!-- ===================================================================== --> @@ -119,8 +118,7 @@ </attribute> </mbean> </server> -]]> - </programlisting> +]]></programlisting> <para> Another, more complete, sample XML file is included in the @@ -154,10 +152,10 @@ classpath: </para> - <programlisting role="JAVA"> - CacheFactory factory = DefaultCacheFactory.getInstance(); - Cache cache = factory.createCache("cache-configuration.xml"); - </programlisting> + <programlisting role="JAVA"><![CDATA[ + CacheFactory factory = DefaultCacheFactory.getInstance(); + Cache cache = factory.createCache("cache-configuration.xml"); + ]]></programlisting> </section> @@ -185,40 +183,38 @@ : </para> - <programlisting role="JAVA"> - <![CDATA[ - Configuration config = new Configuration(); - String tmlc = GenericTransactionManagerLookup.class.getName(); - config.setTransactionManagerLookupClass(tmlc); - config.setIsolationLevel(IsolationLevel.READ_COMMITTED); - config.setCacheMode(CacheMode.LOCAL); - config.setLockParentForChildInsertRemove(true); - config.setLockAcquisitionTimeout(15000); - - EvictionConfig ec = new EvictionConfig(); - ec.setWakeupIntervalSeconds(5); - ec.setDefaultEvictionPolicyClass(LRUPolicy.class.getName()); - - EvictionRegionConfig erc = new EvictionRegionConfig(); - erc.setRegionName("_default_"); - - LRUConfiguration lru = new LRUConfiguration(); - lru.setMaxNodes(5000); - lru.setTimeToLiveSeconds(1000); - - erc.setEvictionPolicyConfig(lru); - - List<EvictionRegionConfig> ercs = new ArrayList<EvictionRegionConfig>(); - ercs.add(erc); - ec.setEvictionRegionConfigs(erc); - - config.setEvictionConfig(ec); - - CacheFactory factory = DefaultCacheFactory.getInstance(); - Cache cache = factory.createCache(config); -]]> - </programlisting> + <programlisting role="JAVA"><![CDATA[ + Configuration config = new Configuration(); + String tmlc = GenericTransactionManagerLookup.class.getName(); + config.setTransactionManagerLookupClass(tmlc); + config.setIsolationLevel(IsolationLevel.READ_COMMITTED); + config.setCacheMode(CacheMode.LOCAL); + config.setLockParentForChildInsertRemove(true); + config.setLockAcquisitionTimeout(15000); + EvictionConfig ec = new EvictionConfig(); + ec.setWakeupIntervalSeconds(5); + ec.setDefaultEvictionPolicyClass(LRUPolicy.class.getName()); + + EvictionRegionConfig erc = new EvictionRegionConfig(); + erc.setRegionName("_default_"); + + LRUConfiguration lru = new LRUConfiguration(); + lru.setMaxNodes(5000); + lru.setTimeToLiveSeconds(1000); + + erc.setEvictionPolicyConfig(lru); + + List<EvictionRegionConfig> ercs = new ArrayList<EvictionRegionConfig>(); + ercs.add(erc); + ec.setEvictionRegionConfigs(erc); + + config.setEvictionConfig(ec); + + CacheFactory factory = DefaultCacheFactory.getInstance(); + Cache cache = factory.createCache(config); +]]></programlisting> + <para> Even the above fairly simple configuration is pretty tedious programming; hence the preferred use of XML-based configuration. However, if your @@ -390,12 +386,12 @@ by programmatically obtaining the <literal>Configuration</literal> object from the running cache and changing values. E.g., - <programlisting role="JAVA"> - - Configuration liveConfig = cache.getConfiguration(); - liveConfig.setLockAcquisitionTimeout(2000); - - </programlisting> + </para> + <programlisting role="JAVA"><![CDATA[ + Configuration liveConfig = cache.getConfiguration(); + liveConfig.setLockAcquisitionTimeout(2000); + ]]></programlisting> + <para> A complete listing of which options may be changed dynamically is in the <link linkend="configuration_reference">configuration reference</link> section. An @@ -420,24 +416,21 @@ </para> <para> E.g., to override the default node versioning used with optimistic locking: - <programlisting role="JAVA"> - - DataVersion v = new MyCustomDataVersion(); - cache.getInvocationContext().getOptionOverrides().setDataVersion(v); - Node ch = cache.getRoot().addChild(Fqn.fromString("/a/b/c")); - - </programlisting> </para> + <programlisting role="JAVA"><![CDATA[ + DataVersion v = new MyCustomDataVersion(); + cache.getInvocationContext().getOptionOverrides().setDataVersion(v); + Node ch = cache.getRoot().addChild(Fqn.fromString("/a/b/c")); +]]></programlisting> + <para> E.g., to suppress replication of a put call in a REPL_SYNC cache: - <programlisting role="JAVA"> - - Node node = cache.getChild(Fqn.fromString("/a/b/c")); - cache.getInvocationContext().getOptionOverrides().setLocalOnly(true); - node.put("localCounter", new Integer(2)); - - </programlisting> </para> + <programlisting role="JAVA"><![CDATA[ + Node node = cache.getChild(Fqn.fromString("/a/b/c")); + cache.getInvocationContext().getOptionOverrides().setLocalOnly(true); + node.put("localCounter", new Integer(2)); + ]]></programlisting> <para> See the javadocs on the <literal>Option</literal> Modified: core/trunk/src/main/docbook/userguide/en/modules/configuration_reference.xml =================================================================== --- core/trunk/src/main/docbook/userguide/en/modules/configuration_reference.xml 2008-03-09 21:52:37 UTC (rev 5405) +++ core/trunk/src/main/docbook/userguide/en/modules/configuration_reference.xml 2008-03-09 21:54:23 UTC (rev 5406) @@ -7,8 +7,7 @@ configurations shipped with the JBoss Cache distribution and tweak according to your needs rather than write one from scratch. </para> - <programlisting role="XML"> - <![CDATA[ + <programlisting role="XML"><![CDATA[ <?xml version="1.0" encoding="UTF-8"?> <!-- ===================================================================== --> @@ -157,8 +156,7 @@ </attribute> </mbean> </server> -]]> - </programlisting> +]]></programlisting> </section> Modified: core/trunk/src/main/docbook/userguide/en/modules/deployment.xml =================================================================== --- core/trunk/src/main/docbook/userguide/en/modules/deployment.xml 2008-03-09 21:52:37 UTC (rev 5405) +++ core/trunk/src/main/docbook/userguide/en/modules/deployment.xml 2008-03-09 21:54:23 UTC (rev 5406) @@ -106,17 +106,15 @@ the cache: </para> - <programlisting role="JAVA"> - <![CDATA[ - MBeanServer server = MBeanServerLocator.locateJBoss(); - ObjectName on = new ObjectName("jboss.cache:service=Cache"); - CacheJmxWrapperMBean cacheWrapper = - (CacheJmxWrapperMBean) MBeanServerInvocationHandler.newProxyInstance(server, on, - CacheJmxWrapperMBean.class, false); - Cache cache = cacheWrapper.getCache(); - Node root = cache.getRoot(); // etc etc - ]]> - </programlisting> + <programlisting role="JAVA"><![CDATA[ + MBeanServer server = MBeanServerLocator.locateJBoss(); + ObjectName on = new ObjectName("jboss.cache:service=Cache"); + CacheJmxWrapperMBean cacheWrapper = + (CacheJmxWrapperMBean) MBeanServerInvocationHandler.newProxyInstance(server, on, + CacheJmxWrapperMBean.class, false); + Cache cache = cacheWrapper.getCache(); + Node root = cache.getRoot(); // etc etc + ]]></programlisting> <para>The MBeanServerLocator class is a helper to find the (only) JBoss MBean server inside the current JVM. The @@ -186,8 +184,7 @@ installation, you can find several more examples. </para> - <programlisting role="XML"> - <![CDATA[ + <programlisting role="XML"><![CDATA[ <?xml version="1.0" encoding="UTF-8"?> <deployment xmlns="urn:jboss:bean-deployer:2.0"> @@ -293,8 +290,7 @@ </bean> </deployment> -]]> - </programlisting> +]]></programlisting> <para> See the JBoss Microcontainer documentation @@ -445,31 +441,31 @@ constructor. </para> - <programlisting role="JAVA"> - CacheFactory factory = DefaultCacheFactory.getInstance(); - // Build but don't start the cache - // (although it would work OK if we started it) - Cache cache = factory.createCache("cache-configuration.xml", false); + <programlisting role="JAVA"><![CDATA[ + CacheFactory factory = DefaultCacheFactory.getInstance(); + // Build but don't start the cache + // (although it would work OK if we started it) + Cache cache = factory.createCache("cache-configuration.xml", false); - CacheJmxWrapperMBean wrapper = new CacheJmxWrapper(cache); - MBeanServer server = getMBeanServer(); // however you do it - ObjectName on = new ObjectName("jboss.cache:service=TreeCache"); - server.registerMBean(wrapper, on); + CacheJmxWrapperMBean wrapper = new CacheJmxWrapper(cache); + MBeanServer server = getMBeanServer(); // however you do it + ObjectName on = new ObjectName("jboss.cache:service=TreeCache"); + server.registerMBean(wrapper, on); - // Invoking lifecycle methods on the wrapper results - // in a call through to the cache - wrapper.create(); - wrapper.start(); + // Invoking lifecycle methods on the wrapper results + // in a call through to the cache + wrapper.create(); + wrapper.start(); - ... use the cache + ... use the cache - ... on application shutdown + ... on application shutdown - // Invoking lifecycle methods on the wrapper results - // in a call through to the cache - wrapper.stop(); - wrapper.destroy(); - </programlisting> + // Invoking lifecycle methods on the wrapper results + // in a call through to the cache + wrapper.stop(); + wrapper.destroy(); + ]]></programlisting> <para> Alternatively, build a @@ -483,29 +479,28 @@ : </para> - <programlisting role="JAVA"> - Configuration config = buildConfiguration(); // whatever it does + <programlisting role="JAVA"><![CDATA[ + Configuration config = buildConfiguration(); // whatever it does - CacheJmxWrapperMBean wrapper = new CacheJmxWrapper(config); - MBeanServer server = getMBeanServer(); // however you do it - ObjectName on = new ObjectName("jboss.cache:service=TreeCache"); - server.registerMBean(wrapper, on); + CacheJmxWrapperMBean wrapper = new CacheJmxWrapper(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(); + // 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 - Cache cache = wrapper.getCache(); + // Now that it's built, created and started, get the cache from the wrapper + Cache cache = wrapper.getCache(); - ... use the cache + ... use the cache - ... on application shutdown + ... on application shutdown - wrapper.stop(); - wrapper.destroy(); - - </programlisting> + wrapper.stop(); + wrapper.destroy(); + ]]></programlisting> </section> <section> @@ -542,8 +537,7 @@ bean: </para> - <programlisting role="XML"> - <![CDATA[ + <programlisting role="XML"><![CDATA[ <?xml version="1.0" encoding="UTF-8"?> <deployment xmlns="urn:jboss:bean-deployer:2.0"> @@ -587,8 +581,7 @@ </bean> </deployment> -]]> - </programlisting> +]]></programlisting> <para> As discussed in the @@ -608,8 +601,7 @@ : </para> - <programlisting role="XML"> - <![CDATA[ + <programlisting role="XML"><![CDATA[ <?xml version="1.0" encoding="UTF-8"?> <deployment xmlns="urn:jboss:bean-deployer:2.0"> @@ -635,8 +627,7 @@ </bean> </deployment> -]]> - </programlisting> +]]></programlisting> </section> </section> @@ -763,73 +754,69 @@ JBoss AS environment. In this example, the client uses a filter to specify which events are of interest. </para> - <programlisting role="JAVA"> - <![CDATA[ - MyListener listener = new MyListener(); - NotificationFilterSupport filter = null; + <programlisting role="JAVA"><![CDATA[ + MyListener listener = new MyListener(); + NotificationFilterSupport filter = null; - // get reference to MBean server - Context ic = new InitialContext(); - MBeanServerConnection server = (MBeanServerConnection)ic.lookup("jmx/invoker/RMIAdaptor"); + // get reference to MBean server + Context ic = new InitialContext(); + MBeanServerConnection server = (MBeanServerConnection)ic.lookup("jmx/invoker/RMIAdaptor"); - // get reference to CacheMgmtInterceptor MBean - String cache_service = "jboss.cache:service=TomcatClusteringCache"; - ObjectName mgmt_name = new ObjectName(cache_service); + // get reference to CacheMgmtInterceptor MBean + String cache_service = "jboss.cache:service=TomcatClusteringCache"; + ObjectName mgmt_name = new ObjectName(cache_service); - // configure a filter to only receive node created and removed events - filter = new NotificationFilterSupport(); - filter.disableAllTypes(); - filter.enableType(CacheNotificationBroadcaster.NOTIF_NODE_CREATED); - filter.enableType(CacheNotificationBroadcaster.NOTIF_NODE_REMOVED); + // configure a filter to only receive node created and removed events + filter = new NotificationFilterSupport(); + filter.disableAllTypes(); + filter.enableType(CacheNotificationBroadcaster.NOTIF_NODE_CREATED); + filter.enableType(CacheNotificationBroadcaster.NOTIF_NODE_REMOVED); - // register the listener with a filter - // leave the filter null to receive all cache events - server.addNotificationListener(mgmt_name, listener, filter, null); + // register the listener with a filter + // leave the filter null to receive all cache events + server.addNotificationListener(mgmt_name, listener, filter, null); - // ... + // ... - // on completion of processing, unregister the listener - server.removeNotificationListener(mgmt_name, listener, filter, null); - ]]> - </programlisting> + // on completion of processing, unregister the listener + server.removeNotificationListener(mgmt_name, listener, filter, null); + ]]></programlisting> <para>The following is the simple notification listener implementation used in the previous example.</para> - <programlisting role="XML"> - <![CDATA[ - private class MyListener implements NotificationListener, Serializable - { - public void handleNotification(Notification notification, Object handback) - { - String message = notification.getMessage(); - String type = notification.getType(); - Object userData = notification.getUserData(); + <programlisting role="JAVA"><![CDATA[ + private class MyListener implements NotificationListener, Serializable + { + public void handleNotification(Notification notification, Object handback) + { + String message = notification.getMessage(); + String type = notification.getType(); + Object userData = notification.getUserData(); - System.out.println(type + ": " + message); + System.out.println(type + ": " + message); - if (userData == null) - { - System.out.println("notification data is null"); - } - else if (userData instanceof String) - { - System.out.println("notification data: " + (String) userData); - } - else if (userData instanceof Object[]) - { - Object[] ud = (Object[]) userData; - for (Object data : ud) - { - System.out.println("notification data: " + data.toString()); - } - } - else - { - System.out.println("notification data class: " + userData.getClass().getName()); - } + if (userData == null) + { + System.out.println("notification data is null"); + } + else if (userData instanceof String) + { + System.out.println("notification data: " + (String) userData); + } + else if (userData instanceof Object[]) + { + Object[] ud = (Object[]) userData; + for (Object data : ud) + { + System.out.println("notification data: " + data.toString()); } } - ]]> - </programlisting> + else + { + System.out.println("notification data class: " + userData.getClass().getName()); + } + } + } + ]]></programlisting> <para>Note that the JBoss Cache management implementation only listens to cache events after a client registers to receive MBean notifications. As soon as no clients are registered for notifications, the MBean will Modified: core/trunk/src/main/docbook/userguide/en/modules/eviction_policies.xml =================================================================== --- core/trunk/src/main/docbook/userguide/en/modules/eviction_policies.xml 2008-03-09 21:52:37 UTC (rev 5405) +++ core/trunk/src/main/docbook/userguide/en/modules/eviction_policies.xml 2008-03-09 21:54:23 UTC (rev 5406) @@ -16,9 +16,8 @@ <title>Basic Configuration</title> <para> The basic eviction policy configuration element looks like: - <programlisting role="XML"> - <![CDATA[ - + </para> + <programlisting role="XML"><![CDATA[ ... <attribute name="EvictionConfig"> @@ -52,9 +51,8 @@ </attribute> ... -]]> - </programlisting> - +]]></programlisting> + <para> <itemizedlist> <listitem> <literal>wakeUpIntervalSeconds</literal> @@ -160,17 +158,17 @@ </para> <para> A sample use case for resident nodes would be ensuring "path" nodes don't add "noise" to an eviction policy. - E.g. - <programlisting role="JAVA"> - <![CDATA[ - ... - Map lotsOfData = generateData(); - cache.put("/a/b/c", lotsOfData); - cache.getRoot().getChild("/a").setResident(true); - cache.getRoot().getChild("/a/b").setResident(true); - ... - ]]> - </programlisting> + E.g.,: + </para> + <programlisting role="JAVA"><![CDATA[ +... + Map lotsOfData = generateData(); + cache.put("/a/b/c", lotsOfData); + cache.getRoot().getChild("/a").setResident(true); + cache.getRoot().getChild("/a/b").setResident(true); +... + ]]></programlisting> + <para> In this example, the nodes <literal>/a</literal> and @@ -222,17 +220,17 @@ : </para> - <programlisting role="JAVA"> - Fqn fqn = Fqn.fromString("/org/jboss/fifo"); + <programlisting role="JAVA"><![CDATA[ + Fqn fqn = Fqn.fromString("/org/jboss/fifo"); - // Create a configuration for an LRUPolicy - LRUConfiguration lruc = new LRUConfiguration(); - lruc.setMaxNodes(10000); + // Create a configuration for an LRUPolicy + LRUConfiguration lruc = new LRUConfiguration(); + lruc.setMaxNodes(10000); - // Create the region and set the config - Region region = cache.getRegion(fqn, true); - region.setEvictionPolicy(lruc); - </programlisting> + // Create the region and set the config + Region region = cache.getRegion(fqn, true); + region.setEvictionPolicy(lruc); + ]]></programlisting> </section> </section> @@ -427,8 +425,8 @@ <para> The following listing shows how the expiration date is indicated and how the policy is applied: - <programlisting role="JAVA"> - <![CDATA[ + </para> + <programlisting role="JAVA"><![CDATA[ Cache cache = DefaultCacheFactory.createCache(); Fqn fqn1 = Fqn.fromString("/node/1"); Long future = new Long(System.currentTimeMillis() + 2000); @@ -441,8 +439,8 @@ // after 5 seconds, expiration completes assertFalse(cache.getRoot().hasChild(fqn1)); -]]> - </programlisting> + ]]></programlisting> + <para> Note that the expiration time of nodes is only checked when the region manager wakes up every <literal>wakeUpIntervalSeconds</literal> Modified: core/trunk/src/main/docbook/userguide/en/modules/replication.xml =================================================================== --- core/trunk/src/main/docbook/userguide/en/modules/replication.xml 2008-03-09 21:52:37 UTC (rev 5405) +++ core/trunk/src/main/docbook/userguide/en/modules/replication.xml 2008-03-09 21:54:23 UTC (rev 5406) @@ -360,9 +360,7 @@ <section> <title>Configuration</title> - <para> - <programlisting role="XML"> - <![CDATA[ + <programlisting role="XML"><![CDATA[ <!-- Buddy Replication config --> <attribute name="BuddyReplicationConfig"> <config> @@ -405,9 +403,7 @@ </config> </attribute> -]]> - </programlisting> - </para> +]]></programlisting> </section> </section> </section> Modified: core/trunk/src/main/docbook/userguide/en/modules/transactions.xml =================================================================== --- core/trunk/src/main/docbook/userguide/en/modules/transactions.xml 2008-03-09 21:52:37 UTC (rev 5405) +++ core/trunk/src/main/docbook/userguide/en/modules/transactions.xml 2008-03-09 21:54:23 UTC (rev 5406) @@ -75,14 +75,13 @@ so-called "dirty read" where data modified in Tx1 can be read in Tx2 before Tx1 commits. In other words, if you have the following sequence, - <programlisting> - <![CDATA[ + </para> + <programlisting><![CDATA[ Tx1 Tx2 W R -]]> - </programlisting> - +]]></programlisting> + <para> using this isolation level will not prevent Tx2 read operation. Implementations typically use an exclusive lock for writes while reads don't need to acquire a lock. @@ -95,15 +94,13 @@ so-called ‘non-repeatable read’ where one thread reads the data twice can produce different results. For example, if you have the following sequence, - <programlisting> - <![CDATA[ + </para> + <programlisting><![CDATA[ Tx1 Tx2 R W R -]]> - </programlisting> - </para> +]]></programlisting> <para>where the second read in Tx1 thread will produce different result. @@ -241,32 +238,36 @@ </section> <section> <title>Configuration</title> - Optimistic locking is enabled by using the NodeLockingScheme XML attribute, and setting it to "OPTIMISTIC": - <programlisting role="XML"> - <![CDATA[ - ... + <para> + Optimistic locking is enabled by using the NodeLockingScheme XML attribute, and setting it to + "OPTIMISTIC": + </para> + <programlisting role="XML"><![CDATA[ +... <!-- Node locking scheme: OPTIMISTIC PESSIMISTIC (default) --> <attribute name="NodeLockingScheme">OPTIMISTIC</attribute> - ... - ]]> - </programlisting> - It is generally advisable that if you have an eviction policy defined along with optimistic locking, you - define - the eviction policy's - <literal>minTimeToLiveSeconds</literal> - parameter to be slightly greater than the transaction - timeout value set in your transaction manager. This ensures that data versions in the cache are not evicted - while transactions are in progress - <footnote> - <para>See - <ulink url="http://jira.jboss.com/jira/browse/JBCACHE-1155">JBCACHE... - </para> - </footnote> - . +... + ]]></programlisting> + <para> + It is generally advisable that if you have an eviction policy defined along with optimistic locking, you + define + the eviction policy's + <literal>minTimeToLiveSeconds</literal> + parameter to be slightly greater than the transaction + timeout value set in your transaction manager. This ensures that data versions in the cache are not + evicted + while transactions are in progress + <footnote> + <para>See + <ulink url="http://jira.jboss.com/jira/browse/JBCACHE-1155">JBCACHE... + </para> + </footnote> + . + </para> </section> </section> </section> @@ -351,10 +352,10 @@ element: </para> - <programlisting role="JAVA"> - TransactionManager tm = getTransactionManager(); // magic method - cache.getConfiguration().getRuntimeConfig().setTransactionManager(tm); - </programlisting> + <programlisting role="JAVA"><![CDATA[ + TransactionManager tm = getTransactionManager(); // magic method + cache.getConfiguration().getRuntimeConfig().setTransactionManager(tm); + ]]></programlisting> <para> Injecting the