JBoss.orgCommunity Documentation

Chapter 11. Configuration References

11.1. Sample XML Configuration File
11.2. Reference table of XML attributes

11.1. Sample XML Configuration File

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



<!-- ===================================================================== -->

<!--                                                                       -->

<!--  Sample JBoss Cache Service Configuration                             -->

<!--                                                                       -->

<!-- ===================================================================== -->



<server>

   

   <!-- ==================================================================== -->

   <!-- Defines JBoss Cache configuration                                      -->

   <!-- ==================================================================== -->



   <!-- Note the value of the 'code' attribute has changed since JBC 1.x -->

   <mbean code="org.jboss.cache.jmx.CacheJmxWrapper" name="jboss.cache:service=Cache">

   

      <!-- Ensure JNDI and the TransactionManager are started before the

           cache.  Only works inside JBoss AS; ignored otherwise -->

      <depends>jboss:service=Naming</depends>

      <depends>jboss:service=TransactionManager</depends>



      <!-- Configure the TransactionManager -->

      <attribute name="TransactionManagerLookupClass">

         org.jboss.cache.transaction.GenericTransactionManagerLookup

      </attribute>



      <!-- Node locking level : SERIALIZABLE

                                REPEATABLE_READ (default)

                                READ_COMMITTED

                                READ_UNCOMMITTED

                                NONE             -->

      <attribute name="IsolationLevel">REPEATABLE_READ</attribute>



      <!-- Lock parent before doing node additions/removes -->

      <attribute name="LockParentForChildInsertRemove">true</attribute>



      <!-- Valid modes are LOCAL (default)

                           REPL_ASYNC

                           REPL_SYNC

                           INVALIDATION_ASYNC

                           INVALIDATION_SYNC   -->

      <attribute name="CacheMode">REPL_ASYNC</attribute>



      <!-- Name of cluster. Needs to be the same for all JBoss Cache nodes in a

           cluster in order to find each other. 

      -->

      <attribute name="ClusterName">JBossCache-Cluster</attribute>



      <!--Uncomment next three statements to use the JGroups multiplexer.

         This configuration is dependent on the JGroups multiplexer being

         registered in an MBean server such as JBossAS.  This type of

         dependency injection only works in the AS; outside it's up to

         your code to inject a ChannelFactory if you want to use one. 

      -->

      <!--

      <depends optional-attribute-name="MultiplexerService" 

            proxy-type="attribute">jgroups.mux:name=Multiplexer</depends>

      <attribute name="MultiplexerStack">tcp</attribute>

      -->



      <!-- JGroups protocol stack properties.

         ClusterConfig isn't used if the multiplexer is enabled above.

      -->

      <attribute name="ClusterConfig">

         <config>

            <!-- UDP: if you have a multihomed machine, set the bind_addr 

                 attribute to the appropriate NIC IP address -->

            <!-- UDP: On Windows machines, because of the media sense feature

                 being broken with multicast (even after disabling media sense)

                 set the loopback attribute to true -->

            <UDP mcast_addr="228.1.2.3" mcast_port="48866"

                 ip_ttl="64" ip_mcast="true"

                 mcast_send_buf_size="150000" mcast_recv_buf_size="80000"

                 ucast_send_buf_size="150000" ucast_recv_buf_size="80000"

                 loopback="false"/>

            <PING timeout="2000" num_initial_members="3"/>

            <MERGE2 min_interval="10000" max_interval="20000"/>

            <FD shun="true"/>

            <FD_SOCK/>

            <VERIFY_SUSPECT timeout="1500"/>

            <pbcast.NAKACK gc_lag="50" retransmit_timeout="600,1200,2400,4800" />

            <UNICAST timeout="600,1200,2400",4800/>

            <pbcast.STABLE desired_avg_gossip="400000"/>

            <FC max_credits="2000000" min_threshold="0.10"/>

            <FRAG2 frag_size="8192"/>

            <pbcast.GMS join_timeout="5000" shun="true" print_local_addr="true"/>

            <pbcast.STATE_TRANSFER/>

         </config>

      </attribute>

      

      <!--

          The max amount of time (in milliseconds) we wait until the

          initial state (ie. the contents of the cache) are retrieved from

          existing members in a clustered environment

      -->

      <attribute name="StateRetrievalTimeout">20000</attribute>



      <!--

          Number of milliseconds to wait until all responses for a

          synchronous call have been received.

      -->

      <attribute name="SyncReplTimeout">20000</attribute>



      <!-- Max number of milliseconds to wait for a lock acquisition -->

      <attribute name="LockAcquisitionTimeout">15000</attribute>



      <!-- Shutdown hook behavior.  Valid choices are: DEFAULT, REGISTER and DONT_REGISTER.

           If this element is omitted, DEFAULT is used.  -->

      <attribute name="ShutdownHookBehavior">DEFAULT</attribute>



      <!-- Enables or disables lazy unmarshalling.  If omitted, the default is that lazy unmarshalling is enabled. -->

      <attribute name="UseLazyDeserialization">true</attribute>      



      <!-- Specific eviction policy configurations. This is LRU -->

      <attribute name="EvictionConfig">

         <config>

            <attribute name="wakeUpIntervalSeconds">5</attribute>

            <!-- This defaults to 200000 if not specified -->

            <attribute name="eventQueueSize">200000</attribute>

            <attribute name="policyClass">org.jboss.cache.eviction.LRUPolicy</attribute>



            <!-- Cache wide default -->

            <region name="/_default_">

               <attribute name="maxNodes">5000</attribute>

               <attribute name="timeToLiveSeconds">1000</attribute>

            </region>

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

               <attribute name="maxNodes">5000</attribute>

               <attribute name="timeToLiveSeconds">1000</attribute>

            </region>

            <region name="/org/jboss/test/data">

               <attribute name="maxNodes">5</attribute>

               <attribute name="timeToLiveSeconds">4</attribute>

            </region>

            <region name="/test">

               <attribute name="maxNodes">10000</attribute>

               <attribute name="timeToLiveSeconds">4</attribute>

            </region>

            <region name="/maxAgeTest">

               <attribute name="maxNodes">10000</attribute>

               <attribute name="timeToLiveSeconds">8</attribute>

               <attribute name="maxAgeSeconds">10</attribute>

            </region>

         </config>

      </attribute>

   </mbean>

