Configuration changes in JBoss Cache 3

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
  

Migration old files to new format

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'

<transaction transactionManagerLookupClass="org.jboss.cache.transaction.GenericTransactionManagerLookup"/>

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.

<transport clusterName="JBossCache-Cluster"/>

specifies the JGroups cluster name and also uses the default JGroups configuration for transport.

<replication>
<sync replTimeout="15000"/>
<buddy enabled="true" poolName="myBuddyPoolReplicationGroup" communicationTimeout="2000">
   <dataGravitation auto="false" removeOnFind="true" searchBackupTrees="true"/>
   <locator class="org.jboss.cache.buddyreplication.NextMemberBuddyLocator">
      <properties>
         numBuddies = 1
         ignoreColocatedBuddies = true
      </properties>
   </locator>
</buddy>
</replication>

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:

<invalidation>
<async useReplQueue="false"/>
</invalidation>

If you want to use a local cache, you can do that by not specifying neither an 'replication' nor an 'invalidation' element.

<startup regionsInactiveOnStartup=”true”/>

the regions will not be active when the cache starts, so it will not respond to replication messages.

<serialization useRegionBasedMarshalling="true"/>

Tells the cache to use different cache loaders for different regions, when (de)serializing data.

<jmxStatistics enabled='true'/>

tells the cache to gather usage information and expose it as JMX statistics

<eviction wakeUpInterval="5000" defaultPolicyClass="org.jboss.cache.eviction.LRUPolicy" defaultEventQueueSize="200000">
<default>
   <attribute name="maxNodes">5000</attribute>
   <attribute name="timeToLiveSeconds">1000</attribute>
</default>
<region name="/org/jboss/data">
   <attribute name="maxNodes">5000</attribute>
   <attribute name="timeToLiveSeconds">1000</attribute>
</region>
</eviction>

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">
<preload>
   <node fqn="/"/>
</preload>
<!-- if passivation is true, only the first cache loader is used; the rest are ignored -->
<loader class="org.jboss.cache.loader.JDBCCacheLoader" async="false" fetchPersistentState="true"
   ignoreModifications="false" purgeOnStartup="false">
   <properties>
      cache.jdbc.table.name=jbosscache
      cache.jdbc.table.create=true
      cache.jdbc.table.drop=true
      cache.jdbc.table.primarykey=jbosscache_pk
      ...
   </properties>
</loader>
</loaders>

This is an cache loader configuration for a shared JDBCCacheLoader, no passivation. The root node will be preloaded on startup, specified through 'preload' element.

<customInterceptors>
<interceptor position="first" class="org.jboss.cache.sample.AaaCustomInterceptor">
   <attribute name="attrOne">value1</attribute>
   <attribute name="attrTwo">value2</attribute>
   <attribute name="attrThree">value3</attribute>
</interceptor>
</customInterceptors>

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