[jboss-cvs] JBossCache/docs/JBossCache-UserGuide/en/modules ...

Brian Stansberry brian.stansberry at jboss.com
Thu May 31 01:29:17 EDT 2007


  User: bstansberry
  Date: 07/05/31 01:29:17

  Modified:    docs/JBossCache-UserGuide/en/modules  configuration.xml
  Log:
  Expand configuration discussion
  
  Revision  Changes    Path
  1.9       +287 -28   JBossCache/docs/JBossCache-UserGuide/en/modules/configuration.xml
  
  (In the diff below, changes in quantity of whitespace are not shown.)
  
  Index: configuration.xml
  ===================================================================
  RCS file: /cvsroot/jboss/JBossCache/docs/JBossCache-UserGuide/en/modules/configuration.xml,v
  retrieving revision 1.8
  retrieving revision 1.9
  diff -u -b -r1.8 -r1.9
  --- configuration.xml	30 Jan 2007 21:43:32 -0000	1.8
  +++ configuration.xml	31 May 2007 05:29:17 -0000	1.9
  @@ -2,54 +2,303 @@
      <title>Configuration</title>
   
      <section>
  -      <title>XML-based Configuration</title>
  +      <title>Configuration Overview</title>
  +      
  +      <para>
  +         The <literal>org.jboss.cache.config.Configuration</literal> class
  +         (along with its 
  +         <link linkend="configuration.elements">component parts</link>)
  +         is a Java Bean that encapsulates the configuration of the 
  +         <literal>Cache</literal> and all of its architectural elements 
  +         (cache loaders, evictions policies, etc.)
  +       </para>
  +       
  +       <para>
  +          The <literal>Configuration</literal> exposes numerous properties which
  +          are summarized in the 
  +          <link linkend="configuration_reference">configuration reference</link>
  +          section of this book and many of which are discussed in later 
  +          chapters. Any time you see a configuration option
  +          discussed in this book, you can assume that the <literal>Configuration</literal>
  +          class or one of its component parts exposes a simple property setter/getter for that configuration option.
  +       </para>
  +       
  +   </section>
  +   
  +   <section>
  +       <title>Creating a <literal>Configuration</literal></title>
  +       
  +       <para> 
  +          As discussed in the <link linkend="api.create_start">User API section</link>,
  +          before a <literal>Cache</literal> can be created, the 
  +          <literal>CacheFactory</literal> must be provided with a 
  +          <literal>Configuration</literal> object or with a file name or
  +          input stream to use to parse a <literal>Configuration</literal>
  +          from XML. The following sections describe how to accomplish this.
  +       </para>
  +   
  +   <section>
  +      <title>Parsing an XML-based Configuration File</title>
         <para>
            The most convenient way to configure JBoss Cache is via an XML file. The JBoss Cache distribution ships
  -         with a number of configuration files for common use cases. It is recommended that these files are used as
  +         with a number of configuration files for common use cases. It is recommended that these files be used as
            a starting point, and tweaked to meet specific needs.
         </para>
  +      
  +      <para>
  +         Here is a simple example configuration file:
  +      </para>
  +      <programlisting>
  +         <![CDATA[
  +<?xml version="1.0" encoding="UTF-8"?>
  +
  +<!-- ===================================================================== -->
  +<!--                                                                       -->
  +<!--  Sample JBoss Cache Service Configuration                             -->
  +<!--                                                                       -->
  +<!-- ===================================================================== -->
  +
  +<server>
  +   
  +   <mbean code="org.jboss.cache.jmx.CacheJmxWrapper" name="jboss.cache:service=Cache">
  +   
  +      <!-- 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">READ_COMMITTED</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">LOCAL</attribute>
  +
  +      <!-- Max number of milliseconds to wait for a lock acquisition -->
  +      <attribute name="LockAcquisitionTimeout">15000</attribute>
  +
  +
  +      <!-- Specific eviction policy configurations. This is LRU -->
  +      <attribute name="EvictionConfig">
  +         <config>
  +            <attribute name="wakeUpIntervalSeconds">5</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>
  +         </config>
  +      </attribute>
  +   </mbean>
  +</server>
  +]]>
  +      </programlisting>
  +      
         <para>
  -         A sample XML file is in
  -         <link linkend="sample_xml_file">the configuration reference</link>
  +         Another, more complete, sample XML file is included in the 
  +         <link linkend="sample_xml_file">configuration reference</link>
            section of this book,
            along with
            <link linkend="configuration_reference">a handy look-up table</link>
  -         of
  -         the various options.
  +         explaining the various options.
         </para>
  +      
  +      <para>
  +         For historical reasons, the format of the JBoss Cache configuraton 
  +         file follows that of a JBoss AS Service Archive (SAR) deployment 
  +         descriptor (and still can be used as such 
  +         <link linkend="deployment.microkernel">inside JBoss AS</link>). Because
  +         of this dual usage, you may see elements in some configuration files 
  +         (such as 
  +         <literal>depends</literal> or <literal>classpath</literal>) that are
  +         not relevant outside JBoss AS.  These can safely be ignored. 
  +      </para>
  +         
  +      <para>
  +         Here's how you tell the <literal>CacheFactory</literal> to create
  +         and start a cache by finding and parsing a configuration file on the 
  +         classpath:
  +      </para>
  +         
  +      <programlisting>
  +            CacheFactory factory = DefaultCacheFactory.getInstance();
  +            Cache cache = factory.createCache("cache-configuration.xml");
  +      </programlisting>
  +      
      </section>
   
      <section>
         <title>Programmatic Configuration</title>
         <para>
  -         In addition to the XML-based configuration above, a programmatic configuration option is available.
  -         <literal>org.jboss.cache.config.Configuration</literal>
  -         is central to configuring JBoss Cache programmatically,
  -         and an instance is created, configured and passed in to a
  -         <literal>org.jboss.cache.CacheFactory</literal>
  -         to
  -         create a cache.
  +         In addition to the XML-based configuration above, the
  +         <literal>Configuration</literal> can be built up programatically,
  +         using the simple property mutators exposed by 
  +         <literal>Configuration</literal> and its components. When constructed, 
  +         the <literal>Configuration</literal> object is preset with JBoss Cache 
  +         defaults and can even be used as-is for a quick start.
         </para>
  +      
         <para>
  -         When constructed, the
  -         <literal>Configuration</literal>
  -         object is preset with JBoss Cache defaults and can even
  -         be used as-is for a quick start.  Configuration values may not be changed programmatically when a cache is running,
  +         Following is an example of programatically creating a 
  +         <literal>Configuration</literal> configured to match the one produced 
  +         by the XML example above, and then using it to create a 
  +         <literal>Cache</literal>:
  +      </para>
  +      
  +      <programlisting>
  +         <![CDATA[
  +            Configuration config = new Configuration();
  +            config.setTransactionManagerLookupClass(GenericTransactionManagerLookup.class.getName());
  +            config.setIsolationLevel(IsolationLevel.READ_COMMITTED);
  +            config.setCacheMode(CacheMode.LOCAL);
  +            config.setLockParentForChildInsertRemove(true);
  +            config.setLockAcquisitionTimeout(15000);
  +            
  +            EvictionConfig ec = new EvictionConfig();
  +            ec.setWakeupIntervalSeconds(5);
  +            ec.setDefaultEvictionPolicyClass(LRUPolicy.class.getName());
  +            
  +            EvictionRegionConfig erc = new EvictionRegionConfig();
  +            erc.setRegionName("_default_");
  +            
  +            LRUConfiguration lru = new LRUConfiguration();
  +            lru.setMaxNodes(5000);
  +            lru.setTimeToLiveSeconds(1000);
  +            
  +            erc.setEvictionPolicyConfig(lru);
  +            
  +            List<EvictionRegionConfig> ercs = new ArrayList<EvictionRegionConfig>();
  +            ercs.add(erc);
  +            ec.setEvictionRegionConfigs(erc);
  +            
  +            config.setEvictionConfig(ec);
  +            
  +            CacheFactory factory = DefaultCacheFactory.getInstance();
  +            Cache cache = factory.createCache(config);         
  +]]>
  +      </programlisting>
  +      
  +      <para>
  +         Even the above fairly simple configuration is pretty tedious programming;
  +         hence the preferred use of XML-based configuration.  However, if your
  +         application requires it, there is no reason not to use XML-based 
  +         configuration for most of the attributes, and then access the
  +         <literal>Configuration</literal> object to programatically change
  +         a few items from the defaults, add an eviction region, etc.
  +      </para>
  +      
  +      <para>
  +         Note that configuration values may not be changed programmatically when a cache is running,
            except those annotated as <literal>@Dynamic</literal>.  Dynamic properties are also marked as such in the
            <link linkend="configuration_reference">configuration reference</link> table.  Attempting to change a non-dynamic
            property will result in a <literal>ConfigurationException</literal>.
  +      </para>
  +   </section>
  +   
  +   <section>
  +      <title>Using an IOC Framework</title>
   
  +      <para>
  +         The <literal>Configuration</literal> class and its
  +         <link linkend="configuration.elements">component parts</link>
  +         are all Java Beans that expose all config elements via simple setters
  +         and getters.  Therefore, any good IOC framework should be able to
  +         build up a <literal>Configuration</literal> from an XML file in
  +         the frameworks own format. See the 
  +         <link linkend="deployment.microcontainer">deployment via the JBoss micrcontainer</link>
  +         section for an example of this.
  +      </para>
  +   </section>
  +   </section>
  +
  +   <section id="configuration.elements">
  +       <title>Composition of a <literal>Configuration</literal> Object</title>
  +       
  +       <para>
  +         A <literal>Configuration</literal> is composed of a number of
  +         subobjects:
  +         
  +         <mediaobject>
  +            <imageobject>
  +               <imagedata fileref="images/Configuration.png"/>
  +            </imageobject>
  +         </mediaobject>
  +       </para>
  +       
  +       <para>
  +          Following is a brief overview of the components of a 
  +          <literal>Configuration</literal>.  See the javadoc and the linked
  +          chapters in this book for a more complete explanation of the
  +          configurations associated with each component.
  +          
  +          <itemizedlist>
  +            <listitem><literal>Configuration</literal>: top level object
  +            in the hierarchy; exposes the configuration properties listed in the 
  +            <link linkend="configuration_reference">configuration reference</link>
  +            section of this book.
  +            </listitem>
  +            
  +            <listitem><literal>BuddyReplicationConfig</literal>: only relevant if 
  +            <link linkend="br">buddy replication</link> is used. General
  +            buddy replication configuration options. Must include a:</listitem>
  +            
  +            <listitem><literal>BuddyLocatorConfig</literal>: implementation-specific 
  +            configuration object for the <literal>BuddyLocator</literal> implementation 
  +            being used. What configuration elements are exposed depends on
  +            the needs of the <literal>BuddyLocator</literal> implementation.</listitem>
  +            
  +            <listitem><literal>EvictionConfig</literal>: only relevant if 
  +            <link linkend="eviction_policies">eviction</link> is used. General
  +            eviction configuration options. Must include at least one:</listitem>
  +            
  +            <listitem><literal>EvictionRegionConfig</literal>: one for each
  +            eviction region; names the region, etc.  Must include a:
  +            </listitem>
  +            
  +            <listitem><literal>EvictionPolicyConfig</literal>: implementation-specific 
  +            configuration object for the <literal>EvictionPolicy</literal> implementation 
  +            being used. What configuration elements are exposed depends on
  +            the needs of the <literal>EvictionPolicy</literal> implementation.</listitem>
  +            
  +            <listitem><literal>CacheLoaderConfig</literal>: only relevant if a
  +            <link linkend="cache_loaders">cache loader</link> is used. General
  +            cache loader configuration options. Must include at least one:</listitem>
  +            
  +            <listitem><literal>IndividualCacheLoaderConfig</literal>: implementation-specific 
  +            configuration object for the <literal>CacheLoader</literal> implementation 
  +            being used. What configuration elements are exposed depends on
  +            the needs of the <literal>CacheLoader</literal> implementation.</listitem>
  +            
  +            <listitem><literal>RuntimeConfig</literal>: exposes to cache clients
  +            certain information about the cache's runtime environment (e.g. membership
  +            in buddy replication groups if 
  +            <link linkend="br">buddy replication</link> is used.) Also allows
  +            direct injection into the cache of needed external services like a
  +            JTA <literal>TransactionManager</literal> or a JGroups 
  +            <literal>ChannelFactory</literal>.
  +            </listitem>
  +         </itemizedlist>
         </para>
      </section>
   
      <section>
         <title>Dynamic Reconfiguration</title>
         <para>
  -         Dynamically changing the configuration of certain options while the cache is running is supported for
  -         certain options, by programmatically obtaining the
  -         <literal>Configuration</literal>
  -         object from the
  -         running cache and changing values. E.g.,
  +         Dynamically changing the configuration of <emphasis>some</emphasis> options while the cache is running is supported, 
  +         by programmatically obtaining the <literal>Configuration</literal>
  +         object from the running cache and changing values. E.g.,
            <programlisting>
   
               Configuration liveConfig = cache.getConfiguration();
  @@ -58,7 +307,7 @@
            </programlisting>
            A complete listing of which options may be changed dynamically is in the
            <link linkend="configuration_reference">configuration reference</link>
  -         section. A
  +         section. An
            <literal>org.jboss.cache.config.ConfigurationException</literal>
            will be thrown if you attempt to change a
            setting that is not dynamic.
  @@ -66,9 +315,9 @@
      </section>
   
      <section id="configuration.options">
  -      <title>Overriding Configuration Options</title>
  +      <title>Overriding the Configuration Via the Option API</title>
         <para>
  -         The Option API allows you to override certain behaviour of the cache on a per invocation basis.
  +         The Option API allows you to override certain behaviours of the cache on a per invocation basis.
            This involves creating an instance of
            <literal>org.jboss.cache.config.Option</literal>
            , setting the options
  @@ -79,7 +328,7 @@
            before invoking your method on the cache.
         </para>
         <para>
  -         E.g.:
  +         E.g., to override the default node versioning used with optimistic locking:
            <programlisting>
   
               MyCustomDataVersion v = new MyCustomDataVersion();
  @@ -89,6 +338,16 @@
            </programlisting>
         </para>
         <para>
  +         E.g., to suppress replication of a put call in a REPL_SYNC cache:
  +         <programlisting>
  +
  +            Node node = cache.getChild(Fqn.fromString("/a/b/c"));
  +            cache.getInvocationContext().getOptionOverrides().setLocalOnly(true);
  +            node.put("localCounter", new Integer(2));
  +
  +         </programlisting>
  +      </para>
  +      <para>
            See the javadocs on the
            <literal>Option</literal>
            class for details on the options available.
  
  
  



More information about the jboss-cvs-commits mailing list