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 ignoreModifications element has been set to true for a specific cache loader. See the configuration section below for details.

...



<!-- Cache loader config block -->

<attribute name="CacheLoaderConfiguration">

   <config>

      <!-- if passivation is true, only the first cache loader is used; the rest are ignored -->

      <passivation>false</passivation>

      <!-- comma delimited FQNs to preload -->

      <preload>/</preload>

      <!-- are the cache loaders shared in a cluster? -->

      <shared>false</shared>



      <!-- we can now have multiple cache loaders, which get chained -->

      <!-- the 'cacheloader' element may be repeated -->

      <cacheloader>



         <class>org.jboss.cache.loader.JDBCCacheLoader</class>



         <!-- properties to pass in to the cache loader -->

         <properties>

            cache.jdbc.driver=com.mysql.jdbc.Driver

            cache.jdbc.url=jdbc:mysql://localhost:3306/jbossdb

            cache.jdbc.user=root

            cache.jdbc.password=

            cache.jdbc.sql-concat=concat(1,2)

         </properties>



         <!-- whether the cache loader writes are asynchronous -->

         <async>false</async>



         <!-- only one cache loader in the chain may set fetchPersistentState to true.

              An exception is thrown if more than one cache loader sets this to true. -->

         <fetchPersistentState>true</fetchPersistentState>



         <!-- determines whether this cache loader ignores writes - defaults to false. -->

         <ignoreModifications>false</ignoreModifications>



         <!-- if set to true, purges the contents of this cache loader when the cache starts up.

              Defaults to false. -->

         <purgeOnStartup>false</purgeOnStartup>



         <!-- defines the cache loader as a singleton store where only the coordinator of the

              cluster will store modifications. -->

         <singletonStore>

            <!-- if true, singleton store functionality is enabled, defaults to false -->

            <enabled>false</enabled>



            <!-- implementation class for singleton store functionality which must extend

                 org.jboss.cache.loader.AbstractDelegatingCacheLoader. Default implementation

                 is org.jboss.cache.loader.SingletonStoreCacheLoader -->

            <class>org.jboss.cache.loader.SingletonStoreCacheLoader</class>



            <!-- properties and default values for the default singleton store functionality

                 implementation -->

            <properties>

               pushStateWhenCoordinator=true

               pushStateWhenCoordinatorTimeout=20000

            </properties>

         </singletonStore>

      </cacheloader>



   </config>

</attribute>

The class 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.

The properties 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 CacheLoader.setConfig(Properties) . Note that backspaces may have to be escaped.

preload 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, /a, /product/catalogue loads the subtrees /a and /product/catalogue 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. .

fetchPersistentState 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.

async 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 org.jboss.cache.loader.AsyncCacheLoader is constructed with an instance of the actual cache loader to be used. The AsyncCacheLoader then delegates all requests to the underlying cache loader, using a separate thread if necessary. See the Javadocs on AsyncCacheLoader for more details. If unspecified, the async element defaults to false .

Note on using the async element: 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 async element to true.

ignoreModifications 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 JDBCCacheLoader used by all servers in the network. This feature allows you to write to the 'local' file cache loader but not the shared JDBCCacheLoader . This property defaults to false , so writes are propagated to all cache loaders configured.

purgeOnStatup empties the specified cache loader (if ignoreModifications is false ) when the cache loader starts up.

shared 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 true prevents repeated and unnecessary writes of the same data to the cache loader by different cache instances. Default value is false .