 <chapter id="configuration">
    <title>Configuration</title>

    <para>All properties of the cache are configured via setters and can be
    retrieved via getters. This can be done either manually, or via the
    <literal>PropertyConfigurator</literal> and an XML file.</para>
	<section>
		<title>Sample XML-Based Configuration</title>
		<para>
			A sample XML configuration file is shown
		    below:
		</para>
    <programlisting>&lt;?xml version="1.0" encoding="UTF-8" ?&gt;
&lt;server&gt;
  &lt;classpath codebase="./lib" archives="jboss-cache.jar, jgroups.jar" /&gt;

  &lt;!--  ====================================================================  --&gt;
  &lt;!--  Defines TreeCache configuration                                       --&gt;
  &lt;!--  ====================================================================  --&gt;
  &lt;mbean code="org.jboss.cache.TreeCache" name="jboss.cache:service=TreeCache"&gt;
    &lt;depends&gt;jboss:service=Naming&lt;/depends&gt;
    &lt;depends&gt;jboss:service=TransactionManager&lt;/depends&gt;


    &lt;!-- Configure the TransactionManager --&gt;
    &lt;attribute name="TransactionManagerLookupClass"&gt;org.jboss.cache.DummyTransactionManagerLookup&lt;/attribute&gt;

	&lt;!-- 
			Node locking scheme : 
								PESSIMISTIC (default)
								OPTIMISTIC 
	--&gt;
	&lt;attribute name="NodeLockingScheme"&gt;PESSIMISTIC&lt;/attribute&gt;		

    &lt;!--
            Node locking isolation level : 
								 SERIALIZABLE
                                 REPEATABLE_READ (default)
                                 READ_COMMITTED
                                 READ_UNCOMMITTED
                                 NONE

			(ignored if NodeLockingScheme is OPTIMISTIC)
    --&gt;
    &lt;attribute name="IsolationLevel"&gt;REPEATABLE_READ&lt;/attribute&gt;

    &lt;!-- Lock parent before doing node additions/removes --&gt;
    &lt;attribute name="LockParentForChildInsertRemove"&gt;true&lt;/attribute&gt;

    &lt;!--     Valid modes are LOCAL
                             REPL_ASYNC
                             REPL_SYNC
                             INVALIDATION_ASYNC
                             INVALIDATION_SYNC
    --&gt;
    &lt;attribute name="CacheMode"&gt;LOCAL&lt;/attribute&gt;
    
    &lt;!--  Whether each interceptor should have an mbean
        registered to capture and display its statistics.  --&gt;
    &lt;attribute name="UseInterceptorMbeans"&gt;true&lt;/attribute&gt;

    &lt;!-- Name of cluster. Needs to be the same for all TreeCache nodes in a
    cluster, in order to find each other --&gt;
    &lt;attribute name="ClusterName"&gt;JBoss-Cache-Cluster&lt;/attribute&gt;

    &lt;!-- Uncomment next three statements to enable JGroups multiplexer.
         This configuration is dependent on the JGroups multiplexer being
         registered in an MBean server such as JBossAS. --&gt;
    &lt;!--
    &lt;depends&gt;jgroups.mux:name=Multiplexer&lt;/depends&gt;
    &lt;attribute name="MultiplexerService"&gt;jgroups.mux:name=Multiplexer&lt;/attribute&gt;
    &lt;attribute name="MultiplexerStack"&gt;udp&lt;/attribute&gt;
    --&gt;

    &lt;!-- JGroups protocol stack properties. ClusterConfig isn't used if the
     multiplexer is enabled and successfully initialized. --&gt;
    &lt;attribute name="ClusterConfig"&gt;
      &lt;config&gt;
        &lt;!-- UDP: if you have a multihomed machine,
                set the bind_addr attribute to the appropriate NIC IP address
        --&gt;
        &lt;!-- 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
        --&gt;
        &lt;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" /&gt;
        &lt;PING timeout="2000" num_initial_members="3" up_thread="false" down_thread="false" /&gt;
        &lt;MERGE2 min_interval="10000" max_interval="20000" /&gt;
        &lt;FD shun="true" up_thread="true" down_thread="true" /&gt;
        &lt;VERIFY_SUSPECT timeout="1500" up_thread="false" down_thread="false" /&gt;
        &lt;pbcast.NAKACK gc_lag="50" max_xmit_size="8192" retransmit_timeout="600,1200,2400,4800" up_thread="false"
           down_thread="false" /&gt;
        &lt;UNICAST timeout="600,1200,2400" window_size="100" min_threshold="10" down_thread="false" /&gt;
        &lt;pbcast.STABLE desired_avg_gossip="20000" up_thread="false" down_thread="false" /&gt;
        &lt;FRAG frag_size="8192" down_thread="false" up_thread="false" /&gt;
        &lt;pbcast.GMS join_timeout="5000" join_retry_timeout="2000" shun="true" print_local_addr="true" /&gt;
        &lt;pbcast.STATE_TRANSFER up_thread="false" down_thread="false" /&gt;
      &lt;/config&gt;
    &lt;/attribute&gt;

    &lt;!--    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
    --&gt;
    &lt;attribute name="InitialStateRetrievalTimeout"&gt;5000&lt;/attribute&gt;

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

    &lt;!--  Max number of milliseconds to wait for a lock acquisition --&gt;
    &lt;attribute name="LockAcquisitionTimeout"&gt;15000&lt;/attribute&gt;

    &lt;!--  Name of the eviction policy class. --&gt;
    &lt;attribute name="EvictionPolicyClass"&gt;org.jboss.cache.eviction.LRUPolicy&lt;/attribute&gt;

    &lt;!--  Specific eviction policy configurations. This is LRU --&gt;
    &lt;attribute name="EvictionPolicyConfig"&gt;
      &lt;config&gt;
        &lt;attribute name="wakeUpIntervalSeconds"&gt;5&lt;/attribute&gt;
        &lt;!--  Cache wide default --&gt;
        &lt;region name="/_default_"&gt;
         &lt;attribute name="maxNodes"&gt;5000&lt;/attribute&gt;
         &lt;attribute name="timeToLiveSeconds"&gt;1000&lt;/attribute&gt;
         &lt;!-- Maximum time an object is kept in cache regardless of idle time --&gt;
         &lt;attribute name="maxAgeSeconds"&gt;120&lt;/attribute&gt;
       &lt;/region&gt;

       &lt;region name="/org/jboss/data"&gt;
         &lt;attribute name="maxNodes"&gt;5000&lt;/attribute&gt;
         &lt;attribute name="timeToLiveSeconds"&gt;1000&lt;/attribute&gt;
       &lt;/region&gt;

       &lt;region name="/org/jboss/test/data"&gt;
         &lt;attribute name="maxNodes"&gt;5&lt;/attribute&gt;
         &lt;attribute name="timeToLiveSeconds"&gt;4&lt;/attribute&gt;
       &lt;/region&gt;
      &lt;/config&gt;
    &lt;/attribute&gt;

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

                &lt;!-- we can now have multiple cache loaders, which get chained --&gt;
                &lt;cacheloader&gt;
                    &lt;class&gt;org.jboss.cache.loader.FileCacheLoader&lt;/class&gt;
                    &lt;!-- same as the old CacheLoaderConfig attribute --&gt;
                    &lt;properties&gt;
                        location=/tmp/myFileStore
                    &lt;/properties&gt;
                    &lt;!-- whether the cache loader writes are asynchronous --&gt;
                    &lt;async&gt;false&lt;/async&gt;
                    &lt;!-- 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. --&gt;
                    &lt;fetchPersistentState&gt;true&lt;/fetchPersistentState&gt;
                    &lt;!-- determines whether this cache loader ignores writes - defaults to false. --&gt;
                    &lt;ignoreModifications&gt;false&lt;/ignoreModifications&gt;
                    &lt;!-- if set to true, purges the contents of this cache loader when the cache starts up.
                    Defaults to false.  --&gt;
                    &lt;purgeOnStartup&gt;false&lt;/purgeOnStartup&gt;
                &lt;/cacheloader&gt;

                &lt;cacheloader&gt;
                    &lt;class&gt;org.jboss.cache.loader.JDBCCacheLoader&lt;/class&gt;
                    &lt;!-- same as the old CacheLoaderConfig attribute --&gt;
                    &lt;properties&gt;
                        cache.jdbc.driver=com.mysql.jdbc.Driver
                        cache.jdbc.url=jdbc:mysql://localhost:3306/jbossdb
                        cache.jdbc.user=root
                        cache.jdbc.password=
                    &lt;/properties&gt;
                    &lt;!-- whether the cache loader writes are asynchronous --&gt;
                    &lt;async&gt;true&lt;/async&gt;
                    &lt;!-- 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. --&gt;
                    &lt;fetchPersistentState&gt;false&lt;/fetchPersistentState&gt;
                    &lt;!-- determines whether this cache loader ignores writes - defaults to false. --&gt;
                    &lt;ignoreModifications&gt;true&lt;/ignoreModifications&gt;
                    &lt;!-- if set to true, purges the contents of this cache loader when the cache starts up.
                    Defaults to false.  --&gt;
                    &lt;purgeOnStartup&gt;false&lt;/purgeOnStartup&gt;
                &lt;/cacheloader&gt;

            &lt;/config&gt;
        &lt;/attribute&gt;


  &lt;/mbean&gt;
