About this document

This document contains a high level overview of Infinispan's internal architecture.  This document is geared towards people with an interest in extending or enhancing Infinispan, or just curious about Infinispan’s internals.

Cache hierarchy

Infinispan’s Cache interface extends the JDK’s ConcurrentMap which gives you a familiar and easy-to-use API.

Caches are created by using a CacheContainer instance - either the EmbeddedCacheManager or a RemoteCacheManager.  In addition to their capabilities as a factory for Caches, CacheContainers also act as a registry for looking up Caches.

EmbeddedCacheManagers create either clustered or standalone Caches that reside in the same JVM.  RemoteCacheManagers, on the other hand, create RemoteCaches that connect to a remote cache tier via the Hot Rod Protocol protocol.

NOTE: Prior to Infinispan 4.1.0, the EmbeddedCacheManager was called the CacheManager, and there was no such thing as a RemoteCacheManager.

Commands

Internally, each and every cache operation is encapsulated by a command.  These command objects represent the type of operation being performed, and also hold references to necessary parameters.  The actual logic of a given command, for example a ReplaceCommand, is encapsulated in the command’s perform() method.  Very object-oriented and easy to test.

Visitors

Commands are processed by Visitors.  The visitor interface, displayed here, exposes methods to visit each of the different types of commands in the system.  This gives us a type-safe mechanism for adding behaviour to a call.

An AbstractVisitor is provided with no-op implementations of each of these methods.  Real implementations then only need override the visitor methods for the commands that interest them, allowing for very concise, readable and testable visitor implementations.

Interceptors

Interceptors are special types of Visitors, which are capable of visiting commands, but also acts in a chain.  A chain of interceptors all visit the command, one in turn, until all registered interceptors visit the command.

The class to note is the CommandInterceptor.  This abstract class implements the interceptor pattern, and also implements Visitor.  Infinispan's interceptors extend CommandInterceptor, and these add specific behaviour to specific commands, such as distribution across a network or writing through to disk.

Putting it all together

So how does this all hang together?  Invocations on the cache cause the cache to first create an invocation context for the call.  Invocation contexts contain, among other things, transactional characteristics of the call.  The cache then creates a command for the call, making use of a command factory which initialises the command instance with parameters and references to other subsystems.

The cache then passes the invocation context and command to the InterceptorChain, which calls each and every registered interceptor in turn to visit the command, adding behaviour to the call.  Finally, the command’s perform() method is invoked and the return value, if any, is propagated back to the caller.

Subsystem Managers

The interceptors act as simple interception points and don’t contain a lot of logic themselves.  Most behavioural logic is encapsulated as managers in various subsystems, some of which are displayed:

Managers themselves are all registered with the ComponentRegistry, an internal lookup for any specific subsystem.

The ComponentRegistry, injection and lifecycle

The ComponentRegistry acts as a very lean dependency injection framework, allowing components and managers to reference and initialise one another.  Here is an example of a component declaring a dependency on a DataContainer and a LockManager, and a DataContainerFactory declaring its ability to construct DataContainers on the fly.

Components registered with the ComponentRegistry may also have a lifecycle, and methods annotated with @Start or @Stop will be invoked before and after they are used by the component registry.

In the example above, the optional priority parameter to @Stop is used to indicate the order in which the component is stopped, in relation to other components.  This follows a Unix Sys-V style ordering, where smaller priority methods are called before higher priority ones.  The default priority, if not specified, is 10.