[jboss-cvs] JBossCache/docs/JBossCache-UserGuide/en/modules ...
Manik Surtani
manik at jboss.org
Fri Mar 30 13:22:07 EDT 2007
User: msurtani
Date: 07/03/30 13:22:07
Modified: docs/JBossCache-UserGuide/en/modules cache_loaders.xml
Log:
JBCACHE-807
Revision Changes Path
1.11 +470 -374 JBossCache/docs/JBossCache-UserGuide/en/modules/cache_loaders.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: cache_loaders.xml
===================================================================
RCS file: /cvsroot/jboss/JBossCache/docs/JBossCache-UserGuide/en/modules/cache_loaders.xml,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -b -r1.10 -r1.11
--- cache_loaders.xml 10 Feb 2007 17:47:03 -0000 1.10
+++ cache_loaders.xml 30 Mar 2007 17:22:07 -0000 1.11
@@ -1,6 +1,8 @@
<chapter id="cache_loaders">
<title>Cache Loaders</title>
- <para>JBoss Cache can use a <literal>CacheLoader</literal> to back up the in-memory cache to a backend datastore.
+ <para>JBoss Cache can use a
+ <literal>CacheLoader</literal>
+ to back up the in-memory cache to a backend datastore.
If JBoss Cache is configured with a cache loader, then the following features are provided:
<itemizedlist>
<listitem>Whenever a cache element is accessed, and that element is not in
@@ -12,7 +14,9 @@
<listitem>Whenever an element is modified, added or removed, then that
modification is persisted in the backend store via the cache loader. If
transactions are used, all modifications created within a transaction
- are persisted. To this end, the <literal>CacheLoader</literal> takes part in the two
+ are persisted. To this end, the
+ <literal>CacheLoader</literal>
+ takes part in the two
phase commit protocol run by the transaction manager, although it does not do so explicitly.
</listitem>
</itemizedlist>
@@ -32,7 +36,8 @@
</figure>
- <para>The interaction between JBoss Cache and a <literal>CacheLoader</literal>
+ <para>The interaction between JBoss Cache and a
+ <literal>CacheLoader</literal>
implementation is as follows. When
<literal>CacheLoaderConfiguration</literal>
(see below) is non-null, an
@@ -60,11 +65,15 @@
<literal>setCache()</literal>
are called. The latter can be used to
store a reference to the cache, the former is used to configure this
- instance of the <literal>CacheLoader</literal>. For example, here a database cache loader
+ instance of the
+ <literal>CacheLoader</literal>
+ . For example, here a database cache loader
could establish a connection to the database.
</para>
- <para>The <literal>CacheLoader</literal> interface has a set of methods that are called
+ <para>The
+ <literal>CacheLoader</literal>
+ interface has a set of methods that are called
when no transactions are used:
<literal>get()</literal>
,
@@ -116,7 +125,8 @@
transaction.
</para>
- <para>See the javadocs on this interface for a detailed explanation on each method and the contract implementations
+ <para>See the javadocs on this interface for a detailed explanation on each method and the contract
+ implementations
would need to fulfil.
</para>
@@ -130,13 +140,16 @@
a chain. The impact is that the cache will look at all of the cache
loaders in the order they've been configured, until it finds a valid,
non-null element of data. When performing writes, all cache loaders are
- written to (except if the <literal>ignoreModifications</literal> element has been set to <literal>true</literal>
+ written to (except if the
+ <literal>ignoreModifications</literal>
+ element has been set to
+ <literal>true</literal>
for a specific cache loader. See the configuration section below for
details.
</para>
<programlisting>
-<![CDATA[
+ <![CDATA[
...
@@ -209,7 +222,8 @@
whereas a database implementation might define the database URL, name
and password to establish a database connection. This configuration is
passed to the cache loader implementation via
- <literal>CacheLoader.setConfig(Properties)</literal>. Note that
+ <literal>CacheLoader.setConfig(Properties)</literal>
+ . Note that
backspaces may have to be escaped.
</para>
@@ -284,9 +298,13 @@
methods are pushed down to the specific cache loader. Situations may
arise where transient application data should only reside in a file
based cache loader on the same server as the in-memory cache, for
- example, with a further shared <literal>JDBCCacheLoader</literal> used by all servers in
+ example, with a further shared
+ <literal>JDBCCacheLoader</literal>
+ used by all servers in
the network. This feature allows you to write to the 'local' file cache
- loader but not the shared <literal>JDBCCacheLoader</literal>. This property defaults to
+ loader but not the shared
+ <literal>JDBCCacheLoader</literal>
+ . This property defaults to
<literal>false</literal>
, so writes are propagated to all cache loaders
configured.
@@ -320,7 +338,9 @@
and
<literal>singletonStore</literal>
at the same time.
- Default value is <literal>false</literal>.
+ Default value is
+ <literal>false</literal>
+ .
</para>
<para>
@@ -335,7 +355,9 @@
property to true would ensure that any changes during this process also
get stored in the cache loader. You would also want to set this property
to true if each node's cache loader is configured with a different
- location. Default value is <literal>false</literal>.
+ location. Default value is
+ <literal>false</literal>
+ .
</para>
<para>
@@ -357,14 +379,18 @@
<para>
<literal>shared</literal>
indicates that the cache loader is shared among different cache instances, for example where all instances in a
- cluster use the same JDBC settings t talk to the same remote, shared database. Setting this to <literal>true</literal>
- prevents repeated and unnecessary writes of the same data to the cache loader by different cache instances. Default value is <literal>false</literal>.
+ cluster use the same JDBC settings t talk to the same remote, shared database. Setting this to
+ <literal>true</literal>
+ prevents repeated and unnecessary writes of the same data to the cache loader by different cache instances.
+ Default value is
+ <literal>false</literal>
+ .
</para>
-</section>
+ </section>
-<section id="cl.impls">
+ <section id="cl.impls">
<title>Shipped Implementations</title>
@@ -374,9 +400,15 @@
<title>File system based cache loaders</title>
<para>
JBoss Cache ships with several cache loaders that utilise the file system as a data store. They all require
- that the <literal><![CDATA[<cacheloader><properties>]]></literal> configuration element
- contains a <literal>location</literal> property, which maps to a directory to be used as a persistent store.
- (e.g., <literal>location=/tmp/myDataStore</literal>). Used mainly for testing and not recommended for production use.
+ that the
+ <literal><![CDATA[<cacheloader><properties>]]></literal>
+ configuration element
+ contains a
+ <literal>location</literal>
+ property, which maps to a directory to be used as a persistent store.
+ (e.g.,
+ <literal>location=/tmp/myDataStore</literal>
+ ). Used mainly for testing and not recommended for production use.
</para>
<itemizedlist>
<listitem>
@@ -386,8 +418,37 @@
loader checks for any potential character portability issues in the
location or tree node names, for example invalid characters, producing
warning messages. These checks can be disabled adding
- <literal>check.character.portability</literal> property to the <literal><![CDATA[<properties>]]></literal> element and setting it to <literal>false</literal>
- (e.g., <literal>check.character.portability=false</literal>).
+ <literal>check.character.portability</literal>
+ property to the
+ <literal><![CDATA[<properties>]]></literal>
+ element and setting it to
+ <literal>false</literal>
+ (e.g.,
+ <literal>check.character.portability=false</literal>
+ ).
+ </para>
+ <para>
+ The FileCacheLoader has some severe limitations which restrict it's use in a production
+ environment, or if used in such an environment, it should be used with due care and sufficient
+ understanding of these limitations.
+ <itemizedlist>
+ <listitem>Due to the way the FileCacheLoader represents a tree structure on disk (directories and
+ files) traversal is inefficient for deep trees.
+ </listitem>
+ <listitem>Usage on shared filesystems like NFS, Windows shares, etc. should be avoided as these do
+ not implement proper file locking and can cause data corruption.
+ </listitem>
+ <listitem>Usage with an isolation level of NONE can cause corrupt writes as multiple threads
+ attempt to write to the same file.
+ </listitem>
+ <listitem>File systems are inherently not transactional, so when attempting to use your cache in a
+ transactional context, failures when writing to the file (which happens during the commit phase)
+ cannot be recovered.
+ </listitem>
+ </itemizedlist>
+
+ As a rule of thumb, it is recommended that the FileCacheLoader not be used in a highly concurrent,
+ transactional or stressful environment, and it's use is restricted to testing.
</para>
</listitem>
@@ -395,7 +456,8 @@
<para>
<literal>BdbjeCacheLoader</literal>
, which is a cache loader implementation based on the Oracle/Sleepycat's
- <ulink url="http://www.oracle.com/database/berkeley-db/index.html">BerkeleyDB Java Edition</ulink>.
+ <ulink url="http://www.oracle.com/database/berkeley-db/index.html">BerkeleyDB Java Edition</ulink>
+ .
</para>
</listitem>
@@ -403,7 +465,9 @@
<para>
<literal>JdbmCacheLoader</literal>
, which is a cache loader
- implementation based on the <ulink url="http://jdbm.sourceforge.net/">JDBM engine</ulink>, a fast and free alternative to
+ implementation based on the
+ <ulink url="http://jdbm.sourceforge.net/">JDBM engine</ulink>
+ , a fast and free alternative to
BerkeleyDB.
</para>
</listitem>
@@ -463,7 +527,9 @@
<para>The current implementation uses just one table. Each row in the table
represents one node and contains three columns:
<itemizedlist>
- <listitem>column for <literal>Fqn</literal> (which is also a primary key
+ <listitem>column for
+ <literal>Fqn</literal>
+ (which is also a primary key
column)
</listitem>
@@ -471,19 +537,31 @@
pairs)
</listitem>
- <listitem>column for parent <literal>Fqn</literal></listitem>
+ <listitem>column for parent
+ <literal>Fqn</literal>
+ </listitem>
</itemizedlist>
</para>
- <para><literal>Fqn</literal>'s are stored as strings. Node content is stored
+ <para>
+ <literal>Fqn</literal>
+ 's are stored as strings. Node content is stored
as a BLOB.
<emphasis>WARNING:</emphasis>
JBoss Cache does not impose any
- limitations on the types of objects used in <literal>Fqn</literal> but this implementation of
- cache loader requires <literal>Fqn</literal> to contain only objects of type
+ limitations on the types of objects used in
+ <literal>Fqn</literal>
+ but this implementation of
+ cache loader requires
+ <literal>Fqn</literal>
+ to contain only objects of type
<literal>java.lang.String</literal>
- . Another limitation for <literal>Fqn</literal> is its
- length. Since <literal>Fqn</literal> is a primary key, its default column type is
+ . Another limitation for
+ <literal>Fqn</literal>
+ is its
+ length. Since
+ <literal>Fqn</literal>
+ is a primary key, its default column type is
<literal>VARCHAR</literal>
which can store text values up to some
maximum length determined by the database in use.
@@ -573,7 +651,8 @@
<emphasis>cache.jdbc.datasource</emphasis>
- JNDI name
of the DataSource. The default value is
- <literal>java:/DefaultDS</literal>.
+ <literal>java:/DefaultDS</literal>
+ .
</listitem>
</itemizedlist>
</para>
@@ -618,20 +697,23 @@
<section>
<title>c3p0 connection pooling</title>
- <para>JBoss Cache implements JDBC connection pooling when running outside of an application server standalone using
+ <para>JBoss Cache implements JDBC connection pooling when running outside of an application server
+ standalone using
the c3p0:JDBC DataSources/Resource Pools library. In order to enable it, just edit the following
property:
<itemizedlist>
<listitem>
<emphasis>cache.jdbc.connection.factory</emphasis>
- Connection factory class name.
- If not set, it defaults to standard non-pooled implementation. To enable c3p0 pooling, just set the
+ If not set, it defaults to standard non-pooled implementation. To enable c3p0 pooling, just set
+ the
connection factory class for c3p0. See example below.
</listitem>
</itemizedlist>
</para>
- <para>You can also set any c3p0 parameters in the same cache loader properties section but don't forget to
+ <para>You can also set any c3p0 parameters in the same cache loader properties section but don't forget
+ to
start the property name with 'c3p0.'. To find a list of available properties, please check the
c3p0 documentation for the c3p0 library version distributed in
<ulink url="http://sourceforge.net/projects/c3p0">c3p0:JDBC DataSources/Resource Pools</ulink>
@@ -657,7 +739,7 @@
<para>
<programlisting>
-<![CDATA[
+ <![CDATA[
<attribute name="CacheLoaderConfiguration">
<config>
<passivation>false</passivation>
@@ -698,7 +780,7 @@
</para>
<programlisting>
-<![CDATA[
+ <![CDATA[
<attribute name="CacheLoaderConfiguration">
<config>
<passivation>false</passivation>
@@ -723,7 +805,7 @@
<para>Cconfiguration example for a cache loader using c3p0 JDBC connection pooling:</para>
<programlisting>
-<![CDATA[
+ <![CDATA[
<attribute name="CacheLoaderConfiguration">
<config>
<passivation>false</passivation>
@@ -774,9 +856,13 @@
different process on a different host.
</para>
- <para>A TcpDelegatingCacheLoader talks to a remote <literal>org.jboss.cache.loader.tcp.TcpCacheServer</literal>,
+ <para>A TcpDelegatingCacheLoader talks to a remote
+ <literal>org.jboss.cache.loader.tcp.TcpCacheServer</literal>
+ ,
which can be a standalone process started on the command line, or embedded as an MBean inside
- JBoss AS. The <literal>TcpCacheServer</literal> has a reference to another JBoss Cache instance, which
+ JBoss AS. The
+ <literal>TcpCacheServer</literal>
+ has a reference to another JBoss Cache instance, which
it can create itself, or which is given to it (e.g. by JBoss, using
dependency injection).
</para>
@@ -789,7 +875,7 @@
<para>The configuration looks as follows:</para>
<programlisting>
-<![CDATA[
+ <![CDATA[
<attribute name="CacheLoaderConfiguration">
<config>
<cacheloader>
@@ -806,7 +892,8 @@
<para>This means this instance of JBoss Cache will delegate all load
and store requests to the remote TcpCacheServer running on
- <literal>myRemoteServer:7500</literal>.
+ <literal>myRemoteServer:7500</literal>
+ .
</para>
<para>A typical use case could be multiple replicated instances of
@@ -832,7 +919,6 @@
</section>
-
<section id="cl.pass">
<title>Cache Passivation</title>
@@ -867,7 +953,9 @@
<para>To enable cache passivation/activation, you can set
<literal>passivation</literal>
- to true. The default is <literal>false</literal>.
+ to true. The default is
+ <literal>false</literal>
+ .
When passivation is used, only the first cache loader configured is
used and all others are ignored.
</para>
@@ -988,7 +1076,9 @@
persisted (atomic updates).
</para>
- <para>Note that JBoss Cache is <emphasis>not</emphasis> an
+ <para>Note that JBoss Cache is
+ <emphasis>not</emphasis>
+ an
XA Resource, that means it doesn't implement recovery. When used with a
transaction manager that supports recovery, this functionality is not
available.
@@ -1058,7 +1148,9 @@
</para>
<para>
- Hierarchical caches could also be set up spanning more than one JVM or server, using the <literal>TcpDelegatingCacheLoader</literal>.
+ Hierarchical caches could also be set up spanning more than one JVM or server, using the
+ <literal>TcpDelegatingCacheLoader</literal>
+ .
<figure>
<title>TCP delegating cache loader</title>
@@ -1078,10 +1170,15 @@
<title>Multiple Cache Loaders</title>
<para>
- You can set up more than one cache loader in a chain. Internally, a delegating <literal>ChainingCacheLoader</literal> is used, with references to each
- cache loader you have configured. Use cases vary depending on the type of cache loaders used in the chain. One example is
- using a filesystem based cache loader, colocated on the same host as the JVM, used as an overflow for memory. This ensures
- data is available relatively easily and with low cost. An additional remote cache loader, such as a <literal>TcpDelegatingCacheLoader</literal>
+ You can set up more than one cache loader in a chain. Internally, a delegating
+ <literal>ChainingCacheLoader</literal>
+ is used, with references to each
+ cache loader you have configured. Use cases vary depending on the type of cache loaders used in the chain.
+ One example is
+ using a filesystem based cache loader, colocated on the same host as the JVM, used as an overflow for
+ memory. This ensures
+ data is available relatively easily and with low cost. An additional remote cache loader, such as a
+ <literal>TcpDelegatingCacheLoader</literal>
provides resilience between server restarts.
</para>
@@ -1101,5 +1198,4 @@
</section>
-
</chapter>
\ No newline at end of file
More information about the jboss-cvs-commits
mailing list