&lt;/server&gt;     </programlisting>

    <para>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.<footnote>
        <para>We will switch to using an XMBean in a future release.</para>
      </footnote></para>
</section>

<section>
	<title>
		Definition of XML attributes
	</title>
    <para>A list of definitions of each of the XML attributes used above:</para>

    <informaltable frame="all">
      <tgroup cols="2">
        <tbody>
          <row>
            <entry>
              <para>Name</para>
            </entry>

            <entry>
              <para>Description</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>BuddyReplicationConfig</para>
            </entry>

            <entry>
              <para>An XML element that contains detailed buddy replication
              configuration. See section above on Buddy Replication.</para>
            </entry>
          </row>

          <row>
            <entry>
              <para>CacheLoaderConfiguration</para>
            </entry>

            <entry>
              <para>An XML element that contains detailed cache loader
              configuration. See section above on Cache Loaders.</para>
            </entry>
          </row>

          <row>
            <entry>
              <para>CacheMode</para>
            </entry>

            <entry>
              <para>LOCAL, REPL_SYNC, REPL_ASYNC, INVALIDATION_SYNC or
              INVALIDATION_ASYNC</para>
            </entry>
          </row>

          <row>
            <entry>
              <para>ClusterConfig</para>
            </entry>

            <entry>
              <para>The configuration of the underlying JGroups stack.              
              Ignored if <literal>MultiplexerService</literal> and
              <literal>MultiplexerStack</literal> are used. 
              See the various *-service.xml files in the source distribution
              <literal>etc/META-INF</literal> folder for examples.
              See the <ulink  url="http://www.jgroups.org">JGroups documentation</ulink>
              or the <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JGroups">JGroups wiki page</ulink> 
              for more information.</para>
            </entry>
          </row>

          <row>
            <entry>
              <para>ClusterName</para>
            </entry>

            <entry>
              <para>Name of cluster. Needs to be the same for all nodes in a
              cluster in order for them to communicate with each other.</para>
            </entry>
          </row>

          <row>
            <entry>
              <para>EvictionPolicyClass</para>
            </entry>

            <entry>
              <para>The name of a class implementing EvictionPolicy. Deprecated;
              it is preferable to configure the eviction policy class as 
              part of the <literal>EvictionPolicyConfig</literal>.</para>
            </entry>
          </row>

          <row>
            <entry>
              <para>EvictionPolicyConfig</para>
            </entry>

            <entry>
              <para>Configuration parameter for the specified eviction policy.
              Note that the content is provider specific.</para>
            </entry>
          </row>

          <row>
            <entry>
              <para>FetchInMemoryState (renamed from
              FetchStateOnStartup)</para>
            </entry>

            <entry>
              <para>Whether or not to acquire the initial in-memory state from
              existing members. Allows for hot/cold caches (true/false). Also
              see the fetchPersistentState element in
              CacheLoaderConfiguration.</para>
            </entry>
          </row>

          <row>
            <entry>
              <para>InactiveOnStartup</para>
            </entry>

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

          <row>
            <entry>
              <para>InitialStateRetrievalTimeout</para>
            </entry>

            <entry>
              <para>Time in milliseconds to wait for initial state
              retrieval. This should be longer than 
              <literal>LockAcquisitionTimeout</literal> as the node 
              providing state may need to wait that long to acquire
              necessary read locks on the cache.</para>
            </entry>
          </row>

          <row>
            <entry>
              <para>IsolationLevel</para>
            </entry>

            <entry>
              <para>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.
                     </para>
            </entry>
          </row>

          <row>
            <entry>
              <para>LockAcquisitionTimeout</para>
            </entry>

            <entry>
              <para>Time in milliseconds to wait for a lock to be acquired. If
              a lock cannot be acquired an exception will be thrown.</para>
            </entry>
          </row>

          <row>
            <entry>
              <para>LockParentForChildInsertRemove</para>
            </entry>

            <entry>
            <para>Controls whether inserting or removing a node requires a write 
            lock on the node's parent (when pessimistic locking is used). The 
            default value is <code>false</code>.</para>
            </entry>
          </row>

           <row>
              <entry>
                 <para>MultiplexerService</para>
              </entry>

              <entry>
                 <para>The JMX object name of the service that defines the JGroups multiplexer.
                    In JBoss AS 5 this service is normally defined in the jgroups-multiplexer.sar.
                    If this attribute is defined, the cache will look up the multiplexer service 
                    in JMX and will use it to obtain a multiplexed JGroups channel. The configuration
                    of the channel will be that associated with <literal>MultiplexerStack</literal>.
                    The <literal>ClusterConfig</literal> attribute will be ignored.
                 </para>
              </entry>
           </row>

           <row>
              <entry>
                 <para>MultiplexerStack</para>
              </entry>

              <entry>
                 <para>The name of the JGroups stack to be used with the TreeCache cluster.
                    Stacks are defined in the configuration of the external <literal>MultiplexerService</literal>
                    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 <literal>udp</literal>. This attribute is used in conjunction with
                    <literal>MultiplexerService</literal>.
                 </para>
              </entry>
           </row>

          <row>
            <entry>
              <para>NodeLockingScheme</para>
            </entry>

            <entry>
              <para>May be PESSIMISTIC (default) or OPTIMISTIC.  See documentation on Transactions and Concurrency for more details.</para>
            </entry>
          </row>

          <row>
             <entry><para>ReplicationVersion</para></entry>
             <entry><para>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 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".
             </para></entry>
          </row>

          <row>
            <entry>
              <para>ReplQueueInterval</para>
            </entry>

            <entry>
              <para>Time in milliseconds for elements from the replication
              queue to be replicated.</para>
            </entry>
          </row>

          <row>
            <entry>
              <para>ReplQueueMaxElements</para>
            </entry>

            <entry>
              <para>Max number of elements in the replication queue until
              replication kicks in.</para>
            </entry>
          </row>

          <row>
            <entry>
              <para>SyncCommitPhase</para>
            </entry>

            <entry>
              <para>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
                    <literal>false</literal>.  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.
              </para>
            </entry>
          </row>

          <row>
            <entry>
              <para>SyncReplTimeout</para>
            </entry>

            <entry>
              <para>For synchronous replication: time in milliseconds to wait
              until replication acks have been received from all nodes in the
              cluster.</para>
            </entry>
          </row>

           <row>
             <entry>
               <para>SyncRollbackPhase</para>
             </entry>

             <entry>
               <para>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
                     <literal>false</literal>.  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.
               </para>
             </entry>
           </row>

          <row>
            <entry>
              <para>TransactionManagerLookupClass</para>
            </entry>

            <entry>
              <para>The fully qualified name of a class implementing
              TransactionManagerLookup. Default is
              JBossTransactionManagerLookup. There is also an option of
              DummyTransactionManagerLookup for example.</para>
            </entry>
          </row>
          
          <row>
            <entry>
              <para>UseInterceptorMbeans</para>
            </entry>

            <entry>
              <para> Specifies whether each interceptor should have an associated
              mbean registered.  Interceptor mbeans are used to capture statistics
              and display them in JMX.  This setting enables or disables all such interceptor 
              mbeans.  Default value is <emphasis>true</emphasis>.</para>
            </entry>
          </row>

          <row>
            <entry>
              <para>UseRegionBasedMarshalling</para>
            </entry>

            <entry>
              <para>When unmarshalling replicated data, this option specifies whether or not to use
                  different classloaders (for different cache regions).  This defaults to <literal>false</literal> if unspecified.</para>
            </entry>
          </row>

          <row>
            <entry>
              <para>UseReplQueue</para>
            </entry>

            <entry>
              <para>For asynchronous replication: whether or not to use a
              replication queue (true/false).</para>
            </entry>
          </row>

            <row>
            <entry>
              <para>LockParentForChildInsertRemove</para>
            </entry>

            <entry>
              <para>
                 When used with pessimistic locking and <literal>IsolationLevel</literal> of <literal>REPEATABLE_READ</literal>,
                 this parameter specifies whether parent nodes need to be locked for writing when adding or removing child nodes.
                 This prevents phantom reads, providing "stronger-than-repeatable-read" data integrity.  This defaults to <literal>false</literal>
                 and is ignored if used with optimistic locking or other isolation levels.
              </para>
            </entry>
          </row>

        </tbody>
      </tgroup>
    </informaltable>
</section>
     <section>
         <title>Overriding options</title>
         <para>
             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 <literal>org.jboss.cache.config.Option</literal>, setting the options you wish to override on the
             <literal>Option</literal> object and passing it in as a parameter to overloaded versions of <literal>get()</literal>, <literal>put()</literal> and
             <literal>remove()</literal>.  See the javadocs on the <literal>Option</literal> class for details on these options.
         </para>
     </section>
  </chapter>