[jbosscache-commits] JBoss Cache SVN: r7381 - in core/trunk/src: main/resources/config-samples and 1 other directories.

Author: manik.surtani(a)jboss.com Date: 2009-01-06 06:08:41 -0500 (Tue, 06 Jan 2009) New Revision: 7381 Modified: core/trunk/src/main/docbook/userguide/en/modules/cache_loaders.xml core/trunk/src/main/resources/config-samples/all.xml core/trunk/src/main/resources/config-samples/cacheloader-enabled.xml core/trunk/src/test/java/org/jboss/cache/config/parsing/SampleConfigFilesCorrectnessTest.java Log: Fixed broken test and updated docs Modified: core/trunk/src/main/docbook/userguide/en/modules/cache_loaders.xml =================================================================== --- core/trunk/src/main/docbook/userguide/en/modules/cache_loaders.xml 2009-01-05 17:54:59 UTC (rev 7380) +++ core/trunk/src/main/docbook/userguide/en/modules/cache_loaders.xml 2009-01-06 11:08:41 UTC (rev 7381) @@ -1,152 +1,152 @@ <chapter id="cache_loaders"> - <title>Cache Loaders</title> - <para>JBoss Cache can use a - <literal>CacheLoader</literal> - to back up the in-memory cache to a backend datastore. - If JBoss Cache is configured with a cache loader, then the following features are provided: - <itemizedlist> - <listitem>Whenever a cache element is accessed, and that element is not in - the cache (e.g. due to eviction or due to server restart), then the cache loader transparently - loads the element into the cache if found in the backend - store. - </listitem> + <title>Cache Loaders</title> + <para>JBoss Cache can use a + <literal>CacheLoader</literal> + to back up the in-memory cache to a backend datastore. + If JBoss Cache is configured with a cache loader, then the following features are provided: + <itemizedlist> + <listitem>Whenever a cache element is accessed, and that element is not in + the cache (e.g. due to eviction or due to server restart), then the cache loader transparently + loads the element into the cache if found in the backend + store. + </listitem> - <listitem>Whenever an element is modified, added or removed, then that - modification is persisted in the backend store via the cache loader. If - transactions are used, all modifications created within a transaction - are persisted. To this end, the - <literal>CacheLoader</literal> - takes part in the two - phase commit protocol run by the transaction manager, although it does not do so explicitly. - </listitem> - </itemizedlist> - </para> + <listitem>Whenever an element is modified, added or removed, then that + modification is persisted in the backend store via the cache loader. If + transactions are used, all modifications created within a transaction + are persisted. To this end, the + <literal>CacheLoader</literal> + takes part in the two + phase commit protocol run by the transaction manager, although it does not do so explicitly. + </listitem> + </itemizedlist> + </para> - <section> - <title>The CacheLoader Interface and Lifecycle</title> + <section> + <title>The CacheLoader Interface and Lifecycle</title> - <figure> - <title>The CacheLoader interface</title> + <figure> + <title>The CacheLoader interface</title> - <mediaobject> - <imageobject> - <imagedata fileref="CacheLoader.png"/> - </imageobject> - </mediaobject> - </figure> + <mediaobject> + <imageobject> + <imagedata fileref="CacheLoader.png"/> + </imageobject> + </mediaobject> + </figure> - <para>The interaction between JBoss Cache and a - <literal>CacheLoader</literal> - implementation is as follows. When - <literal>CacheLoaderConfiguration</literal> - (see below) is non-null, an - instance of each configured - <literal>CacheLoader</literal> - is created when the cache is created, and started when the cache is started. - </para> + <para>The interaction between JBoss Cache and a + <literal>CacheLoader</literal> + implementation is as follows. When + <literal>CacheLoaderConfiguration</literal> + (see below) is non-null, an + instance of each configured + <literal>CacheLoader</literal> + is created when the cache is created, and started when the cache is started. + </para> - <para> - <literal>CacheLoader.create()</literal> - and - <literal>CacheLoader.start()</literal> - are called when the cache is - started. Correspondingly, - <literal>stop()</literal> - and - <literal>destroy()</literal> - are called when the cache is - stopped. - </para> + <para> + <literal>CacheLoader.create()</literal> + and + <literal>CacheLoader.start()</literal> + are called when the cache is + started. Correspondingly, + <literal>stop()</literal> + and + <literal>destroy()</literal> + are called when the cache is + stopped. + </para> - <para>Next, - <literal>setConfig()</literal> - and - <literal>setCache()</literal> - are called. The latter can be used to - store a reference to the cache, the former is used to configure this - instance of the - <literal>CacheLoader</literal> - . For example, here a database cache loader - could establish a connection to the database. - </para> + <para>Next, + <literal>setConfig()</literal> + and + <literal>setCache()</literal> + are called. The latter can be used to + store a reference to the cache, the former is used to configure this + instance of the + <literal>CacheLoader</literal> + . For example, here a database cache loader + could establish a connection to the database. + </para> - <para>The - <literal>CacheLoader</literal> - interface has a set of methods that are called - when no transactions are used: - <literal>get()</literal> - , - <literal>put()</literal> - , - <literal>remove()</literal> - and - <literal>removeData()</literal> - : they get/set/remove the value - immediately. These methods are described as javadoc comments in the - interface. - </para> + <para>The + <literal>CacheLoader</literal> + interface has a set of methods that are called + when no transactions are used: + <literal>get()</literal> + , + <literal>put()</literal> + , + <literal>remove()</literal> + and + <literal>removeData()</literal> + : they get/set/remove the value + immediately. These methods are described as javadoc comments in the + interface. + </para> - <para>Then there are three methods that are used with transactions: - <literal>prepare()</literal> - , - <literal>commit()</literal> - and - <literal>rollback()</literal> - . The - <literal>prepare()</literal> - method - is called when a transaction is to be committed. It has a transaction - object and a list of modfications as argument. The transaction object - can be used as a key into a hashmap of transactions, where the values - are the lists of modifications. Each modification list has a number of - <literal>Modification</literal> - elements, which represent the changes - made to a cache for a given transaction. When - <literal>prepare()</literal> - returns successfully, then the cache loader - <emphasis>must</emphasis> - be able to commit (or rollback) the - transaction successfully. - </para> + <para>Then there are three methods that are used with transactions: + <literal>prepare()</literal> + , + <literal>commit()</literal> + and + <literal>rollback()</literal> + . The + <literal>prepare()</literal> + method + is called when a transaction is to be committed. It has a transaction + object and a list of modfications as argument. The transaction object + can be used as a key into a hashmap of transactions, where the values + are the lists of modifications. Each modification list has a number of + <literal>Modification</literal> + elements, which represent the changes + made to a cache for a given transaction. When + <literal>prepare()</literal> + returns successfully, then the cache loader + <emphasis>must</emphasis> + be able to commit (or rollback) the + transaction successfully. + </para> - <para> - JBoss Cache takes care of calling prepare(), commit() - and rollback() on the cache loaders at the right time. - </para> + <para> + JBoss Cache takes care of calling prepare(), commit() + and rollback() on the cache loaders at the right time. + </para> - <para>The - <literal>commit()</literal> - method tells the cache loader to - commit the transaction, and the - <literal>rollback()</literal> - method - tells the cache loader to discard the changes associated with that - transaction. - </para> + <para>The + <literal>commit()</literal> + method tells the cache loader to + commit the transaction, and the + <literal>rollback()</literal> + method + tells the cache loader to discard the changes associated with that + transaction. + </para> - <para>See the javadocs on this interface for a detailed explanation on each method and the contract - implementations would need to fulfill. - </para> + <para>See the javadocs on this interface for a detailed explanation on each method and the contract + implementations would need to fulfill. + </para> - </section> + </section> - <section> - <title>Configuration</title> + <section> + <title>Configuration</title> - <para>Cache loaders are configured as follows in the JBoss Cache XML - file. Note that you can define several cache loaders, in - a chain. 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 performing writes, all cache loaders are - written to (except if the - <literal>ignoreModifications</literal> - element has been set to - <literal>true</literal> - for a specific cache loader. See the configuration section below for - details. - </para> + <para>Cache loaders are configured as follows in the JBoss Cache XML + file. Note that you can define several cache loaders, in + a chain. 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 performing writes, all cache loaders are + written to (except if the + <literal>ignoreModifications</literal> + element has been set to + <literal>true</literal> + for a specific cache loader. See the configuration section below for + details. + </para> - <programlisting role="XML"><![CDATA[ + <programlisting role="XML"><![CDATA[ ... <!-- Cache loader config block --> @@ -170,138 +170,139 @@ </loaders> ]]></programlisting> - <para>The - <literal>class</literal> - element defines the - class of the cache loader implementation. (Note that, because of a bug in - the properties editor in JBoss AS, backslashes in variables for Windows - filenames might not get expanded correctly, so replace="false" may be - necessary). Note that an implementation of cache loader has to have an empty - constructor. - </para> + <para>The + <literal>class</literal> + element defines the + class of the cache loader implementation. (Note that, because of a bug in + the properties editor in JBoss AS, backslashes in variables for Windows + filenames might not get expanded correctly, so replace="false" may be + necessary). Note that an implementation of cache loader has to have an empty + constructor. + </para> - <para>The - <literal>properties</literal> - element defines a configuration - specific to the given implementation. The filesystem-based - implementation for example defines the root directory to be used, - whereas a database implementation might define the database URL, name - and password to establish a database connection. This configuration is - passed to the cache loader implementation via - <literal>CacheLoader.setConfig(Properties)</literal> - . Note that - backspaces may have to be escaped. - </para> + <para>The + <literal>properties</literal> + element defines a configuration + specific to the given implementation. The filesystem-based + implementation for example defines the root directory to be used, + whereas a database implementation might define the database URL, name + and password to establish a database connection. This configuration is + passed to the cache loader implementation via + <literal>CacheLoader.setConfig(Properties)</literal> + . Note that + backspaces may have to be escaped. + </para> - <para> - <literal>preload</literal> - allows us to define a list of nodes, or - even entire subtrees, that are visited by the cache on startup, in order - to preload the data associated with those nodes. The default ("/") loads - the entire data available in the backend store into the cache, which is - probably not a good idea given that the data in the backend store might - be large. As an example, - <literal>/a, - /product/catalogue - </literal> - loads the subtrees - <literal>/a</literal> - and - <literal>/product/catalogue</literal> - into the cache, but nothing - else. Anything else is loaded lazily when accessed. Preloading makes - sense when one anticipates using elements under a given subtree - frequently. - . - </para> + <para> + <literal>preload</literal> + allows us to define a list of nodes, or + even entire subtrees, that are visited by the cache on startup, in order + to preload the data associated with those nodes. The default ("/") loads + the entire data available in the backend store into the cache, which is + probably not a good idea given that the data in the backend store might + be large. As an example, + <literal>/a, + /product/catalogue + </literal> + loads the subtrees + <literal>/a</literal> + and + <literal>/product/catalogue</literal> + into the cache, but nothing + else. Anything else is loaded lazily when accessed. Preloading makes + sense when one anticipates using elements under a given subtree + frequently. + . + </para> - <para> - <literal>fetchPersistentState</literal> - determines whether or not - to fetch the persistent state of a cache when joining a cluster. Only - one configured cache loader may set this property to true; if more than - one cache loader does so, a configuration exception will be thrown when - starting your cache service. - </para> + <para> + <literal>fetchPersistentState</literal> + determines whether or not + to fetch the persistent state of a cache when joining a cluster. Only + one configured cache loader may set this property to true; if more than + one cache loader does so, a configuration exception will be thrown when + starting your cache service. + </para> - <para> - <literal>async</literal> - determines whether writes to the cache - loader block until completed, or are run on a separate thread so writes - return immediately. If this is set to true, an instance of - <literal>org.jboss.cache.loader.AsyncCacheLoader</literal> - is - constructed with an instance of the actual cache loader to be used. The - <literal>AsyncCacheLoader</literal> - then delegates all requests to the - underlying cache loader, using a separate thread if necessary. See the - Javadocs on - <literal>AsyncCacheLoader</literal> - for more details. If unspecified, the - <literal>async</literal> - element - defaults to - <literal>false</literal> - . - </para> + <para> + <literal>async</literal> + determines whether writes to the cache + loader block until completed, or are run on a separate thread so writes + return immediately. If this is set to true, an instance of + <literal>org.jboss.cache.loader.AsyncCacheLoader</literal> + is + constructed with an instance of the actual cache loader to be used. The + <literal>AsyncCacheLoader</literal> + then delegates all requests to the + underlying cache loader, using a separate thread if necessary. See the + Javadocs on + <literal>AsyncCacheLoader</literal> + for more details. If unspecified, the + <literal>async</literal> + element + defaults to + <literal>false</literal> + . + </para> - <para> - <emphasis role="bold">Note on using the + <para> + <emphasis role="bold">Note on using the + <literal>async</literal> + element: + </emphasis> + there is always the possibility of dirty reads since + all writes are performed asynchronously, and it is thus impossible to + guarantee when (and even if) a write succeeds. This needs to be kept in + mind when setting the <literal>async</literal> - element: - </emphasis> - there is always the possibility of dirty reads since - all writes are performed asynchronously, and it is thus impossible to - guarantee when (and even if) a write succeeds. This needs to be kept in - mind when setting the - <literal>async</literal> - element to true. - </para> + element to true. + </para> - <para> - <literal>ignoreModifications</literal> - determines whether write - methods are pushed down to the specific cache loader. Situations may - arise where transient application data should only reside in a file - based cache loader on the same server as the in-memory cache, for - example, with a further shared - <literal>JDBCCacheLoader</literal> - used by all servers in - the network. This feature allows you to write to the 'local' file cache - loader but not the shared - <literal>JDBCCacheLoader</literal> - . This property defaults to - <literal>false</literal> - , so writes are propagated to all cache loaders - configured. - </para> + <para> + <literal>ignoreModifications</literal> + determines whether write + methods are pushed down to the specific cache loader. Situations may + arise where transient application data should only reside in a file + based cache loader on the same server as the in-memory cache, for + example, with a further shared + <literal>JDBCCacheLoader</literal> + used by all servers in + the network. This feature allows you to write to the 'local' file cache + loader but not the shared + <literal>JDBCCacheLoader</literal> + . This property defaults to + <literal>false</literal> + , so writes are propagated to all cache loaders + configured. + </para> - <para> - <literal>purgeOnStatup</literal> - empties the specified cache loader - (if - <literal>ignoreModifications</literal> - is - <literal>false</literal> - ) - when the cache loader starts up. - </para> + <para> + <literal>purgeOnStatup</literal> + empties the specified cache loader + (if + <literal>ignoreModifications</literal> + is + <literal>false</literal> + ) + when the cache loader starts up. + </para> - <para> - <literal>shared</literal> - indicates that the cache loader is shared among different cache instances, for example where all instances in a - cluster use the same JDBC settings t talk to the same remote, shared database. Setting this to - <literal>true</literal> - prevents repeated and unnecessary writes of the same data to the cache loader by different cache instances. - Default value is - <literal>false</literal> - . - </para> + <para> + <literal>shared</literal> + indicates that the cache loader is shared among different cache instances, for example where all instances + in a + cluster use the same JDBC settings t talk to the same remote, shared database. Setting this to + <literal>true</literal> + prevents repeated and unnecessary writes of the same data to the cache loader by different cache instances. + Default value is + <literal>false</literal> + . + </para> - <section id="sscl"> - <title>Singleton Store Configuration</title> + <section id="sscl"> + <title>Singleton Store Configuration</title> - <programlisting role="XML"><![CDATA[ + <programlisting role="XML"><![CDATA[ <loaders passivation="false" shared="true"> <preload> <node fqn="/a/b/c"/> @@ -322,458 +323,468 @@ </singletonStore> </loader> </loaders> - ]]></programlisting> - <para> - <literal>singletonStore</literal> - element enables modifications to be stored by only one node in the cluster, - the coordinator. Essentially, whenever any data comes in to some node - it is always replicated so as to keep the caches' in-memory states in - sync; the coordinator, though, has the sole responsibility of pushing - that state to disk. This functionality can be activated setting the - <literal>enabled</literal> - 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>loader</literal> - element. You cannot define a cache loader as - <literal>shared</literal> - and with - <literal>singletonStore</literal> - enabled at the same time. - Default value for - <literal>enabled</literal> - is - <literal>false</literal> - . - </para> + ]]></programlisting> + <para> + <literal>singletonStore</literal> + element enables modifications to be stored by only one node in the cluster, + the coordinator. Essentially, whenever any data comes in to some node + it is always replicated so as to keep the caches' in-memory states in + sync; the coordinator, though, has the sole responsibility of pushing + that state to disk. This functionality can be activated setting the + <literal>enabled</literal> + 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>loader</literal> + element. You cannot define a cache loader as + <literal>shared</literal> + and with + <literal>singletonStore</literal> + enabled at the same time. + Default value for + <literal>enabled</literal> + is + <literal>false</literal> + . + </para> - <para> - Optionally, within the - <literal>singletonStore</literal> - element, you can define a - <literal>class</literal> - element that specifies the implementation class that provides the - singleton store functionality. This class must extend - <literal>org.jboss.cache.loader.AbstractDelegatingCacheLoader</literal> - , and if absent, it defaults to - <literal>org.jboss.cache.loader.SingletonStoreCacheLoader</literal> - . - </para> + <para> + Optionally, within the + <literal>singletonStore</literal> + element, you can define a + <literal>class</literal> + element that specifies the implementation class that provides the + singleton store functionality. This class must extend + <literal>org.jboss.cache.loader.AbstractDelegatingCacheLoader</literal> + , and if absent, it defaults to + <literal>org.jboss.cache.loader.SingletonStoreCacheLoader</literal> + . + </para> - <para> - The - <literal>properties</literal> - subelement defines properties that allow changing the behavior of the - class providing the singleton store functionality. By default, - <literal>pushStateWhenCoordinator</literal> - and - <literal>pushStateWhenCoordinatorTimeout</literal> - properties have been defined, but more could be added as - required by the user-defined class providing singleton store - functionality. - </para> + <para> + The + <literal>properties</literal> + subelement defines properties that allow changing the behavior of the + class providing the singleton store functionality. By default, + <literal>pushStateWhenCoordinator</literal> + and + <literal>pushStateWhenCoordinatorTimeout</literal> + properties have been defined, but more could be added as + required by the user-defined class providing singleton store + functionality. + </para> - <para> - <literal>pushStateWhenCoordinator</literal> - allows the in-memory - state to be pushed to the cache store when a node becomes the - coordinator, as a result of the new election of coordinator due to a - cluster topology change. This can be very useful in situations where the - coordinator crashes and there's a gap in time until the new coordinator - is elected. During this time, if this property was set to - <literal>false</literal> - and the - cache was updated, these changes would never be persisted. Setting this - property to - <literal>true</literal> - would ensure that any changes during this process also - get stored in the cache loader. You would also want to set this property - to - <literal>true</literal> - if each node's cache loader is configured with a different - location. Default value is - <literal>true</literal> - . - </para> + <para> + <literal>pushStateWhenCoordinator</literal> + allows the in-memory + state to be pushed to the cache store when a node becomes the + coordinator, as a result of the new election of coordinator due to a + cluster topology change. This can be very useful in situations where the + coordinator crashes and there's a gap in time until the new coordinator + is elected. During this time, if this property was set to + <literal>false</literal> + and the + cache was updated, these changes would never be persisted. Setting this + property to + <literal>true</literal> + would ensure that any changes during this process also + get stored in the cache loader. You would also want to set this property + to + <literal>true</literal> + if each node's cache loader is configured with a different + location. Default value is + <literal>true</literal> + . + </para> - <para> - <literal>pushStateWhenCoordinatorTimeout</literal> - is only relevant if - <literal>pushStateWhenCoordinator</literal> - is - <literal>true</literal> - in which case, sets the maximum number of milliseconds that the process - of pushing the in-memory state to the underlying cache loader should take, - reporting a - <literal>PushStateException</literal> - if exceeded. Default value is 20000. - </para> + <para> + <literal>pushStateWhenCoordinatorTimeout</literal> + is only relevant if + <literal>pushStateWhenCoordinator</literal> + is + <literal>true</literal> + in which case, sets the maximum number of milliseconds that the process + of pushing the in-memory state to the underlying cache loader should take, + reporting a + <literal>PushStateException</literal> + if exceeded. Default value is 20000. + </para> - <para> - <emphasis role="bold">Note on using the - <literal>singletonStore</literal> - element: - </emphasis> - setting - up a cache loader as a singleton and using cache passivation (via - evictions) can lead to undesired effects. If a node is to be passivated - as a result of an eviction, while the cluster is in the process of - electing a new coordinator, the data will be lost. This is because no - coordinator is active at that time and therefore, none of the nodes in - the cluster will store the passivated node. A new coordinator is elected - in the cluster when either, the coordinator leaves the cluster, the - coordinator crashes or stops responding. - </para> - </section> + <para> + <emphasis role="bold">Note on using the + <literal>singletonStore</literal> + element: + </emphasis> + setting + up a cache loader as a singleton and using cache passivation (via + evictions) can lead to undesired effects. If a node is to be passivated + as a result of an eviction, while the cluster is in the process of + electing a new coordinator, the data will be lost. This is because no + coordinator is active at that time and therefore, none of the nodes in + the cluster will store the passivated node. A new coordinator is elected + in the cluster when either, the coordinator leaves the cluster, the + coordinator crashes or stops responding. + </para> + </section> - </section> + </section> - <section id="cl.impls"> + <section id="cl.impls"> - <title>Shipped Implementations</title> + <title>Shipped Implementations</title> - <para>The currently available implementations shipped with JBoss Cache are as follows.</para> + <para>The currently available implementations shipped with JBoss Cache are as follows.</para> - <section> - <title>File system based cache loaders</title> - <para> - JBoss Cache ships with several cache loaders that utilize the file system as a data store. They all require - that the - <literal><![CDATA[<loader><properties>]]></literal> - configuration element - contains a - <literal>location</literal> - property, which maps to a directory to be used as a persistent store. - (e.g., - <literal>location=/tmp/myDataStore</literal> - ). Used mainly for testing and not recommended for production use. - </para> - <itemizedlist> - <listitem> - <para> - <literal>FileCacheLoader</literal> - , which is a simple filesystem-based implementation. By default, this cache - loader checks for any potential character portability issues in the - location or tree node names, for example invalid characters, producing - warning messages. These checks can be disabled adding - <literal>check.character.portability</literal> - property to the - <literal><![CDATA[<properties>]]></literal> - element and setting it to - <literal>false</literal> - (e.g., - <literal>check.character.portability=false</literal> - ). - </para> - <para> - 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> - <listitem>Due to the way the FileCacheLoader represents a tree structure on disk (directories and - files) traversal is inefficient for deep trees. - </listitem> - <listitem>Usage on shared filesystems like NFS, Windows shares, etc. should be avoided as these do - not implement proper file locking and can cause data corruption. - </listitem> - <listitem>Usage with an isolation level of NONE can cause corrupt writes as multiple threads - attempt to write to the same file. - </listitem> - <listitem>File systems are inherently not transactional, so when attempting to use your cache in a - transactional context, failures when writing to the file (which happens during the commit phase) - cannot be recovered. - </listitem> - </itemizedlist> + <section> + <title>File system based cache loaders</title> + <para> + JBoss Cache ships with several cache loaders that utilize the file system as a data store. They all + require + that the + <literal><![CDATA[<loader><properties>]]></literal> + configuration element + contains a + <literal>location</literal> + property, which maps to a directory to be used as a persistent store. + (e.g., + <literal>location=/tmp/myDataStore</literal> + ). Used mainly for testing and not recommended for production use. + </para> + <itemizedlist> + <listitem> + <para> + <literal>FileCacheLoader</literal> + , which is a simple filesystem-based implementation. By default, this cache + loader checks for any potential character portability issues in the + location or tree node names, for example invalid characters, producing + warning messages. These checks can be disabled adding + <literal>check.character.portability</literal> + property to the + <literal><![CDATA[<properties>]]></literal> + element and setting it to + <literal>false</literal> + (e.g., + <literal>check.character.portability=false</literal> + ). + </para> + <para> + 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> + <listitem>Due to the way the FileCacheLoader represents a tree structure on disk + (directories and + files) traversal is inefficient for deep trees. + </listitem> + <listitem>Usage on shared filesystems like NFS, Windows shares, etc. should be avoided as + these do + not implement proper file locking and can cause data corruption. + </listitem> + <listitem>Usage with an isolation level of NONE can cause corrupt writes as multiple threads + attempt to write to the same file. + </listitem> + <listitem>File systems are inherently not transactional, so when attempting to use your + cache in a + transactional context, failures when writing to the file (which happens during the + commit phase) + cannot be recovered. + </listitem> + </itemizedlist> - As a rule of thumb, it is recommended that the FileCacheLoader not be used in a highly concurrent, - transactional or stressful environment, and its use is restricted to testing. - </para> - </listitem> + As a rule of thumb, it is recommended that the FileCacheLoader not be used in a highly + concurrent, + transactional or stressful environment, and its use is restricted to testing. + </para> + </listitem> - <listitem> - <para> - <literal>BdbjeCacheLoader</literal> - , which is a cache loader implementation based on the Oracle/Sleepycat's - <ulink url="http://www.oracle.com/database/berkeley-db/index.html">... Java Edition</ulink> - . - </para> - </listitem> + <listitem> + <para> + <literal>BdbjeCacheLoader</literal> + , which is a cache loader implementation based on the Oracle/Sleepycat's + <ulink url="http://www.oracle.com/database/berkeley-db/index.html">... Java Edition + </ulink> + . + </para> + </listitem> - <listitem> - <para> - <literal>JdbmCacheLoader</literal> - , which is a cache loader - implementation based on the - <ulink url="http://jdbm.sourceforge.net/">JDBM engine</ulink> - , a fast and free alternative to - BerkeleyDB. - </para> - </listitem> - </itemizedlist> + <listitem> + <para> + <literal>JdbmCacheLoader</literal> + , which is a cache loader + implementation based on the + <ulink url="http://jdbm.sourceforge.net/">JDBM engine</ulink> + , a fast and free alternative to + BerkeleyDB. + </para> + </listitem> + </itemizedlist> - <para>Note that the BerkeleyDB implementation is much more efficient than - the filesystem-based implementation, and provides transactional - guarantees, but requires a commercial license if distributed with an - application (see http://www.oracle.com/database/berkeley-db/index.html for - details). - </para> + <para>Note that the BerkeleyDB implementation is much more efficient than + the filesystem-based implementation, and provides transactional + guarantees, but requires a commercial license if distributed with an + application (see http://www.oracle.com/database/berkeley-db/index.html for + details). + </para> - </section> + </section> - <section> - <title>Cache loaders that delegate to other caches</title> - <itemizedlist> - <listitem> - <para> - <literal>LocalDelegatingCacheLoader</literal> - , which enables - loading from and storing to another local (same JVM) cache. - </para> - </listitem> - <listitem> - <para> - <literal>ClusteredCacheLoader</literal> - , which allows querying - of other caches in the same cluster for in-memory data via the same - clustering protocols used to replicate data. Writes are - <emphasis>not</emphasis> - 'stored' though, as replication would - take care of any updates needed. You need to specify a property - called - <literal>timeout</literal> - , a long value telling the cache - loader how many milliseconds to wait for responses from the cluster - before assuming a null value. For example, - <literal>timeout = 3000</literal> - would use a timeout value of 3 seconds. - </para> - </listitem> - </itemizedlist> - </section> + <section> + <title>Cache loaders that delegate to other caches</title> + <itemizedlist> + <listitem> + <para> + <literal>LocalDelegatingCacheLoader</literal> + , which enables + loading from and storing to another local (same JVM) cache. + </para> + </listitem> + <listitem> + <para> + <literal>ClusteredCacheLoader</literal> + , which allows querying + of other caches in the same cluster for in-memory data via the same + clustering protocols used to replicate data. Writes are + <emphasis>not</emphasis> + 'stored' though, as replication would + take care of any updates needed. You need to specify a property + called + <literal>timeout</literal> + , a long value telling the cache + loader how many milliseconds to wait for responses from the cluster + before assuming a null value. For example, + <literal>timeout = 3000</literal> + would use a timeout value of 3 seconds. + </para> + </listitem> + </itemizedlist> + </section> - <section id="cl.jdbc"> - <title>JDBCCacheLoader</title> + <section id="cl.jdbc"> + <title>JDBCCacheLoader</title> - <para>JBossCache is distributed with a JDBC-based cache loader - implementation that stores/loads nodes' state into a relational database. - The implementing class is - <literal>org.jboss.cache.loader.JDBCCacheLoader</literal> - . - </para> + <para>JBossCache is distributed with a JDBC-based cache loader + implementation that stores/loads nodes' state into a relational database. + The implementing class is + <literal>org.jboss.cache.loader.JDBCCacheLoader</literal> + . + </para> - <para>The current implementation uses just one table. Each row in the table - represents one node and contains three columns: - <itemizedlist> - <listitem>column for - <literal>Fqn</literal> - (which is also a primary key - column) - </listitem> + <para>The current implementation uses just one table. Each row in the table + represents one node and contains three columns: + <itemizedlist> + <listitem>column for + <literal>Fqn</literal> + (which is also a primary key + column) + </listitem> - <listitem>column for node contents (attribute/value - pairs) - </listitem> + <listitem>column for node contents (attribute/value + pairs) + </listitem> - <listitem>column for parent - <literal>Fqn</literal> - </listitem> - </itemizedlist> - </para> + <listitem>column for parent + <literal>Fqn</literal> + </listitem> + </itemizedlist> + </para> - <para> - <literal>Fqn</literal>s are stored as strings. Node content is stored - as a BLOB. - <emphasis>WARNING:</emphasis> - JBoss Cache does not impose any - limitations on the types of objects used in - <literal>Fqn</literal> - but this implementation of - cache loader requires - <literal>Fqn</literal> - to contain only objects of type - <literal>java.lang.String</literal> - . Another limitation for - <literal>Fqn</literal> - is its - length. Since - <literal>Fqn</literal> - is a primary key, its default column type is - <literal>VARCHAR</literal> - which can store text values up to some - maximum length determined by the database in use. - </para> + <para> + <literal>Fqn</literal>s are stored as strings. Node content is stored + as a BLOB. + <emphasis>WARNING:</emphasis> + JBoss Cache does not impose any + limitations on the types of objects used in + <literal>Fqn</literal> + but this implementation of + cache loader requires + <literal>Fqn</literal> + to contain only objects of type + <literal>java.lang.String</literal> + . Another limitation for + <literal>Fqn</literal> + is its + length. Since + <literal>Fqn</literal> + is a primary key, its default column type is + <literal>VARCHAR</literal> + which can store text values up to some + maximum length determined by the database in use. + </para> - <para>See - <ulink url="http://www.jboss.org/community/docs/DOC-10864">this wiki page</ulink> - for configuration tips with specific database systems. - </para> + <para>See + <ulink url="http://www.jboss.org/community/docs/DOC-10864">this wiki page</ulink> + for configuration tips with specific database systems. + </para> - <section> - <title>JDBCCacheLoader configuration</title> - <section> - <title>Table configuration</title> + <title>JDBCCacheLoader configuration</title> - <para>Table and column names as well as column types are - configurable with the following properties. - <itemizedlist> - <listitem> - <emphasis>cache.jdbc.table.name</emphasis> - - the name - of the table. Can be prepended with schema name for the given table: - <literal>{schema_name}.{table_name}</literal>. - The default value is 'jbosscache'. - </listitem> + <section> + <title>Table configuration</title> - <listitem> - <emphasis>cache.jdbc.table.primarykey</emphasis> - - the - name of the primary key for the table. The default value is - 'jbosscache_pk'. - </listitem> + <para>Table and column names as well as column types are + configurable with the following properties. + <itemizedlist> + <listitem> + <emphasis>cache.jdbc.table.name</emphasis> + - the name + of the table. Can be prepended with schema name for the given table: + <literal>{schema_name}.{table_name}</literal>. + The default value is 'jbosscache'. + </listitem> - <listitem> - <emphasis>cache.jdbc.table.create</emphasis> - - can be - true or false. Indicates whether to create the table during startup. - If true, the table is created if it doesn't already exist. The - default value is true. - </listitem> + <listitem> + <emphasis>cache.jdbc.table.primarykey</emphasis> + - the + name of the primary key for the table. The default value is + 'jbosscache_pk'. + </listitem> - <listitem> - <emphasis>cache.jdbc.table.drop</emphasis> - - can be - true or false. Indicates whether to drop the table during shutdown. The - default value is true. - </listitem> + <listitem> + <emphasis>cache.jdbc.table.create</emphasis> + - can be + true or false. Indicates whether to create the table during startup. + If true, the table is created if it doesn't already exist. The + default value is true. + </listitem> - <listitem> - <emphasis>cache.jdbc.fqn.column</emphasis> - - FQN - column name. The default value is 'fqn'. - </listitem> + <listitem> + <emphasis>cache.jdbc.table.drop</emphasis> + - can be + true or false. Indicates whether to drop the table during shutdown. The + default value is true. + </listitem> - <listitem> - <emphasis>cache.jdbc.fqn.type</emphasis> - - FQN column - type. The default value is 'varchar(255)'. - </listitem> + <listitem> + <emphasis>cache.jdbc.fqn.column</emphasis> + - FQN + column name. The default value is 'fqn'. + </listitem> - <listitem> - <emphasis>cache.jdbc.node.column</emphasis> - - node - contents column name. The default value is 'node'. - </listitem> + <listitem> + <emphasis>cache.jdbc.fqn.type</emphasis> + - FQN column + type. The default value is 'varchar(255)'. + </listitem> - <listitem> - <emphasis>cache.jdbc.node.type</emphasis> - - node - contents column type. The default value is 'blob'. This type must specify - a valid binary data type for the database being used. - </listitem> - </itemizedlist> - </para> - </section> + <listitem> + <emphasis>cache.jdbc.node.column</emphasis> + - node + contents column name. The default value is 'node'. + </listitem> - <section> - <title>DataSource</title> + <listitem> + <emphasis>cache.jdbc.node.type</emphasis> + - node + contents column type. The default value is 'blob'. This type must specify + a valid binary data type for the database being used. + </listitem> + </itemizedlist> + </para> + </section> - <para>If you are using JBossCache in a managed environment (e.g., an - application server) you can specify the JNDI name of the DataSource - you want to use. - <itemizedlist> - <listitem> - <emphasis>cache.jdbc.datasource</emphasis> - - JNDI name - of the DataSource. The default value is - <literal>java:/DefaultDS</literal> - . - </listitem> - </itemizedlist> - </para> - </section> + <section> + <title>DataSource</title> - <section> - <title>JDBC driver</title> + <para>If you are using JBossCache in a managed environment (e.g., an + application server) you can specify the JNDI name of the DataSource + you want to use. + <itemizedlist> + <listitem> + <emphasis>cache.jdbc.datasource</emphasis> + - JNDI name + of the DataSource. The default value is + <literal>java:/DefaultDS</literal> + . + </listitem> + </itemizedlist> + </para> + </section> - <para>If you are - <emphasis>not</emphasis> - using DataSource you have - the following properties to configure database access using a JDBC - driver. - <itemizedlist> - <listitem> - <emphasis>cache.jdbc.driver</emphasis> - - fully - qualified JDBC driver name. - </listitem> + <section> + <title>JDBC driver</title> - <listitem> - <emphasis>cache.jdbc.url</emphasis> - - URL to connect - to the database. - </listitem> + <para>If you are + <emphasis>not</emphasis> + using DataSource you have + the following properties to configure database access using a JDBC + driver. + <itemizedlist> + <listitem> + <emphasis>cache.jdbc.driver</emphasis> + - fully + qualified JDBC driver name. + </listitem> - <listitem> - <emphasis>cache.jdbc.user</emphasis> - - user name to - connect to the database. - </listitem> + <listitem> + <emphasis>cache.jdbc.url</emphasis> + - URL to connect + to the database. + </listitem> - <listitem> - <emphasis>cache.jdbc.password</emphasis> - - password to - connect to the database. - </listitem> - </itemizedlist> - </para> - </section> + <listitem> + <emphasis>cache.jdbc.user</emphasis> + - user name to + connect to the database. + </listitem> - <section> - <title>c3p0 connection pooling</title> + <listitem> + <emphasis>cache.jdbc.password</emphasis> + - password to + connect to the database. + </listitem> + </itemizedlist> + </para> + </section> - <para>JBoss Cache implements JDBC connection pooling when running outside of an application server - standalone using - the c3p0:JDBC DataSources/Resource Pools library. In order to enable it, just edit the following - property: - <itemizedlist> - <listitem> - <emphasis>cache.jdbc.connection.factory</emphasis> - - Connection factory class name. - If not set, it defaults to standard non-pooled implementation. To enable c3p0 pooling, just set - the - connection factory class for c3p0. See example below. - </listitem> - </itemizedlist> - </para> + <section> + <title>c3p0 connection pooling</title> - <para>You can also set any c3p0 parameters in the same cache loader properties section but don't forget - to - start the property name with 'c3p0.'. To find a list of available properties, please check the - c3p0 documentation for the c3p0 library version distributed in - <ulink url="http://sourceforge.net/projects/c3p0">c3p0:JDBC DataSources/Resource Pools</ulink> - . - Also, in order to provide quick and easy way to try out different pooling - parameters, any of these properties can be set via a System property overriding any values these - properties might have in the JBoss Cache XML configuration file, for example: - <literal>-Dc3p0.maxPoolSize=20</literal> - . - If a c3p0 property is not defined in either the configuration file or as a System property, default - value, as indicated in the c3p0 documentation, will apply. - </para> - </section> + <para>JBoss Cache implements JDBC connection pooling when running outside of an application server + standalone using + the c3p0:JDBC DataSources/Resource Pools library. In order to enable it, just edit the following + property: + <itemizedlist> + <listitem> + <emphasis>cache.jdbc.connection.factory</emphasis> + - Connection factory class name. + If not set, it defaults to standard non-pooled implementation. To enable c3p0 pooling, + just set + the + connection factory class for c3p0. See example below. + </listitem> + </itemizedlist> + </para> - <section> - <title>Configuration example</title> + <para>You can also set any c3p0 parameters in the same cache loader properties section but don't + forget + to + start the property name with 'c3p0.'. To find a list of available properties, please check the + c3p0 documentation for the c3p0 library version distributed in + <ulink url="http://sourceforge.net/projects/c3p0">c3p0:JDBC DataSources/Resource Pools</ulink> + . + Also, in order to provide quick and easy way to try out different pooling + parameters, any of these properties can be set via a System property overriding any values these + properties might have in the JBoss Cache XML configuration file, for example: + <literal>-Dc3p0.maxPoolSize=20</literal> + . + If a c3p0 property is not defined in either the configuration file or as a System property, + default + value, as indicated in the c3p0 documentation, will apply. + </para> + </section> - <para>Below is an example of a JDBCCacheLoader using Oracle as - database. The CacheLoaderConfiguration XML element contains an - arbitrary set of properties which define the database-related - configuration. - </para> + <section> + <title>Configuration example</title> - <programlisting role="XML"><![CDATA[ + <para>Below is an example of a JDBCCacheLoader using Oracle as + database. The CacheLoaderConfiguration XML element contains an + arbitrary set of properties which define the database-related + configuration. + </para> + + <programlisting role="XML"><![CDATA[ <loaders passivation="false" shared="false"> <preload> <node fqn="/some/stuff"/> @@ -787,9 +798,9 @@ cache.jdbc.table.drop=true cache.jdbc.table.primarykey=jbosscache_pk cache.jdbc.fqn.column=fqn - cache.jdbc.fqn.type=varchar(255) + cache.jdbc.fqn.type=VARCHAR(255) cache.jdbc.node.column=node - cache.jdbc.node.type=blob + 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 @@ -801,11 +812,11 @@ </loaders> ]]></programlisting> - <para>As an alternative to configuring the entire JDBC connection, - the name of an existing data source can be given: - </para> + <para>As an alternative to configuring the entire JDBC connection, + the name of an existing data source can be given: + </para> - <programlisting role="XML"><![CDATA[ + <programlisting role="XML"><![CDATA[ <loaders passivation="false" shared="false"> <preload> <node fqn="/some/stuff"/> @@ -820,9 +831,9 @@ </loaders> ]]></programlisting> - <para>Cconfiguration example for a cache loader using c3p0 JDBC connection pooling:</para> + <para>Cconfiguration example for a cache loader using c3p0 JDBC connection pooling:</para> - <programlisting role="XML"><![CDATA[ + <programlisting role="XML"><![CDATA[ <loaders passivation="false" shared="false"> <preload> <node fqn="/some/stuff"/> @@ -836,9 +847,9 @@ cache.jdbc.table.drop=true cache.jdbc.table.primarykey=jbosscache_pk cache.jdbc.fqn.column=fqn - cache.jdbc.fqn.type=varchar(255) + cache.jdbc.fqn.type=VARCHAR(255) cache.jdbc.node.column=node - cache.jdbc.node.type=blob + 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 @@ -853,79 +864,79 @@ </loaders> ]]></programlisting> + </section> </section> - </section> - </section> + </section> - <section id="cl.s3"> - <title>S3CacheLoader</title> + <section id="cl.s3"> + <title>S3CacheLoader</title> - <para>The - <literal>S3CacheLoader</literal> - uses the - <ulink url="http://aws.amazon.com/">Amazon S3</ulink> - (Simple Storage Solution) - for storing cache data. - Since Amazon S3 is remote network storage and has fairly high latency, - it is really best for caches that store large pieces of data, such as media - or files. - But consider this cache loader over the JDBC or - file system based cache loaders if you want remotely managed, highly reliable - storage. Or, use it for applications running on Amazon's EC2 (Elastic Compute Cloud). - </para> + <para>The + <literal>S3CacheLoader</literal> + uses the + <ulink url="http://aws.amazon.com/">Amazon S3</ulink> + (Simple Storage Solution) + for storing cache data. + Since Amazon S3 is remote network storage and has fairly high latency, + it is really best for caches that store large pieces of data, such as media + or files. + But consider this cache loader over the JDBC or + file system based cache loaders if you want remotely managed, highly reliable + storage. Or, use it for applications running on Amazon's EC2 (Elastic Compute Cloud). + </para> - <para> - If you're planning to use Amazon S3 for storage, consider using it with JBoss Cache. - JBoss Cache itself provides in-memory caching for your data to minimize the amount of - remote access calls, thus reducing the latency and cost of fetching your Amazon S3 data. - With cache replication, you are also able to load data from your local cluster - without having to remotely access it every time. - </para> + <para> + If you're planning to use Amazon S3 for storage, consider using it with JBoss Cache. + JBoss Cache itself provides in-memory caching for your data to minimize the amount of + remote access calls, thus reducing the latency and cost of fetching your Amazon S3 data. + With cache replication, you are also able to load data from your local cluster + without having to remotely access it every time. + </para> - <para> - Note that Amazon S3 does not support transactions. If transactions - are used in your application then there is some possibility of state - inconsistency when using this cache loader. However, writes are atomic, in - that if a write fails nothing is considered written and data is never - corrupted. - </para> + <para> + Note that Amazon S3 does not support transactions. If transactions + are used in your application then there is some possibility of state + inconsistency when using this cache loader. However, writes are atomic, in + that if a write fails nothing is considered written and data is never + corrupted. + </para> - <para> - Data is stored in keys based on the Fqn of the Node and Node data is - serialized as a java.util.Map using the - <literal>CacheSPI.getMarshaller()</literal> - instance. - Read the javadoc on how data is structured and stored. - Data is stored using Java serialization. - Be aware this means data is not readily accessible over HTTP to - non-JBoss Cache clients. Your feedback and help would be appreciated - to extend this cache loader for that purpose. - </para> + <para> + Data is stored in keys based on the Fqn of the Node and Node data is + serialized as a java.util.Map using the + <literal>CacheSPI.getMarshaller()</literal> + instance. + Read the javadoc on how data is structured and stored. + Data is stored using Java serialization. + Be aware this means data is not readily accessible over HTTP to + non-JBoss Cache clients. Your feedback and help would be appreciated + to extend this cache loader for that purpose. + </para> - <para> - With this cache loader, single-key operations such as - <literal>Node.remove(Object)</literal> - and - <literal>Node.put(Object, Object)</literal> - are the slowest as data is stored in a single Map instance. - Use bulk operations such as - <literal>Node.replaceAll(Map)</literal> - and - <literal>Node.clearData()</literal> - for more efficiency. - Try the - <literal>cache.s3.optimize</literal> - option as well. - </para> + <para> + With this cache loader, single-key operations such as + <literal>Node.remove(Object)</literal> + and + <literal>Node.put(Object, Object)</literal> + are the slowest as data is stored in a single Map instance. + Use bulk operations such as + <literal>Node.replaceAll(Map)</literal> + and + <literal>Node.clearData()</literal> + for more efficiency. + Try the + <literal>cache.s3.optimize</literal> + option as well. + </para> - <section> - <title>Amazon S3 Library</title> - <para>The S3 cache loader is provided with the default - distribution but requires a library to access the service - at runtime. This runtime library may be obtained through a Sourceforge Maven - Repository. Include the following sections in your pom.xml file: - </para> - <programlisting role="XML"><![CDATA[ + <section> + <title>Amazon S3 Library</title> + <para>The S3 cache loader is provided with the default + distribution but requires a library to access the service + at runtime. This runtime library may be obtained through a Sourceforge Maven + Repository. Include the following sections in your pom.xml file: + </para> + <programlisting role="XML"><![CDATA[ <repository> <id>e-xml.sourceforge.net</id> <url>http://e-xml.sourceforge.net/maven2/repository</url> @@ -938,158 +949,163 @@ <scope>runtime</scope> </dependency> ]]> - </programlisting> - If you do not use Maven, you can still download the - amazon-s3 library by navigating the repository or through - <ulink url="http://e-xml.sourceforge.net/maven2/repository/net/noderunner/a... URL</ulink>. - </section> + </programlisting> + If you do not use Maven, you can still download the + amazon-s3 library by navigating the repository or through + <ulink url="http://e-xml.sourceforge.net/maven2/repository/net/noderunner/a... + this URL</ulink>. + </section> - <section> - <title>Configuration</title> - <para>At a minimum, you must configure your Amazon S3 access key and - secret access key. The following configuration keys are listed in general - order of utility. - </para> + <section> + <title>Configuration</title> + <para>At a minimum, you must configure your Amazon S3 access key and + secret access key. The following configuration keys are listed in general + order of utility. + </para> - <para> - <itemizedlist> - <listitem> - <literal>cache.s3.accessKeyId</literal> - - - Amazon S3 Access Key, available from your account profile. - </listitem> + <para> + <itemizedlist> + <listitem> + <literal>cache.s3.accessKeyId</literal> + - + Amazon S3 Access Key, available from your account profile. + </listitem> - <listitem> - <literal>cache.s3.secretAccessKey</literal> - - - Amazon S3 Secret Access Key, available from your account profile. - As this is a password, be careful not to distribute it or include - this secret key in built software. - </listitem> + <listitem> + <literal>cache.s3.secretAccessKey</literal> + - + Amazon S3 Secret Access Key, available from your account profile. + As this is a password, be careful not to distribute it or include + this secret key in built software. + </listitem> - <listitem> - <literal>cache.s3.secure</literal> - - - The default is<literal>false</literal>: - Traffic is sent unencrypted over the public Internet. - Set to - <literal>true</literal> - to use HTTPS. - Note that unencrypted uploads and downloads use less CPU. - </listitem> + <listitem> + <literal>cache.s3.secure</literal> + - + The default is<literal>false</literal>: + Traffic is sent unencrypted over the public Internet. + Set to + <literal>true</literal> + to use HTTPS. + Note that unencrypted uploads and downloads use less CPU. + </listitem> - <listitem> - <literal>cache.s3.bucket</literal> - - - Name of the bucket to store data. - For different caches using the same access key, use a different bucket name. - Read the S3 documentation on the definition of a bucket. - The default value is <literal>jboss-cache</literal>. - </listitem> + <listitem> + <literal>cache.s3.bucket</literal> + - + Name of the bucket to store data. + For different caches using the same access key, use a different bucket name. + Read the S3 documentation on the definition of a bucket. + The default value is<literal>jboss-cache</literal>. + </listitem> - <listitem> - <literal>cache.s3.callingFormat</literal> - - - One of <literal>PATH</literal>, <literal>SUBDOMAIN</literal>, or - <literal>VANITY</literal>. - Read the S3 documentation on the use of calling domains. - The default value is <literal>SUBDOMAIN</literal>. - </listitem> + <listitem> + <literal>cache.s3.callingFormat</literal> + - + One of<literal>PATH</literal>,<literal>SUBDOMAIN</literal>, or + <literal>VANITY</literal>. + Read the S3 documentation on the use of calling domains. + The default value is<literal>SUBDOMAIN</literal>. + </listitem> - <listitem> - <literal>cache.s3.optimize</literal> - - - The default is <literal>false</literal>. - If true, - <literal>put(Map)</literal> - operations - replace the data stored at an Fqn rather than attempt - to fetch and merge. (This option is fairly experimental - at the moment.) - </listitem> + <listitem> + <literal>cache.s3.optimize</literal> + - + The default is<literal>false</literal>. + If true, + <literal>put(Map)</literal> + operations + replace the data stored at an Fqn rather than attempt + to fetch and merge. (This option is fairly experimental + at the moment.) + </listitem> - <listitem> - <literal>cache.s3.parentCache</literal> - - - The default is <literal>true</literal>. - Set this value to - <literal>false</literal> - if you are using multiple caches - sharing the same S3 bucket, that remove parent nodes of nodes being created - in other caches. (This is not a common use case.) - <para> - JBoss Cache stores nodes in a tree format and automatically - creates intermediate parent nodes as necessary. - The S3 cache loader must also create these parent nodes as well - to allow for operations such as - <literal>getChildrenNames</literal> - to work - properly. Checking if all parent nodes exists for every - <literal>put</literal> - operation is fairly expensive, so by default the cache loader caches - the existence of these parent nodes. - </para> - </listitem> + <listitem> + <literal>cache.s3.parentCache</literal> + - + The default is<literal>true</literal>. + Set this value to + <literal>false</literal> + if you are using multiple caches + sharing the same S3 bucket, that remove parent nodes of nodes being created + in other caches. (This is not a common use case.) + <para> + JBoss Cache stores nodes in a tree format and automatically + creates intermediate parent nodes as necessary. + The S3 cache loader must also create these parent nodes as well + to allow for operations such as + <literal>getChildrenNames</literal> + to work + properly. Checking if all parent nodes exists for every + <literal>put</literal> + operation is fairly expensive, so by default the cache loader caches + the existence of these parent nodes. + </para> + </listitem> - <listitem> - <literal>cache.s3.location</literal> - - - This choses a primary storage location for your data - to reduce loading and retrieval latency. - Set to <literal>EU</literal> - to store data in Europe. - The default is <literal>null</literal>, to store data in - the United States. - </listitem> - </itemizedlist> - </para> - </section> + <listitem> + <literal>cache.s3.location</literal> + - + This choses a primary storage location for your data + to reduce loading and retrieval latency. + Set to + <literal>EU</literal> + to store data in Europe. + The default is<literal>null</literal>, to store data in + the United States. + </listitem> + </itemizedlist> + </para> + </section> - </section> + </section> - <section id="cl.tcp"> - <title>TcpDelegatingCacheLoader</title> + <section id="cl.tcp"> + <title>TcpDelegatingCacheLoader</title> - <para>This cache loader allows to delegate loads and stores to another - instance of JBoss Cache, which could reside (a) in the same address - space, (b) in a different process on the same host, or (c) in a - different process on a different host. - </para> + <para>This cache loader allows to delegate loads and stores to another + instance of JBoss Cache, which could reside (a) in the same address + space, (b) in a different process on the same host, or (c) in a + different process on a different host. + </para> - <para>A TcpDelegatingCacheLoader talks to a remote - <literal>org.jboss.cache.loader.tcp.TcpCacheServer</literal> - , - which can be a standalone process started on the command line, or embedded as an MBean inside - JBoss AS. The - <literal>TcpCacheServer</literal> - has a reference to another JBoss Cache instance, which - it can create itself, or which is given to it (e.g. by JBoss, using - dependency injection). - </para> + <para>A TcpDelegatingCacheLoader talks to a remote + <literal>org.jboss.cache.loader.tcp.TcpCacheServer</literal> + , + which can be a standalone process started on the command line, or embedded as an MBean inside + JBoss AS. The + <literal>TcpCacheServer</literal> + has a reference to another JBoss Cache instance, which + it can create itself, or which is given to it (e.g. by JBoss, using + dependency injection). + </para> - <para> - As of JBoss Cache 2.1.0, the <literal>TcpDelegatingCacheLoader</literal> transparently handles reconnects if the connection - to the TcpCacheServer is lost. - </para> + <para> + As of JBoss Cache 2.1.0, the + <literal>TcpDelegatingCacheLoader</literal> + transparently handles reconnects if the connection + to the TcpCacheServer is lost. + </para> - <para>The TcpDelegatingCacheLoader is configured with the host and port of the remote TcpCacheServer, and uses - this to communicate to - it. In addition, 2 new optional parameters are used to control transparent reconnecting to the - TcpCacheServer. - The - <literal>timeout</literal> - property (defaults to 5000) specifies the length of time the cache loader must continue - retrying to connect to the TcpCacheServer before giving up and throwing an exception. The - <literal>reconnectWaitTime</literal> - (defaults to 500) is how long the cache loader should wait before attempting a reconnect if it detects a - communication failure. - The last two parameters can be used to add a level of fault tolerance to the cache loader, do deal with - TcpCacheServer restarts. - </para> + <para>The TcpDelegatingCacheLoader is configured with the host and port of the remote TcpCacheServer, and + uses + this to communicate to + it. In addition, 2 new optional parameters are used to control transparent reconnecting to the + TcpCacheServer. + The + <literal>timeout</literal> + property (defaults to 5000) specifies the length of time the cache loader must continue + retrying to connect to the TcpCacheServer before giving up and throwing an exception. The + <literal>reconnectWaitTime</literal> + (defaults to 500) is how long the cache loader should wait before attempting a reconnect if it detects a + communication failure. + The last two parameters can be used to add a level of fault tolerance to the cache loader, do deal with + TcpCacheServer restarts. + </para> - <para>The configuration looks as follows:</para> + <para>The configuration looks as follows:</para> - <programlisting role="XML"><![CDATA[ + <programlisting role="XML"><![CDATA[ <loaders passivation="false" shared="false"> <preload> <node fqn="/"/> @@ -1106,434 +1122,438 @@ </loaders> ]]></programlisting> - <para>This means this instance of JBoss Cache will delegate all load - and store requests to the remote TcpCacheServer running on - <literal>myRemoteServer:7500</literal> - . - </para> + <para>This means this instance of JBoss Cache will delegate all load + and store requests to the remote TcpCacheServer running on + <literal>myRemoteServer:7500</literal> + . + </para> - <para>A typical use case could be multiple replicated instances of - JBoss Cache in the same cluster, all delegating to the same - TcpCacheServer instance. The TcpCacheServer might itself delegate to a - database via JDBCCacheLoader, but the point here is that - if we have - 5 nodes all accessing the same dataset - they will load the data from - the TcpCacheServer, which has do execute one SQL statement per - unloaded data set. If the nodes went directly to the database, then - we'd have the same SQL executed multiple times. So TcpCacheServer - serves as a natural cache in front of the DB (assuming that a network - round trip is faster than a DB access (which usually also include a - network round trip)). - </para> + <para>A typical use case could be multiple replicated instances of + JBoss Cache in the same cluster, all delegating to the same + TcpCacheServer instance. The TcpCacheServer might itself delegate to a + database via JDBCCacheLoader, but the point here is that - if we have + 5 nodes all accessing the same dataset - they will load the data from + the TcpCacheServer, which has do execute one SQL statement per + unloaded data set. If the nodes went directly to the database, then + we'd have the same SQL executed multiple times. So TcpCacheServer + serves as a natural cache in front of the DB (assuming that a network + round trip is faster than a DB access (which usually also include a + network round trip)). + </para> - <para>To alleviate single point of failure, we could configure several cache loaders. - The first cache loader is a ClusteredCacheLoader, the second a TcpDelegatingCacheLoader, and the - last a JDBCacheLoader, effectively defining our cost of access to a - cache in increasing order. - </para> + <para>To alleviate single point of failure, we could configure several cache loaders. + The first cache loader is a ClusteredCacheLoader, the second a TcpDelegatingCacheLoader, and the + last a JDBCacheLoader, effectively defining our cost of access to a + cache in increasing order. + </para> - </section> + </section> - <section id="cl.transforming"> - <title>Transforming Cache Loaders</title> + <section id="cl.transforming"> + <title>Transforming Cache Loaders</title> - <para>The way cached data is written to - <literal>FileCacheLoader</literal> - and - <literal>JDBCCacheLoader</literal> - based cache stores has changed in JBoss Cache 2.0 in such way that - these cache loaders now write and read data using the same marhalling framework used to replicate data - across the network. Such change is trivial for replication purposes as it just requires the rest of the - nodes to understand this format. However, changing the format of the data in cache stores brings up a new - problem: how do users, which have their data stored in JBoss Cache 1.x.x format, migrate their stores to - JBoss Cache 2.0 format? - </para> + <para>The way cached data is written to + <literal>FileCacheLoader</literal> + and + <literal>JDBCCacheLoader</literal> + based cache stores has changed in JBoss Cache 2.0 in such way that + these cache loaders now write and read data using the same marhalling framework used to replicate data + across the network. Such change is trivial for replication purposes as it just requires the rest of the + nodes to understand this format. However, changing the format of the data in cache stores brings up a + new + problem: how do users, which have their data stored in JBoss Cache 1.x.x format, migrate their stores to + JBoss Cache 2.0 format? + </para> - <para>With this in mind, JBoss Cache 2.0 comes with two cache loader implementations called - <literal>org.jboss.cache.loader.TransformingFileCacheLoader</literal> - and - <literal>org.jboss.cache.loader.TransformingJDBCCacheLoader</literal> - located within the optional - jbosscache-cacheloader-migration.jar file. These are one-off cache loaders that read data from the - cache store in JBoss Cache 1.x.x format and write data to cache stores in JBoss Cache 2.0 format. - </para> + <para>With this in mind, JBoss Cache 2.0 comes with two cache loader implementations called + <literal>org.jboss.cache.loader.TransformingFileCacheLoader</literal> + and + <literal>org.jboss.cache.loader.TransformingJDBCCacheLoader</literal> + located within the optional + jbosscache-cacheloader-migration.jar file. These are one-off cache loaders that read data from the + cache store in JBoss Cache 1.x.x format and write data to cache stores in JBoss Cache 2.0 format. + </para> - <para>The idea is for users to modify their existing cache configuration file(s) momentarily to use these - cache loaders and for them to create a small Java application that creates an instance of this cache, - recursively reads the entire cache and writes the data read back into the cache. Once the data is - transformed, users can revert back to their original cache configuration file(s). In order to help the users - with this task, a cache loader migration example has been constructed which can be located under the - <literal>examples/cacheloader-migration</literal> - directory within the JBoss Cache distribution. This - example, called - <literal>examples.TransformStore</literal> - , is independent of the actual data stored in - the cache as it writes back whatever it was read recursively. It is highly recommended that anyone - interested in porting their data run this example first, which contains a - <literal>readme.txt</literal> - file with detailed information about the example itself, and also use it as base for their own application. - </para> + <para>The idea is for users to modify their existing cache configuration file(s) momentarily to use these + cache loaders and for them to create a small Java application that creates an instance of this cache, + recursively reads the entire cache and writes the data read back into the cache. Once the data is + transformed, users can revert back to their original cache configuration file(s). In order to help the + users + with this task, a cache loader migration example has been constructed which can be located under the + <literal>examples/cacheloader-migration</literal> + directory within the JBoss Cache distribution. This + example, called + <literal>examples.TransformStore</literal> + , is independent of the actual data stored in + the cache as it writes back whatever it was read recursively. It is highly recommended that anyone + interested in porting their data run this example first, which contains a + <literal>readme.txt</literal> + file with detailed information about the example itself, and also use it as base for their own + application. + </para> - </section> + </section> - </section> + </section> - <section id="cl.pass"> - <title>Cache Passivation</title> + <section id="cl.pass"> + <title>Cache Passivation</title> - <para>A cache loader can be used to enforce node passivation and - activation on eviction in a cache. - </para> + <para>A cache loader can be used to enforce node passivation and + activation on eviction in a cache. + </para> - <para> - <emphasis>Cache Passivation</emphasis> - is the process of removing - an object from in-memory cache and writing it to a secondary data store - (e.g., file system, database) on eviction. - <emphasis>Cache - Activation - </emphasis> - is the process of restoring an object from the - data store into the in-memory cache when it's needed to be used. In both - cases, the configured cache loader will be used to read from the data - store and write to the data store. - </para> + <para> + <emphasis>Cache Passivation</emphasis> + is the process of removing + an object from in-memory cache and writing it to a secondary data store + (e.g., file system, database) on eviction. + <emphasis>Cache + Activation + </emphasis> + is the process of restoring an object from the + data store into the in-memory cache when it's needed to be used. In both + cases, the configured cache loader will be used to read from the data + store and write to the data store. + </para> - <para>When an eviction policy in effect evicts a node - from the cache, if passivation is enabled, a notification that the node - is being passivated will be emitted to the cache listeners and the - node and its children will be stored in the cache loader store. When a - user attempts to retrieve a node that was evicted earlier, the node is loaded - (lazy loaded) from the cache loader store into memory. When - the node and its children have been loaded, they're removed from the - cache loader and a notification is emitted to the cache listeners - that the node has been activated. - </para> + <para>When an eviction policy in effect evicts a node + from the cache, if passivation is enabled, a notification that the node + is being passivated will be emitted to the cache listeners and the + node and its children will be stored in the cache loader store. When a + user attempts to retrieve a node that was evicted earlier, the node is loaded + (lazy loaded) from the cache loader store into memory. When + the node and its children have been loaded, they're removed from the + cache loader and a notification is emitted to the cache listeners + that the node has been activated. + </para> - <para>To enable cache passivation/activation, you can set - <literal>passivation</literal> - to true. The default is - <literal>false</literal> - . - When passivation is used, only the first cache loader configured is - used and all others are ignored. - </para> + <para>To enable cache passivation/activation, you can set + <literal>passivation</literal> + to true. The default is + <literal>false</literal> + . + When passivation is used, only the first cache loader configured is + used and all others are ignored. + </para> - <section> - <title>Cache Loader Behavior with Passivation Disabled vs. Enabled</title> + <section> + <title>Cache Loader Behavior with Passivation Disabled vs. Enabled</title> - <para> - When passivation is disabled, whenever an element is modified, added or - removed, then that modification is persisted in the backend store via - the cache loader. There is no direct relationship between eviction and - cache loading. If you don't use eviction, what's in the persistent store - is basically a copy of what's in memory. If you do use eviction, what's - in the persistent store is basically a superset of what's in memory - (i.e. it includes nodes that have been evicted from memory). - </para> + <para> + When passivation is disabled, whenever an element is modified, added or + removed, then that modification is persisted in the backend store via + the cache loader. There is no direct relationship between eviction and + cache loading. If you don't use eviction, what's in the persistent store + is basically a copy of what's in memory. If you do use eviction, what's + in the persistent store is basically a superset of what's in memory + (i.e. it includes nodes that have been evicted from memory). + </para> - <para> - When passivation is enabled, there is a direct relationship between - eviction and the cache loader. Writes to the persistent store via the - cache loader only occur as part of the eviction process. Data is deleted - from the persistent store when the application reads it back into - memory. In this case, what's in memory and what's in the persistent - store are two subsets of the total information set, with no intersection between the subsets. - </para> + <para> + When passivation is enabled, there is a direct relationship between + eviction and the cache loader. Writes to the persistent store via the + cache loader only occur as part of the eviction process. Data is deleted + from the persistent store when the application reads it back into + memory. In this case, what's in memory and what's in the persistent + store are two subsets of the total information set, with no intersection between the subsets. + </para> - <para> - Following is a simple example, showing what state is in RAM and in the - persistent store after each step of a 6 step process: - </para> + <para> + Following is a simple example, showing what state is in RAM and in the + persistent store after each step of a 6 step process: + </para> - <orderedlist> - <listitem>Insert /A</listitem> - <listitem>Insert /B</listitem> - <listitem>Eviction thread runs, evicts /A</listitem> - <listitem>Read /A</listitem> - <listitem>Eviction thread runs, evicts /B</listitem> - <listitem>Remove /B</listitem> - </orderedlist> + <orderedlist> + <listitem>Insert /A</listitem> + <listitem>Insert /B</listitem> + <listitem>Eviction thread runs, evicts /A</listitem> + <listitem>Read /A</listitem> + <listitem>Eviction thread runs, evicts /B</listitem> + <listitem>Remove /B</listitem> + </orderedlist> - <para>When passivation is disabled:</para> - <programlisting> - 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 disabled:</para> + <programlisting> + 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) 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> + <para>When passivation is enabled:</para> + <programlisting> + 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> - </section> + </section> - <section> - <title>Strategies</title> - <para> - This section discusses different patterns of combining different cache loader types and configuration - options to achieve specific outcomes. - </para> + <section> + <title>Strategies</title> + <para> + This section discusses different patterns of combining different cache loader types and configuration + options to achieve specific outcomes. + </para> - <section> - <title>Local Cache With Store</title> + <section> + <title>Local Cache With Store</title> - <para>This is the simplest case. We have a JBoss Cache instance, whose - cache mode is - <literal>LOCAL</literal> - , therefore no replication is going - on. The cache loader simply loads non-existing elements from the store - and stores modifications back to the store. When the cache is started, - depending on the - <literal>preload</literal> - element, certain data can - be preloaded, so that the cache is partly warmed up. - </para> - </section> + <para>This is the simplest case. We have a JBoss Cache instance, whose + cache mode is + <literal>LOCAL</literal> + , therefore no replication is going + on. The cache loader simply loads non-existing elements from the store + and stores modifications back to the store. When the cache is started, + depending on the + <literal>preload</literal> + element, certain data can + be preloaded, so that the cache is partly warmed up. + </para> + </section> - <section> - <title>Replicated Caches With All Caches Sharing The Same Store</title> + <section> + <title>Replicated Caches With All Caches Sharing The Same Store</title> - <para>The following figure shows 2 JBoss Cache instances sharing the same - backend store: - </para> + <para>The following figure shows 2 JBoss Cache instances sharing the same + backend store: + </para> - <figure> - <title>2 nodes sharing a backend store</title> + <figure> + <title>2 nodes sharing a backend store</title> - <mediaobject> - <imageobject> - <imagedata fileref="SharedCacheLoader.png"/> - </imageobject> - </mediaobject> - </figure> + <mediaobject> + <imageobject> + <imagedata fileref="SharedCacheLoader.png"/> + </imageobject> + </mediaobject> + </figure> - <para>Both nodes have a cache loader that accesses a common shared - backend store. This could for example be a shared filesystem (using - the FileCacheLoader), or a shared database. Because both nodes access - the same store, they don't necessarily need state transfer on - startup. - <footnote> - <para>Of course they can enable state transfer, if they want to - have a warm or hot cache after startup. - </para> - </footnote> - Rather, the - <literal>FetchInMemoryState</literal> - attribute could be set to false, resulting in a 'cold' cache, that - gradually warms up as elements are accessed and loaded for the first - time. This would mean that individual caches in a cluster might have - different in-memory state at any given time (largely depending on - their preloading and eviction strategies). - </para> + <para>Both nodes have a cache loader that accesses a common shared + backend store. This could for example be a shared filesystem (using + the FileCacheLoader), or a shared database. Because both nodes access + the same store, they don't necessarily need state transfer on + startup. + <footnote> + <para>Of course they can enable state transfer, if they want to + have a warm or hot cache after startup. + </para> + </footnote> + Rather, the + <literal>FetchInMemoryState</literal> + attribute could be set to false, resulting in a 'cold' cache, that + gradually warms up as elements are accessed and loaded for the first + time. This would mean that individual caches in a cluster might have + different in-memory state at any given time (largely depending on + their preloading and eviction strategies). + </para> - <para>When storing a value, the writer takes care of storing the - change in the backend store. For example, if node1 made change C1 and - node2 C2, then node1 would tell its cache loader to store C1, and node2 - would tell its cache loader to store C2. - </para> - </section> + <para>When storing a value, the writer takes care of storing the + change in the backend store. For example, if node1 made change C1 and + node2 C2, then node1 would tell its cache loader to store C1, and node2 + would tell its cache loader to store C2. + </para> + </section> - <section> - <title>Replicated Caches With Only One Cache Having A Store</title> + <section> + <title>Replicated Caches With Only One Cache Having A Store</title> - <figure> - <title>2 nodes but only one accesses the backend store</title> + <figure> + <title>2 nodes but only one accesses the backend store</title> - <mediaobject> - <imageobject> - <imagedata fileref="OnlyOneCacheLoader.png"/> - </imageobject> - </mediaobject> - </figure> + <mediaobject> + <imageobject> + <imagedata fileref="OnlyOneCacheLoader.png"/> + </imageobject> + </mediaobject> + </figure> - <para>This is a similar case to the previous one, but here only one - node in the cluster interacts with a backend store via its - cache loader. All other nodes perform in-memory replication. The idea - here is all application state is kept in memory in each node, with - the existence of multiple caches making the data highly available. - (This assumes that a client that needs the data is able to somehow - fail over from one cache to another.) The single persistent backend - store then provides a backup copy of the data in case all caches in - the cluster fail or need to be restarted. - </para> - <para> - Note that here it may make sense for the cache loader to store - changes asynchronously, that is - <emphasis>not</emphasis> - on the caller's thread, in order not to slow - down the cluster by accessing (for example) a database. This is a - non-issue when using asynchronous replication. - </para> - <para> - A weakness with this architecture is that the cache with access - to the cache loader becomes a single point of failure. Furthermore, - if the cluster is restarted, the cache with the cache loader must - be started first (easy to forget). A solution to the first problem - is to configure a cache loader on each node, but set the - <literal>singletonStore</literal> - configuration to - <literal>true</literal>. With this kind of setup, one but only one - node will always be writing to a persistent store. However, this - complicates the restart problem, as before restarting you need - to determine which cache was writing before the shutdown/failure - and then start that cache first. - </para> - </section> + <para>This is a similar case to the previous one, but here only one + node in the cluster interacts with a backend store via its + cache loader. All other nodes perform in-memory replication. The idea + here is all application state is kept in memory in each node, with + the existence of multiple caches making the data highly available. + (This assumes that a client that needs the data is able to somehow + fail over from one cache to another.) The single persistent backend + store then provides a backup copy of the data in case all caches in + the cluster fail or need to be restarted. + </para> + <para> + Note that here it may make sense for the cache loader to store + changes asynchronously, that is + <emphasis>not</emphasis> + on the caller's thread, in order not to slow + down the cluster by accessing (for example) a database. This is a + non-issue when using asynchronous replication. + </para> + <para> + A weakness with this architecture is that the cache with access + to the cache loader becomes a single point of failure. Furthermore, + if the cluster is restarted, the cache with the cache loader must + be started first (easy to forget). A solution to the first problem + is to configure a cache loader on each node, but set the + <literal>singletonStore</literal> + configuration to + <literal>true</literal>. With this kind of setup, one but only one + node will always be writing to a persistent store. However, this + complicates the restart problem, as before restarting you need + to determine which cache was writing before the shutdown/failure + and then start that cache first. + </para> + </section> - <section> - <title>Replicated Caches With Each Cache Having Its Own Store</title> + <section> + <title>Replicated Caches With Each Cache Having Its Own Store</title> - <figure> - <title>2 nodes each having its own backend store</title> + <figure> + <title>2 nodes each having its own backend store</title> - <mediaobject> - <imageobject> - <imagedata fileref="LocalCacheLoader.png"/> - </imageobject> - </mediaobject> - </figure> + <mediaobject> + <imageobject> + <imagedata fileref="LocalCacheLoader.png"/> + </imageobject> + </mediaobject> + </figure> - <para>Here, each node has its own datastore. Modifications to the - cache are (a) replicated across the cluster and (b) persisted using - the cache loader. This means that all datastores have exactly the same - state. When replicating changes synchronously and in a transaction, - the two phase commit protocol takes care that all modifications are - replicated and persisted in each datastore, or none is replicated and - persisted (atomic updates). - </para> + <para>Here, each node has its own datastore. Modifications to the + cache are (a) replicated across the cluster and (b) persisted using + the cache loader. This means that all datastores have exactly the same + state. When replicating changes synchronously and in a transaction, + the two phase commit protocol takes care that all modifications are + replicated and persisted in each datastore, or none is replicated and + persisted (atomic updates). + </para> - <para>Note that JBoss Cache is - <emphasis>not</emphasis> - an - XA Resource, that means it doesn't implement recovery. When used with a - transaction manager that supports recovery, this functionality is not - available. - </para> + <para>Note that JBoss Cache is + <emphasis>not</emphasis> + an + XA Resource, that means it doesn't implement recovery. When used with a + transaction manager that supports recovery, this functionality is not + available. + </para> - <para>The challenge here is state transfer: when a new node starts it - needs to do the following: - </para> + <para>The challenge here is state transfer: when a new node starts it + needs to do the following: + </para> - <orderedlist> - <listitem> - <para>Tell the coordinator (oldest node in a cluster) to send it - the state. This is always a full state transfer, overwriting - any state that may already be present. - </para> - </listitem> + <orderedlist> + <listitem> + <para>Tell the coordinator (oldest node in a cluster) to send it + the state. This is always a full state transfer, overwriting + any state that may already be present. + </para> + </listitem> - <listitem> - <para>The coordinator then needs to wait until all in-flight - transactions have completed. During this time, it will not allow - for new transactions to be started. - </para> - </listitem> + <listitem> + <para>The coordinator then needs to wait until all in-flight + transactions have completed. During this time, it will not allow + for new transactions to be started. + </para> + </listitem> - <listitem> - <para>Then the coordinator asks its cache loader for the entire - state using - <literal>loadEntireState()</literal> - . It then sends - back that state to the new node. - </para> - </listitem> + <listitem> + <para>Then the coordinator asks its cache loader for the entire + state using + <literal>loadEntireState()</literal> + . It then sends + back that state to the new node. + </para> + </listitem> - <listitem> - <para>The new node then tells its cache loader to store that state - in its store, overwriting the old state. This is the - <literal>CacheLoader.storeEntireState()</literal> - method - </para> - </listitem> + <listitem> + <para>The new node then tells its cache loader to store that state + in its store, overwriting the old state. This is the + <literal>CacheLoader.storeEntireState()</literal> + method + </para> + </listitem> - <listitem> - <para>As an option, the transient (in-memory) state can be - transferred as well during the state transfer. - </para> - </listitem> + <listitem> + <para>As an option, the transient (in-memory) state can be + transferred as well during the state transfer. + </para> + </listitem> - <listitem> - <para>The new node now has the same state in its backend store as - everyone else in the cluster, and modifications received from - other nodes will now be persisted using the local - cache loader. - </para> - </listitem> - </orderedlist> + <listitem> + <para>The new node now has the same state in its backend store as + everyone else in the cluster, and modifications received from + other nodes will now be persisted using the local + cache loader. + </para> + </listitem> + </orderedlist> - </section> + </section> - <section> - <title>Hierarchical Caches</title> + <section> + <title>Hierarchical Caches</title> - <para>If you need to set up a hierarchy within a single JVM, you can - use the - <literal>LocalDelegatingCacheLoader</literal> - . This type of - hierarchy can currently only be set up programmatically. - </para> + <para>If you need to set up a hierarchy within a single JVM, you can + use the + <literal>LocalDelegatingCacheLoader</literal> + . This type of + hierarchy can currently only be set up programmatically. + </para> - <para> - Hierarchical caches could also be set up spanning more than one JVM or server, using the - <literal>TcpDelegatingCacheLoader</literal> - . - <figure> - <title>TCP delegating cache loader</title> + <para> + Hierarchical caches could also be set up spanning more than one JVM or server, using the + <literal>TcpDelegatingCacheLoader</literal> + . + <figure> + <title>TCP delegating cache loader</title> - <mediaobject> - <imageobject> - <imagedata fileref="DelegatingCacheLoader.png"/> - </imageobject> - </mediaobject> - </figure> + <mediaobject> + <imageobject> + <imagedata fileref="DelegatingCacheLoader.png"/> + </imageobject> + </mediaobject> + </figure> - </para> + </para> - </section> + </section> - <section> - <title>Multiple Cache Loaders</title> + <section> + <title>Multiple Cache Loaders</title> - <para> - You can set up more than one cache loader in a chain. Internally, a delegating - <literal>ChainingCacheLoader</literal> - is used, with references to each - cache loader you have configured. Use cases vary depending on the type of cache loaders used in the chain. - One example is - using a filesystem based cache loader, co-located on the same host as the JVM, used as an overflow for - memory. This ensures - data is available relatively easily and with low cost. An additional remote cache loader, such as a - <literal>TcpDelegatingCacheLoader</literal> - provides resilience between server restarts. - </para> + <para> + You can set up more than one cache loader in a chain. Internally, a delegating + <literal>ChainingCacheLoader</literal> + is used, with references to each + cache loader you have configured. Use cases vary depending on the type of cache loaders used in the + chain. + One example is + using a filesystem based cache loader, co-located on the same host as the JVM, used as an overflow for + memory. This ensures + data is available relatively easily and with low cost. An additional remote cache loader, such as a + <literal>TcpDelegatingCacheLoader</literal> + provides resilience between server restarts. + </para> - <figure> - <title>Multiple cache loaders in a chain</title> + <figure> + <title>Multiple cache loaders in a chain</title> - <mediaobject> - <imageobject> - <imagedata fileref="MultipleCacheLoaders.png"/> - </imageobject> - </mediaobject> - </figure> + <mediaobject> + <imageobject> + <imagedata fileref="MultipleCacheLoaders.png"/> + </imageobject> + </mediaobject> + </figure> - </section> + </section> - </section> + </section> </chapter> Modified: core/trunk/src/main/resources/config-samples/all.xml =================================================================== --- core/trunk/src/main/resources/config-samples/all.xml 2009-01-05 17:54:59 UTC (rev 7380) +++ core/trunk/src/main/resources/config-samples/all.xml 2009-01-06 11:08:41 UTC (rev 7381) @@ -181,9 +181,9 @@ cache.jdbc.table.drop=true cache.jdbc.table.primarykey=jbosscache_pk cache.jdbc.fqn.column=fqn - cache.jdbc.fqn.type=varchar(255) + cache.jdbc.fqn.type=VARCHAR(255) cache.jdbc.node.column=node - cache.jdbc.node.type=blob + cache.jdbc.node.type=BINARY cache.jdbc.parent.column=parent cache.jdbc.driver=org.hsqldb.jdbcDriver cache.jdbc.url=jdbc:hsqldb:mem:jbosscache Modified: core/trunk/src/main/resources/config-samples/cacheloader-enabled.xml =================================================================== --- core/trunk/src/main/resources/config-samples/cacheloader-enabled.xml 2009-01-05 17:54:59 UTC (rev 7380) +++ core/trunk/src/main/resources/config-samples/cacheloader-enabled.xml 2009-01-06 11:08:41 UTC (rev 7381) @@ -39,9 +39,9 @@ cache.jdbc.table.drop=true cache.jdbc.table.primarykey=jbosscache_pk cache.jdbc.fqn.column=fqn - cache.jdbc.fqn.type=varchar(255) + cache.jdbc.fqn.type=VARCHAR(255) cache.jdbc.node.column=node - cache.jdbc.node.type=blob + cache.jdbc.node.type=BINARY cache.jdbc.parent.column=parent cache.jdbc.driver=org.hsqldb.jdbcDriver cache.jdbc.url=jdbc:hsqldb:mem:jbosscache Modified: core/trunk/src/test/java/org/jboss/cache/config/parsing/SampleConfigFilesCorrectnessTest.java =================================================================== --- core/trunk/src/test/java/org/jboss/cache/config/parsing/SampleConfigFilesCorrectnessTest.java 2009-01-05 17:54:59 UTC (rev 7380) +++ core/trunk/src/test/java/org/jboss/cache/config/parsing/SampleConfigFilesCorrectnessTest.java 2009-01-06 11:08:41 UTC (rev 7381) @@ -21,6 +21,8 @@ */ package org.jboss.cache.config.parsing; +import org.apache.commons.logging.Log; +import org.apache.commons.logging.LogFactory; import org.apache.log4j.AppenderSkeleton; import org.apache.log4j.Level; import org.apache.log4j.Logger; @@ -50,6 +52,7 @@ private InMemoryAppender appender; private Level oldLevel; + private Log log = LogFactory.getLog(SampleConfigFilesCorrectnessTest.class); @BeforeMethod public void setUpTest() @@ -112,13 +115,14 @@ private static class InMemoryAppender extends AppenderSkeleton { - String[] TOLERABLE_WARNINGS = {"Falling back to DummyTransactionManager"}; + String[] TOLERABLE_WARNINGS = {"DummyTransactionManager"}; boolean foundUnknownWarning = false; /** * As this test runs in parallel with other tests tha also log information, we should disregard * other possible warnings from other threads and only consider warnings issues within this test class's test. - * @see #isExpectedThread() + * + * @see #isExpectedThread() */ private Thread loggerThread = Thread.currentThread(); @@ -136,6 +140,8 @@ foundUnknownWarning = false; } } + + if (!skipPrinting) System.out.println("****** " + event.getMessage().toString()); } }