Chapter 24. JBoss Cache Configuration and Deployment

JBoss Cache provides the underlying distributed caching support used by many of the standard clustered services in a JBoss Enterprise Web Platform cluster. You can also deploy JBoss Cache in your own application to handle custom caching requirements. In this chapter we provide some background on the main configuration options available with JBoss Cache, with an emphasis on how those options relate to the JBoss Cache usage by the standard clustered services the Enterprise Web Platform provides. We then discuss the different options available for deploying a custom cache in the Enterprise Web Platform.

Users considering deploying JBoss Cache for direct use by their own application are strongly encouraged to read the JBoss Cache documentation available from http://www.redhat.com/docs/en-US/JBoss_Enterprise_Application_Platform/.

See also Section 17.1.3, “Distributed Caching with JBoss Cache” for information on how the standard JBoss Enterprise Web Platform clustered services use JBoss Cache.

24.1. Key JBoss Cache Configuration Options

JBoss Enterprise Web Platform ships with a reasonable set of default JBoss Cache configurations that are suitable for the standard clustered service use cases (for example, web session replication or JPA/Hibernate caching). Most applications that involve the standard clustered services just work out of the box with the default configurations. You only need to tweak them when you are deploying an application that has special network or performance requirements. In this section we provide a brief overview of some of the key configuration choices. This is by no means a complete discussion; for full details users interested in moving beyond the default configurations are encouraged to read the JBoss Cache documentation available at http://www.redhat.com/docs/en-US/JBoss_Enterprise_Application_Platform/.

Most JBoss Cache configuration examples in this section use the JBoss Microcontainer schema for building up an org.jboss.cache.config.Configuration object graph from XML. JBoss Cache has its own custom XML schema, but the standard JBoss Enterprise Web Platform CacheManager service uses the JBoss Microcontainer schema to be consistent with most other internal Enterprise Web Platform services.

Before getting into the key configuration options, let's have a look at the most likely place that a user would encounter them.

24.1.1. Editing the CacheManager Configuration

As discussed in Section 17.1.3.1, “The JBoss Enterprise Web Platform CacheManager Service”, the standard JBoss Enterprise Web Platform clustered services use the CacheManager service as a factory for JBoss Cache instances. So, cache configuration changes are likely to involve edits to the CacheManager service.

Note

Users can also use the CacheManager as a factory for custom caches used by directly by their own applications; see Section 24.2.1, “Deployment Via the CacheManager Service”.

The CacheManager is configured via the deploy/cluster/jboss-cache-manager.sar/META-INF/jboss-cache-manager-jboss-beans.xml file. The element most likely to be edited is the CacheConfigurationRegistry bean, which maintains a registry of all the named JBC configurations the CacheManager knows about. Most edits to this file would involve adding a new JBoss Cache configuration or changing a property of an existing one.

The following is a redacted version of the CacheConfigurationRegistry bean configuration:

