Chapter 29. 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 Application 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 Application Platform provides. We then discuss the different options available for deploying a custom cache in the Enterprise Application Platform.
Users considering deploying JBoss Cache for direct use by their own application are strongly encouraged to read the JBoss Cache documentation available at the https://access.redhat.com/knowledge/docs/.
See also Section 21.2, “Distributed Caching with JBoss Cache” for information on how the standard JBoss Enterprise Application Platform clustered services use JBoss Cache.

29.1. Key JBoss Cache Configuration Options

JBoss Enterprise Application Platform ships with a reasonable set of default JBoss Cache configurations that are suitable for the standard clustered service use cases (e.g. 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 https://access.redhat.com/knowledge/docs/.
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 Application Platform CacheManager service uses the JBoss Microcontainer schema to be consistent with most other internal Enterprise Application Platform services.
Before getting into the key configuration options, let us have a look at the most likely place that a user would encounter them.

29.1.1. Editing the CacheManager Configuration

As discussed in Section 21.2.1, “The JBoss Enterprise Application Platform CacheManager Service”, the standard JBoss Enterprise Application 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 29.2.1, “Deployment Via the CacheManager Service”.
The CacheManager is configured via the <JBOSS_HOME>/server/<PROFILE>/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 do not 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 (i.e. cache loading, eviction, buddy replication). Rather than delegating this task of XML parsing/Java Bean creation to JBC, we let the Enterprise Application Platform's microcontainer do it directly. This has the advantage of making the microcontainer aware of the configuration beans, which in later Enterprise Application Platform 5.x 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 Application 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 java beans as their values.
Next we will look at some of the key configuration options.

29.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 means the cache instance sends a message to its peers notifying them of the change(s) and before returning waits for them to acknowledge that they have applied the same changes. If the changes are made as part of a JTA transaction, this is done as part of a two-phase commit process during transaction commit. Any locks are held until this acknowledgment is received. Waiting for acknowledgement from all nodes adds delays, but it ensures consistency around the cluster. Synchronous mode is needed when all the nodes in the cluster may access the cached data resulting in a high need for consistency.
  • Asynchronous means the cache instance sends a message to its peers notifying them of the change(s) and then immediately returns, without any acknowledgement that they have applied the same changes. It does not mean sending the message is handled by some other thread besides the one that changed the cache content; the thread that makes the change still spends some time dealing with sending messages to the cluster, just not as much as with synchronous communication. Asynchronous mode is most useful for cases like session replication, where the cache doing the sending expects to be the only one that accesses the data and the cluster messages are used to provide backup copies in case of failure of the sending node. Asynchronous messaging adds a small risk that a later user request that fails over to another node may see out-of-date state, but for many session-type applications this risk is acceptable given the major performance benefits asynchronous mode has over synchronous mode.
  • Local means the cache instance does not send a message at all. A JGroups channel is not even used by the cache. JBoss Cache has many useful features besides its clustering capabilities and is a very useful caching library even when not used in a cluster. Also, even in a cluster, some cached data does not need to be kept consistent around the cluster, in which case Local mode will improve performance. Caching of JPA/Hibernate query result sets is an example of this; Hibernate's second level caching 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
This aspect deals with the content of messages sent around the cluster when a cache changes its local state, i.e. what should the other caches in the cluster do to reflect the change:
  • Replication means the other nodes should update their state to reflect the new state on the sending node. This means the sending node needs to include the changed state, increasing the cost of the message. Replication is necessary if the other nodes have no other way to obtain the state.
  • Invalidation means the other nodes should remove the changed state from their local state. Invalidation reduces the cost of the cluster update messages, since only the cache key of the changed state needs to be transmitted, not the state itself. However, it 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 the cached state can be re-read from the database.
These two aspects combine to form 5 valid values for the cacheMode configuration attribute:
  • LOCAL means no cluster messages are needed.
  • REPL_SYNC means synchronous replication messages are sent.
  • REPL_ASYNC means asynchronous replication messages are sent.
  • INVALIDATION_SYNC means synchronous invalidation messages are sent.
  • INVALIDATION_ASYNC means asynchronous invalidation messages are sent.

29.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 Application Platform, this attribute would have one of two values:
  • org.jboss.cache.transaction.JBossTransactionManagerLookup
    This finds 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
    This is used in the cache configurations used for web session and EJB SFSB caching. It specifies a simple mock TransactionManager that ships with JBoss Cache called the BatchModeTransactionManager. This transaction manager is not a true JTA transaction manager and should not be used for anything other than JBoss Cache. Its usage in JBoss Enterprise Application Platform is to get most of the benefits of JBoss Cache's transactional behavior for the session replication use cases, but without getting tangled up with end user transactions that may run during a request.

29.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 choices for nodeLockingScheme:
  • MVCC or multi-version concurrency control, is 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. The theory is that readers continue reading shared state, while writers copy the shared state, increment a version id, and write that shared state back after verifying that the version is still valid (i.e., another concurrent writer has not changed this state first).
    MVCC is the recommended choice for JPA/Hibernate entity caching.
  • PESSIMISTIC locking involves threads/transactions acquiring either exclusive or non-exclusive locks on nodes before reading or writing. Which is acquired depends on the isolationLevel (see below) but in most cases a non-exclusive lock is acquired for a read and an exclusive lock is acquired for a write. Pessimistic locking requires considerably more overhead than MVCC and allows lesser concurrency, since reader threads must block until a write has completed and released its exclusive lock (potentially a long time if the write is part of a transaction). A write will also be delayed due to ongoing reads.
    Generally MVCC is a better choice than PESSIMISTIC, which is deprecated as of JBoss Cache 3.0. But, for the session caching usage in JBoss Enterprise Application Platform 5.0.0, PESSIMISTIC is still the default. This is largely because for the session use case there are generally not concurrent threads accessing the same cache location, so the benefits of MVCC are not as great.
  • OPTIMISTIC locking seeks to improve upon the concurrency available with PESSIMISTIC by creating a "workspace" for each request/transaction that accesses the cache. Data accessed by the request/transaction (even reads) is copied into the workspace, which is adds overhead. All data is versioned; on completion of non-transactional requests or commits of transactions the version of data in the workspace is compared to the main cache, and an exception is raised if there are inconsistencies. Otherwise changes to the workspace are applied to the main cache.
    OPTIMISTIC locking is deprecated but is still provided to support backward compatibility. Users are encouraged to use MVCC instead, which provides the same benefits at lower cost.
The isolationLevel attribute has two possible values READ_COMMITTED and REPEATABLE_READ which correspond in semantic to database-style isolation levels. Previous versions of JBoss Cache supported all 5 database isolation levels, and if an unsupported isolation level is configured, it is either upgraded or downgraded to the closest supported level.
REPEATABLE_READ is the default isolation level, to maintain compatibility with previous versions of JBoss Cache. READ_COMMITTED, while providing a slightly weaker isolation, has a significant performance benefit over REPEATABLE_READ.

29.1.5. JGroups Integration

Each JBoss Cache instance internally uses a JGroups Channel to handle group communications. Inside JBoss Enterprise Application Platform, we strongly recommend that you use the Enterprise Application 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 it's 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 has 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 29.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.: 
<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 29.2.3, “Deployment Via a -jboss-beans.xml File”), you need 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 29.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>

