JBoss.orgCommunity Documentation
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.
Here is a simple example configuration file:
<?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>
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.
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
inside JBoss AS
). Because
of this dual usage, you may see elements in some configuration files
(such as
depends
or
classpath
) that are
not relevant outside JBoss AS. These can safely be ignored.
Here's how you tell the
CacheFactory
to create
and start a cache by finding and parsing a configuration file on the
classpath:
CacheFactory factory = new DefaultCacheFactory();
Cache cache = factory.createCache("cache-configuration.xml");
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.
Following is an example of programatically creating a
Configuration
configured to match the one produced
by the XML example above, and then using it to create a
Cache
:
Configuration config = new Configuration();
String tmlc = GenericTransactionManagerLookup.class.getName();
config.setTransactionManagerLookupClass(tmlc);
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 = 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 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 the
BuddyLocator
implementation
being used. What configuration elements are exposed depends on
the needs of the
BuddyLocator
implementation.
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:
EvictionPolicyConfig
: implementation-specific
configuration object for the
EvictionPolicy
implementation
being used. What configuration elements are exposed depends on
the needs of the
EvictionPolicy
implementation.
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 the
CacheLoader
implementation
being used. What configuration elements are exposed depends on
the needs of the
CacheLoader
implementation.
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
JTA
TransactionManager
or a JGroups
ChannelFactory
.
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 override the default node versioning used with optimistic locking:
DataVersion v = new MyCustomDataVersion();
cache.getInvocationContext().getOptionOverrides().setDataVersion(v);
Node ch = cache.getRoot().addChild(Fqn.fromString("/a/b/c"));
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.