</server>

11.2.  Reference table of XML attributes

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

Name

Description

BuddyReplicationConfig

An XML element that contains detailed buddy replication configuration. See section on Buddy Replication for details.

CacheLoaderConfig

An XML element that contains detailed cache loader configuration. See chapter on Cache Loaders for details.

CacheLoaderConfiguration

Deprecated . Use CacheLoaderConfig .

CacheMode

LOCAL, REPL_SYNC, REPL_ASYNC, INVALIDATION_SYNC or INVALIDATION_ASYNC. Defaults to LOCAL. See the chapter on Clustering for details.

ClusterConfig

The configuration of the underlying JGroups stack. Ignored if MultiplexerService and MultiplexerStack are used. See the various *-service.xml files in the source distribution etc/META-INF folder for examples. See the JGroups documentation or the JGroups wiki page for more information.

ClusterName

Name of cluster. Needs to be the same for all nodes in a cluster in order for them to communicate with each other.

EvictionPolicyConfig

Configuration parameter for the specified eviction policy. See chapter on eviction policies for details. This property is dynamic .

ExposeManagementStatistics

Specifies whether interceptors that provide statistics should have statistics gathering enabled at startup. Also controls whether a CacheMgmtInterceptor (whose sole purpose is gathering statistics) should be added to the interceptor chain. Default value is true . See the JBoss Cache Statistics section section for more details.

FetchInMemoryState

Whether or not to acquire the initial in-memory state from existing members. Allows for hot caches when enabled. Also see the fetchPersistentState element in CacheLoaderConfig . Defaults to true . This property is dynamic .

InactiveOnStartup

Whether or not the entire tree is inactive upon startup, only responding to replication messages after activateRegion() is called to activate one or more parts of the tree. If true, property FetchInMemoryState is ignored. This property should only be set to true if UseRegionBasedMarshalling is also true .

StateRetrievalTimeout

Time in milliseconds to wait for state retrieval. This should be longer than LockAcquisitionTimeout as the node providing state may need to wait that long to acquire necessary read locks on the cache. This property is dynamic .

IsolationLevel

Node locking isolation level : SERIALIZABLE, REPEATABLE_READ (default), READ_COMMITTED, READ_UNCOMMITTED, and NONE. Note that this is ignored if NodeLockingScheme is OPTIMISTIC. Case doesn't matter. See documentation on Transactions and Concurrency for more details.

LockAcquisitionTimeout

Time in milliseconds to wait for a lock to be acquired. If a lock cannot be acquired an exception will be thrown. This property is dynamic .

LockParentForChildInsertRemove

Controls whether inserting or removing a node requires a write lock on the node's parent (when pessimistic locking is used) or whether it results in an update of the parent node's version (when optimistic locking is used). The default value is false .

MarshallerClass

An instance of org.jboss.cache.marshall.Marshaller used to serialize data to byte streams. Defaults to org.jboss.cache.marshall.VersionAwareMarshaller if not specified.

MultiplexerService

