The
org.jboss.cache.config.Configuration
class (along with its component parts)
is a Java Bean that encapsulates the configuration of the Cache
and all of its architectural elements (cache loaders, evictions policies, etc.)
The Configuration exposes numerous properties which
are summarized in the configuration reference
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 Configuration
class or one of its component parts exposes a simple property setter/getter for that configuration option.
As discussed in the User API section,
before a Cache can be created, the CacheFactory
must be provided with a Configuration object or with a file name or
input stream to use to parse a Configuration from XML. The following sections describe
how to accomplish this.
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 be used as a starting point, and tweaked to meet specific needs.
The simplest example of a configuration XML file, a cache configured to run in LOCAL mode, looks like this:
<?xml version="1.0" encoding="UTF-8"?>
<jbosscache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="urn:jboss:jbosscache-core:config:3.0">
</jbosscache>
This file uses sensible defaults for isolation levels, lock acquisition timeouts, locking modes, etc. Another, more complete, sample XML file is included in the configuration reference section of this book, along with a handy look-up table explaining the various options.
By default JBoss Cache will validate your XML configuration file against an XML schema and throw an
exception if the configuration is invalid. This can be overridden with the -Djbosscache.config.validate=false
JVM parameter. Alternately, you could specify your own schema to validate against, using the
-Djbosscache.config.schemaLocation=url parameter.
By default though, configuration files are validated against the JBoss Cache configuration schema, which is
included in the jbosscache-core.jar or on http://www.jboss.org/jbosscache/jbosscache-config-3.0.xsd.
Most XML editing tools can be used with this schema to ensure the configuration file you create is correct
and valid.
In addition to the XML-based configuration above, the
Configuration
can be built up programatically,
using the simple property mutators exposed by
Configuration
and its components. When constructed,
the
Configuration
object is preset with JBoss Cache
defaults and can even be used as-is for a quick start.
Configuration config = new Configuration();
config.setTransactionManagerLookupClass( GenericTransactionManagerLookup.class.getName() );
config.setIsolationLevel(IsolationLevel.READ_COMMITTED);
config.setCacheMode(CacheMode.LOCAL);
config.setLockAcquisitionTimeout(15000);
CacheFactory factory = new DefaultCacheFactory();
Cache cache = factory.createCache(config);
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
Configuration
object to programatically change
a few items from the defaults, add an eviction region, etc.
Note that configuration values may not be changed programmatically when a cache is running,
except those annotated as
@Dynamic
. Dynamic properties are also marked as such in the
configuration reference
table. Attempting to change a non-dynamic
property will result in a
ConfigurationException
.
The
Configuration
class and its
component parts
are all Java Beans that expose all config elements via simple setters
and getters. Therefore, any good IOC framework such as Spring, Google Guice, JBoss Microcontainer, etc. should be able to
build up a
Configuration
from an XML file in
the framework's own format. See the
deployment via the JBoss micrcontainer
section for an example of this.
A
Configuration
is composed of a number of
subobjects:
Following is a brief overview of the components of a
Configuration
. See the javadoc and the linked
chapters in this book for a more complete explanation of the
configurations associated with each component.
Configuration: top level object in the hierarchy; exposes the configuration properties listed in the configuration reference section of this book.BuddyReplicationConfig: only relevant if buddy replication is used. General buddy replication configuration options. Must include a:BuddyLocatorConfig: implementation-specific configuration object for theBuddyLocatorimplementation being used. What configuration elements are exposed depends on the needs of theBuddyLocatorimplementation.EvictionConfig: only relevant if eviction is used. General eviction configuration options. Must include at least one:EvictionRegionConfig: one for each eviction region; names the region, etc. Must include a:EvictionAlgorithmConfig: implementation-specific configuration object for theEvictionAlgorithmimplementation being used. What configuration elements are exposed depends on the needs of theEvictionAlgorithmimplementation.CacheLoaderConfig: only relevant if a cache loader is used. General cache loader configuration options. Must include at least one:IndividualCacheLoaderConfig: implementation-specific configuration object for theCacheLoaderimplementation being used. What configuration elements are exposed depends on the needs of theCacheLoaderimplementation.RuntimeConfig: exposes to cache clients certain information about the cache's runtime environment (e.g. membership in buddy replication groups if buddy replication is used.) Also allows direct injection into the cache of needed external services like a JTATransactionManageror a JGroupsChannelFactory.
Dynamically changing the configuration of
some
options while the cache is running is supported,
by programmatically obtaining the
Configuration
object from the running cache and changing values. E.g.,
Configuration liveConfig = cache.getConfiguration();
liveConfig.setLockAcquisitionTimeout(2000);
A complete listing of which options may be changed dynamically is in the
configuration reference
section. An
org.jboss.cache.config.ConfigurationException
will be thrown if you attempt to change a
setting that is not dynamic.
The Option API allows you to override certain behaviours 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 the
InvocationContext
before invoking your method on the cache.
E.g., to force a write lock when reading data (when used in a transaction, this provides semantics similar to SELECT FOR UPDATE in a database)
// first start a transaction
cache.getInvocationContext().getOptionOverrides().setForceWriteLock(true);
Node n = cache.getNode(Fqn.fromString("/a/b/c"));
// make changes to the node
// commit transaction
E.g., to suppress replication of a put call in a REPL_SYNC cache:
Node node = cache.getChild(Fqn.fromString("/a/b/c"));
cache.getInvocationContext().getOptionOverrides().setLocalOnly(true);
node.put("localCounter", new Integer(2));
See the javadocs on the
Option
class for details on the options available.