JBoss Cache 3 comes with a new, improved layout of the .xml configuration file. Certain constraints were dropped (e.g. explicit mbean support from xml file), so we took a step forward an refactored the entire configuration to be more readable, concise and consistent.
Summary of changes
- new elements were created to gather related configurations; many of the 2.x configuration elements are attributes of these new elements
- xml schema file is shipped now to verify configuration correctness. Schema can also be used with editing tools and IDEs to make it simpler to write configuration files. The parser was also updated to validate against this XSD (validation errors are being reported in the logs)
- we supply tools for converting from an old XML file format to the new one, so that one does not have to migrate the scripts by hand
- we kept the old parser, so old style configuration files are perfectly supported (not recommended though, as there you cannot specify features like MVCC and custom interceptors)
- Configuration API is unchanged, so if you used programmatic configuration in your code it will work just fine
- all the time related configurations are now in milliseconds (old eviction configurations elements were in seconds). The XSLT script that transforms from old configuration file to new one know how to transform seconds to milliseconds, when necessary.
- it is possible to configure custom interceptors declaratively, in the configuration file
The distribution comes with scripts that will automatically handle the transformation. You can find them in 'DISTR_ROOT/resources/config-samples/config2to3.sh'
and equivalent script for DOS. Executing the script will provide usage and help.
More on the new elements...
The distributions comes with several sample configuration files (DISTR_ROOT/resources/config-samples) which are a good start if you need to write your own, customized configuration.
Below are snapshots from the new configuration file, followed by a description of their meaning.
<locking isolationLevel="REPEATABLE_READ" lockAcquisitionTimeout="10000" nodeLockingScheme="mvcc"/>
the cache will use an mvcc locking scheme (other possible values are 'pessimistic' and 'optimistic' with isolation level set to 'REPEATABLE_READ'
specify a lookup class for the transaction manager.
<stateRetrieval timeout="20000" fetchInMemoryState="true"/>
This instance will retrieve state from other existing instance, having the given timeout.
specifies the JGroups cluster name and also uses the default JGroups configuration for transport.
<buddy enabled="true" poolName="myBuddyPoolReplicationGroup" communicationTimeout="2000">
<dataGravitation auto="false" removeOnFind="true" searchBackupTrees="true"/>
numBuddies = 1
ignoreColocatedBuddies = true
This is a synchronously replicated cache using buddy replication.
For using the cache in asynchronous invalidation mode that does not use replication queues, following configuration might be used:
If you want to use a local cache, you can do that by not specifying neither an 'replication' nor an 'invalidation' element.
the regions will not be active when the cache starts, so it will not respond to replication messages.
Tells the cache to use different cache loaders for different regions, when (de)serializing data.
tells the cache to gather usage information and expose it as JMX statistics
<eviction wakeUpInterval="5000" defaultPolicyClass="org.jboss.cache.eviction.LRUPolicy" defaultEventQueueSize="200000">
This is an eviction configuration. Default policy and queue size (attributes of 'eviction' element) allows defining defaults value for subsequent regions. Also, the 'default' element defines cache wide eviction strategy, overridden on an region bases by following 'region' elements.
<loaders passivation="false" shared="true">
<!-- if passivation is true, only the first cache loader is used; the rest are ignored -->
<loader class="org.jboss.cache.loader.JDBCCacheLoader" async="false" fetchPersistentState="true"
This is an cache loader configuration for a shared JDBCCacheLoader, no passivation. The root node will be preloaded on startup, specified through 'preload' element.
<interceptor position="first" class="org.jboss.cache.sample.AaaCustomInterceptor">
This configures the addition of a custom interceptor to the interceptor chain, after the default interceptor chain for the current configuration is built. The custom interceptor must have setters corresponding to 'attrOne', 'attrTwo' and 'attrThree', must implement org.jboss.cache.interceptors.base.CommandInterceptor, must have an default constructor. Its location in the chain will be determined by the value of the "position" attribute".