The JMX object name of the service that defines the JGroups multiplexer. In JBoss AS 5.0 this service is normally defined in the jgroups-multiplexer.sar. This XML attribute can only be handled by the JBoss AS MBean deployment services; if it is included in a file passed to a CacheFactory the factory's creation of the cache will fail. Inside JBoss AS, the attribute should be specified using the "depends optional-attribute-name" syntax shown in the example above. Inside the AS if this attribute is defined, an instance of org.jgroups.jmx.JChannelFactoryMBean will be injected into the CacheJmxWrapper which will use it to obtain a multiplexed JGroups channel. The configuration of the channel will be that associated with MultiplexerStack . The ClusterConfig attribute will be ignored.

MultiplexerStack

The name of the JGroups stack to be used with the cache cluster. Stacks are defined in the configuration of the external MultiplexerService discussed above. In JBoss AS 5 this is normally done in the jgroups-multiplexer.sar/META-INF/multiplexer-stacks.xml file. The default stack is udp . This attribute is used in conjunction with MultiplexerService .

NodeLockingScheme

May be PESSIMISTIC (default) or OPTIMISTIC.

ReplicationVersion

Tells the cache to serialize cluster traffic in a format consistent with that used by the given release of JBoss Cache. Different JBoss Cache versions use different wire formats; setting this attribute tells a cache from a later release to serialize data using the format from an earlier release. This allows caches from different releases to interoperate. For example, a 2.1.0 cache could have this value set to "2.0.0", allowing it to interoperate with a 2.0.0 cache. Valid values are a dot-separated release number, with any final qualifer also separated by a dot, e.g. "2.0.0" or "2.0.0.GA". Values that indicate a 1.x release are not supported in the 2.x series.

ReplQueueInterval

Time in milliseconds for elements from the replication queue to be replicated. Only used if UseReplQueue is enabled. This property is dynamic .

ReplQueueMaxElements

Max number of elements in the replication queue until replication kicks in. Only used if UseReplQueue is enabled. This property is dynamic .

SyncCommitPhase

This option is used to control the behaviour of the commit part of a 2-phase commit protocol, when using REPL_SYNC (does not apply to other cache modes). By default this is set to false . There is a performance penalty to enabling this, especially when running in a large cluster, but the upsides are greater cluster-wide data integrity. See the chapter on clustered caches for more information on this. This property is dynamic .

SyncReplTimeout

For synchronous replication: time in milliseconds to wait until replication acks have been received from all nodes in the cluster. It is usually best that this is greater than LockAcquisitionTimeout . This property is dynamic .

SyncRollbackPhase

This option is used to control the behaviour of the rollback part of a 2-phase commit protocol, when using REPL_SYNC (does not apply to other cache modes). By default this is set to false . There is a performance penalty to enabling this, especially when running in a large cluster, but the upsides are greater cluster-wide data integrity. See the chapter on clustered caches for more information on this. This property is dynamic .

TransactionManagerLookupClass

The fully qualified name of a class implementing TransactionManagerLookup. Default is JBossTransactionManagerLookup. There is also an option of GenericTransactionManagerLookup for example.

UseInterceptorMbeans

Deprecated . Use ExposeManagementStatistics .

UseRegionBasedMarshalling

When unmarshalling replicated data, this option specifies whether or not to support use of different classloaders for different cache regions. This defaults to false if unspecified. <p></p> <b>DEPRECATED.</b> This option will disappear in JBoss Cache 3.x. See UseLazyDeserialization instead.

UseReplQueue

For asynchronous replication: whether or not to use a replication queue. Defaults to false .

ShutdownHookBehavior

An optional parameter that controls whether JBoss Cache registers a shutdown hook with the JVM runtime. Allowed values areDEFAULT, REGISTER and DONT_REGISTER. REGISTER and DONT_REGISTER forces or suppresses the registration of a shutdown hook, respectively, and DEFAULT registers one if an MBean server (other than the JDK default) cannot be found and it is assumed that the cache is running in a managed environment. The default if unspecified is, as expected, DEFAULT.

UseLazyDeserialization

An optional parameter that can be used to enable or disable the use of lazy deserialization for cached objects. Defaults tofalse, since it adds a small processing overhead. If lazy deserialization is disabled, support for implicitly using context class loaders registered with the calling thread goes away.

ObjectInputStreamPoolSize and ObjectOutputStreamPoolSize

Since JBoss Cache 2.1.0, object input and output streams - used to serialize and deserialize RPC calls in a cluster - are pooled to reduce the overhead of constructing such streams. They are reused by making use of special resettable stream implementations.

by default, these stream pools are set at 50 objects each. You could increase or decrease the pool size if, while profiling, you see a lot of threads blocking on ObjectStreamPool.getInputStream() orObjectStreamPool.getOutputStream(). In general, having more streams is better than having fewer than needed. Based on your application, make sure you have more streams available than number of threads you expect to concurrently write to the cache.