[jbosscache-commits] JBoss Cache SVN: r8135 - enterprise-docs/trunk/Cache_FAQ/en-US.

Author: irooskov(a)redhat.com Date: 2009-07-09 18:54:53 -0400 (Thu, 09 Jul 2009) New Revision: 8135 Added: enterprise-docs/trunk/Cache_FAQ/en-US/JBoss_Cache_Frequently_Asked_Questions_CP06.ent enterprise-docs/trunk/Cache_FAQ/en-US/JBoss_Cache_Frequently_Asked_Questions_CP06.xml Removed: enterprise-docs/trunk/Cache_FAQ/en-US/JBoss_Cache_Frequently_Asked_Questions_CP04.ent enterprise-docs/trunk/Cache_FAQ/en-US/JBoss_Cache_Frequently_Asked_Questions_CP04.xml Modified: enterprise-docs/trunk/Cache_FAQ/en-US/Book_Info.xml Log: updating book for next CP Modified: enterprise-docs/trunk/Cache_FAQ/en-US/Book_Info.xml =================================================================== --- enterprise-docs/trunk/Cache_FAQ/en-US/Book_Info.xml 2009-07-09 22:38:18 UTC (rev 8134) +++ enterprise-docs/trunk/Cache_FAQ/en-US/Book_Info.xml 2009-07-09 22:54:53 UTC (rev 8135) @@ -2,13 +2,13 @@ <!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> <bookinfo> - <title>JBoss Cache Frequently Asked Questions CP04</title> - <subtitle>for Use with JBoss Enterprise Application Platform 4.3 Cumulative Patch 4</subtitle> + <title>JBoss Cache Frequently Asked Questions CP06</title> + <subtitle>for Use with JBoss Enterprise Application Platform 4.3 Cumulative Patch 6</subtitle> <edition>2.0</edition> <pubsnumber>1</pubsnumber> <productname>JBoss Enterprise Application Platform</productname> <productnumber>4.3</productnumber> - <pubdate>June, 2007</pubdate> +<!-- <pubdate>, 2009</pubdate> --> <abstract> <para>This book is a compilation of frequently asked questions about JBoss Cache</para> </abstract> Deleted: enterprise-docs/trunk/Cache_FAQ/en-US/JBoss_Cache_Frequently_Asked_Questions_CP04.ent =================================================================== --- enterprise-docs/trunk/Cache_FAQ/en-US/JBoss_Cache_Frequently_Asked_Questions_CP04.ent 2009-07-09 22:38:18 UTC (rev 8134) +++ enterprise-docs/trunk/Cache_FAQ/en-US/JBoss_Cache_Frequently_Asked_Questions_CP04.ent 2009-07-09 22:54:53 UTC (rev 8135) @@ -1,3 +0,0 @@ -<!ENTITY HOLDER "Red Hat, Inc"> -<!ENTITY YEAR "2008"> -<!ENTITY VERSION ""> Deleted: enterprise-docs/trunk/Cache_FAQ/en-US/JBoss_Cache_Frequently_Asked_Questions_CP04.xml =================================================================== --- enterprise-docs/trunk/Cache_FAQ/en-US/JBoss_Cache_Frequently_Asked_Questions_CP04.xml 2009-07-09 22:38:18 UTC (rev 8134) +++ enterprise-docs/trunk/Cache_FAQ/en-US/JBoss_Cache_Frequently_Asked_Questions_CP04.xml 2009-07-09 22:54:53 UTC (rev 8135) @@ -1,2252 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> -<book id="cache_faq"> - <xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - - <chapter id="general"> - - <title>General Information</title> - <qandaset> - <qandaentry id="a1"> - <question> - <para>What is JBoss Cache?</para> - </question> - - <answer> - <para>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. - </para> - - <para>Currently, JBoss Cache consists of two components: a generic cache - (implemented internally as - <literal>org.jboss.cache.TreeCache</literal> - ) and a POJO cache (implemented - internally as - <literal>org.jboss.cache.aop.PojoCache</literal> - ). - <literal>TreeCache</literal> - is a tree-structured cache that provides replication and - transaction context, while - <literal>PojoCache</literal> - extends the functionality of - <literal>TreeCache</literal> - but behaves as a true object cache providing transparent - and finer-grained object mapping into internal cache. - </para> - </answer> - </qandaentry> - - <qandaentry id="a2"> - <question> - <para>Who are the JBoss Cache developers?</para> - </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> - </answer> - </qandaentry> - - <qandaentry id="a3"> - <question> - <para>What is the license for JBoss Cache?</para> - </question> - - <answer> - <para>JBoss Cache is licensed under - <ulink url="http://www.gnu.org/licenses/lgpl.html">LGPL</ulink> - . - </para> - </answer> - </qandaentry> - - <qandaentry id="a4"> - <question> - <para>Where can I download JBoss Cache?</para> - </question> - - <answer> - <para>The JBoss Cache - <ulink url="http://www.jboss.com/products/jbosscache/downloads">pro... download page</ulink> - has prebuilt binaries as well as source distributions. You can also grab snapshots from the JBoss CVS - repository (see - <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=CVSRepository">... wiki page</ulink> - ) - the module name is - <emphasis role="bold">JBossCache</emphasis> - </para> - </answer> - </qandaentry> - - <qandaentry id="a5"> - <question> - <para>How do I build JBoss Cache from CVS sources?</para> - </question> - - <answer> - <para>To build, do - <literal>sh build.sh - jar - </literal> - . This will produce - <literal>jboss-cache.jar</literal> - in the - <literal>dist/lib</literal> - directory. Or if you want to - build the standalone package, do - <literal>sh build.sh dist</literal> - this will produce - <literal>dist/jboss-cache-dist.zip</literal> - 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. - </para> - </answer> - </qandaentry> - - <qandaentry id="a6"> - <question> - <para>Which JVMs 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> - </answer> - </qandaentry> - - <qandaentry id="a7"> - <question> - <para>From JBoss Cache 1.3.0 onwards, there is a new directory - <code>lib-50</code> - , - what is it? - </para> - </question> - - <answer> - <para>From JBoss Cache 1.3.0 onwards, we support the use of Java 5 annotations, used by PojoCache. - As a result, there are - <code>jboss-aop-jdk50.jar</code> - and - <code>jboss-cache-jdk50.jar</code> - that - are needed to work with the Java 5 annotations. You will need to replace - <code>jboss-aop.jar</code> - and - <code>jboss-cache.jar</code> - in the lib directory with the - <code>-jdk50</code> - versions if you intend - to use PojoCache, Java 5 and annotations. - </para> - </answer> - </qandaentry> - - <qandaentry id="a8"> - <question> - <para>How do I know the version of JBoss Cache that I am using?</para> - </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> - </answer> - </qandaentry> - - <qandaentry id="a9"> - <question> - <para>Can I run JBoss Cache outside of JBoss Application - Server? - </para> - </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> - </listitem> - </itemizedlist> - </answer> - </qandaentry> - - <qandaentry id="a101"> - <question> - <para>Where can I report bugs or problems?</para> - </question> - - <answer> - <para>Please report any bugs or problems to - <ulink - url="http://www.jboss.org/index.html?module=bb&amp;op=viewforum&... Cache - User Forum - </ulink> - . - </para> - </answer> - </qandaentry> - </qandaset> - </chapter> - <chapter id="tree_cache"> - <title>JBoss Cache - Tree Cache</title> - <qandaset> - <qandaentry id="a10"> - <question> - <para>How do I deploy JBoss Cache as a MBean service?</para> - </question> - - <answer> - <para>To deploy JBoss Cache as an MBean inside JBoss, you can copy the - configuration xml file over to the - <literal>deploy</literal> - directory (from - <literal>all</literal> - configuration whereby the - necessary jars are present). Under the standalone package - <literal>etc/META-INF</literal> - directory , there are example - configuration files for different cache modes that can be used to - deploy JBoss Cache as well. - </para> - </answer> - </qandaentry> - - <qandaentry id="a11"> - <question> - <para>How do I know if my JBoss Cache MBean has been deployed?</para> - </question> - - <answer> - <para>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 - <literal>jboss.cache</literal> - domain. - </para> - </answer> - </qandaentry> - - <qandaentry id="a12"> - <question> - <para>How do I access the JBoss Cache MBean?</para> - </question> - - <answer> - <para>Accessing the JBoss Cache MBean is just like accessing any - JBoss MBean. Here is a code snippet: - </para> - - <programlisting> - 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"); - - ... - } - - </programlisting> - </answer> - </qandaentry> - - <qandaentry id="a13"> - <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 id="a14"> - <question> - <para>Can I run multiple JBoss Cache instances on the same VM?</para> - </question> - - <answer> - <para>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. - </para> - </answer> - </qandaentry> - - <qandaentry id="a15"> - <question> - <para>Can TreeCache 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, - see Hibernate documentation, and also see - <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JBossCacheHibernate&qu... - 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 id="a16"> - <question> - <para>What about using PojoCache 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 - provide any advantage. - </para> - </answer> - </qandaentry> - - <qandaentry id="a17"> - <question> - <para>How can I configure JBoss Cache?</para> - </question> - - <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. - </para> - </answer> - </qandaentry> - - <qandaentry id="a18"> - <question> - <para>In the configuration xml file, there are tags such as - <literal>class</literal> - , - <literal>MBean</literal> - , etc. What are - these? - </para> - </question> - - <answer> - <para>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 - <literal>MBean</literal> - tag. If you run in standalone mode, - JBoss Cache will ignore these elements. - </para> - </answer> - </qandaentry> - - <qandaentry id="a19"> - <question> - <para>What is the difference between the different cache - modes? - </para> - </question> - - <answer> - <para>JBossCache has five different cache modes, i.e., - <literal>LOCAL</literal> - , - <literal>REPL_SYNC</literal> - , - <literal>REPL_ASYNC</literal> - , - <literal>INVALIDATION_SYNC</literal> - and - <literal>INVALIDATION_ASYNC</literal> - . If you want to run JBoss Cache as a - single instance, then you should set the cache mode to - <literal>LOCAL</literal> - 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 - <literal>REPL_SYNC</literal> - . - For asynchronous replication, use - <literal>AYSNC_REPL</literal> - . 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 - <literal>INVALIDATION_SYNC</literal> - or - <literal>INVALIDTAION_ASYNC</literal> - . Synchronous and asynchronous behavior applies to invalidation as well as replication. - </para> - - <para>Note that - <literal>ASYNC_REPL</literal> - and - <literal>INVALIDATION_ASYNC</literal> - 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. - </para> - </answer> - </qandaentry> - - <qandaentry id="a20"> - <question> - <para>How does JBoss Cache's replication mechanism work?</para> - </question> - - <answer> - <para>JBoss Cache leverages - <ulink url="http://www.jgroups.org">JGroups</ulink> - as a replication layer. A user - can configure the cluster of JBoss Cache instances by sharing the - same cluster name ( - <literal>cluster name</literal> - ). There is also - an option of whether to populate the cache data upon starting a new - instance in the - <literal>ClusterConfig</literal> - attribute. - </para> - - <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. - </para> - </answer> - </qandaentry> - - <qandaentry id="a21"> - <question> - <para>I run a 2 node cluster. If the network dies, do the caches continue to run?</para> - </question> - - <answer> - <para>Yes, both will continue to run, but depending on your replication mode, all transactions or - operations may not complete. If - <literal>REPL_SYNC</literal> - is used, operations will fail while if - <literal>REPL_ASYNC</literal> - is used they will succeed. Even if they succeed though, caches will be out of sync. - </para> - </answer> - </qandaentry> - - - <qandaentry id="a22"> - <question> - <para>Can I plug in library X instead of JGroups to handle remote calls and group communications?</para> - </question> - - <answer> - <para>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. - </para> - </answer> - </qandaentry> - - <qandaentry id="a23"> - <question> - <para>Does the cache need to replicate to every other instance in the cluster? Isn't this slow if the - cluster is large? - </para> - </question> - - <answer> - <para>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. - </para> - <para> - See the User Guide for more information on Buddy Replication, and how it can be used to achieve very - high - scalability. - </para> - </answer> - </qandaentry> - - <qandaentry id="a24"> - <question> - <para>If I have the need for different TreeCache properties (e.g., - <literal>CacheMode</literal> - and - <literal>IsolationLevel</literal> - ), do I simply need to create multiple - TreeCache 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. - </para> - </answer> - </qandaentry> - - <qandaentry id="a25"> - <question> - <para>Does the Tree Cache config - <literal>ClusterName</literal> - have - any relation to the JBoss AS cluster - <literal>PartitionName</literal> - ? - </para> - </question> - - <answer> - <para>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. - </para> - </answer> - </qandaentry> - - <qandaentry id="a26"> - <question> - <para>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? - </para> - </question> - - <answer> - <para>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. - </para> - </answer> - </qandaentry> - - <qandaentry id="a27"> - <question> - <para>Does JBoss Cache currently 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> - </answer> - </qandaentry> - - <qandaentry id="a28"> - <question> - <para>Does JBoss Cache currently 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 - documentation on how to configure and use this feature. - </para> - </answer> - </qandaentry> - - <qandaentry id="a29"> - <question> - <para>Is JBoss Cache thread safe?</para> - </question> - - <answer> - <para>Yes, it is thread safe.</para> - </answer> - </qandaentry> - - <qandaentry id="a30"> - <question> - <para>Does JBoss Cache support XA (2PC) transactions now?</para> - </question> - - <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. - </para> - </answer> - </qandaentry> - - <qandaentry id="a31"> - <question> - <para>Which TransactionManagers 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 - ( - <literal>org.jboss.cache.tm.DummyTransactionManager</literal> - ) for - testing purposes only. But note that - <literal>DummyTransactionManager</literal> - is not thread safe .i.e., - it does not support concurrent transactions. Instead, only one - transaction is allowed at a time. - </para> - </answer> - </qandaentry> - - <qandaentry id="a32"> - <question> - <para>How do I set up the cache to be transactional?</para> - </question> - - <answer> - <para>You either use the default (JBoss) TransactionManager to run - JBossCache inside JBoss, or you have to implement the - <literal>TransactionManagerLookup</literal> - interface, and return an - instance of your javax.transaction.TransactionManager. 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 - 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> - - <qandaentry id="a33"> - <question> - <para>How do I control the cache locking level?</para> - </question> - - <answer> - <para>JBossCache 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 - isolation levels, namely, - <literal>NONE</literal> - , - <literal>READ_UNCOMMITTED</literal> - , - <literal>READ_COMMITTED</literal> - , - <literal>REPEATABLE_READ</literal> - , and - <literal>SERIALIZABLE</literal> - . Note that these isolation levels are ignored if optimistic locking is used. For details, please - refer - to the - user manual. - </para> - </answer> - </qandaentry> - - <qandaentry id="a34"> - <question> - <para>How does JBoss Cache lock data for concurrent access?</para> - </question> - - <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 - at - the cost of slight processing overhead and performance. See the documentation for a more detailed - discussion on concurrency and locking in JBoss Cache. - </para> - </answer> - </qandaentry> - - - <qandaentry id="a35"> - <question> - <para>How do I enable Optimistic Locking in JBoss Cache?</para> - </question> - - <answer> - <para>Use the XMl attribute - <code>NodeLockingScheme</code> - . Note that - <code>IsolationLevel</code> - is ignored if - <code>NodeLockingScheme</code> - is set to - <code>OPTIMISTIC</code> - . Also note that - <code>NodeLockingScheme</code> - defaults to - <code>PESSIMISTIC</code> - if omitted. - </para> - </answer> - </qandaentry> - - - <qandaentry id="a36"> - <question> - <para>How does the write lock apply to an Fqn node, say, - "/org/jboss/test"? - </para> - </question> - - <answer> - <para>First of all, JBossCache 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). - The locking then is applied to the node under root, for example - "/org" (no locking "/"). - </para> - - <para>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". - </para> - </answer> - </qandaentry> - - <qandaentry id="a37"> - <question> - <para>Can I use the cache locking level even without a transaction - context? - </para> - </question> - - <answer> - <para>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 - <literal>auto_commit</literal> - on. - </para> - </answer> - </qandaentry> - - <qandaentry id="a38"> - <question> - <para>With replication (REPL_SYNC/REPL_ASYNC) or invalidation (INVALIDATION_SYNC/INVALIDATION_ASYNC), how - often does the cache broadcast messages over the network? - </para> - </question> - - <answer> - <para>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). - </para> - </answer> - </qandaentry> - - <qandaentry id="a39"> - <question> - <para>How can I do a mass removal?</para> - </question> - - <answer> - <para>If you do a cache.remove("/root"), it will recursively remove - all the entries under "/root". - </para> - </answer> - </qandaentry> - - <qandaentry id="a40"> - <question> - <para>Can I monitor and manage the JBoss Cache?</para> - </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 - <literal>jconsole</literal> - utility. See the chapter titled - <emphasis role="bold">Management Information</emphasis> - in the JBoss Cache user guide for more details. - </para> - </answer> - </qandaentry> - - <qandaentry id="a41"> - <question> - <para>Can I disable JBoss Cache management attributes in JBoss Cache 1.3.0?</para> - </question> - - <answer> - <para>Yes, you can. Set the - <literal>UseInterceptorMbeans</literal> - configuration attribute to - <literal>false</literal> - (this defaults to - <literal>true</literal> - ). See the chapter titled - <emphasis role="bold">Management Information</emphasis> - in the JBoss Cache user guide for more details. - </para> - </answer> - </qandaentry> - - <qandaentry id="a42"> - <question> - <para>What is jboss-serialization.jar, introduced in JBoss Cache 1.4.x and do I need this?</para> - </question> - <answer> - <para>jboss-serialization.jar is the - <ulink url="http://labs.jboss.org/portal/index.html?ctrl:id=page.default.in... - JBoss Serialization - </ulink> - 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. - </para> - <para> - From 1.4.x, JBoss Cache relies on this library and it is needed to run JBoss Cache. - </para> - </answer> - </qandaentry> - - <qandaentry id="a43"> - <question> - <para>Can I disable JBoss Serialization and revert back to standard Java serialization?</para> - </question> - - <answer> - <para>Yes you can, by passing in the - <literal>-Dserialization.jboss=false</literal> - environment variable to your JVM. - </para> - </answer> - </qandaentry> - - - <qandaentry id="a44"> - <question> - <para>Does JBoss Cache support partitioning?</para> - </question> - - <answer> - <para>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. - </para> - </answer> - </qandaentry> - - <qandaentry id="a45"> - <question> - <para>Does JBoss Cache handle the concept of application classloading - inside, say, a J2EE container? - </para> - </question> - - <answer> - <para>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: - </para> - - <itemizedlist> - <listitem> - <para>Object instance is stored in cache1 and replicated to - cache2. As a result, the instance in cache2 is created by the - system classloader. The replication may fail if the system - classloader on cache2 does not have access to the required - class. Even if replication doesn't fail, a user thread in cache2 - may not be able to access the object if the user thread is - expecting a type defined by the application classloader. - </para> - </listitem> - - <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. - 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 - 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> - . - 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. - </para> - - <para>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. - </para> - - <para>To help with this kind of handling, JBoss has a utility class - called - <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 - issue: - </para> - - <programlisting>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); - } - } - - </programlisting> - </answer> - </qandaentry> - - <qandaentry id="a46"> - <question> - <para>Does JBoss Cache currently support pre-event and post-event - notification? - </para> - </question> - - <answer> - <para>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. - </para> - </answer> - </qandaentry> - - <qandaentry id="a47"> - <question> - <para>How do I implement a custom listener to listen to - <literal>TreeCache</literal> - 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> - - <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 id="a48"> - <question> - <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 - workaround for those replicated caches that upon state transfer did not have access to the - classloaders defining the objects in the cache. - </para> - - <para>On each deployment, JBoss creates a new classloader per the top level deployment artifact, for - example an EAR. You also have to bear in mind that a class in an application server is defined not - only by the class name but also its classloader. So, assuming that the cache is not deployed as part - of your deployment, you could deploy an application and put instances of classes belonging to this - deployment inside the cache. If you did a redeployment and try to do a get operation of the data - previously put, this would result on a ClassCastException. This is because even though the class names - are the same, the class definitions are not. The current classloader is different to the one when - the classes were originally put. - </para> - - <para>By enabling marshalling, you can control the lifecycle of the data in the cache and if on - undeployment, you inactivate the region and unregister the classloader that you'd have registered on - 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 - 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>. - 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> - </answer> - </qandaentry> - - </qandaset> - </chapter> - <chapter - id="PojoCache"> - <title>JBoss Cache - Pojo Cache</title> - <qandaset> - - - <qandaentry> - <question> - <para>What is PojoCache?</para> - </question> - - <answer> - <para>PojoCache (currently implemented PojoCache as a sub-class of - TreeCache) is a fine-grained field-level replicated and - transactional POJO (plain old Java object) cache. By POJO, we mean - that the cache: 1) automatically manages object mapping and - relationship for a client under both local and replicated cache - mode, 2) provides support for inheritance relationship between - "aspectized" POJOs. By leveraging the dynamic AOP in JBossAop, it is - able to map a complex object into the cache store, preserve and - manage the object relationship behind the scene. During replication - mode, it performs fine-granularity (i.e., on a per-field basis) - update, and thus has the potential to boost cache performance and - minimize network traffic. - </para> - - <para>From a user perspective, once your POJO is managed by the - cache, all cache operations are transparent. Therefore, all the - usual in-VM POJO method semantics are still preserved, providing - ease of use. For example, if a POJO has been put in PojoCache (by - calling putObject, for example), then any get/set method will be - intercepted by PojoCache to provide the data from the - cache. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>What's the relationship between PojoCache and TreeCacheAop classes?</para> - </question> - - <answer> - <para>Since release 1.4, we have created a new class called PojoCache (to better reflect the - cache nature). The old implementation TreeCacheAop has been deprecated. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Does PojoCache have all the functional capabilities of - TreeCache? - </para> - </question> - - <answer> - <para>Yes. PojoCache extends TreeCache so it has all the same - features TreeCache such as cache mode, transaction isolation level, - and eviction policy. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>What is the difference between TreeCache and - PojoCache? - </para> - </question> - - <answer> - <para>Think of PojoCache as a TreeCache on steroids. :-) - Seriously, both are cache stores-- one is a generic cache and the other other one POJO Cache. - However, while TreeCache only - provides pure object reference storage (e.g., - <literal>put(FQN fqn, - Object key, Object value) - </literal> - ), PojoCache goes beyond that - and performs fine-grained field level replication object mapping and - relationship management for a user behind the scenes. As a result, - if you have complex object systems that you would like to cache, you - can have PojoCache manage it for you. You simply treat your - object systems as they are residing in-memory, e.g., use your - regular POJO methods without worrying about cache management. - Furthermore, this is true in replication mode as well. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>What are the steps to use the PojoCache feature?</para> - </question> - - <answer> - <para>Starting from release 1.3, depends on the JDK you use, it has slightly different steps. But in - general, - in order to use PojoCache, you will need to: - </para> - - <itemizedlist> - <listitem> - <para>prepare POJO. You can do either via xml declaration or annotation. For annotation, you can - use either the JDK1.4 style or JDK50 one (of which is part of JVM spec). If you use JDK14, you - will - also need - a annotation pre-compiler (annoc) to pre-process it. - </para> - </listitem> - <listitem> - <para>instrumentation. You will need to instrument your POJO either at compile-time or load-time. - If you do it during compile-time, you use so-called aop pre-compiler (aopc) to do bytecode - manipulation. - If you do it via load-time, however, you need either a special system class loader or, in JDK50, - you can - use the javaagent option. - </para> - </listitem> - </itemizedlist> - <para>So if you use JDK50, for example, with annotation and load-time instrumentation, then you won't - need - any pre-processing step to use PojoCache. For a full example, please refer to the distro examples - directory. - There are numerous PojoCache examples that uses different options. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Can I run PojoCache in JBoss AS 3.2.x application - server? - </para> - </question> - - <answer> - <para>Yes and no. Yes, since JBossAop can also be back-ported to - 3.2.x (see JBossAop wiki for details). However, it will take some - effort. Therefore, the recommended JBoss version is 4.x to run - PojoCache. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Can PojoCache run as a MBean as well?</para> - </question> - - <answer> - <para>Yes. It is almost the same as TreeCache MBean. The only - difference is the object name and the class name. E.g., instead - of - <programlisting>&lt;mbean code="org.jboss.cache.TreeCache" - name="jboss.cache:service=TreeCache"&gt;</programlisting> - you will have: - <programlisting>&lt;mbean code="org.jboss.cache.aop.PojoCache" - name="jboss.cache:service=PojoCache"&gt;</programlisting> - in the xml configuration file. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Can I pre-compile the aop classes such that I don't need to - use the system classloader and jboss-aop configuration xml? - </para> - </question> - - <answer> - <para>Yes. The latest versions of JBossCache have a pre-compiler - option called - <literal>aopc</literal> - . You can use this option to - pre-compile your "aspectized" POJO. Once the classes have been byte - code generated, they can be treated as regular class files, i.e., - you will not need to include any - <literal>jboss-aop.xml</literal> - that specifies the advisable POJO and to specify the JBossAop system - class loader. - </para> - - <para>For an example of how to use - <literal>aopc</literal> - , please - see 1) - <literal>tools</literal> - directory for PojoCacheTasks14.xml - and PojoCacheTasks50.xml. Both contain Ant tasks that you can - import to your regular project for - <literal>annoc</literal> - and - <literal>aopc</literal> - . In addition, please also check out the - <literal>examples</literal> - directory for concrete examples. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>How do I use aopc on multiple module directories?</para> - </question> - - <answer> - <para>In aopc, you specify the src path for a specific directory. To - pre-compile multiple ones, you will need to invoke aopc multiple - times. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>What's in the - <literal>jboss-aop.xml</literal> - configuration? - </para> - </question> - - <answer> - <para> - <literal>jboss-aop.xml</literal> - is needed for POJO - instrumentation. In - <literal>jboss-aop.xml</literal> - , you can - declare your POJO (e.g., - <literal>Person</literal> - ) to be - "prepared", a JBossAop term to denote that the object will be - "aspectized" by the system. After this declaration, JBossAop will - invoke any interceptor that associates with this POJO. PojoCache - will dynamically add an - <literal>org.jboss.cache.aop.CacheInterceptor</literal> - to this POJO - to perform object mapping and relationship management. - </para> - - <para>Note that to add your POJO, you should declare all the fields - to be "prepared" as in the example. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Can I use annotation instead of the xml declaration?</para> - </question> - - <answer> - <para>Yes, starting with JBossCache 1.3, you can use annotation to - instrument your POJO for both JDK1.4 and 1.5. Check the documentation for details. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>What are the pro and con of xml vs. annotation?</para> - </question> - - <answer> - <para>It really depends on your organization environment, I'd say, since this can be turned into a - hot debate. Having said that, I feel strongly that POJO annotation is well suited for PojoCache. This - is - because once you specify the annotation, you'd probably change it rarely since there is no parameters - to - tune, for example. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>What are the - <literal&gt;(a)org.jboss.cache.aop.annotation.Transient&lt;/literal&gt; - and - <literal&gt;(a)org.jboss.cache.aop.annotation.Serializable&lt;/literal&gt; - field level annotations? - </para> - </question> - - <answer> - <para>Starting in 1.4, we also offer two additional field-level annotations. The first one, - <literal>@Transient</literal> - , - when applied has the same effect as declaring a field - <literal>transient</literal> - . PojoCache - won't put this field under management. - </para> - <para>The second one, - <literal>@Serializable</literal> - when applied, will cause PojoCache to - treat the field as a Serializable object even when it is - <literal>@PojoCacheable</literal> - . - </para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>What about compile-time vs. load-time instrumentation then?</para> - </question> - - <answer> - <para>Again it depends. But my preference is to do compile-time instrumentation via aopc. I prefer this - approach because it is easier to debug (at least at the development stage). In addition, once I - generate - the - new class, there is no more steps needed. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Is it possible to store the same object multiple times but - with different Fqn paths? Like /foo/byName and /foo/byId ? - </para> - </question> - - <answer> - <para>Yes, you can use PojoCache to do that. It supports the - notion of object reference. PojoCache manages the unique object - through association of the dynamic cache interceptor. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Do I need to declare all my objects "prepared" in - <literal>jboss-aop.xml</literal> - ? - </para> - </question> - - <answer> - <para>Not necessarily. If there is an object that you don't need the - cache to manage for you, you can leave it out of the declaration. - The cache will treat this object as a "primitive" type. However, the - object will need to implement - <literal>Serializable</literal> - interface for replication. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Can the cache aop intercept update via reflection?</para> - </question> - - <answer> - <para>No. The update via reflection will not be intercepted in - JBossAop and therefore PojoCache will not be able to perform the - necessary synchronization. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>When I declare my POJO to be "aspectized", what happens to the - fields with transient, static, and final modifiers? - </para> - </question> - - <answer> - <para>PojoCache currently will ignore the fields with these - modifiers. That is, it won't put these fields into the cache (and - thus no replication either). - </para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>What are those keys such as - <literal>JBoss:internal:class</literal> - and - <literal>AOPInstance</literal> - ? - </para> - </question> - - <answer> - <para>They are for internal use only. Users should ignore these keys - and values in the node hashmap. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>What about Collection classes? Do I need to declare them - "prepared"? - </para> - </question> - - <answer> - <para>No. Since the Collection classes such as - <literal>ArrayList</literal> - are java util classes, aop by default - won't instrument these classes. Instead, PojoCache will generate - a dynamic class proxy for the Collection classes (upon the - <literal>putObject</literal> - call is invoked). The proxy will - delegate the operations to a cache interceptor that implements the - actual Collection classes APIs. That is, the system classes won't be - invoked when used in PojoCache. - </para> - - <para>Internally, the cache interceptor implements the APIs by - direct interaction with respect to the underlying cache store. Note - that this can have implications in performance for certain APIs. For - example, both - <literal>ArrayList</literal> - and - <literal>LinkedList</literal> - will have the same implementation. - Plan is currently underway to optimize these APIs. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>How do I use - <literal>List</literal> - , - <literal>Set</literal> - , - and - <literal>Map</literal> - dynamic proxy? - </para> - </question> - - <answer> - <para>PojoCache supports classes extending from - <literal>List</literal> - , - <literal>Set</literal> - , and - <literal>Map</literal> - without users to declare them "aspectized". - It is done via a dynamic proxy. Here is a code snippet to use an - <literal>ArrayList</literal> - proxy class. - </para> - - <programlisting>ArrayList list = new ArrayList(); - list.add("first"); - - cache.putObject("/list/test", list); - // Put the list under the aop cache - list.add("second"); - // Won't work since AOP intercepts the dynamic proxy not the original POJO. - - ArrayList myList = (List)cache.getObject("/list/test"); - // we are getting a dynamic proxy instead - myList.add("second"); - // it works now - myList.add("third"); - myList.remove("third"); - </programlisting> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>What is the proper way of assigning two different keys with - Collection class object? - </para> - </question> - - <answer> - <para>Let's say you want to assign a - <literal>List</literal> - object - under two different names, you will need to use the class proxy to - insert the second time to ensure both are managed by the cache. Here - is the code snippet. - </para> - - <programlisting>ArrayList list = new ArrayList(); - list.add("first"); - - cache.putObject("/list", list); - // Put the list under the aop cache - - ArrayList myList = (List)cache.getObject("/list"); - // we are getting a dynamic proxy instead - myList.add("second"); - // it works now - - cache.putObject("/list_alias", myList); - // Note you will need to use the proxy here!! - myList.remove("second"); - </programlisting> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>OK, so I know I am supposed to use proxy when manipulating the - Collection classes once they are managed by the cache. But what - happens to Pojos that share the Collection objects, e.g., a - <literal>List</literal> - instance that is shared by 2 Pojos? - </para> - </question> - - <answer> - <para>Pojos that share Collection instance references will be - handled by the cache automatically. That is, when you ask the Cache - to manage it, the Cache will dynamically swap out the regular - Collection references with the dynamic proxy ones. As a result, it - is transparent to the users. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>What happens when my "aspectized" POJO has field members that - are of Collection class ? - </para> - </question> - - <answer> - <para>When a user puts a POJO into the cache through the call - <literal>putObject</literal> - , it will recursively map the field - members into the cache store as well. When the field member is of a - Collection class (e.g., List, Set, or Map), PojoCache will first - map the collection into cache. Then, it will swap out dynamically - the field reference with an corresponding proxy reference. - </para> - - <para>This is necessary so that an internal update on the field - member will be intercepted by the cache. - </para> - </answer> - </qandaentry> - - - <qandaentry> - <question> - <para>What are the limitation of Collection classes in PojoCache?</para> - </question> - - <answer> - <para>Use of Collection class in PojoCache helps you to track fine-grained changes - in your collection fields automatically. However, current implementation has the follow - limitation that we plan to address soon. - </para> - <para>Currently, we only support a limited implementation of Collection classes. That is, - we support APIs in List, Set, and Map. However, since the APIs do not stipulate - of constraints like NULL key or value, it makes mapping of user instance to our proxy tricky. - For example, ArrayList would allow NULL value and some other implementation would not. - The Set interface maps to java.util.HashSet implementation. The List interface maps - to java.util.ArrayList implementation. The Map interface maps to java.util.HashMap - implementation. - </para> - <para>Another related issue is the expected performance. For example, the current implementation is - ordered, - so - that makes insert/delete from the Collection slow. Performance between Set, Map and List collections - also - vary. - Adding items to a Set is slower than a List or Map, since Set does not allow duplicate entries. - </para> - </answer> - </qandaentry> - - - <qandaentry> - <question> - <para>What are the pros and cons of PojoCache?</para> - </question> - - <answer> - <para>As mentioned in the reference doc, PojoCache has the following advantages:</para> - <itemizedlist> - <listitem> - <para>Fine-grained replication and/or persistency. If you use a distributed PojoCache - and once your POJO is put in the cache store, there is no need to use another API to - trigger your changes. Furthermore, the replication are fine-grained field level. Note this - also applies to persistency. - </para> - </listitem> - <listitem> - <para>Fine-grained replication can have potential performance gain if your POJO is big and - the changes are fine-grained, e.g., only to some selected fields. - </para> - </listitem> - <listitem> - <para>POJO can posses object relationship, e.g., multiple referenced. Distributed - PojoCache will handle this transparently for you. - </para> - </listitem> - </itemizedlist> - <para>And here are some cases that you may not want to use PojoCache:</para> - <itemizedlist> - <listitem> - <para>You use only cache. That is you don't need replication or persistency. Then since - everything is operated on the in-memory POJO reference, there is no need for PojoCache. - </para> - </listitem> - <listitem> - <para>You have simple and small POJOs. Your POJO is small in size and also there is no - object relationship, then PojoCache possess not clear advantage to plain cache. - </para> - </listitem> - <listitem> - <para>Your application is bounded by memory usage. Because PojoCache need almost twice as much - of memory (the original POJO in-memory space and also the additional cache store for the - primitive fields), you may not want to use PojoCache. - </para> - </listitem> - <listitem> - <para>Your POJO lifetime is short. That is, you need to create and destroy your POJO often. - Then you need to do "pubObject" and "removeObject" often, it will be slow in performance. - </para> - </listitem> - </itemizedlist> - </answer> - </qandaentry> - </qandaset> - </chapter> - <chapter id="eviction"> - <title>Eviction Policies</title> - - <qandaset> - - - <qandaentry> - <question> - <para>Does JBoss Cache support eviction policies?</para> - </question> - - <answer> - <para>Yes. JBoss Cache currently implements a LRU eviction policy for - both TreeCache - ( - <literal>org.jboss.cache.eviction.LRUPolicy</literal> - ) and - PojoCache - ( - <literal>org.jboss.cache.aop.eviction.AopLRUPolicy</literal> - ). Users - can also plug in their own eviction policy algorithms. See user - manual for details. Currently there is user-contributed policy - called - <literal>FIFOPolicy</literal> - that evicts the node based on - FIFO principle only. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Why can't I use - <literal>org.jboss.cache.eviction.LRUPolicy</literal> - for - PojoCache as well? - </para> - </question> - - <answer> - <para>For PojoCache, you will need to use - <literal>org.jboss.cache.aop.eviction.AopLRUPolicy</literal> - ) because - AOP has its eviction algorithm, although is LRU but has totally - different notion of an "object", for example. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Does JBoss Cache's implemented LRU eviction policy operates in - replication mode? - </para> - </question> - - <answer> - <para>Yes and no. :-)</para> - - <para>The LRU policy only operates in local mode. That is, nodes are - only evicted locally. This may cause the cache contents not to be - synchronized temporarily. But when a user tries to obtain the cached - contents of an evicted node and finds out that is null (e.g., - <literal>get</literal> - returns null), it should get it from the - other data source and re-populate the data in the cache. During this - moment, the node content will be propagated and the cache content - will be in sync. - </para> - - <para>However, you still can run eviction policies with cache mode - set to either - <literal>REPL_SYNC</literal> - or - <literal>REPL_ASYNC</literal> - . Depending on your use case, you can - set multiple cache instances to have their own eviction policy - (which are applied locally) or just have selected instances with - eviction policies activated. - </para> - - <para>Also note that, with cache loader option, a locally evicted - node can also be persisted to the backend store and a user can - retrieve it from the store later on. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Does JBoss Cache support - <literal>Region</literal> - ? - </para> - </question> - - <answer> - <para>Yes. JBoss Cache has the notion of region where a user can - configure the eviction policy parameters (e.g., - <literal>maxNodes</literal> - or - <literal>timeToIdleSeconds</literal> - ) - </para> - - <para>A region in JBoss Cache denotes a portion of tree hierarchy, - e.g., a fully qualified name ( - <literal>FQN</literal> - ). For example, - a user can define - <literal>/org/jboss</literal> - and - <literal>/org/foocom</literal> - as two separate regions. But note - that you can configure the region programmatically now, i.e., - everything has to be configured through the xml file. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>What are the - <literal>EvictionPolicyConfig</literal> - tag - parameters for - <literal>org.jboss.cache.eviction.LRUPolicy</literal> - ? - </para> - </question> - - <answer> - <para>They are:</para> - - - <table> - <title>Parameters</title> - - <tgroup cols="2"> - <tbody> - <row> - <entry>wakeUpIntervalInSeconds</entry> - - <entry>Interval where the clean up thread wakes to process - the sitting queue and sweep away the old data. - </entry> - </row> - - <row> - <entry>region</entry> - - <entry>A area where each eviction policy parameters are - specified. Note that it needs a minimum of - <literal>/_default</literal> - region. - </entry> - </row> - - <row> - <entry>maxNodes</entry> - - <entry>Max number of nodes allowed in the eviction queue. 0 - means no limit. - </entry> - </row> - - <row> - <entry>timeToLiveInSeconds</entry> - - <entry>Age (in seconds) for the node to be evicted in the - queue. 0 denotes no limit. - </entry> - </row> - </tbody> - </tgroup> - </table> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>I have turned on the eviction policy, why do I still get "out - of memory" (OOM) exception? - </para> - </question> - - <answer> - <para>OOM can happen when the speed of cache access exceeds the - speed of eviction policy handling timer. Eviction policy handler - will wake up every - <literal>wakeUpIntervalInSeconds</literal> - seconds to process the eviction event queue. And the queue size is - fixed at 20000 now. So when the queue size is full, it will create a - backlog and cause OOM to happen unless the eviction timer catches - up. To address this problem, in addition to increase the VM heap - size, you can also reduce the - <literal>wakeUpIntervaleInSeconds</literal> - so the timer thread - processes the queue more frequently. - </para> - - <para>We will also externalize the queue size so it will be - configurable in the next release. - </para> - </answer> - </qandaentry> - </qandaset> - </chapter> - <chapter id="cacheloaders"> - <title>Cache Loaders</title> - - <qandaset> - - - <qandaentry> - <question> - <para>What is a CacheLoader?</para> - </question> - - <answer> - <para>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. - </para> - - <para>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. - </para> - - <para>JBossCache currently ships with several CacheLoader - implementations, including: - </para> - - <para> - <itemizedlist> - <listitem> - <para>FileCacheLoader: this implementation uses the file - system to store and retrieve data. JBossCache nodes are mapped - to directories, subnodes to subdirectories etc. Attributes of - a node are mapped to a file - <literal>data</literal> - inside the - directory. - </para> - </listitem> - - <listitem> - <para>BdbjeCacheLoader: this implementation is based on the - Sleepycat 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 - 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> - . - </para> - </listitem> - - <listitem> - <para>JDBCCacheLoader: 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> - </listitem> - </itemizedlist> - </para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Can writing to CacheLoaders 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 - detailed discussion. By default though, all cache loader writes are - synchronous and will block. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Can I write my own CacheLoader ?</para> - </question> - - <answer> - <para>Yes. A CacheLoader is a class implementing - <literal>org.jboss.cache.loader.CacheLoader</literal> - . It is - configured via the XML file (see JBossCache and Tutorial - documentation). - </para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Does a CacheLoader have to use a persistent store ?</para> - </question> - - <answer> - <para>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. - </para> - </answer> - </qandaentry> - - <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> - </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 - <ulink - url="http://www.sleepycat.com/jeforjbosscache">http://www.sl... - </ulink> - . - </para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>Can I use more than one cache loader?</para> - </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 - 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. - </para> - </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-... - and - <ulink url="http://jira.jboss.com/jira/browse/JBCACHE-352">JBCACHE-... - ), 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> - <chapter id="troubleshooting"> - <title>Troubleshooting</title> - <qandaset> - - <qandaentry> - <question> - <para>I am having problems getting JBoss Cache to work, where can I get information on troubleshooting? - </para> - </question> - <answer> - <para>Troubleshooting section can be found in the following - <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JBossCacheTroubleshoot... link</ulink> - . - </para> - </answer> - </qandaentry> - </qandaset> - </chapter> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Revision_History.xml"/> - -</book> Added: enterprise-docs/trunk/Cache_FAQ/en-US/JBoss_Cache_Frequently_Asked_Questions_CP06.ent =================================================================== --- enterprise-docs/trunk/Cache_FAQ/en-US/JBoss_Cache_Frequently_Asked_Questions_CP06.ent (rev 0) +++ enterprise-docs/trunk/Cache_FAQ/en-US/JBoss_Cache_Frequently_Asked_Questions_CP06.ent 2009-07-09 22:54:53 UTC (rev 8135) @@ -0,0 +1,3 @@ +<!ENTITY HOLDER "Red Hat, Inc"> +<!ENTITY YEAR "2009"> +<!ENTITY VERSION ""> Added: enterprise-docs/trunk/Cache_FAQ/en-US/JBoss_Cache_Frequently_Asked_Questions_CP06.xml =================================================================== --- enterprise-docs/trunk/Cache_FAQ/en-US/JBoss_Cache_Frequently_Asked_Questions_CP06.xml (rev 0) +++ enterprise-docs/trunk/Cache_FAQ/en-US/JBoss_Cache_Frequently_Asked_Questions_CP06.xml 2009-07-09 22:54:53 UTC (rev 8135) @@ -0,0 +1,2252 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> +<book id="cache_faq"> + <xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <chapter id="general"> + + <title>General Information</title> + <qandaset> + <qandaentry id="a1"> + <question> + <para>What is JBoss Cache?</para> + </question> + + <answer> + <para>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. + </para> + + <para>Currently, JBoss Cache consists of two components: a generic cache + (implemented internally as + <literal>org.jboss.cache.TreeCache</literal> + ) and a POJO cache (implemented + internally as + <literal>org.jboss.cache.aop.PojoCache</literal> + ). + <literal>TreeCache</literal> + is a tree-structured cache that provides replication and + transaction context, while + <literal>PojoCache</literal> + extends the functionality of + <literal>TreeCache</literal> + but behaves as a true object cache providing transparent + and finer-grained object mapping into internal cache. + </para> + </answer> + </qandaentry> + + <qandaentry id="a2"> + <question> + <para>Who are the JBoss Cache developers?</para> + </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> + </answer> + </qandaentry> + + <qandaentry id="a3"> + <question> + <para>What is the license for JBoss Cache?</para> + </question> + + <answer> + <para>JBoss Cache is licensed under + <ulink url="http://www.gnu.org/licenses/lgpl.html">LGPL</ulink> + . + </para> + </answer> + </qandaentry> + + <qandaentry id="a4"> + <question> + <para>Where can I download JBoss Cache?</para> + </question> + + <answer> + <para>The JBoss Cache + <ulink url="http://www.jboss.com/products/jbosscache/downloads">pro... download page</ulink> + has prebuilt binaries as well as source distributions. You can also grab snapshots from the JBoss CVS + repository (see + <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=CVSRepository">... wiki page</ulink> + ) - the module name is + <emphasis role="bold">JBossCache</emphasis> + </para> + </answer> + </qandaentry> + + <qandaentry id="a5"> + <question> + <para>How do I build JBoss Cache from CVS sources?</para> + </question> + + <answer> + <para>To build, do + <literal>sh build.sh + jar + </literal> + . This will produce + <literal>jboss-cache.jar</literal> + in the + <literal>dist/lib</literal> + directory. Or if you want to + build the standalone package, do + <literal>sh build.sh dist</literal> + this will produce + <literal>dist/jboss-cache-dist.zip</literal> + 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. + </para> + </answer> + </qandaentry> + + <qandaentry id="a6"> + <question> + <para>Which JVMs 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> + </answer> + </qandaentry> + + <qandaentry id="a7"> + <question> + <para>From JBoss Cache 1.3.0 onwards, there is a new directory + <code>lib-50</code> + , + what is it? + </para> + </question> + + <answer> + <para>From JBoss Cache 1.3.0 onwards, we support the use of Java 5 annotations, used by PojoCache. + As a result, there are + <code>jboss-aop-jdk50.jar</code> + and + <code>jboss-cache-jdk50.jar</code> + that + are needed to work with the Java 5 annotations. You will need to replace + <code>jboss-aop.jar</code> + and + <code>jboss-cache.jar</code> + in the lib directory with the + <code>-jdk50</code> + versions if you intend + to use PojoCache, Java 5 and annotations. + </para> + </answer> + </qandaentry> + + <qandaentry id="a8"> + <question> + <para>How do I know the version of JBoss Cache that I am using?</para> + </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> + </answer> + </qandaentry> + + <qandaentry id="a9"> + <question> + <para>Can I run JBoss Cache outside of JBoss Application + Server? + </para> + </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> + </listitem> + </itemizedlist> + </answer> + </qandaentry> + + <qandaentry id="a101"> + <question> + <para>Where can I report bugs or problems?</para> + </question> + + <answer> + <para>Please report any bugs or problems to + <ulink + url="http://www.jboss.org/index.html?module=bb&amp;op=viewforum&... Cache + User Forum + </ulink> + . + </para> + </answer> + </qandaentry> + </qandaset> + </chapter> + <chapter id="tree_cache"> + <title>JBoss Cache - Tree Cache</title> + <qandaset> + <qandaentry id="a10"> + <question> + <para>How do I deploy JBoss Cache as a MBean service?</para> + </question> + + <answer> + <para>To deploy JBoss Cache as an MBean inside JBoss, you can copy the + configuration xml file over to the + <literal>deploy</literal> + directory (from + <literal>all</literal> + configuration whereby the + necessary jars are present). Under the standalone package + <literal>etc/META-INF</literal> + directory , there are example + configuration files for different cache modes that can be used to + deploy JBoss Cache as well. + </para> + </answer> + </qandaentry> + + <qandaentry id="a11"> + <question> + <para>How do I know if my JBoss Cache MBean has been deployed?</para> + </question> + + <answer> + <para>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 + <literal>jboss.cache</literal> + domain. + </para> + </answer> + </qandaentry> + + <qandaentry id="a12"> + <question> + <para>How do I access the JBoss Cache MBean?</para> + </question> + + <answer> + <para>Accessing the JBoss Cache MBean is just like accessing any + JBoss MBean. Here is a code snippet: + </para> + + <programlisting> + 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"); + + ... + } + + </programlisting> + </answer> + </qandaentry> + + <qandaentry id="a13"> + <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 id="a14"> + <question> + <para>Can I run multiple JBoss Cache instances on the same VM?</para> + </question> + + <answer> + <para>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. + </para> + </answer> + </qandaentry> + + <qandaentry id="a15"> + <question> + <para>Can TreeCache 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, + see Hibernate documentation, and also see + <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JBossCacheHibernate&qu... + 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 id="a16"> + <question> + <para>What about using PojoCache 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 + provide any advantage. + </para> + </answer> + </qandaentry> + + <qandaentry id="a17"> + <question> + <para>How can I configure JBoss Cache?</para> + </question> + + <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. + </para> + </answer> + </qandaentry> + + <qandaentry id="a18"> + <question> + <para>In the configuration xml file, there are tags such as + <literal>class</literal> + , + <literal>MBean</literal> + , etc. What are + these? + </para> + </question> + + <answer> + <para>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 + <literal>MBean</literal> + tag. If you run in standalone mode, + JBoss Cache will ignore these elements. + </para> + </answer> + </qandaentry> + + <qandaentry id="a19"> + <question> + <para>What is the difference between the different cache + modes? + </para> + </question> + + <answer> + <para>JBossCache has five different cache modes, i.e., + <literal>LOCAL</literal> + , + <literal>REPL_SYNC</literal> + , + <literal>REPL_ASYNC</literal> + , + <literal>INVALIDATION_SYNC</literal> + and + <literal>INVALIDATION_ASYNC</literal> + . If you want to run JBoss Cache as a + single instance, then you should set the cache mode to + <literal>LOCAL</literal> + 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 + <literal>REPL_SYNC</literal> + . + For asynchronous replication, use + <literal>AYSNC_REPL</literal> + . 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 + <literal>INVALIDATION_SYNC</literal> + or + <literal>INVALIDTAION_ASYNC</literal> + . Synchronous and asynchronous behavior applies to invalidation as well as replication. + </para> + + <para>Note that + <literal>ASYNC_REPL</literal> + and + <literal>INVALIDATION_ASYNC</literal> + 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. + </para> + </answer> + </qandaentry> + + <qandaentry id="a20"> + <question> + <para>How does JBoss Cache's replication mechanism work?</para> + </question> + + <answer> + <para>JBoss Cache leverages + <ulink url="http://www.jgroups.org">JGroups</ulink> + as a replication layer. A user + can configure the cluster of JBoss Cache instances by sharing the + same cluster name ( + <literal>cluster name</literal> + ). There is also + an option of whether to populate the cache data upon starting a new + instance in the + <literal>ClusterConfig</literal> + attribute. + </para> + + <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. + </para> + </answer> + </qandaentry> + + <qandaentry id="a21"> + <question> + <para>I run a 2 node cluster. If the network dies, do the caches continue to run?</para> + </question> + + <answer> + <para>Yes, both will continue to run, but depending on your replication mode, all transactions or + operations may not complete. If + <literal>REPL_SYNC</literal> + is used, operations will fail while if + <literal>REPL_ASYNC</literal> + is used they will succeed. Even if they succeed though, caches will be out of sync. + </para> + </answer> + </qandaentry> + + + <qandaentry id="a22"> + <question> + <para>Can I plug in library X instead of JGroups to handle remote calls and group communications?</para> + </question> + + <answer> + <para>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. + </para> + </answer> + </qandaentry> + + <qandaentry id="a23"> + <question> + <para>Does the cache need to replicate to every other instance in the cluster? Isn't this slow if the + cluster is large? + </para> + </question> + + <answer> + <para>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. + </para> + <para> + See the User Guide for more information on Buddy Replication, and how it can be used to achieve very + high + scalability. + </para> + </answer> + </qandaentry> + + <qandaentry id="a24"> + <question> + <para>If I have the need for different TreeCache properties (e.g., + <literal>CacheMode</literal> + and + <literal>IsolationLevel</literal> + ), do I simply need to create multiple + TreeCache 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. + </para> + </answer> + </qandaentry> + + <qandaentry id="a25"> + <question> + <para>Does the Tree Cache config + <literal>ClusterName</literal> + have + any relation to the JBoss AS cluster + <literal>PartitionName</literal> + ? + </para> + </question> + + <answer> + <para>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. + </para> + </answer> + </qandaentry> + + <qandaentry id="a26"> + <question> + <para>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? + </para> + </question> + + <answer> + <para>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. + </para> + </answer> + </qandaentry> + + <qandaentry id="a27"> + <question> + <para>Does JBoss Cache currently 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> + </answer> + </qandaentry> + + <qandaentry id="a28"> + <question> + <para>Does JBoss Cache currently 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 + documentation on how to configure and use this feature. + </para> + </answer> + </qandaentry> + + <qandaentry id="a29"> + <question> + <para>Is JBoss Cache thread safe?</para> + </question> + + <answer> + <para>Yes, it is thread safe.</para> + </answer> + </qandaentry> + + <qandaentry id="a30"> + <question> + <para>Does JBoss Cache support XA (2PC) transactions now?</para> + </question> + + <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. + </para> + </answer> + </qandaentry> + + <qandaentry id="a31"> + <question> + <para>Which TransactionManagers 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 + ( + <literal>org.jboss.cache.tm.DummyTransactionManager</literal> + ) for + testing purposes only. But note that + <literal>DummyTransactionManager</literal> + is not thread safe .i.e., + it does not support concurrent transactions. Instead, only one + transaction is allowed at a time. + </para> + </answer> + </qandaentry> + + <qandaentry id="a32"> + <question> + <para>How do I set up the cache to be transactional?</para> + </question> + + <answer> + <para>You either use the default (JBoss) TransactionManager to run + JBossCache inside JBoss, or you have to implement the + <literal>TransactionManagerLookup</literal> + interface, and return an + instance of your javax.transaction.TransactionManager. 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 + 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> + + <qandaentry id="a33"> + <question> + <para>How do I control the cache locking level?</para> + </question> + + <answer> + <para>JBossCache 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 + isolation levels, namely, + <literal>NONE</literal> + , + <literal>READ_UNCOMMITTED</literal> + , + <literal>READ_COMMITTED</literal> + , + <literal>REPEATABLE_READ</literal> + , and + <literal>SERIALIZABLE</literal> + . Note that these isolation levels are ignored if optimistic locking is used. For details, please + refer + to the + user manual. + </para> + </answer> + </qandaentry> + + <qandaentry id="a34"> + <question> + <para>How does JBoss Cache lock data for concurrent access?</para> + </question> + + <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 + at + the cost of slight processing overhead and performance. See the documentation for a more detailed + discussion on concurrency and locking in JBoss Cache. + </para> + </answer> + </qandaentry> + + + <qandaentry id="a35"> + <question> + <para>How do I enable Optimistic Locking in JBoss Cache?</para> + </question> + + <answer> + <para>Use the XMl attribute + <code>NodeLockingScheme</code> + . Note that + <code>IsolationLevel</code> + is ignored if + <code>NodeLockingScheme</code> + is set to + <code>OPTIMISTIC</code> + . Also note that + <code>NodeLockingScheme</code> + defaults to + <code>PESSIMISTIC</code> + if omitted. + </para> + </answer> + </qandaentry> + + + <qandaentry id="a36"> + <question> + <para>How does the write lock apply to an Fqn node, say, + "/org/jboss/test"? + </para> + </question> + + <answer> + <para>First of all, JBossCache 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). + The locking then is applied to the node under root, for example + "/org" (no locking "/"). + </para> + + <para>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". + </para> + </answer> + </qandaentry> + + <qandaentry id="a37"> + <question> + <para>Can I use the cache locking level even without a transaction + context? + </para> + </question> + + <answer> + <para>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 + <literal>auto_commit</literal> + on. + </para> + </answer> + </qandaentry> + + <qandaentry id="a38"> + <question> + <para>With replication (REPL_SYNC/REPL_ASYNC) or invalidation (INVALIDATION_SYNC/INVALIDATION_ASYNC), how + often does the cache broadcast messages over the network? + </para> + </question> + + <answer> + <para>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). + </para> + </answer> + </qandaentry> + + <qandaentry id="a39"> + <question> + <para>How can I do a mass removal?</para> + </question> + + <answer> + <para>If you do a cache.remove("/root"), it will recursively remove + all the entries under "/root". + </para> + </answer> + </qandaentry> + + <qandaentry id="a40"> + <question> + <para>Can I monitor and manage the JBoss Cache?</para> + </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 + <literal>jconsole</literal> + utility. See the chapter titled + <emphasis role="bold">Management Information</emphasis> + in the JBoss Cache user guide for more details. + </para> + </answer> + </qandaentry> + + <qandaentry id="a41"> + <question> + <para>Can I disable JBoss Cache management attributes in JBoss Cache 1.3.0?</para> + </question> + + <answer> + <para>Yes, you can. Set the + <literal>UseInterceptorMbeans</literal> + configuration attribute to + <literal>false</literal> + (this defaults to + <literal>true</literal> + ). See the chapter titled + <emphasis role="bold">Management Information</emphasis> + in the JBoss Cache user guide for more details. + </para> + </answer> + </qandaentry> + + <qandaentry id="a42"> + <question> + <para>What is jboss-serialization.jar, introduced in JBoss Cache 1.4.x and do I need this?</para> + </question> + <answer> + <para>jboss-serialization.jar is the + <ulink url="http://labs.jboss.org/portal/index.html?ctrl:id=page.default.in... + JBoss Serialization + </ulink> + 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. + </para> + <para> + From 1.4.x, JBoss Cache relies on this library and it is needed to run JBoss Cache. + </para> + </answer> + </qandaentry> + + <qandaentry id="a43"> + <question> + <para>Can I disable JBoss Serialization and revert back to standard Java serialization?</para> + </question> + + <answer> + <para>Yes you can, by passing in the + <literal>-Dserialization.jboss=false</literal> + environment variable to your JVM. + </para> + </answer> + </qandaentry> + + + <qandaentry id="a44"> + <question> + <para>Does JBoss Cache support partitioning?</para> + </question> + + <answer> + <para>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. + </para> + </answer> + </qandaentry> + + <qandaentry id="a45"> + <question> + <para>Does JBoss Cache handle the concept of application classloading + inside, say, a J2EE container? + </para> + </question> + + <answer> + <para>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: + </para> + + <itemizedlist> + <listitem> + <para>Object instance is stored in cache1 and replicated to + cache2. As a result, the instance in cache2 is created by the + system classloader. The replication may fail if the system + classloader on cache2 does not have access to the required + class. Even if replication doesn't fail, a user thread in cache2 + may not be able to access the object if the user thread is + expecting a type defined by the application classloader. + </para> + </listitem> + + <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. + 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 + 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> + . + 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. + </para> + + <para>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. + </para> + + <para>To help with this kind of handling, JBoss has a utility class + called + <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 + issue: + </para> + + <programlisting>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); + } + } + + </programlisting> + </answer> + </qandaentry> + + <qandaentry id="a46"> + <question> + <para>Does JBoss Cache currently support pre-event and post-event + notification? + </para> + </question> + + <answer> + <para>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. + </para> + </answer> + </qandaentry> + + <qandaentry id="a47"> + <question> + <para>How do I implement a custom listener to listen to + <literal>TreeCache</literal> + 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> + + <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 id="a48"> + <question> + <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 + workaround for those replicated caches that upon state transfer did not have access to the + classloaders defining the objects in the cache. + </para> + + <para>On each deployment, JBoss creates a new classloader per the top level deployment artifact, for + example an EAR. You also have to bear in mind that a class in an application server is defined not + only by the class name but also its classloader. So, assuming that the cache is not deployed as part + of your deployment, you could deploy an application and put instances of classes belonging to this + deployment inside the cache. If you did a redeployment and try to do a get operation of the data + previously put, this would result on a ClassCastException. This is because even though the class names + are the same, the class definitions are not. The current classloader is different to the one when + the classes were originally put. + </para> + + <para>By enabling marshalling, you can control the lifecycle of the data in the cache and if on + undeployment, you inactivate the region and unregister the classloader that you'd have registered on + 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 + 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>. + 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> + </answer> + </qandaentry> + + </qandaset> + </chapter> + <chapter + id="PojoCache"> + <title>JBoss Cache - Pojo Cache</title> + <qandaset> + + + <qandaentry> + <question> + <para>What is PojoCache?</para> + </question> + + <answer> + <para>PojoCache (currently implemented PojoCache as a sub-class of + TreeCache) is a fine-grained field-level replicated and + transactional POJO (plain old Java object) cache. By POJO, we mean + that the cache: 1) automatically manages object mapping and + relationship for a client under both local and replicated cache + mode, 2) provides support for inheritance relationship between + "aspectized" POJOs. By leveraging the dynamic AOP in JBossAop, it is + able to map a complex object into the cache store, preserve and + manage the object relationship behind the scene. During replication + mode, it performs fine-granularity (i.e., on a per-field basis) + update, and thus has the potential to boost cache performance and + minimize network traffic. + </para> + + <para>From a user perspective, once your POJO is managed by the + cache, all cache operations are transparent. Therefore, all the + usual in-VM POJO method semantics are still preserved, providing + ease of use. For example, if a POJO has been put in PojoCache (by + calling putObject, for example), then any get/set method will be + intercepted by PojoCache to provide the data from the + cache. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>What's the relationship between PojoCache and TreeCacheAop classes?</para> + </question> + + <answer> + <para>Since release 1.4, we have created a new class called PojoCache (to better reflect the + cache nature). The old implementation TreeCacheAop has been deprecated. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>Does PojoCache have all the functional capabilities of + TreeCache? + </para> + </question> + + <answer> + <para>Yes. PojoCache extends TreeCache so it has all the same + features TreeCache such as cache mode, transaction isolation level, + and eviction policy. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>What is the difference between TreeCache and + PojoCache? + </para> + </question> + + <answer> + <para>Think of PojoCache as a TreeCache on steroids. :-) + Seriously, both are cache stores-- one is a generic cache and the other other one POJO Cache. + However, while TreeCache only + provides pure object reference storage (e.g., + <literal>put(FQN fqn, + Object key, Object value) + </literal> + ), PojoCache goes beyond that + and performs fine-grained field level replication object mapping and + relationship management for a user behind the scenes. As a result, + if you have complex object systems that you would like to cache, you + can have PojoCache manage it for you. You simply treat your + object systems as they are residing in-memory, e.g., use your + regular POJO methods without worrying about cache management. + Furthermore, this is true in replication mode as well. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>What are the steps to use the PojoCache feature?</para> + </question> + + <answer> + <para>Starting from release 1.3, depends on the JDK you use, it has slightly different steps. But in + general, + in order to use PojoCache, you will need to: + </para> + + <itemizedlist> + <listitem> + <para>prepare POJO. You can do either via xml declaration or annotation. For annotation, you can + use either the JDK1.4 style or JDK50 one (of which is part of JVM spec). If you use JDK14, you + will + also need + a annotation pre-compiler (annoc) to pre-process it. + </para> + </listitem> + <listitem> + <para>instrumentation. You will need to instrument your POJO either at compile-time or load-time. + If you do it during compile-time, you use so-called aop pre-compiler (aopc) to do bytecode + manipulation. + If you do it via load-time, however, you need either a special system class loader or, in JDK50, + you can + use the javaagent option. + </para> + </listitem> + </itemizedlist> + <para>So if you use JDK50, for example, with annotation and load-time instrumentation, then you won't + need + any pre-processing step to use PojoCache. For a full example, please refer to the distro examples + directory. + There are numerous PojoCache examples that uses different options. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>Can I run PojoCache in JBoss AS 3.2.x application + server? + </para> + </question> + + <answer> + <para>Yes and no. Yes, since JBossAop can also be back-ported to + 3.2.x (see JBossAop wiki for details). However, it will take some + effort. Therefore, the recommended JBoss version is 4.x to run + PojoCache. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>Can PojoCache run as a MBean as well?</para> + </question> + + <answer> + <para>Yes. It is almost the same as TreeCache MBean. The only + difference is the object name and the class name. E.g., instead + of + <programlisting>&lt;mbean code="org.jboss.cache.TreeCache" + name="jboss.cache:service=TreeCache"&gt;</programlisting> + you will have: + <programlisting>&lt;mbean code="org.jboss.cache.aop.PojoCache" + name="jboss.cache:service=PojoCache"&gt;</programlisting> + in the xml configuration file. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>Can I pre-compile the aop classes such that I don't need to + use the system classloader and jboss-aop configuration xml? + </para> + </question> + + <answer> + <para>Yes. The latest versions of JBossCache have a pre-compiler + option called + <literal>aopc</literal> + . You can use this option to + pre-compile your "aspectized" POJO. Once the classes have been byte + code generated, they can be treated as regular class files, i.e., + you will not need to include any + <literal>jboss-aop.xml</literal> + that specifies the advisable POJO and to specify the JBossAop system + class loader. + </para> + + <para>For an example of how to use + <literal>aopc</literal> + , please + see 1) + <literal>tools</literal> + directory for PojoCacheTasks14.xml + and PojoCacheTasks50.xml. Both contain Ant tasks that you can + import to your regular project for + <literal>annoc</literal> + and + <literal>aopc</literal> + . In addition, please also check out the + <literal>examples</literal> + directory for concrete examples. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>How do I use aopc on multiple module directories?</para> + </question> + + <answer> + <para>In aopc, you specify the src path for a specific directory. To + pre-compile multiple ones, you will need to invoke aopc multiple + times. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>What's in the + <literal>jboss-aop.xml</literal> + configuration? + </para> + </question> + + <answer> + <para> + <literal>jboss-aop.xml</literal> + is needed for POJO + instrumentation. In + <literal>jboss-aop.xml</literal> + , you can + declare your POJO (e.g., + <literal>Person</literal> + ) to be + "prepared", a JBossAop term to denote that the object will be + "aspectized" by the system. After this declaration, JBossAop will + invoke any interceptor that associates with this POJO. PojoCache + will dynamically add an + <literal>org.jboss.cache.aop.CacheInterceptor</literal> + to this POJO + to perform object mapping and relationship management. + </para> + + <para>Note that to add your POJO, you should declare all the fields + to be "prepared" as in the example. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>Can I use annotation instead of the xml declaration?</para> + </question> + + <answer> + <para>Yes, starting with JBossCache 1.3, you can use annotation to + instrument your POJO for both JDK1.4 and 1.5. Check the documentation for details. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>What are the pro and con of xml vs. annotation?</para> + </question> + + <answer> + <para>It really depends on your organization environment, I'd say, since this can be turned into a + hot debate. Having said that, I feel strongly that POJO annotation is well suited for PojoCache. This + is + because once you specify the annotation, you'd probably change it rarely since there is no parameters + to + tune, for example. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>What are the + <literal&gt;(a)org.jboss.cache.aop.annotation.Transient&lt;/literal&gt; + and + <literal&gt;(a)org.jboss.cache.aop.annotation.Serializable&lt;/literal&gt; + field level annotations? + </para> + </question> + + <answer> + <para>Starting in 1.4, we also offer two additional field-level annotations. The first one, + <literal>@Transient</literal> + , + when applied has the same effect as declaring a field + <literal>transient</literal> + . PojoCache + won't put this field under management. + </para> + <para>The second one, + <literal>@Serializable</literal> + when applied, will cause PojoCache to + treat the field as a Serializable object even when it is + <literal>@PojoCacheable</literal> + . + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>What about compile-time vs. load-time instrumentation then?</para> + </question> + + <answer> + <para>Again it depends. But my preference is to do compile-time instrumentation via aopc. I prefer this + approach because it is easier to debug (at least at the development stage). In addition, once I + generate + the + new class, there is no more steps needed. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>Is it possible to store the same object multiple times but + with different Fqn paths? Like /foo/byName and /foo/byId ? + </para> + </question> + + <answer> + <para>Yes, you can use PojoCache to do that. It supports the + notion of object reference. PojoCache manages the unique object + through association of the dynamic cache interceptor. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>Do I need to declare all my objects "prepared" in + <literal>jboss-aop.xml</literal> + ? + </para> + </question> + + <answer> + <para>Not necessarily. If there is an object that you don't need the + cache to manage for you, you can leave it out of the declaration. + The cache will treat this object as a "primitive" type. However, the + object will need to implement + <literal>Serializable</literal> + interface for replication. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>Can the cache aop intercept update via reflection?</para> + </question> + + <answer> + <para>No. The update via reflection will not be intercepted in + JBossAop and therefore PojoCache will not be able to perform the + necessary synchronization. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>When I declare my POJO to be "aspectized", what happens to the + fields with transient, static, and final modifiers? + </para> + </question> + + <answer> + <para>PojoCache currently will ignore the fields with these + modifiers. That is, it won't put these fields into the cache (and + thus no replication either). + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>What are those keys such as + <literal>JBoss:internal:class</literal> + and + <literal>AOPInstance</literal> + ? + </para> + </question> + + <answer> + <para>They are for internal use only. Users should ignore these keys + and values in the node hashmap. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>What about Collection classes? Do I need to declare them + "prepared"? + </para> + </question> + + <answer> + <para>No. Since the Collection classes such as + <literal>ArrayList</literal> + are java util classes, aop by default + won't instrument these classes. Instead, PojoCache will generate + a dynamic class proxy for the Collection classes (upon the + <literal>putObject</literal> + call is invoked). The proxy will + delegate the operations to a cache interceptor that implements the + actual Collection classes APIs. That is, the system classes won't be + invoked when used in PojoCache. + </para> + + <para>Internally, the cache interceptor implements the APIs by + direct interaction with respect to the underlying cache store. Note + that this can have implications in performance for certain APIs. For + example, both + <literal>ArrayList</literal> + and + <literal>LinkedList</literal> + will have the same implementation. + Plan is currently underway to optimize these APIs. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>How do I use + <literal>List</literal> + , + <literal>Set</literal> + , + and + <literal>Map</literal> + dynamic proxy? + </para> + </question> + + <answer> + <para>PojoCache supports classes extending from + <literal>List</literal> + , + <literal>Set</literal> + , and + <literal>Map</literal> + without users to declare them "aspectized". + It is done via a dynamic proxy. Here is a code snippet to use an + <literal>ArrayList</literal> + proxy class. + </para> + + <programlisting>ArrayList list = new ArrayList(); + list.add("first"); + + cache.putObject("/list/test", list); + // Put the list under the aop cache + list.add("second"); + // Won't work since AOP intercepts the dynamic proxy not the original POJO. + + ArrayList myList = (List)cache.getObject("/list/test"); + // we are getting a dynamic proxy instead + myList.add("second"); + // it works now + myList.add("third"); + myList.remove("third"); + </programlisting> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>What is the proper way of assigning two different keys with + Collection class object? + </para> + </question> + + <answer> + <para>Let's say you want to assign a + <literal>List</literal> + object + under two different names, you will need to use the class proxy to + insert the second time to ensure both are managed by the cache. Here + is the code snippet. + </para> + + <programlisting>ArrayList list = new ArrayList(); + list.add("first"); + + cache.putObject("/list", list); + // Put the list under the aop cache + + ArrayList myList = (List)cache.getObject("/list"); + // we are getting a dynamic proxy instead + myList.add("second"); + // it works now + + cache.putObject("/list_alias", myList); + // Note you will need to use the proxy here!! + myList.remove("second"); + </programlisting> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>OK, so I know I am supposed to use proxy when manipulating the + Collection classes once they are managed by the cache. But what + happens to Pojos that share the Collection objects, e.g., a + <literal>List</literal> + instance that is shared by 2 Pojos? + </para> + </question> + + <answer> + <para>Pojos that share Collection instance references will be + handled by the cache automatically. That is, when you ask the Cache + to manage it, the Cache will dynamically swap out the regular + Collection references with the dynamic proxy ones. As a result, it + is transparent to the users. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>What happens when my "aspectized" POJO has field members that + are of Collection class ? + </para> + </question> + + <answer> + <para>When a user puts a POJO into the cache through the call + <literal>putObject</literal> + , it will recursively map the field + members into the cache store as well. When the field member is of a + Collection class (e.g., List, Set, or Map), PojoCache will first + map the collection into cache. Then, it will swap out dynamically + the field reference with an corresponding proxy reference. + </para> + + <para>This is necessary so that an internal update on the field + member will be intercepted by the cache. + </para> + </answer> + </qandaentry> + + + <qandaentry> + <question> + <para>What are the limitation of Collection classes in PojoCache?</para> + </question> + + <answer> + <para>Use of Collection class in PojoCache helps you to track fine-grained changes + in your collection fields automatically. However, current implementation has the follow + limitation that we plan to address soon. + </para> + <para>Currently, we only support a limited implementation of Collection classes. That is, + we support APIs in List, Set, and Map. However, since the APIs do not stipulate + of constraints like NULL key or value, it makes mapping of user instance to our proxy tricky. + For example, ArrayList would allow NULL value and some other implementation would not. + The Set interface maps to java.util.HashSet implementation. The List interface maps + to java.util.ArrayList implementation. The Map interface maps to java.util.HashMap + implementation. + </para> + <para>Another related issue is the expected performance. For example, the current implementation is + ordered, + so + that makes insert/delete from the Collection slow. Performance between Set, Map and List collections + also + vary. + Adding items to a Set is slower than a List or Map, since Set does not allow duplicate entries. + </para> + </answer> + </qandaentry> + + + <qandaentry> + <question> + <para>What are the pros and cons of PojoCache?</para> + </question> + + <answer> + <para>As mentioned in the reference doc, PojoCache has the following advantages:</para> + <itemizedlist> + <listitem> + <para>Fine-grained replication and/or persistency. If you use a distributed PojoCache + and once your POJO is put in the cache store, there is no need to use another API to + trigger your changes. Furthermore, the replication are fine-grained field level. Note this + also applies to persistency. + </para> + </listitem> + <listitem> + <para>Fine-grained replication can have potential performance gain if your POJO is big and + the changes are fine-grained, e.g., only to some selected fields. + </para> + </listitem> + <listitem> + <para>POJO can posses object relationship, e.g., multiple referenced. Distributed + PojoCache will handle this transparently for you. + </para> + </listitem> + </itemizedlist> + <para>And here are some cases that you may not want to use PojoCache:</para> + <itemizedlist> + <listitem> + <para>You use only cache. That is you don't need replication or persistency. Then since + everything is operated on the in-memory POJO reference, there is no need for PojoCache. + </para> + </listitem> + <listitem> + <para>You have simple and small POJOs. Your POJO is small in size and also there is no + object relationship, then PojoCache possess not clear advantage to plain cache. + </para> + </listitem> + <listitem> + <para>Your application is bounded by memory usage. Because PojoCache need almost twice as much + of memory (the original POJO in-memory space and also the additional cache store for the + primitive fields), you may not want to use PojoCache. + </para> + </listitem> + <listitem> + <para>Your POJO lifetime is short. That is, you need to create and destroy your POJO often. + Then you need to do "pubObject" and "removeObject" often, it will be slow in performance. + </para> + </listitem> + </itemizedlist> + </answer> + </qandaentry> + </qandaset> + </chapter> + <chapter id="eviction"> + <title>Eviction Policies</title> + + <qandaset> + + + <qandaentry> + <question> + <para>Does JBoss Cache support eviction policies?</para> + </question> + + <answer> + <para>Yes. JBoss Cache currently implements a LRU eviction policy for + both TreeCache + ( + <literal>org.jboss.cache.eviction.LRUPolicy</literal> + ) and + PojoCache + ( + <literal>org.jboss.cache.aop.eviction.AopLRUPolicy</literal> + ). Users + can also plug in their own eviction policy algorithms. See user + manual for details. Currently there is user-contributed policy + called + <literal>FIFOPolicy</literal> + that evicts the node based on + FIFO principle only. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>Why can't I use + <literal>org.jboss.cache.eviction.LRUPolicy</literal> + for + PojoCache as well? + </para> + </question> + + <answer> + <para>For PojoCache, you will need to use + <literal>org.jboss.cache.aop.eviction.AopLRUPolicy</literal> + ) because + AOP has its eviction algorithm, although is LRU but has totally + different notion of an "object", for example. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>Does JBoss Cache's implemented LRU eviction policy operates in + replication mode? + </para> + </question> + + <answer> + <para>Yes and no. :-)</para> + + <para>The LRU policy only operates in local mode. That is, nodes are + only evicted locally. This may cause the cache contents not to be + synchronized temporarily. But when a user tries to obtain the cached + contents of an evicted node and finds out that is null (e.g., + <literal>get</literal> + returns null), it should get it from the + other data source and re-populate the data in the cache. During this + moment, the node content will be propagated and the cache content + will be in sync. + </para> + + <para>However, you still can run eviction policies with cache mode + set to either + <literal>REPL_SYNC</literal> + or + <literal>REPL_ASYNC</literal> + . Depending on your use case, you can + set multiple cache instances to have their own eviction policy + (which are applied locally) or just have selected instances with + eviction policies activated. + </para> + + <para>Also note that, with cache loader option, a locally evicted + node can also be persisted to the backend store and a user can + retrieve it from the store later on. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>Does JBoss Cache support + <literal>Region</literal> + ? + </para> + </question> + + <answer> + <para>Yes. JBoss Cache has the notion of region where a user can + configure the eviction policy parameters (e.g., + <literal>maxNodes</literal> + or + <literal>timeToIdleSeconds</literal> + ) + </para> + + <para>A region in JBoss Cache denotes a portion of tree hierarchy, + e.g., a fully qualified name ( + <literal>FQN</literal> + ). For example, + a user can define + <literal>/org/jboss</literal> + and + <literal>/org/foocom</literal> + as two separate regions. But note + that you can configure the region programmatically now, i.e., + everything has to be configured through the xml file. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>What are the + <literal>EvictionPolicyConfig</literal> + tag + parameters for + <literal>org.jboss.cache.eviction.LRUPolicy</literal> + ? + </para> + </question> + + <answer> + <para>They are:</para> + + + <table> + <title>Parameters</title> + + <tgroup cols="2"> + <tbody> + <row> + <entry>wakeUpIntervalInSeconds</entry> + + <entry>Interval where the clean up thread wakes to process + the sitting queue and sweep away the old data. + </entry> + </row> + + <row> + <entry>region</entry> + + <entry>A area where each eviction policy parameters are + specified. Note that it needs a minimum of + <literal>/_default</literal> + region. + </entry> + </row> + + <row> + <entry>maxNodes</entry> + + <entry>Max number of nodes allowed in the eviction queue. 0 + means no limit. + </entry> + </row> + + <row> + <entry>timeToLiveInSeconds</entry> + + <entry>Age (in seconds) for the node to be evicted in the + queue. 0 denotes no limit. + </entry> + </row> + </tbody> + </tgroup> + </table> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>I have turned on the eviction policy, why do I still get "out + of memory" (OOM) exception? + </para> + </question> + + <answer> + <para>OOM can happen when the speed of cache access exceeds the + speed of eviction policy handling timer. Eviction policy handler + will wake up every + <literal>wakeUpIntervalInSeconds</literal> + seconds to process the eviction event queue. And the queue size is + fixed at 20000 now. So when the queue size is full, it will create a + backlog and cause OOM to happen unless the eviction timer catches + up. To address this problem, in addition to increase the VM heap + size, you can also reduce the + <literal>wakeUpIntervaleInSeconds</literal> + so the timer thread + processes the queue more frequently. + </para> + + <para>We will also externalize the queue size so it will be + configurable in the next release. + </para> + </answer> + </qandaentry> + </qandaset> + </chapter> + <chapter id="cacheloaders"> + <title>Cache Loaders</title> + + <qandaset> + + + <qandaentry> + <question> + <para>What is a CacheLoader?</para> + </question> + + <answer> + <para>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. + </para> + + <para>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. + </para> + + <para>JBossCache currently ships with several CacheLoader + implementations, including: + </para> + + <para> + <itemizedlist> + <listitem> + <para>FileCacheLoader: this implementation uses the file + system to store and retrieve data. JBossCache nodes are mapped + to directories, subnodes to subdirectories etc. Attributes of + a node are mapped to a file + <literal>data</literal> + inside the + directory. + </para> + </listitem> + + <listitem> + <para>BdbjeCacheLoader: this implementation is based on the + Sleepycat 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 + 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> + . + </para> + </listitem> + + <listitem> + <para>JDBCCacheLoader: 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> + </listitem> + </itemizedlist> + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>Can writing to CacheLoaders 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 + detailed discussion. By default though, all cache loader writes are + synchronous and will block. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>Can I write my own CacheLoader ?</para> + </question> + + <answer> + <para>Yes. A CacheLoader is a class implementing + <literal>org.jboss.cache.loader.CacheLoader</literal> + . It is + configured via the XML file (see JBossCache and Tutorial + documentation). + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>Does a CacheLoader have to use a persistent store ?</para> + </question> + + <answer> + <para>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. + </para> + </answer> + </qandaentry> + + <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> + </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 + <ulink + url="http://www.sleepycat.com/jeforjbosscache">http://www.sl... + </ulink> + . + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>Can I use more than one cache loader?</para> + </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 + 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. + </para> + </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-... + and + <ulink url="http://jira.jboss.com/jira/browse/JBCACHE-352">JBCACHE-... + ), 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> + <chapter id="troubleshooting"> + <title>Troubleshooting</title> + <qandaset> + + <qandaentry> + <question> + <para>I am having problems getting JBoss Cache to work, where can I get information on troubleshooting? + </para> + </question> + <answer> + <para>Troubleshooting section can be found in the following + <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JBossCacheTroubleshoot... link</ulink> + . + </para> + </answer> + </qandaentry> + </qandaset> + </chapter> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Revision_History.xml"/> + +</book>