---
---
= Class loading
ifndef::sourcedir39[]
include::{includedir}/common.adoc[]
endif::sourcedir39[]

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

[[about]]
== About class loading

Since Ehcache is a library and supports user types both in configuration and in mapping keys or values,
it must offer flexibility around class loading.

[[cl-default]]
=== Default classLoader in Ehcache

The default `ClassLoader` from Ehcache will first try to use the thread context class loader, through `Thread.currentThread().getContextClassLoader()`.
In case this fails to load the requested resource, it will then use the `ClassLoader` that loaded the Ehcache internal classes.

[[cl-user-types]]
== Handling user types

The way to configure a `ClassLoader` and the scope of its use differ between Java and XML based configurations.
However, regardless of the configuration method, each `CacheManager` and `Cache` is always linked individually to a specific `ClassLoader` instance.

[[cl-cfg-java]]
=== Java configuration

During the configuration of the `CacheManager` or `Cache`, there are multiple extension points where a user type can be involved.
This includes `Serializer`, `CacheLoaderWriter` and other similar companion objects.
You can usually give an instance of these types to the configuration or an instance of the class to use.
This effectively negates the need to think in terms of a class loader here.

However you can still pass a specific `ClassLoader` to the `CacheManager` configuration.
You can also give a specific `ClassLoader` per cache if you need to, taking precedence over the one configured at the `CacheManager` level.
These will be used <<cl-runtime,at runtime>>.

If no class loader is specified, the <<cl-default,default class loader>> from Ehcache will be used.

[[cl-cfg-xml]]
=== XML configuration

When using XML to configure Ehcache, references to custom types are given through a fully qualified class name.
This means that transforming these `String` names into the proper class representation may require a specific `ClassLoader`.

In order to support this, the `XmlConfiguration` constructors can take `ClassLoader` parameters:

`public XmlConfiguration(URL url)`::
to use only default ClassLoader

`public XmlConfiguration(URL url, final ClassLoader classLoader)`::
to use a specific ClassLoader at the CacheManager level

`public XmlConfiguration(URL url, final ClassLoader classLoader, final Map<String, ClassLoader> cacheClassLoaders)`::
to use a specific `ClassLoader` at the `CacheManager` level and a map of `<String, ClassLoader>` which will be used to link a specific `ClassLoader` to a `Cache` by its alias

In the same way as for the Java configuration, the `Cache` level configuration takes precedence over the `CacheManager` level one.
If no class loaders are specified, the default class loader from Ehcache will be used.

[[cl-runtime]]
=== At runtime

As soon as serialization is involved with `Cache` keys or values, the class loader plays a role at runtime.
The specific `ClassLoader` per `Cache` will be used by the serialization sub-system.
It will allow deserialization to types that may not be visible by the Ehcache `ClassLoader`.