<bean name="CacheConfigurationRegistry" 
      class="org.jboss.ha.cachemanager.DependencyInjectedConfigurationRegistry">
   
      <!-- If users wish to add configs using a more familiar JBC config format
           they can add them to a cache-configs.xml file specified by this property.
           However, use of the microcontainer format used below is recommended.
      <property name="configResource">META-INF/jboss-cache-configs.xml</property>      
      -->
      
      <!-- The configurations. A Map<String name, Configuration config> -->
      <property name="newConfigurations">
        <map keyClass="java.lang.String" valueClass="org.jboss.cache.config.Configuration">
   
   <!-- The standard configurations follow.  You can add your own and/or edit these. -->   
      
   <!-- Standard cache used for web sessions -->
   <entry><key>standard-session-cache</key>
   <value>      
      <bean name="StandardSessionCacheConfig" class="org.jboss.cache.config.Configuration">
         
         <!-- Provides batching functionality for caches that don't want to 
              interact with regular JTA Transactions -->
         <property name="transactionManagerLookupClass">
            org.jboss.cache.transaction.BatchModeTransactionManagerLookup
         </property>
               
         <!-- Name of cluster. Needs to be the same for all members -->
         <property name="clusterName">${jboss.partition.name:DefaultPartition}-SessionCache</property>
         <!-- Use a UDP (multicast) based stack. Need JGroups flow control (FC)
              because we are using asynchronous replication. -->
         <property name="multiplexerStack">${jboss.default.jgroups.stack:udp}</property>
         <property name="fetchInMemoryState">true</property>
         
         <property name="nodeLockingScheme">PESSIMISTIC</property>
         <property name="isolationLevel">REPEATABLE_READ</property>
         <property name="cacheMode">REPL_ASYNC</property>
      
          .... more details of the standard-session-cache configuration
      </bean>      
   </value>
   </entry>
   
   <!-- Appropriate for web sessions with FIELD granularity -->
   <entry><key>field-granularity-session-cache</key>
   <value>      
      
      <bean name="FieldSessionCacheConfig" class="org.jboss.cache.config.Configuration">              
           .... details of the field-granularity-standard-session-cache configuration
      </bean>      

   </value>

   </entry>

   ... entry elements for the other configurations

  </map>
  </property>
</bean>

The actual JBoss Cache configurations are specified using the JBoss Microcontainer's schema rather than one of the standard JBoss Cache configuration formats. When JBoss Cache parses one of its standard configuration formats, it creates a Java Bean of type org.jboss.cache.config.Configuration with a tree of child Java Beans for some of the more complex sub-configurations (for example, cache loading, eviction, buddy replication). Rather than delegating this task of XML parsing and Java Bean creation to JBC, we let the Enterprise Web Platform's microcontainer do it directly. This has the advantage of making the microcontainer aware of the configuration beans, which in later Enterprise Web Platform releases will be helpful in allowing external management tools to manage the JBC configurations.

The configuration format should be fairly self-explanatory if you look at the standard configurations the Enterprise Web Platform ships; they include all the major elements. The types and properties of the various Java Beans that make up a JBoss Cache configuration can be seen in the JBoss Cache Javadocs. Here is a fairly complete example:

