Chapter 12. Configuration References

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





   <!--

      isolation levels supported: READ_COMMITTED and REPEATABLE_READ

      nodeLockingSchemes: mvcc, pessimistic (deprecated), optimistic (deprecated)

   -->

   <locking

         isolationLevel="REPEATABLE_READ"

         lockParentForChildInsertRemove="false"

         lockAcquisitionTimeout="20000"

         nodeLockingScheme="mvcc"

         writeSkewCheck="false"

         useLockStriping="true"

         concurrencyLevel="500"/>



   <!--

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

      -->

   <transaction

         transactionManagerLookupClass="org.jboss.cache.transaction.GenericTransactionManagerLookup"

         syncRollbackPhase="false"

         syncCommitPhase="false"/>



   <!--

      Used to register JMX statistics in any available MBean server

      -->

   <jmxStatistics

         enabled="false"/>



   <!--

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

   -->

   <startup

         regionsInactiveOnStartup="true"/>



   <!--

      Used to register JVM shutdown hooks.

      hookBehavior: DEFAULT, REGISTER, DONT_REGISTER

   -->

   <shutdown

         hookBehavior="DEFAULT"/>



   <!--

      Used to define async listener notification thread pool size

   -->

   <listeners

         asyncPoolSize="1"

         asyncQueueSize="100000"/>



   <!--

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

   -->

   <invocationBatching

         enabled="false"/>



   <!--

      serialization related configuration, used for replication and cache loading

   -->

   <serialization

         objectInputStreamPoolSize="12"

         objectOutputStreamPoolSize="14"

         version="3.0.0"

         marshallerClass="org.jboss.cache.marshall.VersionAwareMarshaller"

         useLazyDeserialization="false"

         useRegionBasedMarshalling="false"/>



   <!--

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

            <properties>

               numBuddies = 1

               ignoreColocatedBuddies = true

            </properties>

         </locator>

      </buddy>

      -->



      <!--

         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_SOCK/>

         <FD timeout="10000" max_tries="5" shun="true"/>

         <VERIFY_SUSPECT timeout="1500"/>

         <pbcast.NAKACK use_mcast_xmit="false" gc_lag="0"

                        retransmit_timeout="300,600,1200,2400,4800"

                        discard_delivered_msgs="true"/>

         <UNICAST timeout="300,600,1200,2400,3600"/>

         <pbcast.STABLE stability_delay="1000" desired_avg_gossip="50000"

                        max_bytes="400000"/>

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

          -->

      </jgroupsConfig>

   </clustering>



   <!--

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

      </default>

      <region name="/org/jboss/data1">

         <property name="timeToLive" value="2000" />

      </region>

      <region name="/org/jboss/data2" algorithmClass="org.jboss.cache.eviction.FIFOAlgorithm" eventQueueSize="100000">

         <property name="maxNodes" value="3000" />

         <property name="minTimeToLive" value="4000" />

      </region>

   </eviction>



   <!--

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

      <preload>

         <node fqn="/org/jboss"/>

         <node fqn="/org/tempdata"/>

      </preload>



      <!--

         we can have multiple cache loaders, which get chained

      -->

      <loader class="org.jboss.cache.loader.JDBCCacheLoader" async="true" fetchPersistentState="true"

              ignoreModifications="true" purgeOnStartup="true">

         <properties>

            cache.jdbc.table.name=jbosscache

            cache.jdbc.table.create=true

            cache.jdbc.table.drop=true

         </properties>

         <singletonStore enabled="true" class="org.jboss.cache.loader.SingletonStoreCacheLoader">

            <properties>

               pushStateWhenCoordinator=true

               pushStateWhenCoordinatorTimeout=20000

            </properties>

         </singletonStore>

      </loader>

   </loaders>



   <!--

      Define custom interceptors.  All custom interceptors need to extend org.jboss.cache.interceptors.base.CommandInterceptor

   -->

   <!--

   <customInterceptors>

      <interceptor position="first" class="org.jboss.cache.config.parsing.custominterceptors.AaaCustomInterceptor">

         <property name="attrOne" value="value1" />

         <property name="attrTwo" value="value2" />

      </interceptor>

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

                   class="org.jboss.cache.config.parsing.custominterceptors.BbbCustomInterceptor"/>

      <interceptor after="org.jboss.cache.interceptors.CallInterceptor"

                   class="org.jboss.cache.config.parsing.custominterceptors.AaaCustomInterceptor"/>

   </customInterceptors>

   -->

