[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