<bean name="StandardSFSBCacheConfig" class="org.jboss.cache.config.Configuration">

   <!--  No transaction manager lookup -->
         
   <!-- Name of cluster. Needs to be the same for all members -->
   <property name="clusterName">${jboss.partition.name:DefaultPartition}-SFSBCache</property>
   <!-- Use a UDP (multicast) based stack. Need JGroups flow control (FC)
        because we are using asynchronous replication. -->
   <property name="multiplexerStack">${jboss.default.jgroups.stack:udp}</property>
   <property name="fetchInMemoryState">true</property>
   
   <property name="nodeLockingScheme">PESSIMISTIC</property>
   <property name="isolationLevel">REPEATABLE_READ</property>
   <property name="cacheMode">REPL_ASYNC</property>
   
   <property name="useLockStriping">false</property>

   <!-- Number of milliseconds to wait until all responses for a
        synchronous call have been received. Make this longer 
        than lockAcquisitionTimeout.-->
   <property name="syncReplTimeout">17500</property>
   <!-- Max number of milliseconds to wait for a lock acquisition -->
   <property name="lockAcquisitionTimeout">15000</property>
   <!-- The max amount of time (in milliseconds) we wait until the
    state (ie. the contents of the cache) are retrieved from
    existing members at startup. -->
   <property name="stateRetrievalTimeout">60000</property>

   <!--
    SFSBs use region-based marshalling to provide for partial state
    transfer during deployment/undeployment.
   -->
   <property name="useRegionBasedMarshalling">false</property>
   <!-- Must match the value of "useRegionBasedMarshalling" -->
   <property name="inactiveOnStartup">false</property>
   
   <!-- Disable asynchronous RPC marshalling/sending -->
   <property name="serializationExecutorPoolSize">0</property>        
   <!-- We have no asynchronous notification listeners -->
   <property name="listenerAsyncPoolSize">0</property>
     
   <property name="exposeManagementStatistics">true</property>

   <property name="buddyReplicationConfig">
      <bean class="org.jboss.cache.config.BuddyReplicationConfig">
         
         <!--  Just set to true to turn on buddy replication -->
         <property name="enabled">false</property>
         
         <!-- A way to specify a preferred replication group.  We try
              and pick a buddy who shares the same pool name (falling 
              back to other buddies if not available). -->
         <property name="buddyPoolName">default</property>
         
         <property name="buddyCommunicationTimeout">17500</property>
         
         <!-- Do not change these -->
         <property name="autoDataGravitation">false</property>
         <property name="dataGravitationRemoveOnFind">true</property>
         <property name="dataGravitationSearchBackupTrees">true</property>
         
         <property name="buddyLocatorConfig">
            <bean class="org.jboss.cache.buddyreplication.NextMemberBuddyLocatorConfig">
               <!-- The number of backup nodes we maintain -->
               <property name="numBuddies">1</property>
               <!-- Means that each node will *try* to select a buddy on 
                    a different physical host. If not able to do so 
                    though, it will fall back to colocated nodes. -->
               <property name="ignoreColocatedBuddies">true</property>
             </bean>
         </property>
      </bean>
   </property>
   <property name="cacheLoaderConfig">
      <bean class="org.jboss.cache.config.CacheLoaderConfig">
             <!-- Do not change these -->
             <property name="passivation">true</property>
             <property name="shared">false</property>
             
             <property name="individualCacheLoaderConfigs">
               <list>
                  <bean class="org.jboss.cache.loader.FileCacheLoaderConfig">
                     <!-- Where passivated sessions are stored -->
                     <property name="location">${jboss.server.data.dir}${/}sfsb</property>
                     <!-- Do not change these -->
                     <property name="async">false</property>
                     <property name="fetchPersistentState">true</property>
                     <property name="purgeOnStartup">true</property>
                     <property name="ignoreModifications">false</property>
                     <property name="checkCharacterPortability">false</property>
                  </bean>
               </list>
             </property>
      </bean>
   </property>
  
   <!-- EJBs use JBoss Cache eviction -->
   <property name="evictionConfig">
       <bean class="org.jboss.cache.config.EvictionConfig">
         <property name="wakeupInterval">5000</property>
         <!--  Overall default -->
         <property name="defaultEvictionRegionConfig">
            <bean class="org.jboss.cache.config.EvictionRegionConfig">
               <property name="regionName">/</property>
               <property name="evictionAlgorithmConfig">
                  <bean class="org.jboss.cache.eviction.NullEvictionAlgorithmConfig"/>
               </property>
            </bean>
         </property>
         <!-- EJB3 integration code will programatically create
              other regions as beans are deployed -->
      </bean>
   </property>
</bean>

Basically, the XML specifies the creation of an org.jboss.cache.config.Configuration Java Bean and the setting of a number of properties on that bean. Most of the properties are of simple types, but some, such as buddyReplicationConfig and cacheLoaderConfig take various types of Java Bean as their values.

Next we'll look at some of the key configuration options.

24.1.2. Cache Mode

JBoss Cache's cacheMode configuration attribute combines into a single property two related aspects:

Handling of Cluster Updates

This controls how a cache instance on one node should notify the rest of the cluster when it makes changes in its local state. There are three options:

