---
---
= User managed caches
ifndef::sourcedir39[]
include::{includedir}/common.adoc[]
endif::sourcedir39[]

ifdef::notBuildingForSite[]
include::{includedir}/menu.adoc[]
endif::notBuildingForSite[]

[[overview]]
== Overview of User Managed Caches

=== What are user managed caches and what do they offer?

A user managed cache gives you a simple way to configure a cache directly,
without the complexity of setting up or using a CacheManager.
The choice whether to use a `UserManagedCache` rather than a `CacheManager` usually depends on
whether you need all of the built-in functionality of a `CacheManager`.
In cases where your cache requirements are relatively straightforward,
and you do not require the full range of features of a `CacheManager`, consider using a `UserManagedCache` instead.

Typical scenarios for using a `UserManagedCache` are: method local caches, thread local caches or any other place
where the lifecycle of the cache is shorter than the application lifecycle.

[[api-extensions]]
== API Extensions

=== User Managed Cache

If you use a `UserManagedCache`, you need to configure all required services by hand.

The `UserManagedCache` class extends the `Cache` class by offering additional methods:

* `init()` - initializes the cache
* `close()` - releases the cache resources
* `getStatus()` - returns a status

The `init` and `close` methods deal with the lifecycle of the cache and need to be called explicitly,
whereas these methods are hidden when the cache is inside a `CacheManager`.

The interface definition is shown in this code:

[source%nowrap,java,indent=0]
----
include::{sourcedir39}/api/src/main/java/org/ehcache/UserManagedCache.java[lines=17..-1]
----

=== User Managed Persistent Cache

A user managed persistent cache holds cached data in a persistent store such as disk,
so that the stored data can outlive the JVM in which your caching application runs.

If you want to create a user managed persistent cache,
there is an additional interface `PersistentUserManagedCache` that extends `UserManagedCache` and adds the `destroy` method.

The `destroy` method deletes all data structures, including data stored persistently on disk, for a `PersistentUserManagedCache`.

The `destroy` method deals with the lifecycle of the cache and needs to be called explicitly.

The interface definition is shown in this code:

[source%nowrap,java,indent=0]
----
include::{sourcedir39}/api/src/main/java/org/ehcache/PersistentUserManagedCache.java[lines=17..-1]
----

[[code-examples]]
== Code examples for User Managed Caches

=== Example of a basic cache lifecycle

Here is a simple example showing a basic lifecycle of a user managed cache:

[source%nowrap,java,indent=0]
----
include::{sourcedir39}/impl/src/test/java/org/ehcache/docs/UserManagedCaches.java[tag=userManagedCacheExample]
----

<1> Create a `UserManagedCache` instance. You can either pass `true` to have the builder `init()` it for you,
or you can pass `false` and it is up to you to `init()` it prior to using it.
<2> Since `false` was passed in, you have to `init()` the `UserManagedCache` prior to using it.
<3> You can use the cache exactly as a managed cache.
<4> In the same vein, a `UserManagedCache` requires you to close it explicitly using `UserManagedCache.close()`.
If you are also using managed caches simultaneously, the `CacheManager.close()` operation would not impact the user managed cache(s).

From this basic example, explore the API of `UserManagedCacheBuilder` in code or through Javadoc to discover all the directly available features.

The following features apply in the exact same way to user managed caches:

* <<serializers-copiers#,Serializers and Copiers>>
* <<eviction-advisor#,Eviction Advisors>>

Simply use the methods from `UserManagedCacheBuilder` which are equivalent to the ones from `CacheConfigurationBuilder`.

Below we will describe a more advanced setup where you need to maintain a service instance in order to have a working user managed cache.

=== Example with disk persistence and lifecycle

If you want to use disk persistent cache, you will need to create and lifecycle the persistence service:

[source%nowrap,java,indent=0]
----
include::{sourcedir39}/impl/src/test/java/org/ehcache/docs/UserManagedCaches.java[tag=persistentUserManagedCache]
----

<1> Create the persistence service to be used by the cache for storing data on disk.
<2> Pass the persistence service to the builder as well as a name for the cache.
Note that this will make the builder produce a more specific type: `PersistentUserManagedCache`.
<3> As usual, indicate here if the data should outlive the cache.
<4> Closing the cache will not delete the data it saved on disk, since the cache is marked as persistent.
<5> To delete the data on disk after closing the cache, you need to invoke the `destroy` method explicitly.
<6> You need to stop the persistence service once you have finished using the cache.

=== Example with cache event listeners

Cache event listeners require executor services in order to work.
You will have to provide either a `CacheEventDispatcher` implementation or make use of the default one
by providing two executor services: one for ordered events and one for unordered ones.

NOTE: The ordered events executor must be single threaded to guarantee ordering.

For more information on cache event listeners, see the section <<cache-event-listeners#,Cache Event Listeners>>.

[source%nowrap,java,indent=0]
----
include::{sourcedir39}/impl/src/test/java/org/ehcache/docs/UserManagedCaches.java[tag=userManagedListenerCache]
----

<1> Provide the `ExecutorService` for ordered and unordered event delivery.
<2> Provide a listener configuration using `CacheEventListenerConfigurationBuilder`.
