Chapter 11. Configuration
Prev |  | Next

## Chapter 11. Configuration

All properties of the cache are configured via setters and can be retrieved via getters. This can be done either manually, or via the `PropertyConfigurator` and an XML file.

## 11.1. Sample XML-Based Configuration

A sample XML configuration file is shown below:

    <?xml version="1.0" encoding="UTF-8" ?>
    <server>
      <classpath codebase="./lib" archives="jboss-cache.jar, jgroups.jar" />

      <!--  ====================================================================  -->
      <!--  Defines TreeCache configuration                                       -->
      <!--  ====================================================================  -->
      <mbean code="org.jboss.cache.TreeCache" name="jboss.cache:service=TreeCache">
        <depends>jboss:service=Naming</depends>
        <depends>jboss:service=TransactionManager</depends>

        <!-- Configure the TransactionManager -->
        <attribute name="TransactionManagerLookupClass">org.jboss.cache.DummyTransactionManagerLookup</attribute>

    	<!--
    			Node locking scheme :
    								PESSIMISTIC (default)
    								OPTIMISTIC
    	-->
    	<attribute name="NodeLockingScheme">PESSIMISTIC</attribute>

        <!--
                Node locking isolation level :
    								 SERIALIZABLE
                                     REPEATABLE_READ (default)
                                     READ_COMMITTED
                                     READ_UNCOMMITTED
                                     NONE

    			(ignored if NodeLockingScheme is OPTIMISTIC)
        -->
        <attribute name="IsolationLevel">REPEATABLE_READ</attribute>

        <!--     Valid modes are LOCAL
                                 REPL_ASYNC
                                 REPL_SYNC
                                 INVALIDATION_ASYNC
                                 INVALIDATION_SYNC
        -->
        <attribute name="CacheMode">LOCAL</attribute>

        <!--  Whether each interceptor should have an mbean
            registered to capture and display its statistics.  -->
        <attribute name="UseInterceptorMbeans">true</attribute>

        <!-- Name of cluster. Needs to be the same for all clusters, in order
                 to find each other -->
        <attribute name="ClusterName">JBoss-Cache-Cluster</attribute>

        <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="45566" 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" up_thread="false" down_thread="false" />
            <MERGE2 min_interval="10000" max_interval="20000" />
            <FD shun="true" up_thread="true" down_thread="true" />
            <VERIFY_SUSPECT timeout="1500" up_thread="false" down_thread="false" />
            <pbcast.NAKACK gc_lag="50" max_xmit_size="8192" retransmit_timeout="600,1200,2400,4800" up_thread="false"
               down_thread="false" />
            <UNICAST timeout="600,1200,2400" window_size="100" min_threshold="10" down_thread="false" />
            <pbcast.STABLE desired_avg_gossip="20000" up_thread="false" down_thread="false" />
            <FRAG frag_size="8192" down_thread="false" up_thread="false" />
            <pbcast.GMS join_timeout="5000" join_retry_timeout="2000" shun="true" print_local_addr="true" />
            <pbcast.STATE_TRANSFER up_thread="false" down_thread="false" />
          </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="InitialStateRetrievalTimeout">5000</attribute>

        <!--    Number of milliseconds to wait until all responses for a
                synchronous call have been received.
        -->
        <attribute name="SyncReplTimeout">10000</attribute>

        <!--  Max number of milliseconds to wait for a lock acquisition -->
        <attribute name="LockAcquisitionTimeout">15000</attribute>

        <!--  Name of the eviction policy class. -->
        <attribute name="EvictionPolicyClass">org.jboss.cache.eviction.LRUPolicy</attribute>

        <!--  Specific eviction policy configurations. This is LRU -->
        <attribute name="EvictionPolicyConfig">
          <config>
            <attribute name="wakeUpIntervalSeconds">5</attribute>
            <!--  Cache wide default -->
            <region name="/_default_">
             <attribute name="maxNodes">5000</attribute>
             <attribute name="timeToLiveSeconds">1000</attribute>
             <!-- Maximum time an object is kept in cache regardless of idle time -->
             <attribute name="maxAgeSeconds">120</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>
          </config>
        </attribute>

            <!-- New 1.3.x cache loader config block -->
            <attribute name="CacheLoaderConfiguration">
                <config>
                    <!-- if passivation is true, only the first cache loader is used; the rest are ignored -->
                    <passivation>false</passivation>
                    <preload>/a/b, /allTempObjects, /some/specific/fqn</preload>
                    <shared>false</shared>

                    <!-- we can now have multiple cache loaders, which get chained -->
                    <cacheloader>
                        <class>org.jboss.cache.loader.FileCacheLoader</class>
                        <!-- same as the old CacheLoaderConfig attribute -->
                        <properties>
                            location=/tmp/myFileStore
                        </properties>
                        <!-- whether the cache loader writes are asynchronous -->
                        <async>false</async>
                        <!-- only one cache loader in the chain may set fetchPersistentState to true.
                            An exception is thrown if more than one cache loader sets this to true. -->
                        <fetchPersistentState>true</fetchPersistentState>
                        <!-- determines whether this cache loader ignores writes - defaults to false. -->
                        <ignoreModifications>false</ignoreModifications>
                        <!-- if set to true, purges the contents of this cache loader when the cache starts up.
                        Defaults to false.  -->
                        <purgeOnStartup>false</purgeOnStartup>
                    </cacheloader>

                    <cacheloader>
                        <class>org.jboss.cache.loader.JDBCCacheLoader</class>
                        <!-- same as the old CacheLoaderConfig attribute -->
                        <properties>
                            cache.jdbc.driver=com.mysql.jdbc.Driver
                            cache.jdbc.url=jdbc:mysql://localhost:3306/jbossdb
                            cache.jdbc.user=root
                            cache.jdbc.password=
                        </properties>
                        <!-- whether the cache loader writes are asynchronous -->
                        <async>true</async>
                        <!-- only one cache loader in the chain may set fetchPersistentState to true.
                            An exception is thrown if more than one cache loader sets this to true. -->
                        <fetchPersistentState>false</fetchPersistentState>
                        <!-- determines whether this cache loader ignores writes - defaults to false. -->
                        <ignoreModifications>true</ignoreModifications>
                        <!-- if set to true, purges the contents of this cache loader when the cache starts up.
                        Defaults to false.  -->
                        <purgeOnStartup>false</purgeOnStartup>
                    </cacheloader>

                </config>
            </attribute>

      </mbean>
    </server>

