JBoss.orgCommunity Documentation

Chapter 12. Configuration References

12.1. Sample XML Configuration File
12.1.1. XML validation
12.2. Configuration File Quick Reference

This is what a typical XML configuration file looks like. It is recommended that you use one of the configurations shipped with the JBoss Cache distribution and tweak according to your needs rather than write one from scratch.

<?xml version="1.0" encoding="UTF-8"?>

<jbosscache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:jboss:jbosscache-core:config:3.1">

      isolation levels supported: READ_COMMITTED and REPEATABLE_READ
      nodeLockingSchemes: mvcc, pessimistic (deprecated), optimistic (deprecated)

      Used to register a transaction manager and participate in ongoing transactions.

      Used to register JMX statistics in any available MBean server

      If region based marshalling is used, defines whether new regions are inactive on startup.

      Used to register JVM shutdown hooks.

      Used to define async listener notification thread pool size

      Used to enable invocation batching and allow the use of Cache.startBatch()/endBatch() methods.

      serialization related configuration, used for replication and cache loading

      This element specifies that the cache is clustered.
      modes supported: replication (r) or invalidation (i).
   <clustering mode="replication" clusterName="JBossCache-cluster">

         Defines whether to retrieve state on startup
      <stateRetrieval timeout="20000" fetchInMemoryState="false"/>

         Network calls are synchronous.
      <sync replTimeout="20000"/>
         Uncomment this for async replication.
      <!--<async useReplQueue="true" replQueueInterval="10000" replQueueMaxElements="500" serializationExecutorPoolSize="20" serializationExecutorQueueSize="5000000"/>-->

      <!-- Uncomment to use Buddy Replication -->
      <buddy enabled="true" poolName="myBuddyPoolReplicationGroup" communicationTimeout="2000">
         <dataGravitation auto="true" removeOnFind="true" searchBackupTrees="true"/>
         <locator class="org.jboss.cache.buddyreplication.NextMemberBuddyLocator">
               numBuddies = 1
               ignoreColocatedBuddies = true

         Configures the JGroups channel.  Looks up a JGroups config file on the classpath or filesystem.  udp.xml
         ships with jgroups.jar and will be picked up by the class loader.
      <jgroupsConfig configFile="udp.xml">
         <!-- uncomment to define a JGroups stack here

         <PING timeout="2000" num_initial_members="3"/>
         <MERGE2 max_interval="30000" min_interval="10000"/>
         <FD timeout="10000" max_tries="5" shun="true"/>
         <VERIFY_SUSPECT timeout="1500"/>
         <pbcast.NAKACK use_mcast_xmit="false" gc_lag="0"
         <UNICAST timeout="300,600,1200,2400,3600"/>
         <pbcast.STABLE stability_delay="1000" desired_avg_gossip="50000"
         <pbcast.GMS print_local_addr="true" join_timeout="5000" shun="false"
                     view_bundling="true" view_ack_collection_timeout="5000"/>
         <FRAG2 frag_size="60000"/>
         <pbcast.STREAMING_STATE_TRANSFER use_reading_thread="true"/>
         <pbcast.FLUSH timeout="0"/>

      Eviction configuration.  WakeupInterval defines how often the eviction thread runs, in milliseconds.  0 means
      the eviction thread will never run.
   <eviction wakeUpInterval="500">
      <default algorithmClass="org.jboss.cache.eviction.LRUAlgorithm" eventQueueSize="200000">
         <property name="maxNodes" value="5000" />
         <property name="timeToLive" value="1000" />
      <region name="/org/jboss/data1">
         <property name="timeToLive" value="2000" />
      <region name="/org/jboss/data2" algorithmClass="org.jboss.cache.eviction.FIFOAlgorithm" eventQueueSize="100000">
         <property name="maxNodes" value="3000" />
         <property name="minTimeToLive" value="4000" />

      Cache loaders.

      If passivation is enabled, state is offloaded to the cache loaders ONLY when evicted.  Similarly, when the state
      is accessed again, it is removed from the cache loader and loaded into memory.

      Otherwise, state is always maintained in the cache loader as well as in memory.

      Set 'shared' to true if all instances in the cluster use the same cache loader instance, e.g., are talking to the
      same database.
   <loaders passivation="false" shared="false">
         <node fqn="/org/jboss"/>
         <node fqn="/org/tempdata"/>

         we can have multiple cache loaders, which get chained
      <loader class="org.jboss.cache.loader.JDBCCacheLoader" async="true" fetchPersistentState="true"
              ignoreModifications="true" purgeOnStartup="true">
         <singletonStore enabled="true" class="org.jboss.cache.loader.SingletonStoreCacheLoader">

      Define custom interceptors.  All custom interceptors need to extend org.jboss.cache.interceptors.base.CommandInterceptor
      <interceptor position="first" class="org.jboss.cache.config.parsing.custominterceptors.AaaCustomInterceptor">
         <property name="attrOne" value="value1" />
         <property name="attrTwo" value="value2" />
      <interceptor position="last" class="org.jboss.cache.config.parsing.custominterceptors.BbbCustomInterceptor"/>
      <interceptor index="3" class="org.jboss.cache.config.parsing.custominterceptors.AaaCustomInterceptor"/>
      <interceptor before="org.jboss.cache.interceptors.CallInterceptor"
      <interceptor after="org.jboss.cache.interceptors.CallInterceptor"

A list of definitions of each of the XML elements attributes used above, and their bean counterparts for programmatic configuration. If the description of an attribute states that it is dynamic, that means it can be changed after the cache is created and started.

Table 12.4. <locking /> Attributes

<locking /> Attributes
AttributeBean FieldAllowedDefaultDescription
isolationLevelisolationLevelREAD_COMMITTED, REPEATABLE_READREPEATABLE_READThe isolation level used for transactions.
lockParentForChildInsertRemovelockParentForChildInsertRemovetrue, falsefalseSpecifies whether parent nodes are locked when inserting or removing children. This can also be configured on a per-node basis (see Node.setLockForChildInsertRemove()
lockAcquisitionTimeoutlockAcquisitionTimeout (dynamic)Any positive long value10000Length of time, in milliseconds, that a thread will try and acquire a lock. A TimeoutException is usually thrown if a lock cannot be acquired in this given timeframe. Can be overridden on a per-invocation basis using Option.setLockAcquisitionTimeout()
nodeLockingScheme (deprecated)nodeLockingSchememvcc, pessimistic, optimisticmvccSpecifies the node locking scheme to be used.
writeSkewCheckwriteSkewChecktrue, falsefalseSpecifies whether to check for write skews. Only used if nodeLockingScheme is mvcc and isolationLevel is REPEATABLE_READ. See the section on write skews for a more detailed discussion.
useLockStripinguseLockStripingtrue, falsetrueSpecifies whether lock striping is used. Only used if nodeLockingScheme is mvcc. Lock striping usually offers greater performance and better memory usage, although in certain cases deadlocks may occur where several Fqns map to the same shared lock. This can be mitigated by increasing your concurrency level, though the only concrete solution is to disable lock striping altogether.
concurrencyLevelconcurrencyLevelAny positive integer; 0 not allowed.500Specifies the number of shared locks to use for write locks acquired. Only used if nodeLockingScheme is mvcc. See the section on JBoss Cache's MVCC implementation for a more detailed discussion.