Synchronous: When a change is made, the cache sends a message to notify its peers of changes and waits for acknowledgement that its peers have applied those changes before returning. If the changes are made as part of a JTA transaction, this is done as part of a two-phase commit process. Any locks are held until acknowledgement is received. Waiting for this acknowledgement to be received from all nodes adds delays, but ensures consistency around the cluster. Synchronous mode is required when there is a high need for consistency, such as when all nodes can access cached data.
Asynchronous: When a change is made, the cache sends a message to notify its peers of changes and returns immediately without any acknowledgement that the changes have been applied. Asynchronous mode is most useful in session replication, where only the cache that sends the messages accesses data, and cluster messages are used to provide backup copies in the case of a failure on the sending node. Asynchronous messaging has minor consistency risks, in that a later user request that fails over to another node may see out-of-date state. However, this is usually considered an acceptable risk for session-type applications because of the major performance benefits associated with asynchronous messaging.
Local: No message is sent, and no JGroups channel is used by the cache. Local messaging will provide improved performance when cached data need not be kept consistent around the cluster. One example of this is caching JPA/Hibernate query result sets: Hibernate's second level cache logic uses a separate mechanism to invalidate stale query result sets from the second level cache, so JBoss Cache does not need to send messages around the cluster for a query result set cache.

Replication vs. Invalidation

Nodes in a cluster can reflect changes from the sending node in two ways:

Replication: Other nodes update their state to reflect the new state on the sending node. This means that the sending node must include the changed state, increasing the resource cost of the message. Replication is required if there is no other way for other nodes to obtain the changed state.
Invalidation: Other nodes remove the changed state from their local state. Invalidation mode reduces the resource cost of cluster update messages, since only the cache key of the state changed needs to be transmitted. However, this is only an option if the removed state can be retrieved from another source. It is an excellent option for a clustered JPA/Hibernate entity cache, since in this case cached state can be reread from the database.

The cacheMode configuration attribute has five possible values, which form various combinations of the aforementioned aspects:

LOCAL: No cluster messages are required.
REPL_SYNC: Synchronous replication messages are sent.
REPL_ASYNC: Asynchronous replication messages are sent.
INVALIDATION_SYNC: Synchronous invalidation messages are sent.
INVALIDATION_ASYNC: Asynchronous invalidation messages are sent.

24.1.3. Transaction Handling

JBoss Cache integrates with JTA transaction managers to allow transactional access to the cache. When JBoss Cache detects the presence of a transaction, any locks are held for the life of the transaction, changes made to the cache will be reverted if the transaction rolls back, and any cluster-wide messages sent to inform other nodes of changes are deferred and sent in a batch as part of transaction commit (reducing chattiness).

Integration with a transaction manager is accomplished by setting the transactionManagerLookupClass configuration attribute; this specifies the fully qualified class name of a class JBoss Cache can use to find the local transaction manager. Inside JBoss Enterprise Web Platform, this attribute would have one of two values:

org.jboss.cache.transaction.JBossTransactionManagerLookup: The standard transaction manager running in the application server. Use this for any custom caches you deploy where you want caching to participate in any JTA transactions.
org.jboss.cache.transaction.BatchModeTransactionManagerLookup: Used in the cache configurations for web session caching. Specifies the BatchModeTransactionManager, a mock TransactionManager shipped with JBoss Cache. Since this is not a true JTA transaction manager, it should not be used with anything other than JBoss Cache. In JBoss Enterprise Web Platform, it benefits from JBoss Cache's transactional behavior in session replication, without participating in end-user transactions that may run during a request.

Note

The transactionManagerLookupClass should not be configured for caches that are used for JPA/Hibernate caching. Hibernate internally configures the cache to use the same transaction manager that Hibernate uses for database access.

24.1.4. Concurrent Access

JBoss Cache is a thread safe caching API, and uses its own efficient mechanisms of controlling concurrent access. Concurrency is configured via the nodeLockingScheme and isolationLevel configuration attributes.

There are three possible values for nodeLockingScheme:

MVCC (Multi-Versioned Concurrency Control)

A locking scheme commonly used by modern database implementations to control fast, safe concurrent access to shared data. JBoss Cache 3.x uses an innovative implementation of MVCC as the default locking scheme. MVCC is designed to provide the following features for concurrent access:

readers that do not block writers
writers that fail fast

