= XML Configuration

Let's you configure a `CacheManager` at creation time, using a XML file, according to
link:src/main/resources/ehcache-core.xsd[this schema definition], namely:

== `<config>` root element

The root element of our XML configuration. One `<config>` element, and as such one XML file, corresponds to
a `CacheManager`. From Ehcache's perspective though, nothing prohibits from creating multiple `CacheManager` instances
off one XML configuration file. Ehcache does _not_ act as a repository of `CacheManager`, unlike JSR-107's
`javax.cache.spi.CachingProvider`.

=== `<service>` elements

Currently, no built-in services are provided. But `<service>` elements are, and will remain, an extension point for
`CacheManager` lifecycled services, i.e. `Service` instances that will be `.start()` and `.stop()` 'ed by the
`CacheManager` during its own lifecycle state transitions.

These `Service` instances can then be used by `Cache` instances managed by the `CacheManager`. JSR-107 uses this
extension point of the XML configuration (and Ehcache 3's modular architecture), as explained in the
link:../107/README.adoc#_supplement_jsr_107_s_configurations[JSR-107 configuration section].

=== `<cache>` elements

`<cache>` elements each represent a `Cache` that will be created, and then on managed, by the `CacheManager`.
Each `<cache>` requires the `alias` attribute, used at runtime to retrieve the corresponding `Cache<K, V>` instance using
the `org.ehcache.CacheManager.getCache(String, Class<K>, Class<V>)` method. The optional `usesTemplate` attribute, let's you reference
a `<cache-template>` element's `name` attribute. See the <<__code_cache_template_code_elements,cache-template section>>
for further details on using them.

Supported nested elements are optional:

 . `<key-type>`: the fully qualified class name (FQCN) of the keys (`<K>`) held in the `Cache<K, V>`, defaults to `java.lang.Object`
 . `<value-type>`: FQCN of the values (`<V>`) held in the `Cache`, defaults to `java.lang.Object`
 . `<capacity>`: a positive numerical value, defaults to `null`, i.e. unconstrained
 . `<expiry>`: lets you control the expiry type and its parameters
 . `<eviction-advisor>`: FQCN of a `org.ehcache.config.EvictionAdvisor<K, V>` implementation, defaults to `null`, i.e. none
 . `<integration>`: lets you configure a `CacheLoaderWriter` for a _cache-through_ pattern

=== `<cache-template>` elements

`<cache-template>` elements represent a uniquely named (specified using the mandatory `name` attribute) template for
`<cache>` elements to inherit from. A `<cache-template>`. A `<cache>` element that references a `<cache-template>` by
its `name` using the `usesTemplate` attribute, will inherit all of the `<cache-template>` 's properties. Every `<cache>`
can override these properties as it needs.

A `<cache-template>` element may contain all the same child elements as a `<cache>` element.

NOTE: We've setup a complete configuration link:../107/src/test/resources/ehcache-example.xml[example] for you to inspire from.

== XML programmatic parsing

NOTE: If you are obtaining your `CacheManager` through the JSR-107 API, what follows below is automatically done for you
      when invoking `javax.cache.spi.CachingProvider.getCacheManager(java.net.URI, java.lang.ClassLoader)`, so you
      probably don't have to worry about any of this...

[source,java]
----
final URL myUrl = this.getClass().getResource("/my-config.xml"); // <1>
XmlConfiguration xmlConfig = new XmlConfiguration(myUrl); // <2>
CacheManager myCacheManager = CacheManagerBuilder.newCacheManager(xmlConfig); // <3>
----
<1> Obtain a `URL` to your XML file's location
<2> Instantiate a `XmlConfiguration` passing the XML file's URL to it
<3> Using the static `org.ehcache.CacheManagerBuilder.newCacheManager(org.ehcache.config.Configuration)` lets you
    create your `CacheManager` instance using the `Configuration` from the `XmlConfiguration`

We can also use `<cache-template>` declared in the XML file to seed instances of `CacheConfigurationBuilder`. In order
to use a `<cache-template>` element from a XML file, e.g. the `/my-config.xml` contained this XML fragment:

[source,xml]
----
<ehcache:cache-template name="example">
  <ehcache:capacity>120</ehcache:capacity>
</ehcache:cache-template>
----

Creating a `CacheConfigurationBuilder` of that `example` `<cache-template>` element, would be done so:


[source,java]
----
CacheConfigurationBuilder<String, Object> cacheBuilder = xmlConfig.newCacheConfigurationBuilderFromTemplate("example", String.class, Object.class); // <1>
cacheBuilder.capacityConstraint(100L); // <2>
----
<1> Creates a builder, inheriting the capacity constraint of 120 entries, specializing the key type to `java.lang.String`
<2> But you can obviously override the inherited properties, by simply providing a different value prior to building the `CacheConfiguration`
