[jboss-cvs] JBossCache/docs/faq/en ...
Manik Surtani
manik at jboss.org
Mon Mar 26 09:30:03 EDT 2007
User: msurtani
Date: 07/03/26 09:30:03
Modified: docs/faq/en master.xml
Log:
Patched to work under jdk 1.4 until JBBUILD-350 is fixed + updated FAQs
Revision Changes Path
1.44 +265 -326 JBossCache/docs/faq/en/master.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: master.xml
===================================================================
RCS file: /cvsroot/jboss/JBossCache/docs/faq/en/master.xml,v
retrieving revision 1.43
retrieving revision 1.44
diff -u -b -r1.43 -r1.44
--- master.xml 1 Dec 2006 15:29:54 -0000 1.43
+++ master.xml 26 Mar 2007 13:30:03 -0000 1.44
@@ -6,7 +6,7 @@
<bookinfo>
<title>Frequently Asked Questions about JBoss Cache</title>
<releaseinfo>Release 2.0.0</releaseinfo>
- <pubdate>January 2007</pubdate>
+ <pubdate>April 2007</pubdate>
<author>
<firstname>Manik</firstname>
@@ -41,13 +41,15 @@
<abstract>
<para>This is a compilation of the most frequently asked
questions about JBoss Cache. Please report any bugs,
- inconsistencies, or omissions you find in this FAQ to
- <email>jbosscache-dev at jboss.org</email>
- . Please do not mail your questions
- to this list. Post them to the
- <ulink url="http://www.jboss.org/index.html?module=bb&op=viewforum&f=157">JBoss Cache User Forum
+ inconsistencies, or omissions you find in this FAQ on the
+ <ulink url="http://www.jboss.org/index.html?module=bb&op=viewforum&f=157">JBoss Cache User Form
</ulink>
- instead.
+ .
+ </para>
+ <para>
+ This FAQ is divided into specific sections, all pertaining to the core JBoss Cache library. PojoCache has a
+ separate FAQ
+ document pertaining to PojoCache specifics.
</para>
</abstract>
</bookinfo>
@@ -68,36 +70,62 @@
(either within the same JVM or across several JVMs whether they reside on
the same machine or on different machines on a network) and data is
replicated across the whole group. It is transactional because a
- user can configure a JTA compliant transaction manager and make the cache
- operation transactional. Note that the cache can also be run without
+ user can configure a
+ <ulink url="http://java.sun.com/products/jta/">JTA</ulink>
+ compliant transaction
+ manager and make any cache
+ interaction transactional. Note that the cache can also be run without
any replication; this is the local mode.
</para>
- <para>Currently, JBoss Cache consists of two components: a generic cache
- (API as
+ <para>JBoss Cache comes in two flavours: Core and Pojo versions. The core library
+ (using the
<literal>org.jboss.cache.Cache</literal>
- ) and a POJO cache (API
- as
+ interface
+ ) is the underlying library that organises data in a tree-like structure and handles all locking,
+ passivation,
+ eviction and replication characteristics of data in the cache. The pojo library (using the
<literal>org.jboss.cache.pojo.PojoCache</literal>
- ).
- <literal>Cache</literal>
- is implemented internally as a tree-structured cache that
- provides replication and
- transaction context, while
- <literal>PojoCache</literal>
- uses
- <literal>Cache</literal>
- as a
- underlying delegate
- to provide distributed state replication to behave as a true object cache providing transparent
- and finer-grained object mapping into internal cache.
- </para>
-
- <para>JBoss Cache is distributed in three different packaing: jboss-cache-core, jboss-cache-pojo,
- and jboss-cache-all. The first package only contains the core Cache library for users wish only use
- the traiditional generic cache, the second package consists of PojoCache functionality (also
- includes the Cache library as well), and the last one consists all libraries plus javadoc and
- source codes.
+ interface) is built atop the core library and allows introspection
+ of objects in the cache providing transparent coherence by using JBoss AOP. Note that the Pojo version
+ of JBoss Cache
+ (referred to as PojoCache) comes with a separate set of documentation (user guide, FAQ, etc.)
+ available on the
+ <ulink url="http://labs.jboss.com/portal/jbosscache/docs/index.html">JBoss Cache documentation site
+ </ulink>
+ .
+ </para>
+
+ <para>
+ JBoss Cache is made available in one of four different packages:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>jboss-cache-core</literal>
+ </para>
+ contains the core Cache library for users who do not wish to use the additional functionality
+ offered by PojoCache.
+ </listitem>
+ <listitem>
+ <para>
+ <literal>jboss-cache-pojo</literal>
+ </para>
+ contains the core Cache library as well as the PojoCache extensions and dependencies.
+ </listitem>
+ <listitem>
+ <para>
+ <literal>jboss-cache-all</literal>
+ </para>
+ contains all of the above, including unit tests and source code.
+ </listitem>
+ <listitem>
+ <para>
+ <literal>jboss-cache-core-JDK140</literal>
+ </para>
+ contains a JDK 1.4 compatible version of the core Cache library. Note that PojoCache is only
+ available for JDK 5.0.
+ </listitem>
+ </itemizedlist>
</para>
</answer>
</qandaentry>
@@ -108,9 +136,12 @@
</question>
<answer>
- <para>JBossCache has been developed by Bela Ban, Ben Wang, Harald
- Gliebe, Manik Surtani and Brian Stansberry. Manik is the lead on JBoss Cache and Ben is the lead on
- PojoCache.
+ <para>
+ JBoss Cache has an active community of developers and contributors. The project was founded by Bela
+ Ban
+ and is currently led by Manik Surtani. Jason Greene is the lead for the PojoCache subsystem, and other
+ contributors both past and present include Ben Wang, Harald Gliebe, Brian Stansberry, Galder Zamarreno
+ and Elias Ross.
</para>
</answer>
</qandaentry>
@@ -162,21 +193,31 @@
in the
<literal>dist/lib</literal>
directory. Note that you will need to
- use JDK 5.0 to build the distribution. You can still use the binaries you build with J2SE 1.4.x
- though.
+ use JDK 5.0 to build the distribution. To build the JDK 1.4 compatible package, do a
+ <literal>sh build.sh jar-retro</literal>
+ using JDK 5.0.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
- <para>Which JVMs are supported by JBoss Cache?</para>
+ <para>Which versions of the JDK are supported by JBoss Cache?</para>
</question>
<answer>
- <para>JBoss Cache has been tested and supported on J2SE 1.4.x and JDK 5.0.
- On jboss-3.2 CVS tree, it also compiles on JDK1.3, but there is no
- official support for this version and using this is not recommended.
+ <para>
+ JBoss Cache is baselined on Java 5 and this is the platform on which JBoss Cache is most thoroughly
+ tested.
+ If, for whatever reason you have to use JDK 1.4, we provide a retro-weaved version of the core cache
+ library
+ that is JDK 1.4 compatible, using
+ <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JBossRetro">JBoss Retro</ulink>
+ .
+ </para>
+ <para>
+ Java 6 should work as well, and we haven't heard of any specific problems of JBoss Cache run under
+ Java 6.
</para>
</answer>
</qandaentry>
@@ -187,9 +228,9 @@
</question>
<answer>
- <para>Since release 1.2, you can check the jar version by running:
- <code>java -jar jboss-cache.jar org.jboss.cache.Version</code>
- .
+ <para>
+ <code>java -jar jbosscache.jar</code>
+ will spit out version details.
</para>
</answer>
</qandaentry>
@@ -202,20 +243,14 @@
</question>
<answer>
- <para>Of course! JBoss Cache comes in two flavors:</para>
-
- <itemizedlist>
- <listitem>
- <para>Integrated with JBoss Application Server as an MBean service.</para>
- </listitem>
-
- <listitem>
- <para>Standalone, that can run in any Java EE server such
- as BEA WebLogic or IBM Websphere. Of course, it can also run in
- a standalone Java process (i.e., outside Java EE context).
+ <para>
+ Of course! Even though JBoss Cache comes integrated with JBoss Application Server as an MBean service,
+ it
+ can also be run standalone, in any Java EE server such as BEA WebLogic, IBM Websphere or Tomcat. It
+ can also run in
+ a standalone Java process, completely outside of an application server. See the user guide for more
+ details.
</para>
- </listitem>
- </itemizedlist>
</answer>
</qandaentry>
@@ -334,19 +369,6 @@
<qandaentry>
<question>
- <para>Can I run JBoss Cache on JBoss AS 3.2.x releases?</para>
- </question>
-
- <answer>
- <para>Yes. The JBoss Cache source code is also up to date on the
- jboss-3.2 CVS branch. However, only TreeCache is supported there
- since JBossAop (which PojoCache relies on) is only available in JBoss AS 4.x onwards.
- </para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
<para>Can I run multiple JBoss Cache instances on the same VM?</para>
</question>
@@ -362,36 +384,31 @@
<qandaentry>
<question>
- <para>Can TreeCache run as a second level cache inside
+ <para>Can JBoss Cache run as a second level cache inside
Hibernate?
</para>
</question>
<answer>
<para>Yes. Since Hibernate 3.0 release, you can configure it to use
- JBoss Cache (namely, TreeCache) as a second level cache. For details,
+ JBoss Cache as a second level cache. For details,
see Hibernate documentation, and also see
<ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JBossCacheHibernate">
http://wiki.jboss.org/wiki/Wiki.jsp?page=JBossCacheHibernate
</ulink>
</para>
-
- <para>Note that since Hibernate 3.0.2 and JBossCache 1.2.2, we have
- fixed a critical bug that depending on the usage pattern can cause
- deadlock during query caching.
- </para>
</answer>
</qandaentry>
<qandaentry>
<question>
- <para>What about using PojoCache as a Hibernate cache?</para>
+ <para>What about using Pojo Cache as a Hibernate cache?</para>
</question>
<answer>
<para>It is not necessary to use PojoCache for second level
cache inside Hibernate because Hibernate
- manages fine-grained fields in Java objects. So using PojoCache won't
+ manages fine-grained fields in Java objects. Using PojoCache won't
provide any advantage.
</para>
</answer>
@@ -404,8 +421,11 @@
<answer>
<para>You can configure the JBoss Cache through a configuration xml
- file. Or you can set it programmatically through its get/set methods.
- Check with the documentation for both examples.
+ file or programmatically using a
+ <literal>org.jboss.cache.config.Configuration</literal>
+ object, passed in to the
+ <literal>org.jboss.cache.CacheFactory</literal>
+ instance.
</para>
</answer>
</qandaentry>
@@ -503,8 +523,8 @@
<para>Note that once all instances join the same replication group,
every replication change is propagated to all participating members.
There is no mechanism for sub-partitioning where some replication
- can be done within only a subset of members. This is on our to do
- list.
+ can be done within only a subset of members, unless you use the Buddy Replication features. See the
+ user guide for more details on this.
</para>
</answer>
</qandaentry>
@@ -532,7 +552,7 @@
</question>
<answer>
- <para>At this stage (JBoss Cache 1.x) the answer is no. We do have an abstraction layer between the
+ <para>At this stage the answer is no. We do have an abstraction layer between the
communication suite and JBoss Cache in the pipelines, and this may appear as a feature at some stage
in
the future.
@@ -548,7 +568,7 @@
</question>
<answer>
- <para>As of JBoss Cache 1.4.0, replication need not occur to every node in the cluster. This feature -
+ <para>Replication need not occur to every node in the cluster. This feature -
called Buddy Replication -
allows each node to pick one or more 'buddies' in the cluster and only replicate to its buddies. This
allows a cluster to scale
@@ -564,28 +584,49 @@
<qandaentry>
<question>
- <para>If I have the need for different TreeCache properties (e.g.,
+ <para>If I have the need for different configuration properties (e.g.,
<literal>CacheMode</literal>
and
<literal>IsolationLevel</literal>
), do I simply need to create multiple
- TreeCache instances with the appropriate configuration?
+ <literal>org.jboss.cache.Cache</literal>
+ instances with the appropriate configuration?
</para>
</question>
<answer>
<para>Yes. All the above mentioned properties are per cache
- instance. Therefore you will need a separate JBoss Cache
- instance.
+ instance. Therefore you will need separate
+ <literal>org.jboss.cache.Cache</literal>
+ instances.
+ </para>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question>
+ <para>Isn't this expensive from a networking standpoint, i.e., needing to create sockets for each
+ <literal>org.jboss.cache.Cache</literal>
+ instance?
+ </para>
+ </question>
+
+ <answer>
+ <para>
+ Yes, it can be. For such cases it is recommended that you configure your cache using the JGroups
+ Multiplexer, which allows several caches to share
+ a single JGroups channel. Please see the User Guide for details on how to configure the JGroups
+ Multiplexer.
</para>
</answer>
</qandaentry>
+
<qandaentry>
<question>
- <para>Does the Tree Cache config
+ <para>Does the
<literal>ClusterName</literal>
- have
+ configuration element have
any relation to the JBoss AS cluster
<literal>PartitionName</literal>
?
@@ -603,7 +644,7 @@
<qandaentry>
<question>
<para>When using multiple JGroups based components
- [cluster-service.xml, treecache (multiple instances)], what is the
+ [cluster-service.xml, cache (multiple instances)], what is the
correct/valid way to configure those components to make sure my
multicast addresses don't conflict?
</para>
@@ -622,28 +663,28 @@
<qandaentry>
<question>
- <para>Does JBoss Cache currently support cache persistence
+ <para>Does JBoss Cache support cache persistence
storage?
</para>
</question>
<answer>
- <para>Yes. Starting with release 1.1, JBoss Cache has a CacheLoader
- interface that supports cache persistence. See below.
+ <para>Yes. JBoss Cache has a cache loader
+ interface that supports cache persistence. See below for more FAQs on cache loaders.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
- <para>Does JBoss Cache currently support cache passivation/ overflow
+ <para>Does JBoss Cache support cache passivation/ overflow
to a data store?
</para>
</question>
<answer>
- <para>Yes. Starting with release 1.2.4, JBoss Cache uses the
- CacheLoader to support cache passivation/ overflow. See
+ <para>Yes. JBoss Cache uses the
+ cache loader to support cache passivation/ overflow. See
documentation on how to configure and use this feature.
</para>
</answer>
@@ -666,26 +707,26 @@
<answer>
<para>No, although it is also on our to do list. Our internal
- implementation does use a similar 2PC procedure to coordinate a
- transaction among different instances.
+ implementation does use a procedure similar to 2PC to coordinate a
+ transactions among different instances, but JBoss Cache is not an XA resource.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
- <para>Which TransactionManagers are supported by
+ <para>Which transaction managers are supported by
JBoss Cache?
</para>
</question>
<answer>
- <para>JBoss Cache supports any TransactionManager that is JTA
- compliant such as JBossTM. A user can configure the transaction
- manager through the configuration xml setting. JBossCache also has a
- built in dummy transaction manager
+ <para>JBoss Cache supports any TransactionManager that is
+ <ulink link="http://java.sun.com/products/jta/">JTA</ulink>
+ compliant such as JBossTM or JBossTS. JBoss Cache ships with a
+ dummy transaction manager
(
- <literal>org.jboss.cache.tm.DummyTransactionManager</literal>
+ <literal>org.jboss.cache.transaction.DummyTransactionManager</literal>
) for
testing purposes only. But note that
<literal>DummyTransactionManager</literal>
@@ -702,34 +743,23 @@
</question>
<answer>
- <para>You either use the default (JBoss) TransactionManager to run
- JBossCache inside JBoss, or you have to implement the
- <literal>TransactionManagerLookup</literal>
+ <para>You either use the default transaction manager that ships with JBoss AS
+ or you have to implement the
+ <literal>org.jboss.cache.transaction.TransactionManagerLookup</literal>
interface, and return an
- instance of your javax.transaction.TransactionManager. The
+ instance of your
+ <literal>javax.transaction.TransactionManager</literal>
+ implementation. The
configuration property
<literal>TransactionManagerLookupClass</literal>
defines the class
to be used by the cache to fetch a reference to a
- TransactionManager. It is trivial to implement this class to support
- other TransactionManagers. Once this attribute is specified, the
+ transaction manager. It is trivial to implement this interface to support
+ other transaction managers. Once this attribute is specified, the
cache will look up the transaction context from this transaction
manager.
</para>
- <para>For the client code, here is a snippet to start and commit a
- transaction:
- </para>
-
- <programlisting>tx = (UserTransaction)new InitialContext(prop).lookup("UserTransaction");
- tree = new TreeCache();
- config = new PropertyConfigurator();
- config.configure(tree, "META-INF/replSync-service.xml");
-
- tx.begin()
- tree.put(fqn, key, value);
- tx.commit();
- </programlisting>
</answer>
</qandaentry>
@@ -739,13 +769,12 @@
</question>
<answer>
- <para>JBossCache lets you control the cache locking level through
+ <para>JBoss Cache lets you control the cache locking level through
the transaction isolation level. This is configured through the
attribute
<literal>IsolationLevel</literal>
- . Currently, JBossCache
- employs pessimistic locking internally. And the transaction
- isolation level from the pessimist locking corresponds to JDBC
+ . The transaction
+ isolation levels correspond to database
isolation levels, namely,
<literal>NONE</literal>
,
@@ -771,7 +800,7 @@
<answer>
<para>By default JBoss Cache uses pessimistic locking to lock data nodes, based on the isolation level
- configured. Since JBoss Cache 1.3.0, we also offer optimistic locking to allow for greater concurrency
+ configured. We also offer optimistic locking to allow for greater concurrency
at
the cost of slight processing overhead and performance. See the documentation for a more detailed
discussion on concurrency and locking in JBoss Cache.
@@ -812,7 +841,7 @@
</question>
<answer>
- <para>First of all, JBossCache has a notion of
+ <para>First of all, JBoss Cache has a notion of
<literal>root</literal>
that serves as a starting point for every navigational operation.
The default is "/" (since the default separator is "/" for the fqn).
@@ -820,7 +849,7 @@
"/org" (no locking "/").
</para>
- <para>Furthermore, let's say when JBossCache needs to apply a write
+ <para>Furthermore, let's say when JBoss Cache needs to apply a write
lock on node "/org/jboss/test", it will first try to obtain read
lock from the parent nodes recursively (in this example, "/org", and
"/org/jboss"). Only when it succeeds then it will try to obtain a
@@ -837,7 +866,7 @@
</question>
<answer>
- <para>Yes. JBossCache controls the individual node locking behavior
+ <para>Yes. JBoss Cache controls the individual node locking behavior
through the isolation level semantics. This means even if you don't
use a transaction, you can specify the lock level via isolation
level. You can think of the node locking behavior outside of a
@@ -873,8 +902,8 @@
</question>
<answer>
- <para>If you do a cache.remove("/root"), it will recursively remove
- all the entries under "/root".
+ <para>If you do a cache.removeNode(Fqn.fromString("/myroot")), it will recursively remove
+ all the entries under "/myroot".
</para>
</answer>
</qandaentry>
@@ -885,8 +914,7 @@
</question>
<answer>
- <para>With JBoss Cache 1.3.0, you can if you are running JBoss Cache within JBoss AS or are using JDK
- 5.0's
+ <para>Yes, using a JMX console such as the one shipped with JBoss AS or Java 5's
<literal>jconsole</literal>
utility. See the chapter titled
<emphasis role="bold">Management Information</emphasis>
@@ -897,7 +925,7 @@
<qandaentry>
<question>
- <para>Can I disable JBoss Cache management attributes in JBoss Cache 1.3.0?</para>
+ <para>Can I disable JBoss Cache management attributes?</para>
</question>
<answer>
@@ -920,7 +948,8 @@
</question>
<answer>
<para>jboss-serialization.jar is the
- <ulink url="http://labs.jboss.org/portal/index.html?ctrl:id=page.default.info&project=serialization">
+ <ulink
+ url="http://labs.jboss.org/portal/index.html?ctrl:id=page.default.info&project=serialization">
JBoss Serialization
</ulink>
library, which is much more efficient in terms
@@ -942,7 +971,7 @@
<answer>
<para>Yes you can, by passing in the
- <literal>-Dserialization.jboss=false</literal>
+ <literal>-Djboss.serialization=false</literal>
environment variable to your JVM.
</para>
</answer>
@@ -971,7 +1000,7 @@
</question>
<answer>
- <para>Application-specific classloading is used widely inside a J2EE
+ <para>Application-specific classloading is used widely inside a Java EE
container. For example, a web application may require a new
classloader to scope a specific version of the user library.
However, by default JBoss Cache is agnostic to the classloader. In
@@ -993,24 +1022,25 @@
<listitem>
<para>Object instance is created by thread 1 and will be
accessed by thread 2 (with two different classloaders).
- JBossCache has no notion of the different classloaders involved.
+ JBoss Cache has no notion of the different classloaders involved.
As a result, you will have a
<literal>ClassCastException</literal>
. This is a standard
problem in passing an object from one application space to
- another; JBossCache just adds a level of indirection in passing
+ another; JBoss Cache just adds a level of indirection in passing
the object.
</para>
</listitem>
</itemizedlist>
- <para>To solve the first kind of issue, in JBoss Cache 1.2.4 we
- introduced the concept of a
- <literal>TreeCacheMarshaller</literal>
+ <para>To solve the first kind of issue JBoss Cache uses a
+ <literal>CacheMarshaller</literal>
.
Basically, this allows application code to register a classloader
with a portion of the cache tree for use in handling objects
- replicated to that portion. See the TreeCacheMarshaller section of
+ replicated to that portion. See the
+ <literal>CacheMarshaller</literal>
+ section of
the user guide for more details.
</para>
@@ -1030,36 +1060,41 @@
<literal>MarshalledValue</literal>
that wraps around the
serialized object. Here is a code snippet that illustrates how you
- can create a wrapper around JBossCache to handle the classloader
+ can create a wrapper around JBoss Cache to handle the classloader
issue:
</para>
- <programlisting>import org.jboss.invocation.MarshalledValue;
+ <programlisting>
+ import org.jboss.invocation.MarshalledValue;
- public class CacheService {
- private TreeCache cache_;
+ public class CacheService
+ {
+ private Cache cache;
- public object get(Fqn fqn, String key) {
- return getUnMarshalledValue(cache_.get(fqn, key));
+ public Object get(Fqn fqn, String key)
+ {
+ return getUnMarshalledValue(cache.get(fqn, key));
}
- public object set(Fqn fqn, String key, Object value) {
- cache_.put(fqn, key, getMarshalledValue(value));
+ public Object set(Fqn fqn, String key, Object value)
+ {
+ cache.put(fqn, key, getMarshalledValue(value));
return value; // only if successful
}
...
- private Object getUnMarshalledValue(object value) {
+ private Object getUnMarshalledValue(object value)
+ {
// assuming we use the calling thread context classloader
return ((MarshalledValue)value).get();
}
- private Object getMarshalledValue(Object value) {
+ private Object getMarshalledValue(Object value)
+ {
return new MarshalledValue(value);
}
}
-
</programlisting>
</answer>
</qandaentry>
@@ -1074,7 +1109,9 @@
<answer>
<para>Yes. A boolean is passed in to each notification callback identifying whether the callback is
before
- or after the event.
+ or after the event. See the
+ <literal>org.jboss.cache.CacheListener</literal>
+ interface for details.
</para>
</answer>
</qandaentry>
@@ -1082,49 +1119,34 @@
<qandaentry>
<question>
<para>How do I implement a custom listener to listen to
- <literal>TreeCache</literal>
- events?
+ cache events?
</para>
</question>
<answer>
- <para>You create a class (myListener) that extends
- AbstractTreeCacheListener and provide concrete implementation for
- the node events that you are interested in. Then you add this
- listener to the TreeCache instance on startup to listen to the
- events as they occur by calling
- TreeCache.addTreeCacheListener(myListener).
+ <para>
+ Either implement
+ <literal>org.jboss.cache.CacheListener</literal>
+ or extend
+ <literal>org.jboss.cache.AbstractCacheListener</literal>
+ and override for the events you are interested in. You can then register the listener using the
+ <literal>org.jboss.cache.Cache.addCacheListener()</literal>
+ API.
</para>
-
- <programlisting>
- public class MyListener extends AbstractTreeCacheListener
- {
- ...
-
- public void nodeModify(Fqn fqn, boolean pre, boolean isLocal) {
- if(log.isTraceEnabled()){
- if(pre)
- log.trace("Event DataNode about to be modified: " + fqn);
- else
- log.trace("Event DataNode modified: " + fqn);
- }
- }
-
- ...
- }
- </programlisting>
</answer>
</qandaentry>
<qandaentry>
<question>
- <para>Can I use <literal>useRegionBasedMarshalling</literal> attribute in JBoss Cache in order to get
+ <para>Can I use
+ <literal>UseRegionBasedMarshalling</literal>
+ attribute in JBoss Cache in order to get
around ClassCastExceptions happening when accessing data in the cache that has just been redeployed?
</para>
</question>
<answer>
- <para>Yes, you can. Originally, <literal>TreeCache</literal> Marshalling was designed as a
+ <para>Yes, you can. Originally, cache Marshalling was designed as a
workaround for those replicated caches that upon state transfer did not have access to the
classloaders defining the objects in the cache.
</para>
@@ -1144,14 +1166,20 @@
deployment, you'd evict the data in the cache locally. That means that in the next deployment, the
data won't be in the cache, therefore avoiding the problem. Obviously, using marshalling to get
around this problem is only recommended when you have some kind of persistence backing where the data
- survives, for example using CacheLoaders, or when JBossCache is used as a second level cache in a
+ survives, for example using CacheLoaders, or when JBoss Cache is used as a second level cache in a
persistence framework.
</para>
<para>To implement this feature, please follow the instructions indicated in the example located
- in the TreeCacheMarshaller section of the user's guide. It's worth noting that instead of a
- <literal>ServletContextListener</literal>, you could add this code into an <literal>MBean</literal>
- that contained lifecycle methods, such as <literal>start()</literal> and <literal>stop()</literal>.
+ in the CacheMarshaller section of the user's guide. It's worth noting that instead of a
+ <literal>ServletContextListener</literal>
+ , you could add this code into an
+ <literal>MBean</literal>
+ that contained lifecycle methods, such as
+ <literal>start()</literal>
+ and
+ <literal>stop()</literal>
+ .
The key would be for this MBean to depend on the target cache, so that it can operate as long as the
cache is up and running.
</para>
@@ -1235,7 +1263,7 @@
<para>A region in JBoss Cache denotes a portion of tree hierarchy,
e.g., a fully qualified name (
- <literal>FQN</literal>
+ <literal>org.jboss.cache.Fqn</literal>
). For example,
a user can define
<literal>/org/jboss</literal>
@@ -1335,7 +1363,7 @@
processes the queue more frequently.
</para>
- <para>As of JBoss Cache 2.0.0, the eviction queue size is configurable.
+ <para>The eviction queue size is configurable.
</para>
</answer>
</qandaentry>
@@ -1348,19 +1376,19 @@
<qandaentry>
<question>
- <para>What is a CacheLoader?</para>
+ <para>What is a cache loader?</para>
</question>
<answer>
- <para>A CacheLoader is the connection of JBossCache to a
- (persistent) data store. The CacheLoader is called by JBossCache to
+ <para>A cache loader is the connection of JBoss Cache to a
+ (persistent) data store. The cache loader is called by JBoss Cache to
fetch data from a store when that data is not in the cache, and when
- modifications are made to data in the cache the CacheLoader is
+ modifications are made to data in the cache the Cache Loader is
called to store those modifications back to the store.
</para>
- <para>In conjunction with eviction policies, JBossCache with a
- CacheLoader allows a user to maintain a bounded cache for a large
+ <para>In conjunction with eviction policies, JBoss Cache with a
+ cache loader allows a user to maintain a bounded cache for a large
backend datastore. Frequently used data is fetched from the
datastore into the cache, and the least used data is evicted, in
order to provide fast access to frequently accessed data. This is
@@ -1368,49 +1396,48 @@
care of loading and eviction.
</para>
- <para>JBossCache currently ships with several CacheLoader
+ <para>JBoss Cache currently ships with several cache loader
implementations, including:
</para>
<para>
<itemizedlist>
<listitem>
- <para>FileCacheLoader: this implementation uses the file
- system to store and retrieve data. JBossCache nodes are mapped
+ <para>
+ <literal>org.jboss.cache.loader.FileCacheLoader</literal>
+ : this implementation uses the file
+ system to store and retrieve data. JBoss Cache nodes are mapped
to directories, subnodes to subdirectories etc. Attributes of
- a node are mapped to a file
- <literal>data</literal>
+ a node are mapped to a data file
inside the
directory.
</para>
</listitem>
<listitem>
- <para>BdbjeCacheLoader: this implementation is based on the
- Sleepycat Java Edition database, a fast and efficient
+ <para>
+ <literal>org.jboss.cache.loader.BdbjeCacheLoader</literal>
+ : this implementation is based on the
+ Oracle's Berkeley DB Java Edition database, a fast and efficient
transactional database. It uses a single file for the entire
- store. Note that if you use Sleepycat's CacheLoader with
+ store. Note that if you use the Berkeley DB cache loader with
JBoss Cache and wish to ship your product, you will have to acquire a
- <ulink url="http://www.sleepycat.com/jeforjbosscache">commercial license from Sleepycat
+ <ulink url="http://www.sleepycat.com/jeforjbosscache">commercial license from Oracle
</ulink>
.
</para>
</listitem>
<listitem>
- <para>JDBCCacheLoader: this implementation uses the relational database as the persistent
+ <para>
+ <literal>org.jboss.cache.loader.JDBCCacheLoader</literal>
+ : this implementation uses the relational database as the persistent
storage.
</para>
</listitem>
<listitem>
- <para>ClusteredCacheLoader: this implementation queries the rest of the cluster, treating other
- servers' in-memory state as a data store.
- </para>
- </listitem>
-
- <listitem>
- <para>And more. See the documentation for more details.</para>
+ <para>And more. See the chapter on cache loaders in the User Guide for more details.</para>
</listitem>
</itemizedlist>
</para>
@@ -1419,12 +1446,13 @@
<qandaentry>
<question>
- <para>Can writing to CacheLoaders be asynchronous?</para>
+ <para>Can writing to cache loaders be asynchronous?</para>
</question>
<answer>
- <para>As of JBossCache 1.2.4, yes. Set the CacheLoaderAsynchronous
- property to true. See the JBossCache documentation for a more
+ <para>Yes. Set the
+ <literal>async</literal>
+ attrobute to true. See the JBoss Cache User Guide for a more
detailed discussion. By default though, all cache loader writes are
synchronous and will block.
</para>
@@ -1433,26 +1461,27 @@
<qandaentry>
<question>
- <para>Can I write my own CacheLoader ?</para>
+ <para>Can I write my own cache loader ?</para>
</question>
<answer>
- <para>Yes. A CacheLoader is a class implementing
+ <para>Yes. A cache loader is a class implementing
<literal>org.jboss.cache.loader.CacheLoader</literal>
+ or extending
+ <literal>org.jboss.cache.loader.AbstractCacheLoader</literal>
. It is
- configured via the XML file (see JBossCache and Tutorial
- documentation).
+ configured via the XML file (see JBoss Cache User Guide).
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
- <para>Does a CacheLoader have to use a persistent store ?</para>
+ <para>Does a cache loader have to use a persistent store ?</para>
</question>
<answer>
- <para>No, a CacheLoader could for example fetch (and possibly store)
+ <para>No, a cache loader could for example fetch (and possibly store)
its data from a webdav-capable webserver. Another example is a
caching proxy server, which fetches contents from the web. Note that
an implementation of CacheLoader may not implement the 'store'
@@ -1464,78 +1493,13 @@
<qandaentry>
<question>
- <para>What can I use a CacheLoader for?</para>
- </question>
-
- <answer>
- <para>Some applications:</para>
-
- <para>
- <itemizedlist>
- <listitem>
- <para>HTTP sessions can be persisted (besides being replicated
- by JBossCache). The CacheLoader can be configured to be
- shared, or unshared, meaning that every node in a cluster has
- its own local store. It is also possible to attach a
- CacheLoader to just
- <emphasis>one</emphasis>
- of the
- nodes.
- </para>
- </listitem>
-
- <listitem>
- <para>Simple persistence for POJOs. Use of JBossCache aop and
- a local CacheLoader persist POJOs transparently into the store
- provided by the CacheLoader.
- </para>
- </listitem>
-
- <listitem>
- <para>Highly available replicated and persisted data store.
- The service is up as long as at least 1 node is running, but
- even if all nodes are taken offline, when the first node is
- started again, the data previously saved will still be
- available (e.g. a shopping cart).
- </para>
- </listitem>
-
- <listitem>
- <para>A caching web proxy (a la Squid): all data are contents
- of URLs, users access the proxy, and if the URL is not in the
- cache, the CacheLoader fetches it from the web. This could
- actually be a replicated and transactional version of
- Squid.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para>How do I configure JBossCache with a CacheLoader?</para>
- </question>
-
- <answer>
- <para>Through XML: both the fully-qualified classname of the
- CacheLoader and its configuration string have to be given.
- JBossCache will then instantiate a CacheLoader. See JBossCache
- documentation for details.
- </para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para>Do I have to pay to use Sleepycat's CacheLoader?</para>
+ <para>Do I have to pay to use Oracle's Berkeley DB CacheLoader?</para>
</question>
<answer>
<para>Not if you use it only for personal use. As soon as you
distribute your product with BdbjeCacheLoader, you have to purchase
- a commercial license from Sleepycat. See details at
+ a commercial license from Oracle. See details at
<ulink
url="http://www.sleepycat.com/jeforjbosscache">http://www.sleepycat.com/jeforjbosscache
</ulink>
@@ -1550,8 +1514,8 @@
</question>
<answer>
- <para>As of JBossCache 1.3.0, yes. With the new CacheLoaderConfiguration XML
- element (see user manual section on cache loaders) you can now
+ <para>Yes. Within the CacheLoaderConfiguration XML
+ element (see user guide chapter on cache loaders) you can
describe several cache loaders. 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
@@ -1562,31 +1526,6 @@
</answer>
</qandaentry>
- <qandaentry>
- <question>
- <para>Why do cache loaders go into an inconsistent state when I use transactions, pessimistic locking,
- and I
- attempt to read a node after removing it from within the same transaction scope?
- </para>
- </question>
-
- <answer>
- <para>This is a known bug (see
- <ulink url="http://jira.jboss.com/jira/browse/JBCACHE-477">JBCACHE-477</ulink>
- and
- <ulink url="http://jira.jboss.com/jira/browse/JBCACHE-352">JBCACHE-352</ulink>
- ), which have been fixed in JBoss Cache 1.4.0. A very simple workaround if you're using JBoss Cache
- 1.3.x
- is to use optimistic locking.
- </para>
- <para>
- One of the consequences of this bug is that, for example, if you use PojoCache with pojos that have
- private references to a List and you update and remove someelements of that List within a transaction
- (when using pessimistic locking and a cache loader), you may see IllegalStateExceptions thrown.
- </para>
- </answer>
- </qandaentry>
-
</qandaset>
</chapter>
More information about the jboss-cvs-commits
mailing list