It achieves this by using data versioning and copying for concurrent writers. In theory, readers continue reading shared state, while writers copy the shared state, increment the version ID, and write that shared state back after verifying that the version is still valid (that is, thata another convurrent writer has not altered the state first).

MVCC is recommended for JPA/Hibernate entity caching.

PESSIMISTIC

Threads or transactions acquire either exclusive or non-exclusive locks on nodes before reading or writing. The lock type acquired depends on the isolationLevel, but in most cases a non-exclusive lock is acquired for a read, and an exclusive lock is aquired for a write. Pessimistic locking requires more resources than MVCC, and allows less concurrency, since reader threads must block until a write has completed and released its exclusive lock. This can be a long time if the write is part of a transaction. A write will also be delayed due to ongoing reads.

Pessimistic locking is deprecated as of JBoss Cache 3.0. For session caching use in JBoss Enterprise Web Platform, PESSIMISTIC is the default value, since concurrent threads usually do not access the same cache location in session caching and the benefits of MVCC are not as great.

OPTIMISTIC

Improves the concurrency available with pessimistic locking by creating a "workspace" for each request or transaction that accesses the cache. Data accessed by requests (including reads) is copied into the workspace, which increases resource usage. All data is versioned, so when non-transactional requests or transaction commits are completed, the version of data in the workspace is compared to the primary cache. If there are inconsistencies, an exception is raised. Otherwise, changes to the workspace are applied to the main cache.

Optimistic locking is deprecated, but is provided to support backwards compatibility. Users are encouraged to use MVCC instead, which provides the same benefits at a lower cost to resources.

The isolationLevel attribute has two possible values, READ_COMMITTED and REPEATABLE_READ, which correspond to database style isolation levels. The default isolation level is REPEATABLE_READ, which maintains backwards compatibility with previous versions of JBoss Cache. READ_COMMITTED provides slightly weaker isolation, but has significant performance benefits.

24.1.5. JGroups Integration

Each JBoss Cache instance internally uses a JGroups Channel to handle group communications. Inside JBoss Enterprise Web Platform, we strongly recommend that you use the Enterprise Web Platform's JGroups Channel Factory service as the source for your cache's Channel. In this section we discuss how to configure your cache to get its channel from the Channel Factory; if you wish to configure the channel in some other way, see the JBoss Cache documentation.

Caches obtained from the CacheManager Service

This is the simplest approach. The CacheManager service already contains a reference to the Channel Factory service, so the only configuration task is to configure the name of the JGroups protocol stack configuration to use.

If you are configuring your cache via the CacheManager service's jboss-cache-manager-jboss-beans.xml file (see Section 24.2.1, “Deployment Via the CacheManager Service”), add the following to your cache configuration, where the value is the name of the protocol stack configuration (here udp):

<property name="multiplexerStack">udp</property>

Caches Deployed via a -jboss-beans.xml File

If you are deploying a cache via a JBoss Microcontainer -jboss-beans.xml file (see Section 24.2.3, “Deployment Via a -jboss-beans.xml File”), you need to inject a reference to the Channel Factory service as well as specifying the protocol stack configuration:

<property name="runtimeConfig">
   <bean class="org.jboss.cache.config.RuntimeConfig">
      <property name="muxChannelFactory"><inject bean="JChannelFactory"/></property>
   </bean>
</property>
<property name="multiplexerStack">udp</property>

Caches Deployed via a -service.xml File

If you are deploying a cache MBean via -service.xml file (see Section 24.2.2, “Deployment Via a -service.xml File”), CacheJmxWrapper is the class of your MBean; that class exposes a MuxChannelFactory MBean attribute. You dependency inject the Channel Factory service into this attribute, and set the protocol stack name via the MultiplexerStack attribute:

<attribute name="MuxChannelFactory"><inject bean="JChannelFactory"/></attribute>
<attribute name="MultiplexerStack">udp</attribute>