</jbosscache>

12.1.1. XML validation

Configuration XML files are validated using an XSD schema. This schema is included in jbosscache-core.jar and is also available online: http://www.jboss.org/jbosscache/jbosscache-config-3.0.xsd. Most IDEs and XML authoring tools will be able to use this schema to validate your configuration file as you write it.

JBoss Cache also validates your configuration file when you start up, and will throw an exception if it encounters an invalid file. You can suppress this behavior by passing in -Djbosscache.config.validate=false to your JVM when you start up. Alternatively, you can point the validator to a different schema by passing in -Djbosscache.config.schemaLocation=url.

12.2. Configuration File Quick Reference

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.1. The <jbosscache /> Element

The `<jbosscache />` Element
Description	This is the root element for the JBoss Cache configuration file. This is the only mandatory element in a valid JBoss Cache configuration file.
Parent	none (is root element)
Children	`<clustering />`, `<customInterceptors />`, `<eviction />`, `<invocationBatching />`, `<jmxStatistics />`, `<listeners />`, `<loaders />`, `<locking />`, `<serialization />`, `<shutdown />`, `<startup />`, `<transaction />`
Bean Equivalent	`Configuration`

Table 12.2. <jbosscache /> Attributes

`<jbosscache />` Attributes
Attribute	Bean Field	Allowed	Default	Description
xmlns	-	urn:jboss:jbosscache-core:config:3.2	urn:jboss:jbosscache-core:config:3.2	Defines the XML namespace for all configuration entries.
xmlns:xsi	-	http://www.w3.org/2001/XMLSchema-instance	http://www.w3.org/2001/XMLSchema-instance	Defines the XML schema instance for the configuration.

Table 12.3. The <locking /> Element

The `<locking />` Element
Description	This element specifies locking behavior on the cache.
Parent	`<jbosscache />`
Children
Bean equivalent	`Configuration`

Table 12.4. <locking /> Attributes

`<locking />` Attributes
Attribute	Bean Field	Allowed	Default	Description
isolationLevel	isolationLevel	READ_COMMITTED, REPEATABLE_READ	REPEATABLE_READ	The isolation level used for transactions.
lockParentForChildInsertRemove	lockParentForChildInsertRemove	true, false	false	Specifies whether parent nodes are locked when inserting or removing children. This can also be configured on a per-node basis (see `Node.setLockForChildInsertRemove()`
lockAcquisitionTimeout	lockAcquisitionTimeout (dynamic)	Any positive long value	10000	Length 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)	nodeLockingScheme	mvcc, pessimistic, optimistic	mvcc	Specifies the node locking scheme to be used.
writeSkewCheck	writeSkewCheck	true, false	false	Specifies 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.
useLockStriping	useLockStriping	true, false	true	Specifies 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.
concurrencyLevel	concurrencyLevel	Any positive integer; 0 not allowed.	500	Specifies 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.

Table 12.5. The <transaction /> Element

The `<transaction />` Element
Description	This element specifies transactional behavior on the cache.
Parent	`<jbosscache />`
Children
Bean equivalent	`Configuration`

Table 12.6. <transaction /> Attributes

