[jbosscache-commits] JBoss Cache SVN: r6958 - in core/trunk/src/main/docbook: tutorial/en and 2 other directories.

Author: manik.surtani(a)jboss.com Date: 2008-10-15 14:11:20 -0400 (Wed, 15 Oct 2008) New Revision: 6958 Modified: 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/master.xml core/trunk/src/main/docbook/userguide/en/modules/basic_api.xml core/trunk/src/main/docbook/userguide/en/modules/compatibility.xml core/trunk/src/main/docbook/userguide/en/modules/configuration.xml core/trunk/src/main/docbook/userguide/en/modules/deployment.xml core/trunk/src/main/docbook/userguide/en/modules/introduction.xml core/trunk/src/main/docbook/userguide/en/modules/preface.xml Log: More documentation changes Modified: core/trunk/src/main/docbook/faq/en/master.xml =================================================================== --- core/trunk/src/main/docbook/faq/en/master.xml 2008-10-15 15:44:27 UTC (rev 6957) +++ core/trunk/src/main/docbook/faq/en/master.xml 2008-10-15 18:11:20 UTC (rev 6958) @@ -12,40 +12,38 @@ <author> <firstname>Manik</firstname> <surname>Surtani</surname> - <email&gt;manik(a)jboss.org&lt;/email&gt; + <email>manik AT jboss DOT org</email> </author> <author> <firstname>Ben</firstname> <surname>Wang</surname> - <email&gt;ben.wang(a)jboss.com&lt;/email&gt; + <email>ben DOT wang AT jboss DOT com</email> </author> <author> <firstname>Bela</firstname> <surname>Ban</surname> - <email&gt;bela(a)jboss.com&lt;/email&gt; + <email>bela AT jboss DOT com</email> </author> <author> <firstname>Scott</firstname> <surname>Marlow</surname> - <email&gt;smarlow(a)novell.com&lt;/email&gt; + <email>smarlow AT novell DOT com</email> </author> <author> <firstname>Galder</firstname> <surname>Zamarreño</surname> - <email&gt;galder.zamarreno(a)jboss.com&lt;/email&gt; + <email>galder DOT zamarreno AT jboss DOT com</email> </author> <abstract> <para>This is a compilation of the most frequently asked questions about JBoss Cache. Please report any bugs, inconsistencies, or omissions you find in this FAQ on the - <ulink url="http://jboss.org/index.html?module=bb&amp;op=main&amp;c... Cache User Forum - </ulink> - . + <ulink url="http://www.jboss.org/jbosscache">JBoss Cache User Forum</ulink>. </para> <para> This FAQ is divided into specific sections, all pertaining to the core JBoss Cache library. POJO Cache has a @@ -60,7 +58,7 @@ <year>2006</year> <year>2007</year> <year>2008</year> - <holder>JBoss, a division of Red Hat Inc.</holder> + <holder>JBoss, a division of Red Hat Inc., and all authors as named.</holder> </copyright> </bookinfo> @@ -97,9 +95,8 @@ of objects in the cache providing transparent coherence by using JBoss AOP. Note that the POJO edition of JBoss Cache (often referred to as POJO Cache) comes with a separate set of documentation (user guide, FAQ, etc.) - available on the - <ulink url="http://labs.jboss.com/portal/jbosscache/docs/index.html"&g... Cache documentation site - </ulink>. + available on the JBoss Cache + <ulink url="http://www.jboss.org/jbosscache/">documentation website</ulink>. </para> <para> @@ -266,10 +263,7 @@ <answer> <para>Please report any bugs or problems to - <ulink - url="http://jboss.org/index.html?module=bb&amp;op=main&amp;c... Cache - User Forum - </ulink>. + <ulink url="http://www.jboss.org/jbosscache">JBoss Cache User Forum</ulink>. </para> </answer> </qandaentry> Modified: core/trunk/src/main/docbook/tutorial/en/master.xml =================================================================== --- core/trunk/src/main/docbook/tutorial/en/master.xml 2008-10-15 15:44:27 UTC (rev 6957) +++ core/trunk/src/main/docbook/tutorial/en/master.xml 2008-10-15 18:11:20 UTC (rev 6958) @@ -9,16 +9,22 @@ <author> <firstname>Manik</firstname> <surname>Surtani</surname> - <email&gt;manik(a)jboss.org&lt;/email&gt; + <email>manik AT jboss DOT org</email> </author> + <author> + <firstname>Galder</firstname> + <surname>Zamarreño</surname> + <email>galder DOT zamarreno AT jboss DOT com</email> + </author> + <!-- copyright info --> <copyright> <year>2005</year> <year>2006</year> <year>2007</year> <year>2008</year> - <holder>JBoss, a division of Red Hat Inc.</holder> + <holder>JBoss, a division of Red Hat Inc., and all authors as named.</holder> </copyright> </articleinfo> @@ -33,10 +39,7 @@ </para> <para> For details of configuration, usage and APIs, please refer to the - <ulink - url="http://labs.jboss.org/jbosscache/docs/index.html">user manuals - </ulink> - . + <ulink url="http://labs.jboss.org/jbosscache/docs/index.html">user manuals</ulink>. </para> </section> @@ -62,10 +65,7 @@ <title>Configuration</title> <para>First download the JBoss Cache 3.x distribution from - <ulink - url="http://labs.jboss.org/jbosscache/download/index.html">the download page - </ulink> - . You will need the ALL distribution ( + <ulink url="http://labs.jboss.org/jbosscache/download/index.html">the download page</ulink>. You will need the ALL distribution ( <literal>jbosscache-core-3.X.Y.GA-all.zip</literal>). Unzip it, and you will get a directory containing the distribution, such as <literal>jbosscache-core-3.X.Y</literal> Modified: core/trunk/src/main/docbook/userguide/en/master.xml =================================================================== --- core/trunk/src/main/docbook/userguide/en/master.xml 2008-10-15 15:44:27 UTC (rev 6957) +++ core/trunk/src/main/docbook/userguide/en/master.xml 2008-10-15 18:11:20 UTC (rev 6958) @@ -29,46 +29,27 @@ <author> <firstname>Manik</firstname> <surname>Surtani</surname> - <email&gt;manik(a)jboss.org&lt;/email&gt; + <email>manik AT jboss DOT org</email> </author> <author> - <firstname>Bela</firstname> - <surname>Ban</surname> - <email&gt;bela(a)jboss.com&lt;/email&gt; - </author> - - <author> - <firstname>Ben</firstname> - <surname>Wang</surname> - <email&gt;ben.wang(a)jboss.com&lt;/email&gt; - </author> - - <author> <firstname>Brian</firstname> <surname>Stansberry</surname> - <email&gt;brian.stansberry(a)jboss.com&lt;/email&gt; + <email>brian DOT stansberry AT jboss DOT com</email> </author> <author> <firstname>Galder</firstname> <surname>Zamarreño</surname> - <email&gt;galder.zamarreno(a)jboss.com&lt;/email&gt; + <email>galder DOT zamarreno AT jboss DOT com</email> </author> <author> - <firstname>Daniel</firstname> - <surname>Huang</surname> - <email&gt;dhuang(a)jboss.org&lt;/email&gt; - </author> - - <author> <firstname>Mircea</firstname> <surname>Markus</surname> - <email&gt;mircea.markus(a)jboss.com&lt;/email&gt; + <email>mircea DOT markus AT jboss DOT com</email> </author> - <!-- copyright info --> <copyright> <year>2004</year> @@ -76,7 +57,7 @@ <year>2006</year> <year>2007</year> <year>2008</year> - <holder>JBoss, a division of Red Hat Inc.</holder> + <holder>JBoss, a division of Red Hat Inc., and all authors as named.</holder> </copyright> </bookinfo> @@ -91,8 +72,7 @@ <partintro> <para> This section covers what developers would need to quickly start using JBoss Cache in their projects. It - covers an - overview of the concepts and API, configuration and deployment information. + covers an overview of the concepts and API, configuration and deployment information. </para> </partintro> &introduction; @@ -107,9 +87,9 @@ <title>JBoss Cache Architecture</title> <partintro> <para> - This section digs deeper into the JBoss Cache architecture, and is meant for developers wishing to extend or - enhance JBoss Cache, write plugins or are just looking for detailed knowledge of how things work under the - hood. + This section digs deeper into the JBoss Cache architecture, and is meant for developers wishing to use the more + advanced cache features,extend or enhance the cache, write plugins, or are just looking for detailed knowledge + of how things work under the hood. </para> </partintro> &architecture; Modified: core/trunk/src/main/docbook/userguide/en/modules/basic_api.xml =================================================================== --- core/trunk/src/main/docbook/userguide/en/modules/basic_api.xml 2008-10-15 15:44:27 UTC (rev 6957) +++ core/trunk/src/main/docbook/userguide/en/modules/basic_api.xml 2008-10-15 18:11:20 UTC (rev 6958) @@ -3,24 +3,12 @@ <section> <title>API Classes</title> <para> - The - <literal>Cache</literal> - interface is the primary mechanism for interacting with JBoss Cache. It is - constructed and optionally started using the - <literal>CacheFactory</literal> - . The - <literal>CacheFactory</literal> - allows you to create a - <literal>Cache</literal> - either from a - <literal>Configuration</literal> - object - or an XML file. Once you have a reference to a - <literal>Cache</literal> - , you can use it to look up - <literal>Node</literal> - objects in the tree structure, and store data in the tree. - + The <literal>Cache</literal> interface is the primary mechanism for interacting with JBoss Cache. It is + constructed and optionally started using the <literal>CacheFactory</literal>. The <literal>CacheFactory</literal> + allows you to create a <literal>Cache</literal> either from a <literal>Configuration</literal> object or an XML + file. The cache organizes data into a tree structure, made up of nodes. Once you have a reference to a + <literal>Cache</literal>, you can use it to look up <literal>Node</literal> objects in the tree structure, + and store data in the tree. <mediaobject> <imageobject> <imagedata fileref="PublicAPI.png" format="PNG"/> @@ -38,55 +26,32 @@ <section id="api.create_start"> <title>Instantiating and Starting the Cache</title> <para> - An instance of the - <literal>Cache</literal> - interface can only be created - via a - <literal>CacheFactory</literal>. (This is unlike JBoss Cache 1.x, - where an instance of the old - <literal>TreeCache</literal> - class could - be directly instantiated.) + An instance of the <literal>Cache</literal> interface can only be created via a <literal>CacheFactory</literal>. + This is unlike JBoss Cache 1.x, where an instance of the old <literal>TreeCache</literal> class could be directly + instantiated. </para> <para> - <literal>CacheFactory</literal> - provides a number of overloaded methods - for creating a - <literal>Cache</literal> - , but they all do the same thing: + The <literal>CacheFactory</literal> provides a number of overloaded methods for creating a <literal>Cache</literal>, + but they all fundamentally do the same thing: <itemizedlist> - <listitem>Gain access to a - <literal>Configuration</literal> - , either - by having one passed in as a method parameter, or by parsing XML - content and constructing one. The XML content can come from a - provided input stream or from a classpath or filesystem location. - See the - <link linkend="configuration">chapter on Configuration</link> - for - more on obtaining a - <literal>Configuration</literal> - . + <listitem> + Gain access to a <literal>Configuration</literal>, either by having one passed in as a method + parameter or by parsing XML content and constructing one. The XML content can come from a provided input + stream, from a classpath or filesystem location. See the <link linkend="configuration">chapter on Configuration</link> + for more on obtaining a <literal>Configuration</literal>. </listitem> - <listitem>Instantiate the - <literal>Cache</literal> - and provide - it with a reference to the - <literal>Configuration</literal> - . + <listitem> + Instantiate the <literal>Cache</literal> and provide it with a reference to the <literal>Configuration</literal>. </listitem> - <listitem>Optionally invoke the cache's - <literal>create()</literal> - and - <literal>start()</literal> - methods. + <listitem> + Optionally invoke the cache's <literal>create()</literal> and <literal>start()</literal> methods. </listitem> </itemizedlist> </para> <para> - An example of the simplest mechanism for creating and starting - a cache, using the default configuration values: + Here is an example of the simplest mechanism for creating and starting a cache, using the default + configuration values: </para> <programlisting role="JAVA"><![CDATA[ @@ -94,10 +59,9 @@ Cache cache = factory.createCache(); ]]></programlisting> - <para>Here we tell the - <literal>CacheFactory</literal> - to find and - parse a configuration file on the classpath: + <para> + In this example, we tell the <literal>CacheFactory</literal> to find and parse a configuration file on + the classpath: </para> <programlisting role="JAVA"><![CDATA[ @@ -105,14 +69,13 @@ 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>In this example, 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"><![CDATA[ CacheFactory factory = new DefaultCacheFactory(); - Cache cache = factory.createCache("cache-configuration.xml", false); + Cache cache = factory.createCache("/opt/configurations/cache-configuration.xml", false); Configuration config = cache.getConfiguration(); config.setClusterName(this.getClusterName()); @@ -126,13 +89,9 @@ <section> <title>Caching and Retrieving Data</title> - <para>Next, let's use the - <literal>Cache</literal> - API to access - a - <literal>Node</literal> - in the cache and then do some - simple reads and writes to that node. + <para> + Next, lets use the <literal>Cache</literal> API to access a <literal>Node</literal> in the cache and then + do some simple reads and writes to that node. </para> <programlisting role="JAVA"><![CDATA[ // Let's get a hold of the root node. @@ -172,12 +131,8 @@ ]]></programlisting> <para> - The - <literal>Cache</literal> - interface also exposes put/get/remove - operations that take an - <link linkend="basic_api.fqn">Fqn</link> - as an argument: + The <literal>Cache</literal> interface also exposes put/get/remove operations that take an + <link linkend="basic_api.fqn">Fqn</link> as an argument, for convenience: </para> <programlisting role="JAVA"><![CDATA[ @@ -200,46 +155,30 @@ </section> <section id="basic_api.fqn"> - <title>The - <literal>Fqn</literal> - Class + <title> + The <literal>Fqn</literal> Class </title> <para> - The previous section used the - <literal>Fqn</literal> - class in its - examples; now let's learn a bit more about that class. + The previous section used the <literal>Fqn</literal> class in its examples; now let's learn a bit more about + that class. </para> <para> - A Fully Qualified Name (Fqn) encapsulates a list of names which represent - a path to a particular location in the cache's tree structure. The - elements in the list are typically - <literal>String</literal> - s but can be - any - <literal>Object</literal> - or a mix of different types. + A Fully Qualified Name (Fqn) encapsulates a list of names which represent a path to a particular location in + the cache's tree structure. The elements in the list are typically <literal>String</literal>s but can be + any <literal>Object</literal> or a mix of different types. </para> <para> - This path can be absolute (i.e., relative to the root node), or relative - to any node in the cache. Reading the documentation on each API call that - makes use of - <literal>Fqn</literal> - will tell you whether the API expects - a relative or absolute - <literal>Fqn</literal> - . + This path can be absolute (i.e., relative to the root node), or relative to any node in the cache. Reading the + documentation on each API call that makes use of <literal>Fqn</literal> will tell you whether the API expects + a relative or absolute <literal>Fqn</literal>. </para> <para> - The - <literal>Fqn</literal> - class provides are variety of constructors; - see the javadoc for all the possibilities. The following illustrates the - most commonly used approaches to creating an Fqn: + The <literal>Fqn</literal> class provides are variety of factory methods; see the javadoc for all the + possibilities. The following illustrates the most commonly used approaches to creating an Fqn: </para> <programlisting role="JAVA"><![CDATA[ @@ -267,7 +206,7 @@ It is good practice to stop and destroy your cache when you are done using it, particularly if it is a clustered cache and has thus used a JGroups channel. Stopping and destroying a cache ensures - resources like the JGroups channel are properly cleaned up. + resources like network sockets and maintenance threads are properly cleaned up. </para> <programlisting role="JAVA"><![CDATA[ @@ -296,20 +235,13 @@ <section> <title>Cache Modes</title> <para> - Although technically not part of the API, the - <emphasis>mode</emphasis> - in which the cache is configured to operate affects the cluster-wide - behavior of any - <literal>put</literal> - or - <literal>remove</literal> + Although technically not part of the API, the <emphasis>mode</emphasis> in which the cache is configured to + operate affects the cluster-wide behavior of any <literal>put</literal> or <literal>remove</literal> operation, so we'll briefly mention the various modes here. </para> <para> - JBoss Cache modes are denoted by the - <literal>org.jboss.cache.config.Configuration.CacheMode</literal> - enumeration. - They consist of: + JBoss Cache modes are denoted by the <literal>org.jboss.cache.config.Configuration.CacheMode</literal> + enumeration. They consist of: <itemizedlist> <listitem> <emphasis>LOCAL</emphasis> @@ -343,13 +275,10 @@ </listitem> </itemizedlist> </para> - <para>See the - <link linkend="clustering">chapter on Clustering</link> - for - more details on how the cache's mode affects behavior. See the - <link linkend="configuration">chapter on Configuration</link> - for info - on how to configure things like the cache's mode. + <para> + See the <link linkend="clustering">chapter on Clustering</link> for more details on how cache mode + affects behavior. See the <link linkend="configuration">chapter on Configuration</link> for info on how to + configure things like cache mode. </para> </section> @@ -366,13 +295,11 @@ ]]></programlisting> <para> Similar methods exist for removing or querying registered listeners. See the javadocs on the - <literal>Cache</literal> - interface for more details. + <literal>Cache</literal> interface for more details. </para> <para> Basically any public class can be used as a listener, provided it is annotated with the - <literal>@CacheListener</literal> - annotation. In addition, the class needs to have one or + <literal>@CacheListener</literal> annotation. In addition, the class needs to have one or more methods annotated with one of the method-level annotations (in the <literal>org.jboss.cache.notifications.annotation</literal> package). Methods annotated as such need to be public, have a void return type, and accept a single parameter @@ -572,9 +499,7 @@ </para> <para> Refer to the javadocs on the annotations as well as the - <literal>Event</literal> - subtypes - for details of what is passed in to your method, and when. + <literal>Event</literal> subtypes for details of what is passed in to your method, and when. </para> <para> Example: Modified: core/trunk/src/main/docbook/userguide/en/modules/compatibility.xml =================================================================== --- core/trunk/src/main/docbook/userguide/en/modules/compatibility.xml 2008-10-15 15:44:27 UTC (rev 6957) +++ core/trunk/src/main/docbook/userguide/en/modules/compatibility.xml 2008-10-15 18:11:20 UTC (rev 6958) @@ -29,7 +29,7 @@ <section> <title>Compatibility Matrix</title> <para> - A <ulink url="http://labs.jboss.com/portal/jbosscache/compatibility/index.htm... matrix</ulink> is maintained on the JBoss Cache website, which contains information on + A <ulink url="http://www.jboss.org/jbosscache/compatibility/index.html"&... matrix</ulink> is maintained on the JBoss Cache website, which contains information on different versions of JBoss Cache, JGroups and JBoss AS. </para> </section> Modified: core/trunk/src/main/docbook/userguide/en/modules/configuration.xml =================================================================== --- core/trunk/src/main/docbook/userguide/en/modules/configuration.xml 2008-10-15 15:44:27 UTC (rev 6957) +++ core/trunk/src/main/docbook/userguide/en/modules/configuration.xml 2008-10-15 18:11:20 UTC (rev 6958) @@ -7,26 +7,16 @@ <para> The <literal>org.jboss.cache.config.Configuration</literal> - class - (along with its - <link linkend="configuration.elements">component parts</link> - ) - is a Java Bean that encapsulates the configuration of the - <literal>Cache</literal> - and all of its architectural elements - (cache loaders, evictions policies, etc.) + class (along with its <link linkend="configuration.elements">component parts</link>) + is a Java Bean that encapsulates the configuration of the <literal>Cache</literal> + and all of its architectural elements (cache loaders, evictions policies, etc.) </para> <para> - The - <literal>Configuration</literal> - exposes numerous properties which - are summarized in the - <link linkend="configuration_reference">configuration reference</link> - section of this book and many of which are discussed in later - chapters. Any time you see a configuration option - discussed in this book, you can assume that the - <literal>Configuration</literal> + The <literal>Configuration</literal> exposes numerous properties which + are summarized in the <link linkend="configuration_reference">configuration reference</link> + section of this book and many of which are discussed in later chapters. Any time you see a configuration option + discussed in this book, you can assume that the <literal>Configuration</literal> class or one of its component parts exposes a simple property setter/getter for that configuration option. </para> @@ -38,19 +28,11 @@ </title> <para> - As discussed in the - <link linkend="api.create_start">User API section</link> - , - before a - <literal>Cache</literal> - can be created, the - <literal>CacheFactory</literal> - must be provided with a - <literal>Configuration</literal> - object or with a file name or - input stream to use to parse a - <literal>Configuration</literal> - from XML. The following sections describe how to accomplish this. + As discussed in the <link linkend="api.create_start">User API section</link>, + before a <literal>Cache</literal> can be created, the <literal>CacheFactory</literal> + must be provided with a <literal>Configuration</literal> object or with a file name or + input stream to use to parse a <literal>Configuration</literal> from XML. The following sections describe + how to accomplish this. </para> <section> @@ -84,6 +66,7 @@ <link linkend="configuration_reference">a handy look-up table</link> explaining the various options. </para> + </section> <section id="configuration.validation"> <title>Validating Configuration Files</title> <para> @@ -100,21 +83,6 @@ </para> </section> - <para> - Here's how you tell the - <literal>CacheFactory</literal> - to create - and start a cache by finding and parsing a configuration file on the - classpath: - </para> - - <programlisting role="JAVA"><![CDATA[ - CacheFactory factory = new DefaultCacheFactory(); - Cache cache = factory.createCache("cache-configuration.xml"); - ]]></programlisting> - - </section> - <section> <title>Programmatic Configuration</title> <para> @@ -325,42 +293,42 @@ will be thrown if you attempt to change a setting that is not dynamic. </para> - </section> - <section id="configuration.options"> - <title>Overriding the Configuration Via the Option API</title> - <para> - The Option API allows you to override certain behaviours of the cache on a per invocation basis. - This involves creating an instance of - <literal>org.jboss.cache.config.Option</literal> - , setting the options - you wish to override on the - <literal>Option</literal> - object and passing it in the - <literal>InvocationContext</literal> - before invoking your method on the cache. - </para> - <para> - E.g., to override the default node versioning used with optimistic locking: - </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> + <section id="configuration.options"> + <title>Overriding the Configuration via the Option API</title> + <para> + The Option API allows you to override certain behaviours of the cache on a per invocation basis. + This involves creating an instance of + <literal>org.jboss.cache.config.Option</literal> + , setting the options + you wish to override on the + <literal>Option</literal> + object and passing it in the + <literal>InvocationContext</literal> + before invoking your method on the cache. + </para> + <para> + E.g., to override the default node versioning used with optimistic locking: + </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: - </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> - class for details on the options available. - </para> + <para> + E.g., to suppress replication of a put call in a REPL_SYNC cache: + </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> + class for details on the options available. + </para> + </section> </section> </chapter> Modified: core/trunk/src/main/docbook/userguide/en/modules/deployment.xml =================================================================== --- core/trunk/src/main/docbook/userguide/en/modules/deployment.xml 2008-10-15 15:44:27 UTC (rev 6957) +++ core/trunk/src/main/docbook/userguide/en/modules/deployment.xml 2008-10-15 18:11:20 UTC (rev 6958) @@ -25,127 +25,23 @@ </para> <para> + After creation, you could share your cache instance among different application components either by using an + IOC container such as Spring, JBoss Microcontainer, Picocontainer, etc., or by binding it to JNDI, or simply + holding a static reference to the cache. + </para> + + <para> If, after deploying your cache you wish to expose a management interface to it in JMX, see the <link linkend="jmx.registration.programatic">section on Programatic Registration in JMX</link> . </para> </section> - - <section id="deployment.microkernel"> - <title>JMX-Based Deployment in JBoss AS (JBoss AS 5.x and 4.x)</title> - <para>If JBoss Cache is run in JBoss AS then the cache can be deployed as an - MBean simply by copying a standard cache configuration file to the server's - <literal>deploy</literal> - directory. The standard format of JBoss Cache's - standard XML configuration file (as shown in the - <link linkend="sample_xml_file">Configuration Reference</link> - ) is the same - as a JBoss AS MBean deployment descriptor, so the AS's SAR Deployer has - no trouble handling it. Also, you don't have to place the configuration - file directly in - <literal>deploy</literal> - ; you can package it along - with other services or JEE components in a SAR or EAR. - </para> - - <para> - In AS 5, if you're using a server config based on the standard - <literal>all</literal> - config, then that's all you need to do; all required - jars will be on the classpath. Otherwise, you will need to ensure - <literal>jbosscache.jar</literal> - and - <literal>jgroups-all.jar</literal> - are on the classpath. You may need to add other jars if you're using - things like - <literal>JdbmCacheLoader</literal> - . The simplest way to do - this is to copy the jars from the JBoss Cache distribution's - <literal>lib</literal> - directory to the server config's - <literal>lib</literal> - directory. You could also package the jars with the configuration file - in Service Archive (.sar) file or an EAR. - </para> - - <para> - It is possible to deploy a JBoss Cache 2.0 instance in JBoss AS 4.x - (at least in 4.2.0.GA; other AS releases are completely untested). - However, the significant API changes between the JBoss Cache 2.x and 1.x releases - mean none of the standard AS 4.x clustering services (e.g. - http session replication) that rely on JBoss Cache will work with - JBoss Cache 2.x. Also, be aware that usage of JBoss Cache 2.x in AS 4.x is not - something the JBoss Cache developers are making any significant effort to test, - so be sure to test your application well (which of course you're doing anyway.) - </para> - - <para> - Note in the - <link linkend="sample_xml_file">example</link> - the value of the - <literal>mbean</literal> - element's - <literal>code</literal> - attribute: - <literal>org.jboss.cache.jmx.CacheJmxWrapper</literal> - . This is the - class JBoss Cache uses to handle JMX integration; the - <literal>Cache</literal> - itself does not expose an MBean - interface. See the - <link linkend="jmx.mbeans">JBoss Cache MBeans section</link> - for more on the - <literal>CacheJmxWrapper</literal> - . - </para> - - <para> - Once your cache is deployed, in order to use it with an in-VM client - such as a servlet, a JMX proxy can be used to get a reference to - 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> - - <para>The MBeanServerLocator class is a helper to find the (only) JBoss - MBean server inside the current JVM. The - <literal>javax.management.MBeanServerInvocationHandler</literal> - class' - <literal>newProxyInstance</literal> - method creates a - dynamic proxy implementing the given interface and uses JMX to - dynamically dispatch methods invoked against the generated interface - to the MBean. The name used to look up the MBean is the same as defined - in the cache's configuration file. - </para> - - <para> - Once the proxy to the - <literal>CacheJmxWrapper</literal> - is obtained, - the - <literal>getCache()</literal> - will return a reference to the - <literal>Cache</literal> - itself. - </para> - - </section> - <section id="deployment.microcontainer"> <title>Via JBoss Microcontainer (JBoss AS 5.x)</title> <para> - Beginning with AS 5, JBoss AS also supports deployment of POJO services via + Beginning with AS 5, JBoss AS supports deployment of POJO services via deployment of a file whose name ends with <literal>-beans.xml</literal> . @@ -155,7 +51,7 @@ <literal>Cache</literal> is a POJO service, and all the components in a <literal>Configuration</literal> - are also POJOS, so deploying a cache in this way is a natural step. + are also POJOs, so deploying a cache in this way is a natural step. </para> <para> Deployment of the cache is done using the JBoss Microcontainer that forms the @@ -175,11 +71,10 @@ configured. </para> <para> - The rules for how to deploy the file, how to package it, how to - ensure the required jars are on the classpath, etc. are the same - as for a - <link linkend="deployment.microkernel">JMX-based deployment</link> - . + You need to ensure that the <literal>jbosscache-core.jar</literal> and <literal>jgroups.jar</literal> libraries + are in your server's <literal>lib</literal> directory. This is usually the case when you use JBoss AS in its + <literal>all</literal> configuration. Note that you will have to bring in any additional jars you require, such + as <literal>jdbm.jar</literal> based on your cache configuration. </para> <para> Following is an example @@ -187,7 +82,7 @@ file. If you look in the <literal>server/all/deploy</literal> - directory of an AS 5 + directory of a JBoss AS 5 installation, you can find several more examples. </para> @@ -215,74 +110,26 @@ <property name="clusterName">Example-EntityCache</property> - <!-- - Node locking level : SERIALIZABLE - REPEATABLE_READ (default) - READ_COMMITTED - READ_UNCOMMITTED - NONE - --> <property name="isolationLevel">REPEATABLE_READ</property> - <!-- Valid modes are LOCAL - REPL_ASYNC - REPL_SYNC - --> <property name="cacheMode">REPL_SYNC</property> - <!-- The max amount of time (in milliseconds) we wait until the - initial state (ie. the contents of the cache) are retrieved from - existing members in a clustered environment - --> <property name="initialStateRetrievalTimeout">15000</property> - <!-- Number of milliseconds to wait until all responses for a - synchronous call have been received. - --> <property name="syncReplTimeout">20000</property> - <!-- Max number of milliseconds to wait for a lock acquisition --> <property name="lockAcquisitionTimeout">15000</property> <property name="exposeManagementStatistics">true</property> - <!-- Must be true if any entity deployment uses a scoped classloader --> <property name="useRegionBasedMarshalling">true</property> - <!-- Must match the value of "useRegionBasedMarshalling" --> <property name="inactiveOnStartup">true</property> - <!-- Specific eviction policy configurations. This is LRU --> - <property name="evictionConfig"> - <bean name="ExampleEvictionConfig" - class="org.jboss.cache.config.EvictionConfig"> - <property name="defaultEvictionPolicyClass"> - org.jboss.cache.eviction.LRUPolicy - </property> - <property name="wakeupIntervalSeconds">5</property> - <property name="evictionRegionConfigs"> - <list> - <bean name="ExampleDefaultEvictionRegionConfig" - class="org.jboss.cache.config.EvictionRegionConfig"> - <property name="regionName">/_default_</property> - <property name="evictionPolicyConfig"> - <bean name="ExampleDefaultLRUConfig" - class="org.jboss.cache.eviction.LRUConfiguration"> - <property name="maxNodes">5000</property> - <property name="timeToLiveSeconds">1000</property> - </bean> - </property> - </bean> - </list> - </property> - </bean> - </property> - </bean> <!-- Factory to build the Cache. --> <bean name="DefaultCacheFactory" class="org.jboss.cache.DefaultCacheFactory"> - <constructor factoryClass="org.jboss.cache.DefaultCacheFactory" - factoryMethod="getInstance"/> + <constructor factoryClass="org.jboss.cache.DefaultCacheFactory" /> </bean> <!-- The cache itself --> @@ -300,13 +147,10 @@ ]]></programlisting> <para> - See the JBoss Microcontainer documentation - <footnote> - <para>http://labs.jboss.com/jbossmc/docs</para> - </footnote> + See <ulink url="http://www.jboss.org/jbossmc/docs">the JBoss Microcontainer documentation</ulink> for details on the above syntax. Basically, each <literal>bean</literal> - element represents an object; most going to create a + element represents an object and is used to create a <literal>Configuration</literal> and its <link linkend="configuration.elements">constituent parts</link> @@ -330,21 +174,9 @@ </section> <section> - <title>Binding to JNDI in JBoss AS</title> + <title>Automatic binding to JNDI in JBoss AS</title> <para> - With the 1.x JBoss Cache releases, a proxy to the cache could be bound - into JBoss AS's JNDI tree using the AS's - <literal>JRMPProxyFactory</literal> - service. With JBoss Cache 2.x, this no longer works. An alternative - way of doing a similar thing with a POJO (i.e. non-JMX-based) service - like a - <literal>Cache</literal> - is under development by the JBoss AS - team - <footnote> - <para>http://jira.jboss.com/jira/browse/JBAS-4456</para> - </footnote> - . That feature is not available as of the time of this writing, + This feature is not available as of the time of this writing, although it will be completed before AS 5.0.0.GA is released. We will add a wiki page describing how to use it once it becomes available. </para> @@ -392,29 +224,11 @@ javadoc for more details. </para> <para> - It is important to note a significant architectural difference between JBoss Cache 1.x and 2.x. In 1.x, - the old - <literal>TreeCache</literal> - class was itself an MBean, and essentially exposed the cache's entire - API via JMX. In 2.x, JMX has been returned to it's fundamental role as a management layer. The - <literal>Cache</literal> - object itself is completely unaware of JMX; instead JMX functionality is added - through a wrapper class designed for that purpose. Furthermore, the interface exposed through JMX - has been limited to management functions; the general - <literal>Cache</literal> - API is no longer exposed - through JMX. For example, it is no longer possible to invoke a cache - <literal>put</literal> - or - <literal>get</literal> - via the JMX interface. - </para> - <para> If a <literal>CacheJmxWrapper</literal> is registered, JBoss Cache also provides MBeans - for each interceptor configured in the cache's interceptor stack. These - MBeans are used to capture and expose statistics related to cache operations. They are hierarchically + for several other internal components and subsystems. These + MBeans are used to capture and expose statistics related to the subsystems they represent. They are hierarchically associated with the <literal>CacheJmxWrapper</literal> MBean and have service names that reflect this relationship. For Modified: core/trunk/src/main/docbook/userguide/en/modules/introduction.xml =================================================================== --- core/trunk/src/main/docbook/userguide/en/modules/introduction.xml 2008-10-15 15:44:27 UTC (rev 6957) +++ core/trunk/src/main/docbook/userguide/en/modules/introduction.xml 2008-10-15 18:11:20 UTC (rev 6958) @@ -8,7 +8,7 @@ <para> JBoss Cache is a tree-structured, clustered, transactional cache. It can be used in a standalone, non-clustered environment, to cache frequently accessed data in memory thereby removing data retrieval or calculation bottlenecks - while providing "enterprise" features such as JTA compatibility, eviction and persistence. + while providing "enterprise" features such as <ulink url="http://java.sun.com/products/jta">JTA</ulink> compatibility, eviction and persistence. </para> <para> JBoss Cache is also a clustered cache, and can be used in a cluster to replicate state providing a high degree @@ -17,8 +17,10 @@ </para> <para> When used in a clustered mode, the cache is an effective mechanism of building high availability, fault - tolerance and even load balancing into custom applications and frameworks. For example, the JBoss Application - Server makes extensive use of JBoss Cache in clustering services such as HTTP and <ulink url="http://java.sun.com/products/ejb/">EJB</ulink> sessions, as well as + tolerance and even load balancing into custom applications and frameworks. For example, the + <ulink url="http://www.jboss.org/projects/jbossas/">JBoss Application Server</ulink> and Red Hat's + <ulink url="http://www.jboss.com">Enterprise Application Platform</ulink> make extensive use of JBoss Cache to + cluster services such as HTTP and <ulink url="http://java.sun.com/products/ejb/">EJB</ulink> sessions, as well as providing a distributed entity cache for <ulink url="http://en.wikipedia.org/wiki/Java_Persistence_API">JPA&...;. </para> <para> @@ -36,8 +38,9 @@ </itemizedlist> </para> <para> - POJO Cache has a complete and separate set of documentation, including a user guide, FAQ and tutorial and - as such, POJO Cache is not discussed further in this book. + POJO Cache has a complete and separate set of documentation, including a user guide, FAQ and tutorial all + available on the JBoss Cache <ulink url="http://www.jboss.org/jbosscache">documentation website</ulink>. + As such, POJO Cache will not be discussed further in this book. </para> </section> @@ -46,74 +49,97 @@ <section> <title>Summary of Features</title> - <para> - JBoss Cache offers a simple and straightforward API, where data (simple Java objects) can be placed in the - cache and, based on configuration options selected, this data may be one or all of: - <itemizedlist> - <listitem>cached in-memory for efficient, threadsafe retrieval.</listitem> - <listitem>replicated to some or all cache instances in a cluster.</listitem> - <listitem>persisted to disk and/or a remote cluster ("far-cache").</listitem> - <listitem>garbage collected from memory when memory runs low, and passivated to disk so state isn't lost. - </listitem> - </itemizedlist> - In addition, JBoss Cache offers a rich set of enterprise-class features: - <itemizedlist> - <listitem>being able to participate in JTA transactions (works with Java EE compliant TransactionManagers). - </listitem> - <listitem>attach to JMX consoles and provide runtime statistics on the state of the cache.</listitem> - <listitem>allow client code to attach listeners and receive notifications on cache events.</listitem> - </itemizedlist> - </para> + <section> + <title>Caching objects</title> - <para>A cache is organised as a tree, with a single root. Each node in the tree essentially contains a Map, - which acts as a store for key/value pairs. The only requirement placed on objects that are cached is that - they implement - <literal>java.io.Serializable</literal>. - </para> + <para> + JBoss Cache offers a simple and straightforward API, where data - simple Java objects - can be placed in the + cache. Based on configuration options selected, this data may be one or all of: + <itemizedlist> + <listitem>cached in-memory for efficient, threadsafe retrieval.</listitem> + <listitem>replicated to some or all cache instances in a cluster.</listitem> + <listitem>persisted to disk and/or a remote, in-memory cache cluster ("far-cache").</listitem> + <listitem>garbage collected from memory when memory runs low, and passivated to disk so state isn't lost. + </listitem> + </itemizedlist> + In addition, JBoss Cache offers a rich set of enterprise-class features: + <itemizedlist> + <listitem>being able to participate in <ulink url="http://java.sun.com/products/jta">JTA</ulink> transactions + (works with most Java EE compliant transaction managers).</listitem> + <listitem>attach to JMX consoles and provide runtime statistics on the state of the cache.</listitem> + <listitem>allow client code to attach listeners and receive notifications on cache events.</listitem> + <listitem>allow grouping of cache operations into batches, for efficient replication</listitem> + </itemizedlist> + </para> + </section> - <para>JBoss Cache - can be either local or replicated. Local trees exist - only inside the JVM in which they are created, whereas replicated trees - propagate any changes to some or all other trees in the same cluster. A - cluster may span different hosts on a network or just different JVMs - on a single host. - </para> + <section> + <title>Local and clustered modes</title> - <para>When a change is made to an object in the cache and that change is done in - the context of a transaction, the replication of changes is deferred until the transaction - commits successfully. All modifications are kept in a list associated with - the transaction for the caller. When the transaction commits, we replicate the - changes. Otherwise, (on a rollback) we simply undo the changes locally - resulting in zero network traffic and overhead. For example, if a caller - makes 100 modifications and then rolls back the transaction, we will not replicate - anything, resulting in no network traffic. - </para> + <para> + The cache is organised as a tree, with a single root. Each node in the tree essentially contains a map, + which acts as a store for key/value pairs. The only requirement placed on objects that are cached is that + they implement <literal>java.io.Serializable</literal>. + </para> - <para>If a caller has no transaction associated with it, we will replicate right after each modification, e.g. in the above - case we would send 100 messages, plus an additional message for the - rollback. In this sense, running without a transaction can be thought of as analogous as running with - auto-commit switched on in JDBC terminology, where each operation is committed automatically. - </para> + <para> + JBoss Cache can be either local or replicated. Local caches exist only within the scope of the JVM in which + they are created, whereas replicated caches propagate any changes to some or all other caches in the same + cluster. A cluster may span different hosts on a network or just different JVMs on a single host. + </para> - <para> - JBoss Cache works out of the box with most popular transaction managers, and even provides an API where - custom transaction manager lookups can be written. - </para> + </section> - <para> - The cache is also completely thread-safe. It uses multi-versioned concurrency control (MVCC) to ensure thread - safety between readers and writers, while maintaining a high degree of concurrency. The specific MVCC implementation - used in JBoss Cache allows for readers to be completely free of locks and synchronized blocks, ensuring a very high - degree of performance for read-heavy applications. + <section> + <title>Clustered caches and transactions</title> + + <para> + When a change is made to an object in the cache and that change is done in + the context of a transaction, the replication of changes is deferred until the transaction + completes successfully. All modifications are kept in a list associated with + the transaction of the caller. When the transaction commits, changes are replicated. Otherwise, on a rollback, + we simply undo the changes locally and discard the modification list, resulting in zero network traffic and + overhead. For example, if a caller makes 100 modifications and then rolls back the transaction, nothing is + replicated, resulting in no network traffic. </para> - <para> - Optimistic and pessimistic locking schemes, from older versions of JBoss Cache, are still available but are - deprecated in favour of MVCC, and will be removed in future releases. - </para> - <para> - The JBoss Cache MVCC implementation supports READ_COMMITTED and REPEATABLE_READ isolation levels, corresponding - to their database equivalents. - </para> + + <para> + If a caller has no transaction or batch associated with it, modifications are replicated immediately. E.g. + in the example used earlier, 100 messages would be broadcast for each modification. In this sense, running without + a batch or transaction can be thought of as analogous as running with auto-commit switched on in JDBC terminology, + where each operation is committed automatically and immediately. + </para> + + <para> + JBoss Cache works out of the box with most popular transaction managers, and even provides an API where + custom transaction manager lookups can be written. + </para> + + <para> + All of the above holds true for batches as well, which has similar behavior. + </para> + </section> + + + <section> + <title>Thread safety</title> + <para> + The cache is completely thread-safe. It employs multi-versioned concurrency control (MVCC) to ensure thread + safety between readers and writers, while maintaining a high degree of concurrency. The specific MVCC implementation + used in JBoss Cache allows for reader threads to be completely free of locks and synchronized blocks, ensuring a very high + degree of performance for read-heavy applications. It also uses custom, highly performant lock implementations + that employ modern compare-and-swap techniques for writer threads, which are tuned to multicore CPU architectures. + </para> + <para> + Optimistic and pessimistic locking schemes from older versions of JBoss Cache are still available but are + deprecated in favour of MVCC, and will be removed in future releases. Use of these locking schemes is + strongly discouraged. + </para> + <para> + The JBoss Cache MVCC implementation only supports READ_COMMITTED and REPEATABLE_READ isolation levels, corresponding + to their database equivalents. + </para> + </section> </section> <section> @@ -121,10 +147,11 @@ Requirements </title> <para> - JBoss Cache requires Java 5.0 (or newer). + JBoss Cache requires a Java 5.0 (or newer) compatible virtual machine and set of libraries, and is developed + and tested on Sun's JDK 5.0 and JDK 6. </para> <para> - However, there is a way to build JBoss Cache as a Java 1.4.x compatible binary using + There is a way to build JBoss Cache as a Java 1.4.x compatible binary using <ulink url="http://www.jboss.org/community/docs/DOC-10738">JBossRet... to retroweave the Java 5.0 binaries. However, Red Hat Inc. does not offer professional support around the retroweaved @@ -135,16 +162,16 @@ </para> <para> In addition to Java 5.0, at a minimum, JBoss Cache has dependencies on - <ulink url="http://www.jgroups.org">JGroups</ulink> - , and Apache's <ulink url="http://jakarta.apache.org/commons/logging/">commons-log...;. - JBoss Cache ships with all dependent libraries necessary to run out of the box. + <ulink url="http://www.jgroups.org">JGroups</ulink>, and Apache's + <ulink url="http://jakarta.apache.org/commons/logging/">commons-log...;. JBoss Cache ships with all + dependent libraries necessary to run out of the box, as well as several optional jars for optional features. </para> </section> <section> <title>License</title> <para> - JBoss Cache is an open source product, using the business and OEM-friendly + JBoss Cache is an open source project, using the business and OEM-friendly <ulink url="http://www.opensource.org/">OSI-approved</ulink> <ulink url="http://www.gnu.org/copyleft/lesser.html">LGPL license.</ulink> Commercial development support, production support and training for JBoss Cache is available through Modified: core/trunk/src/main/docbook/userguide/en/modules/preface.xml =================================================================== --- core/trunk/src/main/docbook/userguide/en/modules/preface.xml 2008-10-15 15:44:27 UTC (rev 6957) +++ core/trunk/src/main/docbook/userguide/en/modules/preface.xml 2008-10-15 18:11:20 UTC (rev 6958) @@ -3,7 +3,7 @@ <para> This is the official JBoss Cache user guide. Along with its accompanying documents (an FAQ, a tutorial and a - whole set of documents on POJO Cache), this is freely available on the JBoss Cache <ulink url="http://labs.jboss.com/jbosscache">documentation site.</ulink> + whole set of documents on POJO Cache), this is freely available on the JBoss Cache <ulink url="http://www.jboss.org/jbosscache">documentation website</ulink>. </para> <para> When used, JBoss Cache refers to JBoss Cache Core, a tree-structured, clustered, transactional cache. @@ -27,16 +27,15 @@ </para> <para> - For further discussion, use the - <ulink url="http://jboss.org/index.html?module=bb&amp;op=main&amp;c... forum</ulink> - linked on the JBoss Cache <ulink url="http://labs.jboss.com/jbosscache">website.</ulink> We also provide a mechanism for - tracking bug reports and feature requests on the JBoss Cache <ulink url="http://jira.jboss.com/jira/browse/JBCACHE">JIRA issue tracker.</ulink> + For further discussion, use the user forum available on the JBoss Cache + <ulink url="http://www.jboss.org/jbosscache">website.</ulink> We also provide a mechanism for + tracking bug reports and feature requests on the JBoss Cache <ulink url="http://jira.jboss.com/jira/browse/JBCACHE">JIRA issue tracker</ulink>. </para> <para> If you are interested in the development of JBoss Cache or in translating this documentation into other languages, - we'd love to hear from you. Please post a message on the - <ulink url="http://jboss.org/index.html?module=bb&amp;op=main&amp;c... forum</ulink> - or contact us by using the JBoss Cache <ulink url="https://lists.jboss.org/mailman/listinfo/jbosscache-dev"&g... mailing list.</ulink> + we'd love to hear from you. Please post a message on the JBoss Cache + <ulink url="http://www.jboss.org/jbosscache">user forum</ulink> + or contact us by using the JBoss Cache <ulink url="https://lists.jboss.org/mailman/listinfo/jbosscache-dev"&g... mailing list</ulink>. </para> <para> @@ -46,7 +45,11 @@ </para> <para> - Happy reading! + I always appreciate feedback, suggestions and corrections, and these should be directed to the + <ulink url="https://lists.jboss.org/mailman/listinfo/jbosscache-dev"&g... mailing list</ulink> rather than + direct emails to any of the authors. We hope you find this book useful, and wish you happy reading! </para> - + <para> + <emphasis role="bold">Manik Surtani</emphasis>, October 2008 + </para> </preface> \ No newline at end of file