24.1.6. Eviction

Eviction allows the cache to control memory by removing data (typically the least frequently used data). If you wish to configure eviction for a custom cache, see the JBoss Cache documentation for all of the available options. For details on configuring it for JPA/Hibernate caching, see the Eviction chapter in the "Using JBoss Cache as a Hibernate Second Level Cache" guide at http://www.jboss.org/jbossclustering/docs/hibernate-jbosscache-guide-3.pdf. For web session caches, eviction should not be configured; the distributable session manager handles eviction itself. For EJB3 SFSB caches, stick with the eviction configuration in the Enterprise Web Platform's standard sfsb-cache configuration (see Section 17.1.3.1, “The JBoss Enterprise Web Platform CacheManager Service”). The EJB container will configure eviction itself using the values included in each bean's configuration.

24.1.7. Cache Loaders

Cache loading allows JBoss Cache to store data in a persistent store in addition to what it keeps in memory. This data can either be an overflow, where the data in the persistent store is not reflected in memory, or it can be a superset of what is in memory, where everything in memory is also reflected in the persistent store, along with items that have been evicted from memory. Which of these two modes is used depends on the setting of the passivation flag in the JBoss Cache cache loader configuration section. A true value means the persistent store acts as an overflow area written to when data is evicted from the in-memory cache.

If you wish to configure cache loading for a custom cache, see the JBoss Cache documentation for all of the available options. Do not configure cache loading for a JPA/Hibernate cache, as the database itself serves as a persistent store; adding a cache loader is redundant.

The caches used for web session and EJB3 SFSB caching use passivation. Next we'll discuss the cache loader configuration for those caches in some detail.

24.1.7.1. CacheLoader Configuration for Web Session and SFSB Caches

HttpSession and SFSB passivation rely on JBoss Cache's Cache Loader passivation for storing and retrieving the passivated sessions. Therefore the cache instance used by your webapp's clustered session manager or your bean's EJB container must be configured to enable Cache Loader passivaton.

In most cases you don't need to do anything to alter the cache loader configurations for the standard web session and SFSB caches; the standard JBoss Enterprise Web Platform configurations should suit your needs. The following is a bit more detail in case you're interested or want to change from the defaults.

The Cache Loader configuration for the standard-session-cache configuration serves as a good example:

<property name="cacheLoaderConfig">
   <bean class="org.jboss.cache.config.CacheLoaderConfig">
          <!-- Do not change these -->
          <property name="passivation">true</property>
          <property name="shared">false</property>
          
          <property name="individualCacheLoaderConfigs">
            <list>
               <bean class="org.jboss.cache.loader.FileCacheLoaderConfig">
                  <!-- Where passivated sessions are stored -->
                  <property name="location">${jboss.server.data.dir}${/}session</property>
                  <!-- Do not change these -->
                  <property name="async">false</property>
                  <property name="fetchPersistentState">true</property>
                  <property name="purgeOnStartup">true</property>
                  <property name="ignoreModifications">false</property>
                  <property name="checkCharacterPortability">false</property>
               </bean>
            </list>
          </property>
   </bean>
</property>

passivation must be set to true.
shared must be set to false. Do not passivate sessions to a shared persistent store, or if another node activates the session, the session will be removed from the persistent store and from the memory on other nodes that have passivated it. Backup copies will be lost.
individualCacheLoaderConfigs accepts a list of cache loader configurations. You can also chain cache loaders (see the JBoss Cache documentation for details). For session passivation, a single cache loader is sufficient.
class must refer to the configuration class for a cache loader implementation, for example, org.jboss.cache.loader.FileCacheLoaderConfig or org.jboss.cache.loader.JDBCCacheLoaderConfig. See the JBoss Cache documentation for more information about the available CacheLoader implementations. If you want to use JDBCCacheLoader (to persist to a database rather than the filesystem used by FileCacheLoader), take note of the comments about the shared property. Do not use a shared database. Each node in the cluster must have its own storage location.
FileCacheLoaderConfig's location property defines the root node of the filesystem tree where passivated sessions should be stored. The default is to store them in your JBoss Enterprise Web Platform configuration's data directory.
async must be false to ensure passivated sessions are promptly written to the persistent store.
fetchPersistentState property must be true to ensure passivated sessions are included in the set of session backup copies transferred over from other nodes when the cache starts.
purgeOnStartup should be true to ensure out-of-date session data left over from a previous shutdown of a server doesn't pollute the current data set.
ignoreModifications should be false
checkCharacterPortability should be false for a minor performance improvement.

