JBoss Cache Users' Guide
A clustered,
transactional cache
Release 3.2.0 Malagueta
iii
Preface ............................................................................................................................ vii
I. Introduction to JBoss Cache ........................................................................................... 1
1. Overview .............................................................................................................. 3
1.1. What is JBoss Cache? ................................................................................ 3
1.1.1. And what is POJO Cache? ............................................................... 3
1.2. Summary of Features ................................................................................. 3
1.2.1. Caching objects ............................................................................... 3
1.2.2. Local and clustered modes ............................................................... 4
1.2.3. Clustered caches and transactions .................................................... 4
1.2.4. Thread safety .................................................................................. 5
1.3. Requirements ............................................................................................ 5
1.4. License ...................................................................................................... 5
2. User API .............................................................................................................. 7
2.1. API Classes ............................................................................................... 7
2.2. Instantiating and Starting the Cache ............................................................ 9
2.3. Caching and Retrieving Data ..................................................................... 10
2.3.1. Organizing Your Data and Using the Node Structure ......................... 11
2.4. The Fqn Class ......................................................................................... 11
2.5. Stopping and Destroying the Cache ........................................................... 12
2.6. Cache Modes ........................................................................................... 13
2.7. Adding a Cache Listener - registering for cache events ............................... 13
2.7.1. Synchronous and Asynchronous Notifications ................................... 16
2.8. Using Cache Loaders ................................................................................ 16
2.9. Using Eviction Policies .............................................................................. 17
3. Configuration ..................................................................................................... 19
3.1. Configuration Overview ............................................................................. 19
3.2. Creating a Configuration ....................................................................... 19
3.2.1. Parsing an XML-based Configuration File ........................................ 19
3.2.2. Validating Configuration Files .......................................................... 19
3.2.3. Programmatic Configuration ............................................................ 20
3.2.4. Using an IOC Framework ............................................................... 20
3.3. Composition of a Configuration Object ................................................... 21
3.4. Dynamic Reconfiguration ........................................................................... 22
3.4.1. Overriding the Configuration via the Option API ................................ 22
4. Batching API ...................................................................................................... 25
4.1. Introduction ............................................................................................... 25
4.2. Configuring batching ................................................................................. 25
4.3. Batching API ............................................................................................ 25
5. Deploying JBoss Cache .................................................................................... 27
5.1. Standalone Use/Programatic Deployment ................................................... 27
5.2. Via JBoss Microcontainer (JBoss AS 5.x) ................................................... 27
5.3. Automatic binding to JNDI in JBoss AS ...................................................... 27
5.4. Runtime Management Information .............................................................. 27
5.4.1. JBoss Cache MBeans .................................................................... 28
JBoss Cache Users' Guide
iv
5.4.2. Registering the CacheJmxWrapper with the MBeanServer ................ 28
5.4.3. JBoss Cache Statistics ................................................................... 31
5.4.4. Receiving JMX Notifications ............................................................ 31
5.4.5. Accessing Cache MBeans in a Standalone Environment using the
jconsole Utility ....................................................................................... 33
6. Version Compatibility and Interoperability ......................................................... 35
6.1. API compatibility ....................................................................................... 35
6.2. Wire-level interoperability ........................................................................... 35
6.3. Compatibility Matrix ................................................................................... 35
II. JBoss Cache Architecture ............................................................................................ 37
7. Architecture ....................................................................................................... 39
7.1. Data Structures Within The Cache ............................................................. 39
7.2. SPI Interfaces ........................................................................................... 40
7.3. Method Invocations On Nodes ................................................................... 42
7.3.1. Interceptors .................................................................................... 42
7.3.2. Commands and Visitors .................................................................. 43
7.3.3. InvocationContexts ......................................................................... 43
7.4. Managers For Subsystems ........................................................................ 44
7.4.1. RpcManager .................................................................................. 44
7.4.2. BuddyManager ............................................................................... 44
7.4.3. CacheLoaderManager .................................................................... 44
7.5. Marshalling And Wire Formats ................................................................... 44
7.5.1. The Marshaller Interface ................................................................. 45
7.5.2. VersionAwareMarshaller ................................................................. 46
7.6. Class Loading and Regions ....................................................................... 46
8. Cache Modes and Clustering ............................................................................. 47
8.1. Cache Replication Modes .......................................................................... 47
8.1.1. Local Mode .................................................................................... 47
8.1.2. Replicated Caches ......................................................................... 47
8.2. Invalidation ............................................................................................... 51
8.3. State Transfer ........................................................................................... 51
8.3.1. State Transfer Types ...................................................................... 51
8.3.2. Byte array and streaming based state transfer .................................. 51
8.3.3. Full and partial state transfer .......................................................... 52
8.3.4. Transient ("in-memory") and persistent state transfer ........................ 53
8.3.5. Non-Blocking State Transfer ........................................................... 54
8.3.6. Configuring State Transfer .............................................................. 54
9. Cache Loaders ................................................................................................... 55
9.1. The CacheLoader Interface and Lifecycle ................................................... 56
9.2. Configuration ............................................................................................ 57
9.2.1. Singleton Store Configuration .......................................................... 59
9.3. Shipped Implementations .......................................................................... 60
9.3.1. File system based cache loaders .................................................... 60
9.3.2. Cache loaders that delegate to other caches .................................... 61
v
9.3.3. JDBCCacheLoader ......................................................................... 61
9.3.4. S3CacheLoader ............................................................................. 65
9.3.5. TcpDelegatingCacheLoader ............................................................ 67
9.3.6. Transforming Cache Loaders .......................................................... 68
9.4. Cache Passivation .................................................................................... 69
9.4.1. Cache Loader Behavior with Passivation Disabled vs. Enabled .......... 69
9.5. Strategies ................................................................................................. 70
9.5.1. Local Cache With Store .................................................................. 71
9.5.2. Replicated Caches With All Caches Sharing The Same Store ............ 71
9.5.3. Replicated Caches With Only One Cache Having A Store ................. 72
9.5.4. Replicated Caches With Each Cache Having Its Own Store ............... 73
9.5.5. Hierarchical Caches ....................................................................... 74
9.5.6. Multiple Cache Loaders .................................................................. 75
10. Eviction ............................................................................................................ 79
10.1. Design .................................................................................................... 79
10.1.1. Collecting Statistics ...................................................................... 79
10.1.2. Determining Which Nodes to Evict ................................................. 79
10.1.3. How Nodes are Evicted ................................................................ 80
10.1.4. Eviction threads ............................................................................ 80
10.2. Eviction Regions ..................................................................................... 80
10.2.1. Resident Nodes ............................................................................ 80
10.3. Configuring Eviction ................................................................................ 81
10.3.1. Basic Configuration ...................................................................... 81
10.3.2. Programmatic Configuration .......................................................... 82
10.4. Shipped Eviction Policies ......................................................................... 83
10.4.1. LRUAlgorithm - Least Recently Used ............................................. 83
10.4.2. FIFOAlgorithm - First In, First Out ................................................. 83
10.4.3. MRUAlgorithm - Most Recently Used ............................................. 83
10.4.4. LFUAlgorithm - Least Frequently Used .......................................... 84
10.4.5. ExpirationAlgorithm ....................................................................... 84
10.4.6. ElementSizeAlgorithm - Eviction based on number of key/value pairs
in a node ................................................................................................ 85
11. Transactions and Concurrency ........................................................................ 87
11.1. Concurrent Access .................................................................................. 87
11.1.1. Multi-Version Concurrency Control (MVCC) .................................... 87
11.1.2. Pessimistic and Optimistic Locking Schemes .................................. 90
11.2. JTA Support ........................................................................................... 91
III. JBoss Cache Configuration References ....................................................................... 93
12. Configuration References ................................................................................ 95
12.1. Sample XML Configuration File ................................................................ 95
12.1.1. XML validation ............................................................................ 100
12.2. Configuration File Quick Reference ....................................................... 100
13. JMX References ............................................................................................. 129
13.1. JBoss Cache Statistics .......................................................................... 129
