7.3. Method Invocations On Nodes

Since the cache is essentially a collection of nodes, aspects such as clustering, persistence, eviction, etc. need to be applied to these nodes when operations are invoked on the cache as a whole or on individual nodes. To achieve this in a clean, modular and extensible manner, an interceptor chain is used. The chain is built up of a series of interceptors, each one adding an aspect or particular functionality. The chain is built when the cache is created, based on the configuration used.
It is important to note that the NodeSPI offers some methods (such as the xxxDirect() method family) that operate on a node directly without passing through the interceptor stack. Plug-in authors should note that using such methods will affect the aspects of the cache that may need to be applied, such as locking, replication, etc. To put it simply, do not use such methods unless you really know what you are doing!

7.3.1. Interceptors

JBoss Cache essentially is a core data structure - an implementation of DataContainer - and aspects and features are implemented using interceptors in front of this data structure. A CommandInterceptor is an abstract class, interceptor implementations extend this.
CommandInterceptor implements the Visitor interface so it is able to alter commands in a strongly typed manner as the command makes its way to the data structure. More on visitors and commands in the next section.
Interceptor implementations are chained together in the InterceptorChain class, which dispatches a command across the chain of interceptors. A special interceptor, the CallInterceptor, always sits at the end of this chain to invoke the command being passed up the chain by calling the command's process() method.
JBoss Cache ships with several interceptors, representing different behavioral aspects, some of which are:
  • TxInterceptor - looks for ongoing transactions and registers with transaction managers to participate in synchronization events
  • ReplicationInterceptor - replicates state across a cluster using the RpcManager class
  • CacheLoaderInterceptor - loads data from a persistent store if the data requested is not available in memory
The interceptor chain configured for your cache instance can be obtained and inspected by calling CacheSPI.getInterceptorChain(), which returns an ordered List of interceptors in the order in which they would be encountered by a command.

7.3.1.1. Writing Custom Interceptors

Custom interceptors to add specific aspects or features can be written by extending CommandInterceptor and overriding the relevant visitXXX() methods based on the commands you are interested in intercepting. There are other abstract interceptors you could extend instead, such as the PrePostProcessingCommandInterceptor and the SkipCheckChainedInterceptor. Please see their respective javadocs for details on the extra features provided.
The custom interceptor will need to be added to the interceptor chain by using the Cache.addInterceptor() methods. See the javadocs on these methods for details.
Adding custom interceptors via XML is also supported, please see the Chapter 12, Configuration References for details.