= The Ehcache 3.x JSR-107 Provider

== Getting started with Ehcache3 & JSR-107

There isn't anything special for you to do to use Ehcache3 as the caching provider for your application: add the
`ehcache-3.0.0.jar` to your application's classpath (possibly removing the previous provider's jar) and you are ready to
go:

[source,java]
----
CachingProvider provider = Caching.getCachingProvider(); // <1>
CacheManager cacheManager = provider.getCacheManager(); // <2>
----
<1> Retrieves the default `CachingProvider`, this should be `org.ehcache.EhCachingProvider`,
    which you can also force, by using the `Caching.getCachingProvider(String)` static method instead;
<2> Retrieve the default `CacheManager` instance using the provider.

=== Using a specific configuration file

You can also add a XML file that preconfigure `Cache` instances upfront. See
link:../xml/README.adoc[the XML README file] for more details on configuring `Cache` in XML.

In order to pre-configure the `CacheManager` at creation time using the XML file, simply:

[source,java]
----
CachingProvider provider = Caching.getCachingProvider();
CacheManager cacheManager = provider.getCacheManager( // <1>
        this.getClass().getResource("/ehcache.xml").toURI(), // <2>
        Customer.class.getClassLoader()); // <3>
----
<1> Invoking `javax.cache.spi.CachingProvider.getCacheManager(java.net.URI, java.lang.ClassLoader)`
<2> where the first argument is an `URI` pointing to our XML configuration file, e.g. `ehcache.xml`;
<3> the second argument being the `ClassLoader` to use to load user-types if needed; i.e. `Class` instances that are
    stored in the `Cache` managed by our `CacheManager`.

NOTE: You can also use the `CachingProvider.getCacheManager()` method that doesn't take any argument instead.
      The `URI` and `ClassLoader` used to configure the `CacheManager` will then use the
      vendor specific values returned by `CachingProvider.getDefaultURI` and `.getDefaultClassLoader` respectively.
      Be aware that these aren¹t entirely spec¹ed for Ehcache3 and may change in future releases!

=== Supplement JSR-107's configurations

You can also create `cache-templates` as of Ehcache3, see
link:../xml/README.adoc#__code_cache_template_code_elements[Cache Templates] section of the XML README file for more details. The Ehcache3
JSR-107 Caching Provider comes with an extension to the regular XML configuration, so you can:

 . Configure a default template all programmatically created `Cache` instances will inherit from, and
 . Configure a given named `Cache` to inherit from a specific template.

This feature is particularly useful to configure `Cache` beyond the JSR-107 specification, e.g. giving them a capacity
constraint. All is needed is adding a jsr107 service in your XML configuration file:

[source,xml]
----
<config
    xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
    xmlns='http://www.ehcache.org/v3'
    xmlns:jsr107='http://www.ehcache.org/v3/jsr107'> <!--1-->

  <service> <!--2-->
    <jsr107:defaults default-template="tinyCache"> <!--3-->
      <jsr107:cache name="foos" template="stringCache"/> <!--4-->
    </jsr107:defaults>
  </service>

  <cache-template name="stringCache">
    <key-type>java.lang.String</key-type>
    <value-type>java.lang.String</value-type>
    <capacity>2000</capacity>
  </cache-template>

  <cache-template name="tinyCache">
    <capacity>20</capacity>
  </cache-template>
</config>
----
<1> First, declare a namespace for the 107 extension, e.g. `jsr107`
<2> Within a `service` element at the top of you configuration, add a `jsr107:defaults` element
<3> The element takes an optional attribute `default-template`, which references the `cache-template` to use for all
    `javax.cache.Cache` created by the application at runtime using `javax.cache.CacheManager.createCache`. In
    this example, the default `cache-template` used will be `tinyCache`, meaning that atop of their particular config,
    programmatically created `Cache` instances will have their capacity constrained to 20 entries.
<4> Nested within the `jsr107:defaults`, add specific `cache-templates` to use for given named `Cache`, e.g. when
    creating the `Cache` named `foos` at runtime, Ehcache will enhance its config, giving it a capacity of 2000 entries,
    as well as insuring both key and value types are `String`.