29.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, refer to the JBoss Cache User Guide available in the JBoss Enterprise Application Platform 5 documentation suite at https://access.redhat.com/knowledge/docs/.
For web session caches, eviction should not be configured; the distributable session manager handles eviction itself. For EJB 3 SFSB caches, stick with the eviction configuration in the Enterprise Application Platform's standard sfsb-cache configuration (see Section 21.2.1, “The JBoss Enterprise Application Platform CacheManager Service”). The EJB container will configure eviction itself using the values included in each bean's configuration.

29.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 just redundant.
The caches used for web session and EJB3 SFSB caching use passivation. Next we will discuss the cache loader configuration for those caches in some detail.

29.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 do not need to do anything to alter the cache loader configurations for the standard web session and SFSB caches; the standard JBoss Enterprise Application Platform configurations should suit your needs. The following is a bit more detail in case you are interested or want to change from the defaults.
The Cache Loader configuration for the standard-session-cache config 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>
Some explanation:
  • passivation property MUST be true
  • shared property MUST be false. Do not passivate sessions to a shared persistent store, otherwise if another node activates the session, it will be gone from the persistent store and also gone from memory on other nodes that have passivated it. Backup copies will be lost.
  • individualCacheLoaderConfigs property accepts a list of Cache Loader configurations. JBC allows you to chain cache loaders; see the JBoss Cache docs. For the session passivation use case a single cache loader is sufficient.
  • class attribute on a cache loader config bean must refer to the configuration class for a cache loader implementation (e.g. org.jboss.cache.loader.FileCacheLoaderConfig or org.jboss.cache.loader.JDBCCacheLoaderConfig). See the JBoss Cache documentation for more on the available CacheLoader implementations. If you wish to use JDBCCacheLoader (to persist to a database rather than the file system used by FileCacheLoader) note the comment above about the shared property. Do not use a shared database, or at least not a shared table in the database. Each node in the cluster must have its own storage location.
  • location property for FileCacheLoaderConfig defines the root node of the file system tree where passivated sessions should be stored. The default is to store them in your JBoss Enterprise Application 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 does not pollute the current data set.
  • ignoreModifications should be false
  • checkCharacterPortability should be false as a minor performance optimization.

29.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 does not 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 occurrence; 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 (a.k.a. "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 (e.g. 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 will 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, it will if possible 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 and dataGravitationSearchBackupTrees. Session replication will not work properly if these are changed.