The CacheLoader is configured as follows in the JBossCache XML file:
<!-- ==================================================================== -->
<!-- Defines TreeCache configuration -->
<!-- ==================================================================== -->
<mbean code="org.jboss.cache.TreeCache" name="jboss.cache:service=TreeCache">
<!-- New 1.3.x 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>
<!-- same as the old CacheLoaderConfig attribute -->
<properties>
cache.jdbc.driver=com.mysql.jdbc.Driver
cache.jdbc.url=jdbc:mysql://localhost:3306/jbossdb
cache.jdbc.user=root
cache.jdbc.password=
</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>
</cacheloader>
</config>
</attribute>
</mbean>
Note: In JBossCache releases prior to 1.3.0, the cache loader configuration block used to look like this. Note that this form is DEPRECATED and you will have to replace your cache loader configuration with a block similar to the one above.
<!-- ==================================================================== -->
<!-- Defines TreeCache configuration -->
<!-- ==================================================================== -->
<mbean code="org.jboss.cache.TreeCache" name="jboss.cache:service=TreeCache">
<attribute name="CacheLoaderClass">org.jboss.cache.loader.bdbje.BdbjeCacheLoader
</attribute>
<!-- attribute name="CacheLoaderClass">org.jboss.cache.loader.FileCacheLoader
</attribute -->
<attribute name="CacheLoaderConfig" replace="false">
location=c:\\tmp\\bdbje
</attribute>
<attribute name="CacheLoaderShared">true</attribute>
<attribute name="CacheLoaderPreload">/</attribute>
<attribute name="CacheLoaderFetchTransientState">false</attribute>
<attribute name="CacheLoaderFetchPersistentState">true</attribute>
<attribute name="CacheLoaderAsynchronous">true</attribute>
</mbean>
The CacheLoaderClass attribute defines the class of the CacheLoader implementation. (Note that, because of a bug in the properties editor in JBoss, backslashes in variables for Windows filenames might not get expanded correctly, so replace="false" may be necessary).
The currently available implementations shipped with JBossCache are:
FileCacheLoader, which is a simple filesystem-based implementation. The <cacheloader><properties> element needs to contain a "location" property, which maps to a directory where the file is located (e.g., "location=c:\\tmp").
BdbjeCacheLoader, which is a CacheLoader implementation based on the Sleepycat DB Java Edition. The <cacheloader><properties> element needs to contain a "location" property, which maps to a directory,where the database file for Sleepycat resides (e.g., "location=c:\\tmp").
JDBCCacheLoader, which is a CacheLoader implementation using JDBC to access any relational database. The <cacheloader><properties> element contains a number of properties needed to connect to the database such as username, password, and connection URL. See the section on JDBCCacheLoader for more details.
LocalDelegatingCacheLoader, which enables loading from and storing to another local (same VM) TreeCache.
TcpDelegatingCacheLoader, which enables loading from and storing to a remote (different VM) TreeCache using TCP as the transport mechanism. This CacheLoader is available in JBossCache version 1.3.0 and above.
ClusteredCacheLoader, 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 not 'stored' though, as replication would take care of any updates needed. You need to specify a property called "timeout", a long value telling the cache loader how many milliseconds to wait for responses from the cluster before assuming a null value. For example, "timeout = 3000" would use a timeout value of 3 seconds. This CacheLoader is available in JBossCache version 1.3.0 and above.
Note that the Sleepycat 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.sleepycat.com/jeforjbosscache for details).
An implementation of CacheLoader has to have an empty constructor due to the way it is instantiated.
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 CacheLoader implementation via CacheLoader.setConfig(Properties). Note that backspaces may have to be escaped. Analogous to the CacheLoaderConfig attribute in pre-1.3.0 configurations.
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. Note that preloading loads all nodes and associated attributes from the given node, recursively up to the root node. Analogous to the CacheLoaderPreload attribute in pre-1.3.0 configurations.
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. Analogous to the CacheLoaderFetchPersistentState attribute in pre-1.3.0 configurations.
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 org.jboss.cache.loader.AsyncCacheLoader for more details. If unspecified, the async element defaults to false. Analogous to the CacheLoaderAsynchronous attribute in pre-1.3.0 configurations.
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 JDBC cache loader used by all servers in the network. This feature allows you to write to the 'local' file cache loader but not the shared JDBC cache loader. 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.