These are frequently asked questions regarding JBoss Cache.
What is JBoss Cache? | |
JBoss Cache is a replicated and transactional cache. It is replicated since multiple JBoss Cache instances can be distributed (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 any replication; this is the local mode. Currently, JBoss Cache consists of two components: a generic cache (implemented internally as org.jboss.cache.TreeCache) and a POJO cache (implemented internally as org.jboss.cache.aop.PojoCache). TreeCache is a tree-structured cache that provides replication and transaction context, while PojoCache extends the functionality of TreeCache but behaves as a true object cache providing transparent and finer-grained object mapping into internal cache. | |
Who are the JBoss Cache developers? | |
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. | |
What is the license for JBoss Cache? | |
JBoss Cache is licensed under LGPL. | |
Where can I download JBoss Cache? | |
The JBoss Cache product download page has prebuilt binaries as well as source distributions. You can also grab snapshots from the JBoss CVS repository (see this wiki page) - the module name is JBossCache | |
How do I build JBoss Cache from CVS sources? | |
To build, do sh build.sh jar. This will produce jboss-cache.jar in the dist/lib directory. Or if you want to build the standalone package, do sh build.sh dist this will produce dist/jboss-cache-dist.zip 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. | |
Which JVMs are supported by JBoss Cache? | |
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. | |
From JBoss Cache 1.3.0 onwards, there is a new directory lib-50, what is it? | |
From JBoss Cache 1.3.0 onwards, we support the use of Java 5 annotations, used by PojoCache. As a result, there are jboss-aop-jdk50.jar and jboss-cache-jdk50.jar that are needed to work with the Java 5 annotations. You will need to replace jboss-aop.jar and jboss-cache.jar in the lib directory with the -jdk50 versions if you intend to use PojoCache, Java 5 and annotations. | |
How do I know the version of JBoss Cache that I am using? | |
Since release 1.2, you can check the jar version by running: java -jar jboss-cache.jar org.jboss.cache.Version. | |
Can I run JBoss Cache outside of JBoss Application Server? | |
Of course! JBoss Cache comes in two flavors:
| |
Where can I report bugs or problems? | |
Please report any bugs or problems to JBoss Cache User Forum. |
How do I deploy JBoss Cache as a MBean service? | |
To deploy JBoss Cache as an MBean inside JBoss, you can copy the configuration xml file over to the deploy directory (from all configuration whereby the necessary jars are present). Under the standalone package etc/META-INF directory , there are example configuration files for different cache modes that can be used to deploy JBoss Cache as well. | |
How do I know if my JBoss Cache MBean has been deployed? | |
To verify that your JBoss Cache MBean is deployed correctly, you can first check the log output under the command console. Next you can verify it from JBoss JMX console. Look for jboss.cache domain. | |
How do I access the JBoss Cache MBean? | |
Accessing the JBoss Cache MBean is just like accessing any JBoss MBean. Here is a code snippet: import org.jboss.mx.util.MBeanServerLocator; import org.jboss.mx.util.MBeanProxyExt; import org.jboss.cache.TreeCacheMBean; import javax.management.MBeanServer; ... MBeanServer server; TreeCacheMBean cache; public init() throws Exception { try { server = MBeanServerLocator.locateJBoss(); cache = (TreeCacheMBean) MBeanProxyExt.create(TreeCacheMBean.class, "jboss.cache:service=TreeCache", server); } catch (Exception ex) { // handle exception } } public void myBusinessMethod() { Object value = cache.get("/my/node", "myKey"); HashMap stuff = new HashMap(); stuff.put("key1", "value1"); stuff.put("key2", "value2"); stuff.put("key3", "value3"); cache.put("/my/new/node", stuff); cache.remove("/my/node"); ... } | |
Can I run JBoss Cache on JBoss AS 3.2.x releases? | |
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. | |
Can I run multiple JBoss Cache instances on the same VM? | |
Yes. There are some scenarios where you may want to run multiple instances of JBoss Cache. For example, you want to run multiple local cache instances with each instance having its own configuration (e.g., different cache policy). In this case, you will need multiple xml configuration files. | |
Can TreeCache run as a second level cache inside Hibernate? | |
Yes. Since Hibernate 3.0 release, you can configure it to use JBoss Cache (namely, TreeCache) as a second level cache. For details, see Hibernate documentation, and also see http://wiki.jboss.org/wiki/Wiki.jsp?page=JBossCacheHibernate 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. | |
What about using PojoCache as a Hibernate cache? | |
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 provide any advantage. | |
How can I configure JBoss Cache? | |
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. | |
In the configuration xml file, there are tags such as class, MBean, etc. What are these? | |
These are tags for deploying JBoss Cache as a JBoss MBean service. For consistency, we have kept them in the standalone package as well, specifically, the MBean tag. If you run in standalone mode, JBoss Cache will ignore these elements. | |
What is the difference between the different cache modes? | |
JBossCache has five different cache modes, i.e., LOCAL, REPL_SYNC, REPL_ASYNC, INVALIDATION_SYNC and INVALIDATION_ASYNC. If you want to run JBoss Cache as a single instance, then you should set the cache mode to LOCAL so that it won't attempt to replicate anything. If you want to have synchronous replication among different JBoss Cache instances, you set it to REPL_SYNC. For asynchronous replication, use AYSNC_REPL. If you do not wish to replicate cached data but simply inform other caches in a cluster that data under specific addresses are now stale and should be evicted from memory, use INVALIDATION_SYNC or INVALIDTAION_ASYNC. Synchronous and asynchronous behavior applies to invalidation as well as replication. Note that ASYNC_REPL and INVALIDATION_ASYNC are non-blocking. This can be useful when you want to have another JBoss Cache serving as a mirror or backup and you don't want to wait for confirmation that this mirror has received your messages. | |
How does JBoss Cache's replication mechanism work? | |
JBoss Cache leverages JGroups as a replication layer. A user can configure the cluster of JBoss Cache instances by sharing the same cluster name (cluster name). There is also an option of whether to populate the cache data upon starting a new instance in the ClusterConfig attribute. 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. | |
I run a 2 node cluster. If the network dies, do the caches continue to run? | |
Yes, both will continue to run, but depending on your replication mode, all transactions or operations may not complete. If REPL_SYNC is used, operations will fail while if REPL_ASYNC is used they will succeed. Even if they succeed though, caches will be out of sync. | |
Can I plug in library X instead of JGroups to handle remote calls and group communications? | |
At this stage (JBoss Cache 1.x) 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. | |
Does the cache need to replicate to every other instance in the cluster? Isn't this slow if the cluster is large? | |
As of JBoss Cache 1.4.0, 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 very easily with no extra impact on memory or network traffic with each node added. See the User Guide for more information on Buddy Replication, and how it can be used to achieve very high scalability. | |
If I have the need for different TreeCache properties (e.g., CacheMode and IsolationLevel), do I simply need to create multiple TreeCache instances with the appropriate configuration? | |
Yes. All the above mentioned properties are per cache instance. Therefore you will need a separate JBoss Cache instance. | |
Does the Tree Cache config ClusterName have any relation to the JBoss AS cluster PartitionName? | |
Yes. They are both JGroups group names. Besides the notion of a channel in JGroups, it also can partition the channel into different group names. | |
When using multiple JGroups based components [cluster-service.xml, treecache (multiple instances)], what is the correct/valid way to configure those components to make sure my multicast addresses don't conflict? | |
There are two parameters to consider: multicast address (plus port) and the group name. At minimum, you will have to run components using a different group name. But whether to run them on the same channel depends upon whether the communication performance is critical for you or not. If it is, then it'd be best to run them on different channels. | |
Does JBoss Cache currently support cache persistence storage? | |
Yes. Starting with release 1.1, JBoss Cache has a CacheLoader interface that supports cache persistence. See below. | |
Does JBoss Cache currently support cache passivation/ overflow to a data store? | |
Yes. Starting with release 1.2.4, JBoss Cache uses the CacheLoader to support cache passivation/ overflow. See documentation on how to configure and use this feature. | |
Is JBoss Cache thread safe? | |
Yes, it is thread safe. | |
Does JBoss Cache support XA (2PC) transactions now? | |
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. | |
Which TransactionManagers are supported by JBoss Cache? | |
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 (org.jboss.cache.tm.DummyTransactionManager) for testing purposes only. But note that DummyTransactionManager is not thread safe .i.e., it does not support concurrent transactions. Instead, only one transaction is allowed at a time. | |
How do I set up the cache to be transactional? | |
You either use the default (JBoss) TransactionManager to run JBossCache inside JBoss, or you have to implement the TransactionManagerLookup interface, and return an instance of your javax.transaction.TransactionManager. The configuration property TransactionManagerLookupClass 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 cache will look up the transaction context from this transaction manager. For the client code, here is a snippet to start and commit a transaction: 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(); | |
How do I control the cache locking level? | |
JBossCache lets you control the cache locking level through the transaction isolation level. This is configured through the attribute IsolationLevel. Currently, JBossCache employs pessimistic locking internally. And the transaction isolation level from the pessimist locking corresponds to JDBC isolation levels, namely, NONE, READ_UNCOMMITTED, READ_COMMITTED, REPEATABLE_READ, and SERIALIZABLE. Note that these isolation levels are ignored if optimistic locking is used. For details, please refer to the user manual. | |
How does JBoss Cache lock data for concurrent access? | |
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 at the cost of slight processing overhead and performance. See the documentation for a more detailed discussion on concurrency and locking in JBoss Cache. | |
How do I enable Optimistic Locking in JBoss Cache? | |
Use the XMl attribute NodeLockingScheme. Note that IsolationLevel is ignored if NodeLockingScheme is set to OPTIMISTIC. Also note that NodeLockingScheme defaults to PESSIMISTIC if omitted. | |
How does the write lock apply to an Fqn node, say, "/org/jboss/test"? | |
First of all, JBossCache has a notion of root that serves as a starting point for every navigational operation. The default is "/" (since the default separator is "/" for the fqn). The locking then is applied to the node under root, for example "/org" (no locking "/"). Furthermore, let's say when JBossCache 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 write lock on "/org/jboss/test". | |
Can I use the cache locking level even without a transaction context? | |
Yes. JBossCache 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 transaction as if it is under transaction with auto_commit on. | |
With replication (REPL_SYNC/REPL_ASYNC) or invalidation (INVALIDATION_SYNC/INVALIDATION_ASYNC), how often does the cache broadcast messages over the network? | |
If the updates are under transaction, then the broadcasts happen only when the transaction is about to commit (actually during the prepare stage internally). That is, it will be a batch update. However, if the operations are not under transaction context, then each update will trigger replication. Note that this has performance implication if network transport is heavy (it usually is). | |
How can I do a mass removal? | |
If you do a cache.remove("/root"), it will recursively remove all the entries under "/root". | |
Can I monitor and manage the JBoss Cache? | |
With JBoss Cache 1.3.0, you can if you are running JBoss Cache within JBoss AS or are using JDK 5.0's jconsole utility. See the chapter titled Management Information in the JBoss Cache user guide for more details. | |
Can I disable JBoss Cache management attributes in JBoss Cache 1.3.0? | |
Yes, you can. Set the UseInterceptorMbeans configuration attribute to false (this defaults to true). See the chapter titled Management Information in the JBoss Cache user guide for more details. | |
What is jboss-serialization.jar, introduced in JBoss Cache 1.4.x and do I need this? | |
jboss-serialization.jar is the JBoss Serialization library, which is much more efficient in terms of speed and CPU usage as well as the generated byte stream size than standard Java serialization. This very significantly improves replication performance of custom objects placed in the cache. From 1.4.x, JBoss Cache relies on this library and it is needed to run JBoss Cache. | |
Can I disable JBoss Serialization and revert back to standard Java serialization? | |
Yes you can, by passing in the -Dserialization.jboss=false environment variable to your JVM. | |
Does JBoss Cache support partitioning? | |
Not right now. JBoss Cache does not support partitioning that a user can configure to have different set of data residing on different cache instances while still participating as a replication group. | |
Does JBoss Cache handle the concept of application classloading inside, say, a J2EE container? | |
Application-specific classloading is used widely inside a J2EE 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 general, this leads to two kinds of problems:
To solve the first kind of issue, in JBoss Cache 1.2.4 we introduced the concept of a TreeCacheMarshaller. 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 the user guide for more details. To solve the second kind of issue, the only solution (that we know of) is to cache "serialized" byte code and only de-serialize it during every object get (and this will be expensive!). That is, during a put operation, the object instance will be serialized and therefore can be deserialized safely by a "foreign" classloader. However, the performance penalty of this approach is quite severe so in general another local in-vm version will need to be used as a "near-line" cache. Note also that each time the serialized bytes are deserialized, a new instance of the object is created. To help with this kind of handling, JBoss has a utility class called MarshalledValue 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 issue: import org.jboss.invocation.MarshalledValue; public class CacheService { private TreeCache cache_; 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)); return value; // only if successful } ... private Object getUnMarshalledValue(object value) { // assuming we use the calling thread context classloader return ((MarshalledValue)value).get(); } private Object getMarshalledValue(Object value) { return new MarshalledValue(value); } } | |
Does JBoss Cache currently support pre-event and post-event notification? | |
Yes. Starting with release 1.2.4, JBoss Cache has introduced ExtendedTreeCacheListener which takes in consideration pre and post event notification. See documentation for more details. Note that TreeCacheListener and ExtendedTreeCacheListener will be merged into TreeCacheListener in release 1.3. | |
How do I implement a custom listener to listen to TreeCache events? | |
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). 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); } } ... } |
What is a CacheLoader? | |
A CacheLoader is the connection of JBossCache to a (persistent) data store. The CacheLoader is called by JBossCache 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 called to store those modifications back to the store. In conjunction with eviction policies, JBossCache with a CacheLoader 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 all configured through XML, and the programmer doesn't have to take care of loading and eviction. JBossCache currently ships with several CacheLoader implementations, including:
| |
Can writing to CacheLoaders be asynchronous? | |
As of JBossCache 1.2.4, yes. Set the CacheLoaderAsynchronous property to true. See the JBossCache documentation for a more detailed discussion. By default though, all cache loader writes are synchronous and will block. | |
Can I write my own CacheLoader ? | |
Yes. A CacheLoader is a class implementing org.jboss.cache.loader.CacheLoader. It is configured via the XML file (see JBossCache and Tutorial documentation). | |
Does a CacheLoader have to use a persistent store ? | |
No, a CacheLoader 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' functionality in this case, but just the 'load' functionality. | |
What can I use a CacheLoader for? | |
Some applications:
| |
How do I configure JBossCache with a CacheLoader? | |
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. | |
Do I have to pay to use Sleepycat's CacheLoader? | |
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 http://www.sleepycat.com/jeforjbosscache. | |
Can I use more than one cache loader? | |
As of JBossCache 1.3.0, yes. With the new CacheLoaderConfiguration XML element (see user manual section on cache loaders) you can now 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 performing writes, all cache loaders are written to (except if the ignoreModifications element has been set to true for a specific cache loader. | |
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? | |
This is a known bug (see JBCACHE-477 and JBCACHE-352), 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. 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. |
I am having problems getting JBoss Cache to work, where can I get information on troubleshooting? | |
Troubleshooting section can be found in the following wiki link. |