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

Author: manik.surtani(a)jboss.com Date: 2008-10-17 14:11:32 -0400 (Fri, 17 Oct 2008) New Revision: 6981 Modified: core/trunk/src/main/docbook/faq/en/master.xml core/trunk/src/main/docbook/userguide/en/master.xml core/trunk/src/main/docbook/userguide/en/modules/architecture.xml core/trunk/src/main/docbook/userguide/en/modules/cache_loaders.xml core/trunk/src/main/docbook/userguide/en/modules/compatibility.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 core/trunk/src/main/docbook/userguide/en/modules/replication.xml core/trunk/src/main/docbook/userguide/en/modules/transactions.xml core/trunk/src/main/java/org/jboss/cache/Cache.java core/trunk/src/main/java/org/jboss/cache/CacheSPI.java 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-17 17:17:17 UTC (rev 6980) +++ core/trunk/src/main/docbook/faq/en/master.xml 2008-10-17 18:11:32 UTC (rev 6981) @@ -94,7 +94,7 @@ <literal>org.jboss.cache.pojo.PojoCache</literal> interface) is built atop the core library and allows introspection 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.) + (often referred to as POJO Cache) comes with a separate set of documentation (Users' Guide, FAQ, etc.) available on the JBoss Cache <ulink url="http://www.jboss.org/jbosscache/">documentation website</ulink>. </para> @@ -216,7 +216,7 @@ <para> Absolutely! Even though JBoss Cache comes integrated with JBoss Application Server, it can also be used in any other Java EE server such as BEA WebLogic, IBM Websphere or Tomcat. It - can also run in a standalone Java process, completely outside of an application server. See the user guide for more + can also run in a standalone Java process, completely outside of an application server. See the Users' Guide for more details. </para> </answer> @@ -438,7 +438,7 @@ every replication change is propagated to all participating members. There is no mechanism for sub-partitioning where some replication can be done within only a subset of members, unless you use the Buddy Replication features. See the - user guide for more details on this. + Users' Guide for more details on this. </para> </answer> </qandaentry> @@ -489,7 +489,7 @@ very easily with no extra impact on memory or network traffic with each node added. </para> <para> - See the User Guide for more information on Buddy Replication, and how it can be used to achieve very + See the Users' Guide for more information on Buddy Replication, and how it can be used to achieve very high scalability. </para> @@ -536,7 +536,7 @@ <para> Yes, it can be. For such cases it is recommended that you configure your cache using the JGroups Multiplexer, which allows several caches to share - a single JGroups channel. Please see the User Guide for details on how to configure the JGroups + a single JGroups channel. Please see the Users' Guide for details on how to configure the JGroups Multiplexer. </para> <para> @@ -752,7 +752,7 @@ <answer> <para> - Please see the configuration section of the user guide for details. + Please see the configuration section of the Users' Guide for details. </para> </answer> </qandaentry> @@ -816,7 +816,7 @@ <literal>jconsole</literal> utility. See the chapter titled <emphasis role="bold">Management Information</emphasis> - in the JBoss Cache user guide for more details. + in the JBoss Cache Users' Guide for more details. </para> </answer> </qandaentry> @@ -827,7 +827,7 @@ </question> <answer> - <para>Yes, you can. See the section on configuration in the JBoss Cache user guide. + <para>Yes, you can. See the section on configuration in the JBoss Cache Users' Guide. </para> </answer> </qandaentry> @@ -912,7 +912,7 @@ replicated to that portion. See the <literal>CacheMarshaller</literal> section of - the user guide for more details. + the Users' Guide for more details. </para> <para>To solve the second kind of issue, you can use the the <literal>UseLazyDeserialization</literal> configuration @@ -948,7 +948,7 @@ <answer> <para> - See the user guide on this subject. + See the Users' Guide on this subject. </para> </answer> </qandaentry> @@ -988,7 +988,7 @@ </para> <para>To implement this feature, please follow the instructions indicated in the example located - in the CacheMarshaller section of the user's guide. It's worth noting that instead of a + in the CacheMarshaller section of the Users' Guide. It's worth noting that instead of a <literal>ServletContextListener</literal> , you could add this code into an <literal>MBean</literal> @@ -1191,7 +1191,7 @@ </listitem> <listitem> - <para>And more. See the chapter on cache loaders in the User Guide for more details.</para> + <para>And more. See the chapter on cache loaders in the Users' Guide for more details.</para> </listitem> </itemizedlist> </para> @@ -1205,7 +1205,7 @@ <answer> <para> - No, it is not. The FileCacheLoader has some severe limitations which restrict it's use in a production + No, it is not. The FileCacheLoader has some severe limitations which restrict its use in a production environment, or if used in such an environment, it should be used with due care and sufficient understanding of these limitations. <itemizedlist> @@ -1225,7 +1225,7 @@ </itemizedlist> As a rule of thumb, it is recommended that the FileCacheLoader not be used in a highly concurrent, - transactional or stressful environment, and it's use is restricted to testing. + transactional or stressful environment, and its use is restricted to testing. </para> </answer> </qandaentry> @@ -1238,7 +1238,7 @@ <answer> <para>Yes. Set the <literal>async</literal> - attrobute to true. See the JBoss Cache User Guide for a more + attrobute to true. See the JBoss Cache Users' Guide for a more detailed discussion. By default though, all cache loader writes are synchronous and will block. </para> @@ -1256,7 +1256,7 @@ or extending <literal>org.jboss.cache.loader.AbstractCacheLoader</literal> . It is - configured via the XML file (see JBoss Cache User Guide). + configured via the XML file (see JBoss Cache Users' Guide). </para> </answer> </qandaentry> @@ -1334,7 +1334,7 @@ <answer> <para>Yes. Within the CacheLoaderConfiguration XML - element (see user guide chapter on cache loaders) you can + element (see Users' Guide chapter on cache loaders) you can describe several cache loaders. The impact is that the cache will look at all of the cache loaders in the order they've been configured, until it finds a valid, non-null element of data. When @@ -1354,7 +1354,7 @@ <answer> <para>Yes. See "Transforming Cache Loaders" section within the "Cache Loaders" section located in the - JBoss Cache users guide. + JBoss Cache Users' Guide. </para> </answer> </qandaentry> @@ -1368,7 +1368,7 @@ <answer> <para> - As of JBoss Cache 2.1.0, the answer is yes. See the User Guide for details on how to configure and + As of JBoss Cache 2.1.0, the answer is yes. See the Users' Guide for details on how to configure and tune your retries and wait period for reestablishing the TCP connection. </para> Modified: core/trunk/src/main/docbook/userguide/en/master.xml =================================================================== --- core/trunk/src/main/docbook/userguide/en/master.xml 2008-10-17 17:17:17 UTC (rev 6980) +++ core/trunk/src/main/docbook/userguide/en/master.xml 2008-10-17 18:11:32 UTC (rev 6981) @@ -18,7 +18,7 @@ ]> <book lang="en"> <bookinfo> - <title>JBoss Cache User Guide</title> + <title>JBoss Cache Users' Guide</title> <subtitle>A clustered, transactional cache</subtitle> <!-- Release version and date --> @@ -78,8 +78,8 @@ &introduction; &basic_api; &configuration; + &batching; &deployment; - &batching; &compatibility; </part> Modified: core/trunk/src/main/docbook/userguide/en/modules/architecture.xml =================================================================== --- core/trunk/src/main/docbook/userguide/en/modules/architecture.xml 2008-10-17 17:17:17 UTC (rev 6980) +++ core/trunk/src/main/docbook/userguide/en/modules/architecture.xml 2008-10-17 18:11:32 UTC (rev 6981) @@ -3,33 +3,16 @@ <section id="architecture.tree_structure"> <title>Data Structures Within The Cache</title> - <para> - A - <literal>Cache</literal> - consists of a collection of - <literal>Node</literal> - instances, organised in a tree - structure. Each - <literal>Node</literal> - contains a - <literal>Map</literal> - which holds the data + A <literal>Cache</literal> consists of a collection of <literal>Node</literal> instances, organised in a tree + structure. Each <literal>Node</literal> contains a <literal>Map</literal> which holds the data objects to be cached. It is important to note that the structure is a mathematical tree, and not a graph; each - <literal>Node</literal> - has one and only one parent, and the root node is denoted by the constant fully qualitied name, - <literal>Fqn.ROOT</literal> - . + <literal>Node</literal> has one and only one parent, and the root node is denoted by the constant fully qualified + name, <literal>Fqn.ROOT</literal>. </para> <para> - The reason for organising nodes as such is to improve concurrent access to data and make replication and - persistence - more fine-grained. - </para> - <para> <figure> <title>Data structured as a tree</title> - <mediaobject> <imageobject> <imagedata fileref="TreeCacheArchitecture.png"/> @@ -39,16 +22,10 @@ In the diagram above, each box represents a JVM. You see 2 caches in separate JVMs, replicating data to each other. - These VMs can be located on the same physical machine, or on 2 different machines connected by a network link. - The - underlying group communication between networked nodes is done using - <ulink url="http://www.jgroups.org">JGroups</ulink> - . </para> - <para>Any modifications (see - <link linkend="api">API chapter</link> - ) in one cache instance will be replicated to + <para> + Any modifications (see <link linkend="api">API chapter</link>) in one cache instance will be replicated to the other cache. Naturally, you can have more than 2 caches in a cluster. Depending on the transactional settings, this replication will occur either after each modification or at the end of a transaction, at commit time. When a new cache is created, it can optionally acquire the contents @@ -59,21 +36,11 @@ <section id="architecture.SPI_interfaces"> <title>SPI Interfaces</title> <para> - In addition to - <literal>Cache</literal> - and - <literal>Node</literal> - interfaces, JBoss Cache exposes more powerful - <literal>CacheSPI</literal> - and - <literal>NodeSPI</literal> - interfaces, which offer more control over the internals - of JBoss Cache. These interfaces are not intended for general use, but are designed for people who wish to - extend and enhance JBoss Cache, or write custom - <literal>Interceptor</literal> - or - <literal>CacheLoader</literal> - instances. + In addition to <literal>Cache</literal> and <literal>Node</literal> interfaces, JBoss Cache exposes more + powerful <literal>CacheSPI</literal> and <literal>NodeSPI</literal> interfaces, which offer more control over + the internals of JBoss Cache. These interfaces are not intended for general use, but are designed for people + who wish to extend and enhance JBoss Cache, or write custom <literal>Interceptor</literal> or + <literal>CacheLoader</literal> instances. </para> <figure> <title>SPI Interfaces</title> @@ -85,41 +52,21 @@ </mediaobject> </figure> <para> - The - <literal>CacheSPI</literal> - interface cannot be created, but is injected into - <literal>Interceptor</literal> - and - <literal>CacheLoader</literal> - implementations by the - <literal>setCache(CacheSPI cache)</literal> - methods on these interfaces. - <literal>CacheSPI</literal> - extends - <literal>Cache</literal> - so all the functionality of the basic API is made available. + The <literal>CacheSPI</literal> interface cannot be created, but is injected into <literal>Interceptor</literal> + and <literal>CacheLoader</literal> implementations by the <literal>setCache(CacheSPI cache)</literal> + methods on these interfaces. <literal>CacheSPI</literal> extends <literal>Cache</literal> + so all the functionality of the basic API is also available. </para> <para> - Similarly, a - <literal>NodeSPI</literal> - interface cannot be created. Instead, one is obtained by performing operations on - <literal>CacheSPI</literal> - , - obtained as above. For example, - <literal>Cache.getRoot() : Node</literal> - is overridden as - <literal>CacheSPI.getRoot() : NodeSPI</literal> - . + Similarly, a <literal>NodeSPI</literal> interface cannot be created. Instead, one is obtained by performing + operations on <literal>CacheSPI</literal>, obtained as above. For example, <literal>Cache.getRoot() : Node</literal> + is overridden as <literal>CacheSPI.getRoot() : NodeSPI</literal>. </para> <para> - It is important to note that directly casting a - <literal>Cache</literal> - or - <literal>Node</literal> - to it's SPI - counterpart is not recommended and is bad practice, since the inheritace of interfaces it is not a contract - that is guaranteed to be upheld moving forward. The exposed public APIs, on the other hand, is guaranteed to - be upheld. + It is important to note that directly casting a <literal>Cache</literal> or <literal>Node</literal> + to its SPI counterpart is not recommended and is bad practice, since the inheritace of interfaces it is not a + contract that is guaranteed to be upheld moving forward. The exposed public APIs, on the other hand, is + guaranteed to be upheld. </para> </section> @@ -133,42 +80,33 @@ when the cache is created, based on the configuration used. </para> <para> - It is important to note that the - <literal>NodeSPI</literal> - offers some methods (such as the - <literal>xxxDirect()</literal> - method - family) that operate on a node directly without passing through the interceptor stack. Plugin authors should - note - that using such methods will affect the aspects of the cache that may need to be applied, such as locking, - replication, etc. Basically, don't use such methods unless you - <emphasis>really</emphasis> + It is important to note that the <literal>NodeSPI</literal> offers some methods (such as the <literal>xxxDirect()</literal> + method family) that operate on a node directly without passing through the interceptor stack. Plugin authors + should note that using such methods will affect the aspects of the cache that may need to be applied, such as + locking, replication, etc. To put it simply, don't use such methods unless you <emphasis>really</emphasis> know what you're doing! </para> - <section id="architecture.interceptors"> + + <section id="architecture.interceptors"> <title>Interceptors</title> <para> - An - <literal>Interceptor</literal> - is an abstract class, several of which comprise an interceptor chain. It - exposes an - <literal>invoke()</literal> - method, which must be overridden by implementing classes to add behaviour - to a call before passing the call down the chain by calling - <literal>super.invoke()</literal> - . + JBoss Cache essentially is a core data structure - an implementation of <literal>DataContainer</literal> - and + aspects and features are implemented using interceptors in front of this data structure. A + <literal>CommandInterceptor</literal> is an abstract class, interceptor implementations extend this. </para> - <figure> - <title>SPI Interfaces</title> - - <mediaobject> - <imageobject> - <imagedata fileref="Interceptor.png"/> - </imageobject> - </mediaobject> - </figure> <para> - JBoss Cache ships with several interceptors, representing different configuration options, some of which + <literal>CommandInterceptor</literal> implements the <literal>Visitor</literal> interface so it is able to + alter commands in a strongly typed manner as the command makes its way to the data structure. More on + visitors and commands in the next section. + </para> + <para> + Interceptor implementations are chained together in the <literal>InterceptorChain</literal> class, which + dispatches a command across the chain of interceptors. A special interceptor, the <literal>CallInterceptor</literal>, + always sits at the end of this chain to invoke the command being passed up the chain by calling the + command's <literal>process()</literal> method. + </para> + <para> + JBoss Cache ships with several interceptors, representing different behavioral aspects, some of which are: <itemizedlist> <listitem> @@ -178,7 +116,7 @@ </listitem> <listitem> <literal>ReplicationInterceptor</literal> - - replicates state across a cluster using a JGroups channel + - replicates state across a cluster using the RpcManager class </listitem> <listitem> <literal>CacheLoaderInterceptor</literal> @@ -186,51 +124,53 @@ </listitem> </itemizedlist> The interceptor chain configured for your cache instance can be obtained and inspected by calling - <literal>CacheSPI.getInterceptorChain()</literal> - , - which returns an ordered - <literal>List</literal> - of interceptors. + <literal>CacheSPI.getInterceptorChain()</literal>, which returns an ordered <literal>List</literal> + of interceptors in the order in which they would be encountered by a command. </para> <section id="architecture.custom_interceptors"> <title>Writing Custom Interceptors</title> <para> Custom interceptors to add specific aspects or features can be written by extending - <literal>Interceptor</literal> - and overriding - <literal>invoke()</literal> - . The custom interceptor will need to be added to the interceptor chain by using the - <literal>CacheSPI.addInterceptor()</literal> - method. + <literal>CommandInterceptor</literal> and overriding the relevant + <literal>visitXXX()</literal> methods based on the commands you are interested in intercepting. There + are other abstract interceptors you could extend instead, such as the <literal>PrePostProcessingCommandInterceptor</literal> + and the <literal>SkipCheckChainedInterceptor</literal>. Please see their respective javadocs for details + on the extra features provided. </para> <para> - Adding custom interceptors via XML is not supported at this time. + The custom interceptor will need to be added to the interceptor chain by using the + <literal>Cache.addInterceptor()</literal> methods. See the javadocs on these methods for details. </para> + <para> + Adding custom interceptors via XML is also supported, please see the + <link linkend="configuration_reference_chapter">XML configuration reference</link> for details. + </para> </section> </section> - <section id="architecture.methodcalls"> - <title>MethodCalls</title> - <para> - <literal>org.jboss.cache.marshall.MethodCall</literal> - is a class that encapsulates a - <literal>java.lang.reflection.Method</literal> - and an - <literal>Object[]</literal> - representing the method's arguments. It is an extension of the - <literal>org.jgroups.blocks.MethodCall</literal> - class, that adds a mechanism for identifying known methods using magic numbers and method ids, - which makes marshalling and unmarshalling more efficient and performant. - </para> - <para> - This is central to the - <literal>Interceptor</literal> - architecture, and is the only parameter passed in to - <literal>Interceptor.invoke()</literal> - . - </para> - </section> - + <section id="architecture.commands"> + <title>Commands and Visitors</title> + <para> + Internally, JBoss Cache uses a command/visitor pattern to execute API calls. Whenever a method is called + on the cache interface, the <literal>CacheInvocationDelegate</literal>, which implements the <literal>Cache</literal> + interface, creates an instance of <literal>VisitableCommand</literal> and dispatches this command up a chain of + interceptors. Interceptors, which implement the <literal>Visitor</literal> interface, are able to handle + <literal>VisitableCommand</literal>s they are interested in, and add behavior to the command. + </para> + <para> + Each command contains all knowledge of the command being executed such as parameters used and processing + behavior, encapsulated in a <literal>process()</literal> method. For example, the <literal>RemoveNodeCommand</literal> + is created and passed up the interceptor chain when <literal>Cache.removeNode()</literal> is called, and + <literal>RemoveNodeCommand.process()</literal> has the necessary knowledge of how to remove a node from + the data structure. + </para> + <para> + In addition to being visitable, commands are also replicable. The JBoss Cache marshallers know how to + efficiently marshall commands and invoke them on remote cache instances using an internal RPC mechanism + based on JGroups. + </para> + </section> + <section id="architecture.invocationcontext"> <title>InvocationContexts</title> <para> @@ -238,7 +178,7 @@ holds intermediate state for the duration of a single invocation, and is set up and destroyed by the <literal>InvocationContextInterceptor</literal> - which sits at the start of the chain. + which sits at the start of the interceptor chain. </para> <para> <literal>InvocationContext</literal> @@ -255,15 +195,13 @@ linkend="configuration.options"> <literal>Option</literal> overrides - </link> - . + </link>, and information around which nodes have been locked, etc. </para> <para> The <literal>InvocationContext</literal> can be obtained by calling - <literal>Cache.getInvocationContext()</literal> - . + <literal>Cache.getInvocationContext()</literal>. </para> </section> </section> @@ -346,21 +284,17 @@ <literal>VersionAwareMarshaller</literal> and a concrete - <literal>CacheMarshaller200</literal> + <literal>CacheMarshaller300</literal> . </para> <para> The marshaller can be obtained by calling - <literal>CacheSPI.getMarshaller()</literal> - , and defaults to the - <literal>VersionAwareMarshaller</literal> - . + <literal>CacheSPI.getMarshaller()</literal>, and defaults to the + <literal>VersionAwareMarshaller</literal>. Users may also write their own marshallers by implementing the <literal>Marshaller</literal> - interface and - adding it to their configuration, by using the - <literal>MarshallerClass</literal> - configuration attribute. + interface or extending the <literal>AbstractMarshaller</literal> class, and adding it to their configuration + by using the <literal>Configuration.setMarshallerClass()</literal> setter. </para> </section> @@ -376,86 +310,16 @@ know which specific marshaller implementation to delegate the call to. For example, <literal>CacheMarshaller200</literal> - , is the marshaller for JBoss Cache 2.0.x. - JBoss Cache 2.1.x, say, may ship with - <literal>CacheMarshaller210</literal> - with an improved wire protocol. - Using a + is the marshaller for JBoss Cache 2.0.x. + JBoss Cache 3.0.x ships with + <literal>CacheMarshaller300</literal> + with an improved wire protocol. Using a <literal>VersionAwareMarshaller</literal> helps achieve wire protocol compatibility between minor releases but still affords us the flexibility to tweak and improve the wire protocol between minor or micro releases. </para> - - <section> - <title>CacheLoaders</title> - <para> - Some of the existing cache loaders, such as the - <literal>JDBCCacheLoader</literal> - and the - <literal>FileCacheLoader</literal> - relied on persisting data using - <literal>ObjectOutputStream</literal> - as well, but now, they are using the - <literal>VersionAwareMarshaller</literal> - to marshall the persisted - data to their cache stores. - </para> - </section> - </section> - - <section> - <title>CacheMarshaller200</title> - <para> - This marshaller treats well-known objects that need marshalling - such as - <literal>MethodCall</literal> - , - <literal>Fqn</literal> - , - <literal>DataVersion</literal> - , and even some JDK objects such as - <literal>String</literal> - , - <literal>List</literal> - , - <literal>Boolean</literal> - and others as types that do not need complete class definitions. - Instead, each of these well-known types are represented by a - <literal>short</literal> - , which is a lot more efficient. - </para> - <para> - In addition, reference counting is done to reduce duplication of writing certain objects multiple times, to - help - keep the streams small and efficient. - </para> - <para> - Also, if - <literal>UseRegionBasedMarshalling</literal> - is enabled (disabled by default) the marshaller adds region - information to the stream before writing any data. This region information is in the form of a - <literal>String</literal> - representation of an - <literal>Fqn</literal> - . When unmarshalling, the - <literal>RegionManager</literal> - can be used to - find the relevant - <literal>Region</literal> - , and use a region-specific - <literal>ClassLoader</literal> - to unmarshall - the stream. This is specifically useful when used to cluster state for application servers, where each - deployment has - it's own - <literal>ClassLoader</literal> - . See the section below on - <link linkend="architecture.regions">regions</link> - for more information. - </para> - </section> - </section> <section id="architecture.regions"> <title>Class Loading and Regions</title> @@ -468,15 +332,12 @@ would require replication. It is common for application servers to assign separate <literal>ClassLoader</literal> instances to each application deployed, but have JBoss Cache libraries referenced by the application server's - <literal>ClassLoader</literal> - . + <literal>ClassLoader</literal>. </para> <para> To enable us to successfully marshall and unmarshall objects from such class loaders, we use a concept called regions. A region is a portion of the cache which share a common class loader (a region also has other uses - - see - <link linkend="eviction_policies">eviction policies</link> - ). + see <link linkend="eviction_policies">eviction policies</link>). </para> <para> A region is created by using the @@ -490,9 +351,7 @@ are active unless the <literal>InactiveOnStartup</literal> configuration attribute is set to - <literal>true</literal> - . + <literal>true</literal>. </para> </section> - </chapter> Modified: core/trunk/src/main/docbook/userguide/en/modules/cache_loaders.xml =================================================================== --- core/trunk/src/main/docbook/userguide/en/modules/cache_loaders.xml 2008-10-17 17:17:17 UTC (rev 6980) +++ core/trunk/src/main/docbook/userguide/en/modules/cache_loaders.xml 2008-10-17 18:11:32 UTC (rev 6981) @@ -151,22 +151,15 @@ ... <!-- Cache loader config block --> -<attribute name="CacheLoaderConfiguration"> - <config> +<!-- if passivation is true, only the first cache loader is used; the rest are ignored --> +<loaders passivation="false" shared="false"> + <preload> + <!-- Fqns to preload --> + <node fqn="/some/stuff"/> + </preload> <!-- if passivation is true, only the first cache loader is used; the rest are ignored --> - <passivation>false</passivation> - <!-- comma delimited FQNs to preload --> - <preload>/</preload> - <!-- are the cache loaders shared in a cluster? --> - <shared>false</shared> - - <!-- we can now have multiple cache loaders, which get chained --> - <!-- the 'cacheloader' element may be repeated --> - <cacheloader> - - <class>org.jboss.cache.loader.JDBCCacheLoader</class> - - <!-- properties to pass in to the cache loader --> + <loader class="org.jboss.cache.loader.JDBCCacheLoader" async="false" fetchPersistentState="true" + ignoreModifications="false" purgeOnStartup="false"> <properties> cache.jdbc.driver=com.mysql.jdbc.Driver cache.jdbc.url=jdbc:mysql://localhost:3306/jbossdb @@ -174,43 +167,8 @@ cache.jdbc.password= cache.jdbc.sql-concat=concat(1,2) </properties> - - <!-- whether the cache loader writes are asynchronous --> - <async>false</async> - - <!-- only one cache loader in the chain may set fetchPersistentState to true. - An exception is thrown if more than one cache loader sets this to true. --> - <fetchPersistentState>true</fetchPersistentState> - - <!-- determines whether this cache loader ignores writes - defaults to false. --> - <ignoreModifications>false</ignoreModifications> - - <!-- if set to true, purges the contents of this cache loader when the cache starts up. - Defaults to false. --> - <purgeOnStartup>false</purgeOnStartup> - - <!-- defines the cache loader as a singleton store where only the coordinator of the - cluster will store modifications. --> - <singletonStore> - <!-- if true, singleton store functionality is enabled, defaults to false --> - <enabled>false</enabled> - - <!-- implementation class for singleton store functionality which must extend - org.jboss.cache.loader.AbstractDelegatingCacheLoader. Default implementation - is org.jboss.cache.loader.SingletonStoreCacheLoader --> - <class>org.jboss.cache.loader.SingletonStoreCacheLoader</class> - - <!-- properties and default values for the default singleton store functionality - implementation --> - <properties> - pushStateWhenCoordinator=true - pushStateWhenCoordinatorTimeout=20000 - </properties> - </singletonStore> - </cacheloader> - - </config> -</attribute> + </loader> + </loaders> ]]></programlisting> <para>The @@ -344,6 +302,28 @@ <section> <title>Singleton Store Configuration</title> + <programlisting role="XML"><![CDATA[ + <loaders passivation="false" shared="true"> + <preload> + <node fqn="/a/b/c"/> + <node fqn="/f/r/s"/> + </preload> + + <!-- we can now have multiple cache loaders, which get chained --> + <loader class="org.jboss.cache.loader.JDBCCacheLoader" async="false" fetchPersistentState="false" + ignoreModifications="false" purgeOnStartup="false"> + <properties> + cache.jdbc.datasource=java:/DefaultDS + </properties> + <singletonStore enabled="true" class="org.jboss.cache.loader.SingletonStoreCacheLoader"> + <properties> + pushStateWhenCoordinator=true + pushStateWhenCoordinatorTimeout=20000 + </properties> + </singletonStore> + </loader> + </loaders> + ]]></programlisting> <para> <literal>singletonStore</literal> element enables modifications to be stored by only one node in the cluster, @@ -355,7 +335,7 @@ subelement to true in all nodes, but again only the coordinator of the cluster will store the modifications in the underlying cache loader as defined in - <literal>cacheloader</literal> + <literal>loader</literal> element. You cannot define a cache loader as <literal>shared</literal> and with @@ -446,6 +426,7 @@ coordinator crashes or stops responding. </para> </section> + </section> <section id="cl.impls"> @@ -459,7 +440,7 @@ <para> JBoss Cache ships with several cache loaders that utilise the file system as a data store. They all require that the - <literal><![CDATA[<cacheloader><properties>]]></literal> + <literal><![CDATA[<loader><properties>]]></literal> configuration element contains a <literal>location</literal> @@ -486,7 +467,7 @@ ). </para> <para> - The FileCacheLoader has some severe limitations which restrict it's use in a production + The FileCacheLoader has some severe limitations which restrict its use in a production environment, or if used in such an environment, it should be used with due care and sufficient understanding of these limitations. <itemizedlist> @@ -506,7 +487,7 @@ </itemizedlist> As a rule of thumb, it is recommended that the FileCacheLoader not be used in a highly concurrent, - transactional or stressful environment, and it's use is restricted to testing. + transactional or stressful environment, and its use is restricted to testing. </para> </listitem> @@ -602,8 +583,7 @@ </para> <para> - <literal>Fqn</literal> - 's are stored as strings. Node content is stored + <literal>Fqn</literal>s are stored as strings. Node content is stored as a BLOB. <emphasis>WARNING:</emphasis> JBoss Cache does not impose any @@ -626,10 +606,7 @@ </para> <para>See - <ulink - url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JDBCCacheLoader"> - http://wiki.jboss.org/wiki/Wiki.jsp?page=JDBCCacheLoader - </ulink> + <ulink url="http://www.jboss.org/community/docs/DOC-10864">this wiki page</ulink> for configuration tips with specific database systems. </para> @@ -646,7 +623,7 @@ <emphasis>cache.jdbc.table.name</emphasis> - the name of the table. Can be prepended with schema name for the given table: - &lt;schema_name&gt;.&lt;table_name&gt;. + <literal>{schema_name}.{table_name}</literal>. The default value is 'jbosscache'. </listitem> @@ -798,37 +775,31 @@ </para> <programlisting role="XML"><![CDATA[ -<attribute name="CacheLoaderConfiguration"> -<config> - <passivation>false</passivation> - <preload>/some/stuff</preload> - <cacheloader> - <class>org.jboss.cache.loader.JDBCCacheLoader</class> - - <properties> - cache.jdbc.table.name=jbosscache - cache.jdbc.table.create=true - cache.jdbc.table.drop=true - cache.jdbc.table.primarykey=jbosscache_pk - cache.jdbc.fqn.column=fqn - cache.jdbc.fqn.type=varchar(255) - cache.jdbc.node.column=node - cache.jdbc.node.type=blob - cache.jdbc.parent.column=parent - cache.jdbc.driver=oracle.jdbc.OracleDriver - cache.jdbc.url=jdbc:oracle:thin:@localhost:1521:JBOSSDB - cache.jdbc.user=SCOTT - cache.jdbc.password=TIGER - cache.jdbc.sql-concat=concat(1,2) - </properties> - - <async>false</async> - <fetchPersistentState>true</fetchPersistentState> - <ignoreModifications>false</ignoreModifications> - <purgeOnStartup>false</purgeOnStartup> - </cacheloader> -</config> -</attribute> +<loaders passivation="false" shared="false"> + <preload> + <node fqn="/some/stuff"/> + </preload> + <!-- if passivation is true, only the first cache loader is used; the rest are ignored --> + <loader class="org.jboss.cache.loader.JDBCCacheLoader" async="false" fetchPersistentState="true" + ignoreModifications="false" purgeOnStartup="false"> + <properties> + cache.jdbc.table.name=jbosscache + cache.jdbc.table.create=true + cache.jdbc.table.drop=true + cache.jdbc.table.primarykey=jbosscache_pk + cache.jdbc.fqn.column=fqn + cache.jdbc.fqn.type=varchar(255) + cache.jdbc.node.column=node + cache.jdbc.node.type=blob + cache.jdbc.parent.column=parent + cache.jdbc.driver=oracle.jdbc.OracleDriver + cache.jdbc.url=jdbc:oracle:thin:@localhost:1521:JBOSSDB + cache.jdbc.user=SCOTT + cache.jdbc.password=TIGER + cache.jdbc.sql-concat=concat(1,2) + </properties> + </loader> + </loaders> ]]></programlisting> <para>As an alternative to configuring the entire JDBC connection, @@ -836,63 +807,51 @@ </para> <programlisting role="XML"><![CDATA[ -<attribute name="CacheLoaderConfiguration"> -<config> - <passivation>false</passivation> - <preload>/some/stuff</preload> - <cacheloader> - <class>org.jboss.cache.loader.JDBCCacheLoader</class> - - <properties> - cache.jdbc.datasource=java:/DefaultDS - </properties> - - <async>false</async> - <fetchPersistentState>true</fetchPersistentState> - <ignoreModifications>false</ignoreModifications> - <purgeOnStartup>false</purgeOnStartup> - </cacheloader> -</config> -</attribute> + <loaders passivation="false" shared="false"> + <preload> + <node fqn="/some/stuff"/> + </preload> + <!-- if passivation is true, only the first cache loader is used; the rest are ignored --> + <loader class="org.jboss.cache.loader.JDBCCacheLoader" async="false" fetchPersistentState="true" + ignoreModifications="false" purgeOnStartup="false"> + <properties> + cache.jdbc.datasource=java:/DefaultDS + </properties> + </loader> + </loaders> ]]></programlisting> <para>Cconfiguration example for a cache loader using c3p0 JDBC connection pooling:</para> <programlisting role="XML"><![CDATA[ -<attribute name="CacheLoaderConfiguration"> -<config> - <passivation>false</passivation> - <preload>/some/stuff</preload> - <cacheloader> - <class>org.jboss.cache.loader.JDBCCacheLoader</class> - - <properties> - cache.jdbc.table.name=jbosscache - cache.jdbc.table.create=true - cache.jdbc.table.drop=true - cache.jdbc.table.primarykey=jbosscache_pk - cache.jdbc.fqn.column=fqn - cache.jdbc.fqn.type=varchar(255) - cache.jdbc.node.column=node - cache.jdbc.node.type=blob - cache.jdbc.parent.column=parent - cache.jdbc.driver=oracle.jdbc.OracleDriver - cache.jdbc.url=jdbc:oracle:thin:@localhost:1521:JBOSSDB - cache.jdbc.user=SCOTT - cache.jdbc.password=TIGER - cache.jdbc.sql-concat=concat(1,2) - cache.jdbc.connection.factory=org.jboss.cache.loader.C3p0ConnectionFactory - c3p0.maxPoolSize=20 - c3p0.checkoutTimeout=5000 - </properties> - - <async>false</async> - <fetchPersistentState>true</fetchPersistentState> - <ignoreModifications>false</ignoreModifications> - <purgeOnStartup>false</purgeOnStartup> - </cacheloader> -</config> -</attribute> + <loaders passivation="false" shared="false"> + <preload> + <node fqn="/some/stuff"/> + </preload> + <!-- if passivation is true, only the first cache loader is used; the rest are ignored --> + <loader class="org.jboss.cache.loader.JDBCCacheLoader" async="false" fetchPersistentState="true" + ignoreModifications="false" purgeOnStartup="false"> + <properties> + cache.jdbc.table.name=jbosscache + cache.jdbc.table.create=true + cache.jdbc.table.drop=true + cache.jdbc.table.primarykey=jbosscache_pk + cache.jdbc.fqn.column=fqn + cache.jdbc.fqn.type=varchar(255) + cache.jdbc.node.column=node + cache.jdbc.node.type=blob + cache.jdbc.parent.column=parent + cache.jdbc.driver=oracle.jdbc.OracleDriver + cache.jdbc.url=jdbc:oracle:thin:@localhost:1521:JBOSSDB + cache.jdbc.user=SCOTT + cache.jdbc.password=TIGER + cache.jdbc.sql-concat=concat(1,2) + cache.jdbc.connection.factory=org.jboss.cache.loader.C3p0ConnectionFactory + c3p0.maxPoolSize=20 + c3p0.checkoutTimeout=5000 + </properties> + </loader> + </loaders> ]]></programlisting> </section> @@ -1110,7 +1069,7 @@ </para> <para> - As of JBoss Cache 2.1.0, the TcpDelegatingCacheLoader transparently handles reconnects if the connection + As of JBoss Cache 2.1.0, the <literal>TcpDelegatingCacheLoader</literal> transparently handles reconnects if the connection to the TcpCacheServer is lost. </para> @@ -1132,19 +1091,20 @@ <para>The configuration looks as follows:</para> <programlisting role="XML"><![CDATA[ -<attribute name="CacheLoaderConfiguration"> -<config> - <cacheloader> - <class>org.jboss.cache.loader.TcpDelegatingCacheLoader</class> - <properties> - host=myRemoteServer - port=7500 - timeout=10000 - reconnectWaitTime=250 - </properties> - </cacheloader> -</config> -</attribute> + <loaders passivation="false" shared="false"> + <preload> + <node fqn="/"/> + </preload> + <!-- if passivation is true, only the first cache loader is used; the rest are ignored --> + <loader class="org.jboss.cache.loader.TcpDelegatingCacheLoader"> + <properties> + host=myRemoteServer + port=7500 + timeout=10000 + reconnectWaitTime=250 + </properties> + </loader> + </loaders> ]]></programlisting> <para>This means this instance of JBoss Cache will delegate all load @@ -1298,22 +1258,22 @@ <para>When passivation is disabled:</para> <programlisting> - 1) RAM: /A Disk: /A - 2) RAM: /A, /B Disk: /A, /B - 3) RAM: /B Disk: /A, /B - 4) RAM: /A, /B Disk: /A, /B - 5) RAM: /A Disk: /A, /B - 6) RAM: /A Disk: /A + 1) Memory: /A Disk: /A + 2) Memory: /A, /B Disk: /A, /B + 3) Memory: /B Disk: /A, /B + 4) Memory: /A, /B Disk: /A, /B + 5) Memory: /A Disk: /A, /B + 6) Memory: /A Disk: /A </programlisting> <para>When passivation is enabled:</para> <programlisting> - 1) RAM: /A Disk: - 2) RAM: /A, /B Disk: - 3) RAM: /B Disk: /A - 4) RAM: /A, /B Disk: - 5) RAM: /A Disk: /B - 6) RAM: /A Disk: + 1) Memory: /A Disk: + 2) Memory: /A, /B Disk: + 3) Memory: /B Disk: /A + 4) Memory: /A, /B Disk: + 5) Memory: /A Disk: /B + 6) Memory: /A Disk: </programlisting> </section> Modified: core/trunk/src/main/docbook/userguide/en/modules/compatibility.xml =================================================================== --- core/trunk/src/main/docbook/userguide/en/modules/compatibility.xml 2008-10-17 17:17:17 UTC (rev 6980) +++ core/trunk/src/main/docbook/userguide/en/modules/compatibility.xml 2008-10-17 18:11:32 UTC (rev 6981) @@ -1,10 +1,12 @@ <chapter id="compatibility"> <title>Version Compatibility and Interoperability</title> + <section> + <title>API compatibility</title> <para> Within a major version, releases of JBoss Cache are meant to be compatible and interoperable. Compatible in the sense that it should be possible to - upgrade an application from one version to another by simply replacing the + upgrade an application from one version to another by simply replacing jars. Interoperable in the sense that if two different versions of JBoss Cache are used in the same cluster, they should be able to exchange replication and state transfer messages. Note however that interoperability @@ -15,22 +17,31 @@ <para> As such, JBoss Cache 2.x.x is not API or binary compatible with prior 1.x.x versions. - However, JBoss Cache 2.1.x will be API and binary compatible with 2.0.x. + On the other hand, JBoss Cache 2.1.x will be API and binary compatible with 2.0.x. </para> <para> - A configuration attribute, <literal>ReplicationVersion</literal>, is available and is used + We have made best efforts, however, to keep JBoss Cache 3.x both binary and API compatible with 2.x. Still, + it is recommended that client code is updated not to use deprecated methods, classes and configuration files. + </para> + </section> + <section> + <title>Wire-level interoperability</title> + + <para> + A configuration parameter, <literal>Configuration.setReplicationVersion()</literal>, is available and is used to control the wire format of inter-cache communications. They can be wound back from more efficient and newer protocols to "compatible" versions when talking to older releases. This mechanism allows us to improve JBoss Cache by using more efficient wire formats while still providing a means to preserve interoperability. </para> - + </section> <section> <title>Compatibility Matrix</title> <para> - 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. + 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 Application Server. </para> </section> Modified: core/trunk/src/main/docbook/userguide/en/modules/deployment.xml =================================================================== --- core/trunk/src/main/docbook/userguide/en/modules/deployment.xml 2008-10-17 17:17:17 UTC (rev 6980) +++ core/trunk/src/main/docbook/userguide/en/modules/deployment.xml 2008-10-17 18:11:32 UTC (rev 6981) @@ -1,7 +1,7 @@ <chapter id="deployment"> <title>Deploying JBoss Cache</title> <section id="deployment.standalone"> - <title>Standalone Use / Programatic Deployment</title> + <title>Standalone Use/Programatic Deployment</title> <para> When used in a standalone Java program, all that needs to be done is to instantiate the cache using the <literal>CacheFactory</literal> @@ -20,21 +20,19 @@ server wishes to programatically deploy a cache rather than relying on an application server's deployment features. An example of this would be a webapp deploying a cache via a - <literal>javax.servlet.ServletContextListener</literal> - . + <literal>javax.servlet.ServletContextListener</literal>. </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 + IOC container such as Spring, JBoss Microcontainer, 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> - . + <link linkend="jmx.registration.programatic">section on Programatic Registration in JMX</link>. </para> </section> <section id="deployment.microcontainer"> @@ -43,28 +41,23 @@ <para> Beginning with AS 5, JBoss AS supports deployment of POJO services via deployment of a file whose name ends with - <literal>-beans.xml</literal> - . + <literal>-beans.xml</literal>. A POJO service is one whose implementation is via a "Plain Old Java Object", meaning a simple java bean that isn't required to implement any special interfaces or extend any particular superclass. A - <literal>Cache</literal> - is a POJO service, and all the components in a + <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. </para> <para> Deployment of the cache is done using the JBoss Microcontainer that forms the core of JBoss AS. JBoss Microcontainer is a sophisticated IOC framework - (similar to Spring). A - <literal>-beans.xml</literal> - file is basically + similar to Spring. A <literal>-beans.xml</literal> file is basically a descriptor that tells the IOC framework how to assemble the various beans that make up a POJO service. </para> <para> - For each configurable option exposed by the - <literal>Configuration</literal> + For each configurable option exposed by the <literal>Configuration</literal> components, a getter/setter must be defined in the configuration class. This is required so that JBoss Microcontainer can, in typical IOC way, call these methods when the corresponding properties have been @@ -73,11 +66,11 @@ <para> 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 + <literal>all</literal> configuration. Note that you will have to bring in any optional jars you require, such as <literal>jdbm.jar</literal> based on your cache configuration. </para> <para> - Following is an example + The following is an example <literal>-beans.xml</literal> file. If you look in the @@ -121,10 +114,6 @@ <property name="lockAcquisitionTimeout">15000</property> <property name="exposeManagementStatistics">true</property> - - <property name="useRegionBasedMarshalling">true</property> - <property name="inactiveOnStartup">true</property> - </bean> <!-- Factory to build the Cache. --> @@ -152,33 +141,22 @@ <literal>bean</literal> element represents an object and is used to create a <literal>Configuration</literal> - and its - <link linkend="configuration.elements">constituent parts</link> - . + and its <link linkend="configuration.elements">constituent parts</link>. </para> <para> An interesting thing to note in the above example is the use of the - <literal>RuntimeConfig</literal> - object. External resources like - a - <literal>TransactionManager</literal> - and a JGroups - <literal>ChannelFactory</literal> - that are visible to the - microcontainer are dependency injected into the - <literal>RuntimeConfig</literal> - . - The assumption here is that in some other deployment descriptor in the AS, - the referenced beans have been described. + <literal>RuntimeConfig</literal> object. External resources like a <literal>TransactionManager</literal> + and a JGroups <literal>ChannelFactory</literal> that are visible to the microcontainer are dependency injected + into the <literal>RuntimeConfig</literal>. The assumption here is that in some other deployment descriptor in + the AS, the referenced beans have already been described. </para> </section> <section> <title>Automatic binding to JNDI in JBoss AS</title> <para> - 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. + 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> </section> @@ -186,8 +164,7 @@ <title>Runtime Management Information</title> <para>JBoss Cache includes JMX MBeans to expose cache functionality and provide statistics that can be used to analyze cache operations. JBoss Cache can also broadcast cache events as MBean notifications for - handling - via JMX monitoring tools. + handling via JMX monitoring tools. </para> <section id="jmx.mbeans"> @@ -195,49 +172,35 @@ <para> JBoss Cache provides an MBean that can be registered with your environments JMX server to allow access to the cache instance via JMX. This MBean is the - <literal>org.jboss.cache.jmx.CacheJmxWrapper</literal> - . - It is a StandardMBean, so it's MBean interface is - <literal>org.jboss.cache.jmx.CacheJmxWrapperMBean</literal> - . + <literal>org.jboss.cache.jmx.CacheJmxWrapper</literal>. + It is a StandardMBean, so its MBean interface is <literal>org.jboss.cache.jmx.CacheJmxWrapperMBean</literal>. This MBean can be used to: <itemizedlist> - <listitem>Get a reference to the underlying - <literal>Cache</literal> - . + <listitem> + Get a reference to the underlying <literal>Cache</literal>. </listitem> - <listitem>Invoke create/start/stop/destroy lifecycle operations on - the underlying - <literal>Cache</literal> - . + <listitem> + Invoke create/start/stop/destroy lifecycle operations on the underlying <literal>Cache</literal>. </listitem> - <listitem>Inspect various details about the cache's current state (number of nodes, lock information, - etc.) + <listitem> + Inspect various details about the cache's current state (number of nodes, lock information, etc.) </listitem> - <listitem>See numerous details about the cache's configuration, and + <listitem> + See numerous details about the cache's configuration, and change those configuration items that can be changed when the cache has already been started. </listitem> </itemizedlist> - See the - <literal>CacheJmxWrapperMBean</literal> - javadoc for more details. + See the <literal>CacheJmxWrapperMBean</literal> javadoc for more details. </para> <para> - If a - <literal>CacheJmxWrapper</literal> - is registered, JBoss Cache also provides MBeans - 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 - example, a replication interceptor MBean for the - <literal>jboss.cache:service=TomcatClusteringCache</literal> - instance will be - accessible through the service named - <literal>jboss.cache:service=TomcatClusteringCache,cache-interceptor=ReplicationInterceptor</literal> - . + If a <literal>CacheJmxWrapper</literal> is registered, JBoss Cache also provides MBeans + 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 + example, a replication interceptor MBean for the <literal>jboss.cache:service=TomcatClusteringCache</literal> + instance will be accessible through the service named + <literal>jboss.cache:service=TomcatClusteringCache,cache-interceptor=ReplicationInterceptor</literal>. </para> </section> @@ -245,21 +208,18 @@ <title>Registering the CacheJmxWrapper with the MBeanServer</title> <para> - The best way to ensure the - <literal>CacheJmxWrapper</literal> - is registered - in JMX depends on how you are deploying your cache: + The best way to ensure the <literal>CacheJmxWrapper</literal> is registered in JMX depends on how you are + deploying your cache. </para> <section id="jmx.registration.programatic"> <title>Programatic Registration</title> + <section id="jmx.registration.programatic.construct"> + <title>With a Cache instance</title> <para> - Simplest way to do this is to create your - <literal>Cache</literal> - and pass it to the - <literal>CacheJmxWrapper</literal> - constructor. + Simplest way to do this is to create your <literal>Cache</literal> and pass it to the + <literal>CacheJmxWrapper</literal> constructor. </para> <programlisting role="JAVA"><![CDATA[ @@ -270,7 +230,7 @@ CacheJmxWrapperMBean wrapper = new CacheJmxWrapper(cache); MBeanServer server = getMBeanServer(); // however you do it - ObjectName on = new ObjectName("jboss.cache:service=TreeCache"); + ObjectName on = new ObjectName("jboss.cache:service=Cache"); server.registerMBean(wrapper, on); // Invoking lifecycle methods on the wrapper results @@ -287,17 +247,14 @@ wrapper.stop(); wrapper.destroy(); ]]></programlisting> + </section> + <section id="jmx.registration.programatic.cfg"> + <title>With a Configuration instance</title> <para> - Alternatively, build a - <literal>Configuration</literal> - object - and pass it to the - <literal>CacheJmxWrapper</literal> - . The wrapper - will construct the - <literal>Cache</literal> - : + Alternatively, build a <literal>Configuration</literal> object and pass it to the + <literal>CacheJmxWrapper</literal>. The wrapper will construct the <literal>Cache</literal> on your + behalf. </para> <programlisting role="JAVA"><![CDATA[ @@ -322,39 +279,16 @@ wrapper.stop(); wrapper.destroy(); ]]></programlisting> + </section> </section> <section> - <title>JMX-Based Deployment in JBoss AS (JBoss AS 4.x and 5.x)</title> - + <title>JMX-Based Deployment in JBoss AS (JBoss AS 5.x)</title> <para> - When you - <link linkend="deployment.microkernel">deploy your cache in JBoss AS using a -service.xml file</link> - , - a - <literal>CacheJmxWrapper</literal> - is automatically registered. There is no need - to do anything further. The - <literal>CacheJmxWrapper</literal> - is accessible from an MBean server - through the service name specified in the cache configuration file's - <literal>mbean</literal> - element. - </para> - </section> - - <section> - <title>Via JBoss Microcontainer (JBoss AS 5.x)</title> - - <para> - <literal>CacheJmxWrapper</literal> - is a POJO, so the microcontainer - has no problem creating one. The trick is - getting it to register your bean in JMX. This can be done by - specifying the + <literal>CacheJmxWrapper</literal> is a POJO, so the microcontainer has no problem creating one. The + trick is getting it to register your bean in JMX. This can be done by specifying the <literal>org.jboss.aop.microcontainer.aspects.jmx.JMX</literal> - annotation on the - <literal>CacheJmxWrapper</literal> + annotation on the <literal>CacheJmxWrapper</literal> bean: </para> @@ -373,8 +307,7 @@ <!-- 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 --> @@ -405,21 +338,11 @@ ]]></programlisting> <para> - As discussed in the - <link linkend="jmx.registration.programatic">Programatic Registration</link> - section, - <literal>CacheJmxWrapper</literal> - can do the work of building, - creating and starting the - <literal>Cache</literal> - if it is provided - with a - <literal>Configuration</literal> - . With the microcontainer, - this is the preferred approach, as it saves the boilerplate XML - needed to create the - <literal>CacheFactory</literal> - : + As discussed in the <link linkend="jmx.registration.programatic">Programatic Registration</link> + section, <literal>CacheJmxWrapper</literal> can do the work of building, creating and starting the + <literal>Cache</literal> if it is provided with a <literal>Configuration</literal>. With the + microcontainer, this is the preferred approach, as it saves the boilerplate XML + needed to create the <literal>CacheFactory</literal>. </para> <programlisting role="XML"><![CDATA[ @@ -456,30 +379,18 @@ <section id="jmx.statistics"> <title>JBoss Cache Statistics</title> <para> - JBoss Cache captures statistics in its interceptors and exposes the statistics through interceptor - MBeans. Gathering of statistics is enabled by default; this can be disabled for a specific cache - instance through the - <literal>ExposeManagementStatistics</literal> - configuration attribute. Note that - the majority of the statistics are provided by the - <literal>CacheMgmtInterceptor</literal> - , + JBoss Cache captures statistics in its interceptors and various other components, and exposes these + statistics through a set of MBeans. Gathering of statistics is enabled by default; this can be disabled for + a specific cache instance through the <literal>Configuration.setExposeManagementStatistics()</literal> + setter. Note that the majority of the statistics are provided by the <literal>CacheMgmtInterceptor</literal>, so this MBean is the most significant in this regard. If you want to disable all statistics for performance - reasons, you set - <literal>ExposeManagementStatistics</literal> - to - <literal>false</literal> - as this will - prevent the - <literal>CacheMgmtInterceptor</literal> - from being included in the cache's interceptor stack + reasons, you set <literal>Configuration.setExposeManagementStatistics(false)</literal> and this will + prevent the <literal>CacheMgmtInterceptor</literal> from being included in the cache's interceptor stack when the cache is started. </para> <para> - If a - <literal>CacheJmxWrapper</literal> - is registered with JMX, the wrapper also ensures that - an MBean is registered in JMX for each interceptor that exposes statistics + If a <literal>CacheJmxWrapper</literal> is registered with JMX, the wrapper also ensures that + an MBean is registered in JMX for each interceptor and component that exposes statistics. <footnote> <para> Note that if the @@ -493,57 +404,11 @@ that this sort of "discovery" of the JMX environment was beyond the proper scope of a caching library, so we removed this functionality. </para> - </footnote> - . + </footnote>. Management tools can then access those MBeans to examine the statistics. See the section in the <link linkend="jmx_reference.statistics">JMX Reference chapter</link> - pertaining to the - statistics that are made available via JMX. + pertaining to the statistics that are made available via JMX. </para> - <para> - The name under which the interceptor MBeans will be registered is derived by taking the - <literal>ObjectName</literal> - under which the - <literal>CacheJmxWrapper</literal> - is - registered and adding a - <literal>cache-interceptor</literal> - attribute key whose value - is the non-qualified name of the interceptor class. So, for example, if the - <literal>CacheJmxWrapper</literal> - were registered under - <literal>jboss.cache:service=TreeCache</literal> - , the name of the - <literal>CacheMgmtInterceptor</literal> - MBean would be - <literal>jboss.cache:service=TreeCache,cache-interceptor=CacheMgmtInterceptor</literal> - . - </para> - <para> - Each interceptor's MBean exposes a - <literal>StatisticsEnabled</literal> - attribute that can be used to disable maintenance of statistics for - that interceptor. In addition, each interceptor MBean provides the following common operations and - attributes. - <itemizedlist> - <listitem> - <literal>dumpStatistics</literal> - - returns a - <literal>Map</literal> - containing the interceptor's attributes and values. - </listitem> - <listitem> - <literal>resetStatistics</literal> - - resets all statistics maintained by the interceptor. - </listitem> - <listitem> - <literal>setStatisticsEnabled(boolean)</literal> - - allows statistics to be disabled for a specific interceptor. - </listitem> - </itemizedlist> - </para> - <para> - </para> </section> <section> @@ -552,24 +417,16 @@ JBoss Cache users can register a listener to receive cache events described earlier in the <link linkend="api.listener">User API</link> chapter. Users can alternatively utilize the cache's management information infrastructure to receive these - events - via JMX notifications. Cache events are accessible as notifications by registering a - <literal>NotificationListener</literal> - for the - <literal>CacheJmxWrapper</literal> - . + events via JMX notifications. Cache events are accessible as notifications by registering a + <literal>NotificationListener</literal> for the <literal>CacheJmxWrapper</literal>. </para> <para> - See the section in the - <link linkend="jmx_reference.notifications">JMX Reference chapter</link> - pertaining - to JMX notifications for a list of notifications that can be received through the - <literal>CacheJmxWrapper</literal> - . + See the section in the <link linkend="jmx_reference.notifications">JMX Reference chapter</link> + pertaining to JMX notifications for a list of notifications that can be received through the + <literal>CacheJmxWrapper</literal>. </para> - <para> The following is an example of how to programmatically receive cache notifications when running in a JBoss AS environment. In this example, the client uses a filter to specify which events are of interest. @@ -647,63 +504,37 @@ </section> - <section> - <title>Accessing Cache MBeans in a Standalone Environment</title> + <section id="jconsole"> + <title>Accessing Cache MBeans in a Standalone Environment using the <literal>jconsole</literal> Utility</title> <para> JBoss Cache MBeans are easily accessed when running cache instances in an application server that provides an MBean server interface such as JBoss JMX Console. Refer to your server documentation for instructions on how to access MBeans running in a server's MBean container. </para> <para> - In addition, though, JBoss Cache MBeans are also accessible when running in a non-server environment if the - JVM is JDK 5.0 or later. When running a standalone cache in a JDK 5.0 environment, you can access the - cache's MBeans as follows. + In addition, though, JBoss Cache MBeans are also accessible when running in a non-server environment using + your JDK's <literal>jconsole</literal> tool. When running a standalone cache outside of an application server, + you can access the cache's MBeans as follows. </para> <para> <orderedlist> <listitem> - Set the system property - <literal>-Dcom.sun.management.jmxremote</literal> - when starting the JVM - where the cache will run. + Set the system property <literal>-Dcom.sun.management.jmxremote</literal> + when starting the JVM where the cache will run. </listitem> <listitem> - Once the JVM is running, start the JDK 5.0 - <literal>jconsole</literal> - utility, located in your JDK's - <literal>/bin</literal> - directory. + Once the JVM is running, start the <literal>jconsole</literal> utility, located in your JDK's + <literal>/bin</literal> directory. </listitem> - <listitem>When the utility loads, you will be able to select your running JVM and connect to it. The - JBoss Cache - MBeans will be available on the MBeans panel. + <listitem> + When the utility loads, you will be able to select your running JVM and connect to it. The + JBoss Cache MBeans will be available on the MBeans panel. </listitem> </orderedlist> </para> - <para>Note that the - <literal>jconsole</literal> - utility will automatically register as a listener for cache notifications when - connected to a JVM running JBoss Cache instances. + <para>Note that the <literal>jconsole</literal> utility will automatically register as a listener for cache + notifications when connected to a JVM running JBoss Cache instances. </para> - - <para>The following figure shows cache interceptor MBeans in - <literal>jconsole</literal> - . Cache statistics are displayed - for the - <literal>CacheMgmtInterceptor</literal> - : - </para> - - <figure> - <title>CacheMgmtInterceptor MBean in jconsole</title> - - <mediaobject> - <imageobject> - <imagedata fileref="CacheMgmtInterceptor.png"/> - </imageobject> - </mediaobject> - </figure> - </section> </section> </chapter> Modified: core/trunk/src/main/docbook/userguide/en/modules/introduction.xml =================================================================== --- core/trunk/src/main/docbook/userguide/en/modules/introduction.xml 2008-10-17 17:17:17 UTC (rev 6980) +++ core/trunk/src/main/docbook/userguide/en/modules/introduction.xml 2008-10-17 18:11:32 UTC (rev 6981) @@ -38,7 +38,7 @@ </itemizedlist> </para> <para> - POJO Cache has a complete and separate set of documentation, including a user guide, FAQ and tutorial all + POJO Cache has a complete and separate set of documentation, including a Users' 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> Modified: core/trunk/src/main/docbook/userguide/en/modules/preface.xml =================================================================== --- core/trunk/src/main/docbook/userguide/en/modules/preface.xml 2008-10-17 17:17:17 UTC (rev 6980) +++ core/trunk/src/main/docbook/userguide/en/modules/preface.xml 2008-10-17 18:11:32 UTC (rev 6981) @@ -2,7 +2,7 @@ <title>Preface</title> <para> - This is the official JBoss Cache user guide. Along with its accompanying documents (an FAQ, a tutorial and a + This is the official JBoss Cache Users' 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://www.jboss.org/jbosscache">documentation website</ulink>. </para> <para> Modified: core/trunk/src/main/docbook/userguide/en/modules/replication.xml =================================================================== --- core/trunk/src/main/docbook/userguide/en/modules/replication.xml 2008-10-17 17:17:17 UTC (rev 6980) +++ core/trunk/src/main/docbook/userguide/en/modules/replication.xml 2008-10-17 18:11:32 UTC (rev 6981) @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="UTF-8"?> <chapter id="clustering"> - <title>Clustering</title> + <title>Cache Modes and Clustering</title> <para>This chapter talks about aspects around clustering JBoss Cache.</para> @@ -17,9 +17,7 @@ <title>Local Mode</title> <para>Local caches don't join a cluster and don't communicate with other - caches in a cluster. Therefore their elements don't need to be - serializable - however, we recommend making them serializable, enabling - a user to change the cache mode at any time. The dependency on the + caches in a cluster. The dependency on the JGroups library is still there, although a JGroups channel is not started. </para> @@ -30,11 +28,10 @@ <para>Replicated caches replicate all changes to some or all of the other cache instances in the cluster. Replication can either happen after each - modification (no transactions), or at the end of a transaction (commit - time). + modification (no transactions or batches), or at the end of a transaction or batch. </para> - <para>Replication can be synchronous or asynchronous . Use of either one + <para>Replication can be synchronous or asynchronous. Use of either one of the options is application dependent. Synchronous replication blocks the caller (e.g. on a <literal>put()</literal> @@ -45,7 +42,8 @@ returns immediately). JBoss Cache also offers a replication queue, where modifications are replicated periodically (i.e. interval-based), or when the queue size exceeds a number of elements, or - a combination thereof. + a combination thereof. A replication queue can therefore offer much higher performance as the actual + replication is performed by a background thread. </para> <para>Asynchronous replication is faster (no caller blocking), because @@ -360,51 +358,8 @@ <section> <title>Configuration</title> - <programlisting role="XML"><![CDATA[ -<!-- Buddy Replication config --> -<attribute name="BuddyReplicationConfig"> - <config> - - <!-- Enables buddy replication. This is the ONLY mandatory configuration element here. --> - <buddyReplicationEnabled>true</buddyReplicationEnabled> - - <!-- These are the default values anyway --> - <buddyLocatorClass>org.jboss.cache.buddyreplication.NextMemberBuddyLocator</buddyLocatorClass> - - <!-- numBuddies is the number of backup nodes each node maintains. ignoreColocatedBuddies means - that each node will *try* to select a buddy on a different physical host. If not able to do so though, - it will fall back to colocated nodes. --> - <buddyLocatorProperties> - numBuddies = 1 - ignoreColocatedBuddies = true - </buddyLocatorProperties> - - <!-- A way to specify a preferred replication group. If specified, we try and pick a buddy which shares - the same pool name (falling back to other buddies if not available). This allows the sysdmin to - hint at backup buddies are picked, so for example, nodes may be hinted topick buddies on a different - physical rack or power supply for added fault tolerance. --> - <buddyPoolName>myBuddyPoolReplicationGroup</buddyPoolName> - - <!-- Communication timeout for inter-buddy group organisation messages (such as assigning to and - removing from groups, defaults to 1000. --> - <buddyCommunicationTimeout>2000</buddyCommunicationTimeout> - - <!-- Whether data is removed from old owners when gravitated to a new owner. Defaults to true. --> - <dataGravitationRemoveOnFind>true</dataGravitationRemoveOnFind> - - <!-- Whether backup nodes can respond to data gravitation requests, or only the data owner is - supposed to respond. Defaults to true. --> - <dataGravitationSearchBackupTrees>true</dataGravitationSearchBackupTrees> - - <!-- Whether all cache misses result in a data gravitation request. Defaults to false, requiring - callers to enable data gravitation on a per-invocation basis using the Options API. --> - <autoDataGravitation>false</autoDataGravitation> - - </config> -</attribute> - -]]></programlisting> - </section> + See the <link linkend="configuration_reference_chapter">configuration reference section</link> for details on configuring buddy replication. + </section> </section> </section> </section> @@ -416,7 +371,7 @@ every time data is changed in a cache other caches in the cluster receive a message informing them that their data is now stale and should be evicted from memory. Invalidation, when used with a shared cache loader - (see chapter on Cache Loaders) would cause remote caches to refer to the + (see chapter on <link linkend="cache_loaders">cacahe loaders</link>) would cause remote caches to refer to the shared cache loader to retrieve modified data. The benefit of this is twofold: network traffic is minimised as invalidation messages are very small compared to replicating updated data, and also that other caches in @@ -425,7 +380,7 @@ </para> <para>Invalidation messages are sent after each modification (no - transactions), or at the end of a transaction, upon successful commit. + transactions or batches), or at the end of a transaction or batch, upon successful commit. This is usually more efficient as invalidation messages can be optimised for the transaction as a whole rather than on a per-modification basis. @@ -579,7 +534,7 @@ cluster, it becomes the buddy of one or more other instances, and one or more other instances become its buddy. Each time an instance determines it has a new buddy providing backup for it, it pushes - it's current state to the new buddy. This "pushing" of state to the + its current state to the new buddy. This "pushing" of state to the new buddy is slightly different from other forms of state transfer, which are based on a "pull" approach (i.e. recipient asks for and receives state). However, the process of preparing and integrating Modified: core/trunk/src/main/docbook/userguide/en/modules/transactions.xml =================================================================== --- core/trunk/src/main/docbook/userguide/en/modules/transactions.xml 2008-10-17 17:17:17 UTC (rev 6980) +++ core/trunk/src/main/docbook/userguide/en/modules/transactions.xml 2008-10-17 18:11:32 UTC (rev 6981) @@ -161,7 +161,7 @@ In addition to the above, in version 2.1.0 and above, JBoss Cache offers the ability to override this configuration on a per-node basis. See <literal>Node.setLockForChildInsertRemove()</literal> - and it's + and its corresponding javadocs for details. </para> </section> Modified: core/trunk/src/main/java/org/jboss/cache/Cache.java =================================================================== --- core/trunk/src/main/java/org/jboss/cache/Cache.java 2008-10-17 17:17:17 UTC (rev 6980) +++ core/trunk/src/main/java/org/jboss/cache/Cache.java 2008-10-17 18:11:32 UTC (rev 6981) @@ -23,6 +23,7 @@ import net.jcip.annotations.ThreadSafe; import org.jboss.cache.config.Configuration; +import org.jboss.cache.interceptors.base.CommandInterceptor; import org.jgroups.Address; import java.util.List; @@ -535,4 +536,43 @@ * @since 3.0 */ void endBatch(boolean successful); + + /** + * Adds a custom interceptor to the interceptor chain, at specified position, where the first interceptor in the chain + * is at position 0 and the last one at getInterceptorChain().size() - 1. + * + * @param i the interceptor to add + * @param position the position to add the interceptor + * + * @since 3.0 + */ + void addInterceptor(CommandInterceptor i, int position); + + /** + * Adds a custom interceptor to the interceptor chain, after an instance of the specified interceptor type. Throws a + * cache exception if it cannot find an interceptor of the specified type. + * + * @param i interceptor to add + * @param afterInterceptor interceptor type after which to place custom interceptor + * + * @since 3.0 + */ + void addInterceptor(CommandInterceptor i, Class<? extends CommandInterceptor> afterInterceptor); + + /** + * Removes the interceptor at a specified position, where the first interceptor in the chain + * is at position 0 and the last one at getInterceptorChain().size() - 1. + * + * @param position the position at which to remove an interceptor + * @since 3.0 + */ + void removeInterceptor(int position); + + /** + * Removes the interceptor of specified type. + * + * @param interceptorType type of interceptor to remove + * @since 3.0 + */ + void removeInterceptor(Class<? extends CommandInterceptor> interceptorType); } Modified: core/trunk/src/main/java/org/jboss/cache/CacheSPI.java =================================================================== --- core/trunk/src/main/java/org/jboss/cache/CacheSPI.java 2008-10-17 17:17:17 UTC (rev 6980) +++ core/trunk/src/main/java/org/jboss/cache/CacheSPI.java 2008-10-17 18:11:32 UTC (rev 6981) @@ -120,39 +120,6 @@ Marshaller getMarshaller(); /** - * Adds a custom interceptor to the interceptor chain, at specified position, where the first interceptor in the chain - * is at position 0 and the last one at getInterceptorChain().size() - 1. - * - * @param i the interceptor to add - * @param position the position to add the interceptor - */ - void addInterceptor(CommandInterceptor i, int position); - - /** - * Adds a custom interceptor to the interceptor chain, after an instance of the specified interceptor type. Throws a - * cache exception if it cannot find an interceptor of the specified type. - * - * @param i interceptor to add - * @param afterInterceptor interceptor type after which to place custom interceptor - */ - void addInterceptor(CommandInterceptor i, Class<? extends CommandInterceptor> afterInterceptor); - - /** - * Removes the interceptor at a specified position, where the first interceptor in the chain - * is at position 0 and the last one at getInterceptorChain().size() - 1. - * - * @param position the position at which to remove an interceptor - */ - void removeInterceptor(int position); - - /** - * Removes the interceptor of specified type. - * - * @param interceptorType type of interceptor to remove - */ - void removeInterceptor(Class<? extends CommandInterceptor> interceptorType); - - /** * Retrieves the current CacheCacheLoaderManager instance associated with the current Cache instance. * <p/> * From 2.1.0, Interceptor authors should obtain this by injection rather than this method. See the