API Module

Contains all the interfaces, as well as exceptions, an Ehcache user would use explicitly. As a rule of thumb, you rarely want any actual code in this module. And when adding an interface, it should be a care one to the library, either from a user perspective, or from a SPI one.

CacheManager and its Cache instances

The CacheManager not only acts as a repository of Cache instances, but it also lifecycles them. The CacheManager is also responsible for lifecycling Service instances. These Service instances are provided by the CacheManager for its Cache instances to use. The Cache and Service instances can look up any Service by it’s type by querying the ServiceLocator.

CacheManager and Cache are two of the most important interfaces into Ehcache. They get supplemented by other interfaces such as Expiry, CacheEvent and other satellite types.

Configuration types

In order to create a CacheManager, you need to have a CacheConfiguration for each and every Cache instance you want to use. You also may need to configure some additional Service instances one or some of your Cache need (see below).

A CacheConfiguration is read-only and as such immutable. The new RuntimeCacheConfiguration type exposes additional mutative methods on parameters that are tunable at runtime (i.e. once a Cache is in Status.AVAILABLE).

SPI types

In

User-facing SPIs

Generic Service instances and their ServiceConfiguration

The ServiceLocator

Every CacheManager has its own ServiceLocator instance. The ServiceLocator acts as a repository of concrete Service which can then be looked up by type. The Service instances it knows about are the ones provided to it at CacheManager construction time. Service instances can be injected directly, but will more generally be declared for use by providing a matching ServiceConfiguration to the CacheManagerBuilder. Not all Service are necessarily required to be user facing (through one of their ServiceConfiguration for instance). If a requested Service can’t be found, it’ll be looked up using Java’s ServiceLoader facility from the classpath.

The ServiceLoader fallback for Service lookups can be used by the end-user, but is expected to be used mainly by anyone building an Ehcache Distribution (i.e. a so-called überjar created by some mean from all the different modules that composes it). The idea is to only couple different Service to the minimal and the strictly required level.