2.2. JBossCache Configuration

JBoss Cache provides distributed cache and state replication services for the JBoss cluster. A JBoss cluster can have multiple JBoss Cache MBeans (known as the TreeCache MBean), one for HTTP session replication, one for stateful session beans, one for cached entity beans, etc. A generic TreeCache MBean configuration is listed below. Application specific TreeCache MBean configurations are covered in later chapters when those applications are discussed.

<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 level : SERIALIZABLE
                                 REPEATABLE_READ (default)
                                 READ_COMMITTED
                                 READ_UNCOMMITTED
                                 NONE        
    --> 
    <attribute name="IsolationLevel">REPEATABLE_READ</attribute> 

    <! --     Valid modes are LOCAL
                             REPL_ASYNC
                             REPL_SYNC
    --> 
    <attribute name="CacheMode">LOCAL</attribute>
 
    <! -- Name of cluster. Needs to be the same for all clusters, in order
             to find each other --> 
    <attribute name="ClusterName">TreeCache-Cluster</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> 
            </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>

    <attribute name="CacheLoaderClass">
        org.jboss.cache.loader.bdbje.BdbjeCacheLoader
    </attribute>
    
    <attribute name="CacheLoaderConfig">
       location=c:\\tmp
    </attribute>
    <attribute name="CacheLoaderShared">true</attribute>
    <attribute name="CacheLoaderPreload">
        /a/b/c,/all/my/objects
    </attribute>
    <attribute name="CacheLoaderFetchTransientState">false</attribute>
    <attribute name="CacheLoaderFetchPersistentState">true</attribute>
    
    <attribute name="ClusterConfig">
        ... JGroups config for the cluster ...
    </attribute>
</mbean>

The JGroups configuration element (i.e., the ClusterConfig attribute) is omitted from the above listing. You have learned how to configure JGroups earlier in this chapter (Section 2.1, “JGroups Configuration”). The TreeCache MBean takes the following attributes.

CacheLoaderClass specifies the fully qualified class name of the CacheLoader implementation.
CacheLoaderConfig contains a set of properties from which the specific CacheLoader implementation can configure itself.
CacheLoaderFetchPersistentState specifies whether to fetch the persistent state from another node. The persistence is fetched only if CacheLoaderShared is false. This attribute is only used if FetchStateOnStartup is true.
CacheLoaderFetchTransientState specifies whether to fetch the in-memory state from another node. This attribute is only used if FetchStateOnStartup is true.
CacheLoaderPreload contains a list of comma-separate nodes that need to be preloaded (e.g., /aop, /productcatalogue).
CacheLoaderShared specifies whether we want to shared a datastore, or whether each node wants to have its own local datastore.
CacheMode specifies how to synchronize cache between nodes. The possible values are LOCAL, REPL_SYNC, or REPL_ASYNC.
ClusterName specifies the name of the cluster. This value needs to be the same for all nodes in a cluster in order for them to find each other.
ClusterConfig contains the configuration of the underlying JGroups stack (see Section 2.1, “JGroups Configuration”.
EvictionPolicyClass specifies the name of a class implementing EvictionPolicy. You can use a JBoss Cache provided EvictionPolicy class or provide your own policy implementation. If this attribute is empty, no eviction policy is enabled.
EvictionPolicyConfig contains the configuration parameter for the specified eviction policy. Note that the content is provider specific.
FetchStateOnStartup specifies whether or not to acquire the initial state from existing members. It allows for warm/hot caches (true/false). This can be further defined by CacheLoaderFetchTransientState and CacheLoaderFetchPersistentState.
InitialStateRetrievalTimeout specifies the time in milliseconds to wait for initial state retrieval.
IsolationLevel specifies the node locking level. Possible values are SERIALIZABLE, REPEATABLE_READ (default), READ_COMMITTED, READ_UNCOMMITTED, and NONE.
LockAcquisitionTimeout specifies the time in milliseconds to wait for a lock to be acquired. If a lock cannot be acquired an exception will be thrown.
ReplQueueInterval specifies the time in milliseconds for elements from the replication queue to be replicated.
SyncReplTimeout specifies the time in milliseconds to wait until replication ACKs have been received from all nodes in the cluster. This attribute applies to synchronous replication mode only (i.e., CacheMode attribute is REPL_SYNC).
UseReplQueue specifies whether or not to use a replication queue (true/false). This attribute applies to synchronous replication mode only (i.e., CacheMode attribute is REPL_ASYNC).
ReplQueueMaxElements specifies the maximum number of elements in the replication queue until replication kicks in.
TransactionManagerLookupClass specifies the fully qualified name of a class implementing TransactionManagerLookup. The default is JBossTransactionManagerLookup for the transaction manager inside the JBoss AS. There is also an option of DummyTransactionManagerLookup for simple standalone examples.