The PropertyConfigurator.configure() method needs to have as argument a filename which is located on the classpath; it will use be used to configure JBoss Cache from the properties defined in it. Note that this configuration file is used to configure JBoss Cache both as a standalone cache, and as an MBean if run inside the JBoss container.[8]

## 11.2. Definition of XML attributes

A list of definitions of each of the XML attributes used above:

Name | Description
BuddyReplicationConfig | An XML element that contains detailed buddy replication configuration. See section above on Buddy Replication.
CacheLoaderConfiguration | An XML element that contains detailed cache loader configuration. See section above on Cache Loaders.
CacheMode | LOCAL, REPL_SYNC, REPL_ASYNC, INVALIDATION_SYNC or INVALIDATION_ASYNC
ClusterName | Name of cluster. Needs to be the same for all nodes in a cluster in order to find each other.
ClusterConfig | The configuration of the underlying JGroups stack. See cluster-service.xml for an example.
EvictionPolicyClass | The name of a class implementing EvictionPolicy. If empty, no eviction policy is enabled.
EvictionPolicyConfig | Configuration parameter for the specified eviction policy. Note that the content is provider specific.
FetchInMemoryState (renamed from FetchStateOnStartup) | Whether or not to acquire the initial in-memory state from existing members. Allows for warm/hot caches (true/false). Also see the fetchPersistentState element in CacheLoaderConfiguration.
InitialStateRetrievalTimeout | Time in milliseconds to wait for initial 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.
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`.
NodeLockingScheme | May be PESSIMISTIC (default) or OPTIMISTIC. See documentation on Transactions and Concurrency for more details.
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.
ReplicationVersion | Tells the cache to serialize replication 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 1.2.4.SP2 cache could have this value set to "1.2.3", allowing it to interoperate with a 1.2.3 cache. Valid values are a dot-separated release number, with any SP qualifer also separated by a dot, e.g. "1.2.3" or "1.2.4.SP2".
ReplQueueInterval | Time in milliseconds for elements from the replication queue to be replicated.
SyncReplTimeout | For synchronous replication: time in milliseconds to wait until replication acks have been received from all nodes in the cluster.
ReplQueueMaxElements | Max number of elements in the replication queue until replication kicks in.
StateTransferVersion | The binary format to use for state transfer data. Different releases of JBossCache use different formats; if this attribute is set a later release will use an earlier release's format, allowing interoperability. Valid values are "124" for JBossCache 1.2.4, "130" for release 1.3.0, etc. Earliest valid version is 124.
TransactionManagerLookupClass | The fully qualified name of a class implementing TransactionManagerLookup. Default is JBossTransactionManagerLookup. There is also an option of DummyTransactionManagerLookup for example.
UseInterceptorMbeans | Specifies whether each interceptor should have an associated mbean registered. Interceptor mbeans are used to capture and display statistics. This setting enables or disables all such interceptor mbeans. Default value is true.
UseRegionBasedMarshalling | When unmarshalling replicated data, this option specifies whether or not to use different classloaders (for different cache regions). This defaults to `false` if unspecified.
UseReplQueue | For asynchronous replication: whether or not to use a replication queue (true/false).

## 11.3. Overriding options

As of JBoss Cache 1.3.0, a new API has been introduced, to allow you to override certain behaviour of the cache on a per invocation basis. This involves creating an instance of `org.jboss.cache.config.Option`, setting the options you wish to override on the `Option` object and passing it in as a parameter to overloaded versions of `get()`, `put()` and `remove()`. See the javadocs on the `Option` class for details on these options.

[8] We will switch to using an XMBean in a future release.

Prev | Up | Next
Chapter 10. Version Compatibility and Interoperability | Home | Chapter 12. Management Information