`<transaction />` Attributes
Attribute	Bean Field	Allowed	Default	Description
transactionManagerLookupClass	transactionManagerLookupClass	A valid class that is available on the classpath	none	Specifies the `TransactionManagerLookupClass` implementation to use to obtain a transaction manager. If not specified (and a `TransactionManager` is not injected using `RuntimeConfig.setTransactionManager()`, the cache will not be able to participate in any transactions.
syncCommitPhase	syncCommitPhase (dynamic)	true, false	false	If enabled, commit messages that are broadcast around a cluster are done so synchronously. This is usually of little value since detecting a failure in broadcasting a commit means little else can be done except log a message, since some nodes in a cluster may have already committed and cannot rollback.
syncRollbackPhase	syncRollbackPhase (dynamic)	true, false	false	If enabled, rollback messages that are broadcast around a cluster are done so synchronously. This is usually of little value since detecting a failure in broadcasting a rollback means little else can be done except log a message, since some nodes in a cluster may have already committed and cannot rollback.

Table 12.7. The <jmxStatistics /> Element

The `<jmxStatistics />` Element
Description	This element specifies whether cache statistics are gathered and reported via JMX.
Parent	`<jbosscache />`
Children
Bean equivalent	`Configuration`

Table 12.8. <jmxStatistics /> Attributes

`<jmxStatistics />` Attributes
Attribute	Bean Field	Allowed	Default	Description
enabled	exposeManagementStatistics	true, false	true	Controls whether cache statistics are gathered and exposed via JMX.

Table 12.9. The <startup /> Element

The `<startup />` Element
Description	This element specifies behavior when the cache starts up.
Parent	`<jbosscache />`
Children
Bean equivalent	`Configuration`

Table 12.10. <startup /> Attributes

`<startup />` Attributes
Attribute	Bean Field	Allowed	Default	Description
regionsInactiveOnStartup	inactiveOnStartup	true, false	false	If region-based marshalling is enabled, this attribute controls whether new regions created are inactive on startup.

Table 12.11. The <shutdown /> Element

The `<shutdown />` Element
Description	This element specifies behavior when the cache shuts down.
Parent	`<jbosscache />`
Children
Bean equivalent	`Configuration`

Table 12.12. <shutdown /> Attributes

`<shutdown />` Attributes
Attribute	Bean Field	Allowed	Default	Description
hookBehavior	shutdownHookBehavior	DEFAULT, DONT_REGISTER, REGISTER	DEFAULT	This attribute determines whether the cache registers a JVM shutdown hook so that it can clean up resources if the JVM is receives a shutdown signal. By default a shutdown hook is registered if no MBean server (apart from the JDK default) is detected. REGSTER forces the cache to register a shutdown hook even if an MBean server is detected, and DONT_REGISTER forces the cache NOT to register a shutdown hook, even if no MBean server is detected.

Table 12.13. The <listeners /> Element

The `<listeners />` Element
Description	This element specifies behavior of registered cache listeners.
Parent	`<jbosscache />`
Children
Bean equivalent	`Configuration`

Table 12.14. <listeners /> Attributes

`<listeners />` Attributes
Attribute	Bean Field	Allowed	Default	Description
asyncPoolSize	listenerAsyncPoolSize	integer	1	The size of the threadpool used to dispatch events to cache listeners that have registered as asynchronous listeners. If this number is less than 1, all asynchronous listeners will be treated as synchronous listeners and notified synchronously.
asyncQueueSize	listenerAsyncQueueSize	positive integer	50000	The size of the bounded queue used by the async listener threadpool. Only considered if `asyncPoolSize` is greater than 0. Increase this if you see a lot of threads blocking trying to add events to this queue.

Table 12.15. The <invocationBatching /> Element

The `<invocationBatching />` Element
Description	This element specifies behavior of invocation batching.
Parent	`<jbosscache />`
Children
Bean equivalent	`Configuration`

Table 12.16. <invocationBatching /> Attributes

`<invocationBatching />` Attributes
Attribute	Bean Field	Allowed	Default	Description
enabled	invocationBatchingEnabled	true, false	false	Whether invocation batching is enabled or not. See the chapter on invocation batching for details.

Table 12.17. The <serialization /> Element

The `<serialization />` Element
Description	This element specifies behavior of object serialization in JBoss Cache.
Parent	`<jbosscache />`
Children
Bean equivalent	`Configuration`

Table 12.18. <serialization /> Attributes

`<serialization />` Attributes
Attribute	Bean Field	Allowed	Default	Description
marshallerClass	marshallerClass	A valid class that is available on the classpath	VersionAwareMarshaller	Specifies the marshaller to use when serializing and deserializing objects, either for replication or persistence.
useLazyDeserialization	useLazyDeserialization	true, false	false	A mechanism by which serialization and deserialization of objects is deferred till the point in time in which they are used and needed. This typically means that any deserialization happens using the thread context class loader of the invocation that requires deserialization, and is an effective mechanism to provide classloader isolation.
useRegionBasedMarshalling (deprecated)	useRegionBasedMarshalling	true, false	false	An older mechanism by which classloader isolation was achieved, by registering classloaders on specific regions.
version	replicationVersion	Valid JBoss Cache version string	Current version	Used by the `VersionAwareMarshaller` in determining which version stream parser to use by default when initiating communications in a cluster. Useful when you need to run a newer version of JBoss Cache in a cluster containing older versions, and can be used to perform rolling upgrades.
objectInputStreamPoolSize	objectInputStreamPoolSize	Positive integer	50	Not used at the moment.
objectOutputStreamPoolSize	objectOutputStreamPoolSize	Positive integer	50	Not used at the moment.

Table 12.19. The <eviction /> Element

The `<eviction />` Element
Description	This element controls how eviction works in the cache.
Parent	`<jbosscache />`
Children	`<default />`, `<region />`
Bean equivalent	`EvictionConfig`

Table 12.20. <eviction /> Attributes

`<eviction />` Attributes
Attribute	Bean Field	Allowed	Default	Description
wakeUpInterval	wakeupInterval	integer	5000	The frequency with which the eviction thread runs, in milliseconds. If set to less than 1, the eviction thread never runs and is effectively disabled.

Table 12.21. The <default /> Element

The `<default />` Element
Description	This element defines the default eviction region.
Parent	`<eviction />`
Children	`<property />`
Bean equivalent	`EvictionRegionConfig`

Table 12.22. <default /> Attributes

`<default />` Attributes
Attribute	Bean Field	Allowed	Default	Description
algorithmClass	evictionAlgorithmConfig	A valid class that is available on the classpath	none	This attribute needs to be specified if this tag is being used. Note that if being configured programmatically, the eviction algorithm's corresponding `EvictionAlgorithmConfig` file should be used instead. E.g., where you would use `LRUAlgorithm` in XML, you would use an instance of `LRUAlgorithmConfig` programmatically.
actionPolicyClass	evictionActionPolicyClassName	A valid class that is available on the classpath	DefaultEvictionActionPolicy	The eviction action policy class, defining what happens when a node needs to be evicted.
eventQueueSize	eventQueueSize (dynamic	integer	200000	The size of the bounded eviction event queue.

Table 12.23. The <region /> Element

The `<region />` Element
Description	This element defines an eviction region. Multiple instances of this tag can exist provided they have unique `name` attributes.
Parent	`<eviction />`
Children	`<property />`
Bean equivalent	`EvictionRegionConfig`

Table 12.24. <region /> Attributes

`<region />` Attributes
Attribute	Bean Field	Allowed	Default	Description
name	regionFqn	A String that could be parsed using Fqn.fromString()	none	This should be a unique name that defines this region. See the chapter on eviction for details of eviction regions.
algorithmClass	evictionAlgorithmConfig	A valid class that is available on the classpath	none	This attribute needs to be specified if this tag is being used. Note that if being configured programmatically, the eviction algorithm's corresponding `EvictionAlgorithmConfig` file should be used instead. E.g., where you would use `LRUAlgorithm` in XML, you would use an instance of `LRUAlgorithmConfig` programmatically.
actionPolicyClass	evictionActionPolicyClassName	A valid class that is available on the classpath	DefaultEvictionActionPolicy	The eviction action policy class, defining what happens when a node needs to be evicted.
eventQueueSize	eventQueueSize (dynamic	integer	200000	The size of the bounded eviction event queue.

Table 12.25. The <property /> Element

The `<property />` Element
Description	A mechanism of passing in name-value properties to the enclosing configuration element.
Parent	`<default />`, `<region />`, `<interceptor />`
Children
Bean equivalent	Either direct setters or `setProperties()` enclosing bean

Table 12.26. <property /> Attributes

`<property />` Attributes
Attribute	Bean Field	Allowed	Default	Description
name	Either direct setters or `setProperties()` enclosing bean	String	none	Property name
value	Either direct setters or `setProperties()` enclosing bean	String	none	Property value

Table 12.27. The <loaders /> Element

The `<loaders />` Element
Description	Defines any cache loaders.
Parent	`<jbosscache />`
Children	`<preload />`, `<loader />`
Bean equivalent	CacheLoaderConfig

Table 12.28. <loaders /> Attributes

`<loaders />` Attributes
Attribute	Bean Field	Allowed	Default	Description
passivation	passivation	true, false	false	If true, cache loaders are used in passivation mode. See the chapter on cache loaders for a detailed discussion on this.
shared	shared	true, false	false	If true, cache loaders are used in shared mode. See the chapter on cache loaders for a detailed discussion on this.

Table 12.29. The <preload /> Element

The `<preload />` Element
Description	Defines preloading of Fqn subtrees when a cache starts up. This element has no attributes.
Parent	`<loaders />`
Children	`<node />`
Bean equivalent	CacheLoaderConfig

Table 12.30. The <node /> Element

The `<node />` Element
Description	This element defines a subtree under which all content will be preloaded from the cache loaders when the cache starts. Multiple subtrees can be preloaded, although it only makes sense to define more than one subtree if they do not overlap.
Parent	`<preload />`
Children
Bean equivalent	CacheLoaderConfig

Table 12.31. <node /> Attributes

`<node />` Attributes
Attribute	Bean Field	Allowed	Default	Description
fqn	preload	String	none	An Fqn to preload. This should be a String that can be parsed with Fqn.fromString(). When doing this programmatically, you should create a single String containing all of the Fqns you wish to preload, separated by spaces, and pass that into `CacheLoaderConfig.setPreload()`.

Table 12.32. The <loader /> Element

The `<loader />` Element
Description	This element defines a cache loader. Multiple elements may be used to create cache loader chains.
Parent	`<loaders />`
Children	`<properties />`, `<singletonStore />`
Bean equivalent	IndividualCacheLoaderConfig

Table 12.33. <loader /> Attributes

`<loader />` Attributes
Attribute	Bean Field	Allowed	Default	Description
class	className	A valid class that is available on the classpath	none	A cache loader implementation to use.
async	async	true, false	false	All modifications to this cache loader happen asynchronously, on a separate thread.
fetchPersistentState	fetchPersistentState	true, false	false	When a cache starts up, retrieve persistent state from the cache loaders in other caches in the cluster. Only one loader element may set this to true. Also, only makes sense if the `<clustering />` tag is present.
purgeOnStartup	purgeOnStartup	true, false	false	Purges this cache loader when it starts up.

Table 12.34. The <properties /> Element

The `<properties />` Element
Description	This element contains a set of properties that can be read by a `java.util.Properties` instance. This tag has no attributes, and the contents of this tag will be parsed by `Properties.load()`.
Parent	`<loader />`, `<singletonStore />`, `<locator />`
Children
Bean equivalent	IndividualCacheLoaderConfig.setProperties()

Table 12.35. The <singletonStore /> Element

The `<singletonStore />` Element
Description	This element configures the enclosing cache loader as a singleton store cache loader.
Parent	`<loader />`
Children	`<properties />`
Bean equivalent	SingletonStoreConfig

Table 12.36. <singletonStore /> Attributes

`<singletonStore />` Attributes
Attribute	Bean Field	Allowed	Default	Description
class	className	A valid class that is available on the classpath	SingletonStoreCacheLoader	A singleton store wrapper implementation to use.
enabled	enabled	true, false	false	If true, the singleton store cache loader is enabled.

Table 12.37. The <customInterceptors /> Element

The `<customInterceptors />` Element
Description	This element allows you to define custom interceptors for the cache. This tag has no attributes.
Parent	`<jbosscache />`
Children	`<interceptor />`
Bean equivalent	None. At runtime, instantiate your own interceptor and pass it in to the cache using `Cache.addInterceptor()`.

Table 12.38. The <interceptor /> Element

The `<interceptor />` Element
Description	This element allows you configure a custom interceptor. This tag may appear multiple times.
Parent	`<customInterceptor />`
Children	`<property />`
Bean equivalent	None. At runtime, instantiate your own interceptor and pass it in to the cache using `Cache.addInterceptor()`.

Table 12.39. <interceptor /> Attributes

`<interceptor />` Attributes
Attribute	Bean Field	Allowed	Default	Description
class	-	A valid class that is available on the classpath	none	An implementation of `CommandInterceptor`.
position	-	first, last		A position at which to place this interceptor in the chain. First is the first interceptor encountered when an invocation is made on the cache, last is the last interceptor before the call is passed on to the data structure. Note that this attribute is mutually exclusive with `before`, `after` and `index`.
before	-	Fully qualified class name of an interceptor		Will place the new interceptor directly before the instance of the named interceptor. Note that this attribute is mutually exclusive with `position`, `after` and `index`.
after	-	Fully qualified class name of an interceptor		Will place the new interceptor directly after the instance of the named interceptor. Note that this attribute is mutually exclusive with `position`, `before` and `index`.
index	-	Positive integers		A position at which to place this interceptor in the chain, with 0 being the first position. Note that this attribute is mutually exclusive with `position`, `before` and `after`.

Table 12.40. The <clustering /> Element

The `<clustering />` Element
Description	If this element is present, the cache is started in clustered mode. Attributes and child elements define clustering characteristics.
Parent	`<jbosscache />`
Children	`<stateRetrieval />`, `<sync />`, `<async />`, `<buddy />`, `<jgroupsConfig />`
Bean equivalent	Configuration

Table 12.41. <clustering /> Attributes

`<clustering />` Attributes
Attribute	Bean Field	Allowed	Default	Description
mode	cacheMode	replication, invalidation, r, i	replication	See the chapter on clustering for the differences between replication and invalidation. When using the bean, synchronous and asynchronous communication is combined with clustering mode to give you the enumberation `Configuration.CacheMode`.
clusterName	clusterName	String	JBossCache-cluster	A cluster name which is used to identify the cluster to join.

Table 12.42. The <sync /> Element

The `<sync />` Element
Description	If this element is present, all communications are synchronous, in that whenever a thread sends a message sent over the wire, it blocks until it receives an acknowledgement from the recipient. This element is mutually exclusive with the `<async />` element.
Parent	`<clustering />`
Children
Bean equivalent	Configuration.setCacheMode()

Table 12.43. <sync /> Attributes

`<sync />` Attributes
Attribute	Bean Field	Allowed	Default	Description
replTimeout	syncReplTimeout (dynamic)	positive integer	15000	This is the timeout used to wait for an acknowledgement when making a remote call, after which an exception is thrown.

Table 12.44. The <async /> Element

The `<async />` Element
Description	If this element is present, all communications are asynchronous, in that whenever a thread sends a message sent over the wire, it does not wait for an acknowledgement before returning. This element is mutually exclusive with the `<sync />` element.
Parent	`<clustering />`
Children
Bean equivalent	Configuration.setCacheMode()

Table 12.45. <async /> Attributes

`<async />` Attributes
Attribute	Bean Field	Allowed	Default	Description
serializationExecutorPoolSize	serializationExecutorPoolSize	positive integer	25	In addition to replication happening asynchronously, even serialization of contents for replication happens in a separate thread to allow the caller to return as quickly as possible. This setting controls the size of the serializer thread pool. Setting this to any value less than 1 means serialization does not happen asynchronously.
serializationExecutorQueueSize	serializationExecutorQueueSize	positive integer	50000	This is used to define the size of the bounded queue that holds tasks for the serialization executor. This is ignored if a serialization executor is not used, such as when `serializationExecutorPoolSize` is less than 1.
useReplQueue	useReplQueue	true, false	false	If true, this forces all async communications to be queued up and sent out periodically as a batch.
replQueueInterval	replQueueInterval	positive integer	5000	If `useReplQueue` is set to true, this attribute controls how often the asynchronous thread used to flush the replication queue runs. This should be a positive integer which represents thread wakeup time in milliseconds.
replQueueMaxElements	replQueueMaxElements	positive integer	1000	If `useReplQueue` is set to true, this attribute can be used to trigger flushing of the queue when it reaches a specific threshold.

Table 12.46. The <stateRetrieval /> Element

The `<stateRetrieval />` Element
Description	This tag controls ho state is retrieved from neighboring caches when this cache instance starts.
Parent	`<clustering />`
Children
Bean equivalent	Configuration

Table 12.47. <stateRetrieval /> Attributes

`<stateRetrieval />` Attributes
Attribute	Bean Field	Allowed	Default	Description
fetchInMemoryState	fetchInMemoryState	true, false	true	If true, this will cause the cache to ask neighboring caches for state when it starts up, so the cache starts "warm".
timeout	stateRetrievalTimeout	positive integer	10000	This is the maximum amount of time - in milliseconds - to wait for state from neighboring caches, before throwing an exception and aborting startup.
nonBlocking	useNonBlockingStateTransfer	true, false	false	This configuration switch enables the Non-Blocking State Transfer mechanism, new in 3.1.0. Note that this requires MVCC as a node locking scheme, and that STREAMING_STATE_TRANSFER is present in the JGroups stack used.

Table 12.48. The <buddy /> Element

The `<buddy />` Element
Description	If this tag is present, then state is not replicated across the entire cluster. Instead, buddy replication is used to select cache instances to maintain backups on. See this section on buddy replication for details. Note that this is only used if the clustering mode is `replication`, and not if it is `invalidation`.
Parent	`<clustering />`
Children	`<dataGravitation />`, `<locator />`,
Bean equivalent	BuddyReplicationConfig

Table 12.49. <buddy /> Attributes

`<buddy />` Attributes
Attribute	Bean Field	Allowed	Default	Description
enabled	enabled	true, false	false	If true, buddy replication is enabled.
communicationTimeout	buddyCommunicationTimeout	positive integer	10000	This is the maximum amount of time - in milliseconds - to wait for buddy group organization communications from buddy caches.
poolName	buddyPoolName	String		This is used as a means to identify cache instances and provide hints to the buddy selection algorithms. More information on the section on buddy replication.

Table 12.50. The <dataGravitation /> Element

The `<dataGravitation />` Element
Description	This tag configures how data gravitation is conducted. See this section on buddy replication for details.
Parent	`<buddy />`
Children
Bean equivalent	BuddyReplicationConfig

Table 12.51. <dataGravitation /> Attributes

`<dataGravitation />` Attributes
Attribute	Bean Field	Allowed	Default	Description
auto	autoDataGravitation	true, false	true	If true, when a get() is performed on a cache and nothing is found, a gravitation from neighboring caches is attempted. If this is false, then gravitations can only occur if the `Option.setForceDataGravitation()` option is provided.
removeOnFind	dataGravitationRemoveOnFind	true, false	true	If true, when gravitation occurs, the instance that requests the gravitation takes ownership of the state and requests that all other instances remove the gravitated state from memory.
searchBackupTrees	dataGravitationSearchBackupTrees	true, false	true	If true, incoming gravitation requests will cause the cache to search not just its primary data structure but its backup structure as well.

Table 12.52. The <locator /> Element

The `<locator />` Element
Description	This tag provides a pluggable mechanism for providing buddy location algorithms.
Parent	`<buddy />`
Children	`<properties />`
Bean equivalent	BuddyLocatorConfig

Table 12.53. <locator /> Attributes

`<locator />` Attributes
Attribute	Bean Field	Allowed	Default	Description
class	className	A valid class that is available on the classpath	NextMemberBuddyLocator	A `BuddyLocator` implementation to use when selecting buddies from the cluster. Please refer to `BuddyLocator` javadocs for details.

Table 12.54. The <jgroupsConfig /> Element

The `<jgroupsConfig />` Element
Description	This tag provides a configuration which is used with JGroups to create a network communication channel.
Parent	`<clustering />`
Children	A series of elements representing JGroups protocols (see JGroups documentation). Note that there are no child elements if any of the element attributes are used instead. See section on attributes.
Bean equivalent	Configuration

Table 12.55. <jgroupsConfig /> Attributes

`<jgroupsConfig />` Attributes
Attribute	Bean Field	Allowed	Default	Description
configFile	clusterConfig	A JGroups configuration file on the classpath	udp.xml	If this attribute is used, then any JGroups elements representing protocols within this tag are ignored. Instead, JGroups settings are read from the file specified. Note that this cannot be used with the `multiplexerStack` attribute.
multiplexerStack	muxStackName	A valid multiplexer stack name that exists in the channel factory passed in to the `RuntimeConfig`		This can only be used with the `RuntimeConfig`, where you pass in a JGroups `ChannelFactory` instance using `RuntimeConfig.setMuxChannelFactory()`. If this attribute is used, then any JGroups elements representing protocols within this tag are ignored. Instead, the JGroups channel is created using the factory passed in. Note that this cannot be used with the `configFile` attribute.