JBoss Enterprise Web Platform 5

JBoss Cache User Guide

for Use with JBoss Enterprise Web Platform 5

Edition 5.1.1

Legal Notice

Copyright © 2011 Red Hat, Inc.
This document is licensed by Red Hat under the Creative Commons Attribution-ShareAlike 3.0 Unported License. If you distribute this document, or a modified version of it, you must provide attribution to Red Hat, Inc. and provide a link to the original. If the document is modified, all Red Hat trademarks must be removed.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the Infinity Logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack Logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.

Abstract

This book is the User Guide for Cache of the JBoss Enterprise Web Platform 5 and its patch releases.
Preface
1. Document Conventions
1.1. Typographic Conventions
1.2. Pull-quote Conventions
1.3. Notes and Warnings
2. Getting Help and Giving Feedback
2.1. Do You Need Help?
2.2. Give us Feedback
I. Introduction to JBoss Cache
1. Overview
1.1. What is JBoss Cache?
1.1.1. And what is POJO Cache?
1.2. Summary of Features
1.2.1. Caching objects
1.2.2. Local and clustered modes
1.2.3. Clustered caches and transactions
1.2.4. Thread safety
1.3. Requirements
1.4. License
2. User API
2.1. API Classes
2.2. Instantiating and Starting the Cache
2.3. Caching and Retrieving Data
2.3.1. Organizing Your Data and Using the Node Structure
2.4. The Fqn Class
2.5. Stopping and Destroying the Cache
2.6. Cache Modes
2.7. Adding a Cache Listener - registering for cache events
2.7.1. Synchronous and Asynchronous Notifications
2.8. Using Cache Loaders
2.9. Using Eviction Policies
3. Configuration
3.1. Configuration Overview
3.2. Creating a Configuration
3.2.1. Parsing an XML-based Configuration File
3.2.2. Validating Configuration Files
3.2.3. Programmatic Configuration
3.2.4. Using an IOC Framework
3.3. Composition of a Configuration Object
3.4. Dynamic Reconfiguration
3.4.1. Overriding the Configuration via the Option API
4. Batching API
4.1. Introduction
4.2. Configuring batching
4.3. Batching API
5. Deploying JBoss Cache
5.1. Standalone Use/Programatic Deployment
5.2. Via JBoss Microcontainer (JBoss AS 5.x)
5.3. Automatic binding to JNDI in JBoss AS
5.4. Runtime Management Information
5.4.1. JBoss Cache MBeans
5.4.2. Registering the CacheJmxWrapper with the MBeanServer
5.4.3. JBoss Cache Statistics
5.4.4. Receiving JMX Notifications
5.4.5. Accessing Cache MBeans in a Standalone Environment using the jconsole Utility
II. JBoss Cache Architecture
6. Architecture
6.1. Data Structures Within The Cache
6.2. SPI Interfaces
6.3. Method Invocations On Nodes
6.3.1. Interceptors
6.3.2. Commands and Visitors
6.3.3. InvocationContexts
6.4. Managers For Subsystems
6.4.1. RpcManager
6.4.2. BuddyManager
6.4.3. CacheLoaderManager
6.5. Marshalling And Wire Formats
6.5.1. The Marshaller Interface
6.5.2. VersionAwareMarshaller
6.6. Class Loading and Regions
7. Cache Modes and Clustering
7.1. Cache Replication Modes
7.1.1. Local Mode
7.1.2. Replicated Caches
7.2. Invalidation
7.3. State Transfer
7.3.1. State Transfer Types
7.3.2. Byte array and streaming based state transfer
7.3.3. Full and partial state transfer
7.3.4. Transient ("in-memory") and persistent state transfer
7.3.5. Configuring State Transfer
8. Cache Loaders
8.1. The CacheLoader Interface and Lifecycle
8.2. Configuration
8.2.1. Singleton Store Configuration
8.3. Shipped Implementations
8.3.1. File system based cache loaders
8.3.2. Cache loaders that delegate to other caches
8.3.3. JDBCCacheLoader
8.3.4. S3CacheLoader
8.3.5. TcpDelegatingCacheLoader
8.3.6. Transforming Cache Loaders
8.4. Cache Passivation
8.4.1. Cache Loader Behavior with Passivation Disabled vs. Enabled
8.5. Strategies
8.5.1. Local Cache With Store
8.5.2. Replicated Caches With All Caches Sharing The Same Store
8.5.3. Replicated Caches With Only One Cache Having A Store
8.5.4. Replicated Caches With Each Cache Having Its Own Store
8.5.5. Hierarchical Caches
8.5.6. Multiple Cache Loaders
9. Eviction
9.1. Design
9.1.1. Collecting Statistics
9.1.2. Determining Which Nodes to Evict
9.1.3. How Nodes are Evicted
9.1.4. Eviction threads
9.2. Eviction Regions
9.2.1. Resident Nodes
9.3. Configuring Eviction
9.3.1. Basic Configuration
9.3.2. Programmatic Configuration
9.4. Shipped Eviction Policies
9.4.1. LRUAlgorithm - Least Recently Used
9.4.2. FIFOAlgorithm - First In, First Out
9.4.3. MRUAlgorithm - Most Recently Used
9.4.4. LFUAlgorithm - Least Frequently Used
9.4.5. ExpirationAlgorithm
9.4.6. ElementSizeAlgorithm - Eviction based on number of key/value pairs in a node
10. Transactions and Concurrency
10.1. Concurrent Access
10.1.1. Multi-Version Concurrency Control (MVCC)
10.1.2. Pessimistic and Optimistic Locking Schemes
10.2. JTA Support
III. JBoss Cache Configuration References
11. Configuration References
11.1. Sample XML Configuration File
11.1.1. XML validation
11.2. Configuration File Quick Reference
12. JMX References
12.1. JBoss Cache Statistics
12.2. JMX MBean Notifications
A. Revision History