24.1.8. Buddy Replication

Buddy Replication is a JBoss Cache feature that allows you to suppress replicating your data to all instances in a cluster. Instead, each instance picks one or more buddies in the cluster, and only replicates to those specific buddies. This greatly helps scalability, as there is no longer a memory and network traffic impact every time another instance is added to a cluster.

If the cache on another node needs data that it doesn't have locally, it can ask the other nodes in the cluster to provide it; nodes that have a copy will provide it as part of a process called data gravitation. The new node will become the owner of the data, placing a backup copy of the data on its buddies. The ability to gravitate data means there is no need for all requests for data to occur on a node that has a copy of it; any node can handle a request for any data. However, data gravitation is expensive and should not be a frequent occurence; ideally it should only occur if the node that is using some data fails or is shut down, forcing interested clients to fail over to a different node. This makes buddy replication primarily useful for session-type applications with session affinity (also known as sticky sessions) where all requests for a particular session are normally handled by a single server.

Buddy replication can be enabled for the web session and EJB3 SFSB caches. Do not add buddy replication to the cache configurations used for other standard clustering services (for example, JPA/Hibernate caching). Services not specifically engineered for buddy replication are highly unlikely to work correctly if it is introduced.

Configuring buddy replication is fairly straightforward. As an example we'll look at the buddy replication configuration section from the CacheManager service's standard-session-cache config:

<property name="buddyReplicationConfig">
   <bean class="org.jboss.cache.config.BuddyReplicationConfig">
               
      <!--  Just set to true to turn on buddy replication -->
      <property name="enabled">true</property>
               
      <!-- A way to specify a preferred replication group.  We try
           and pick a buddy who shares the same pool name (falling 
           back to other buddies if not available). -->
      <property name="buddyPoolName">default</property>
               
      <property name="buddyCommunicationTimeout">17500</property>
               
      <!-- Do not change these -->
      <property name="autoDataGravitation">false</property>
      <property name="dataGravitationRemoveOnFind">true</property>
      <property name="dataGravitationSearchBackupTrees">true</property>
               
      <property name="buddyLocatorConfig">
         <bean class="org.jboss.cache.buddyreplication.NextMemberBuddyLocatorConfig">
            <!-- The number of backup copies we maintain -->
            <property name="numBuddies">1</property>
            <!-- Means that each node will *try* to select a buddy on 
                 a different physical host. If not able to do so 
                 though, it will fall back to colocated nodes. -->
            <property name="ignoreColocatedBuddies">true</property>
          </bean>
      </property>
   </bean>
</property>

The main things you would be likely to configure are:

buddyReplicationEnabled — true if you want buddy replication; false if data should be replicated to all nodes in the cluster, in which case none of the other buddy replication configurations matter.
numBuddies — to how many backup nodes should each node replicate its state.
buddyPoolName — allows logical subgrouping of nodes within the cluster; if possible, buddies will be chosen from nodes in the same buddy pool.

The ignoreColocatedBuddies switch means that when the cache is trying to find a buddy, where possible it will not choose a buddy on the same physical host as itself. If the only server it can find is running on its own machine, it will use that server as a buddy.

Do not change the settings for autoDataGravitation, dataGravitationRemoveOnFind or dataGravitationSearchBackupTrees. Session replication will not work properly if these are changed.