Skip to content

README.adoc

Latest commit

 

History

History
86 lines (70 loc) · 4.25 KB

README.adoc

File metadata and controls

86 lines (70 loc) · 4.25 KB
Raw

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:

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 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:

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 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:

  1. Configure a default template all programmatically created Cache instances will inherit from, and

  2. 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:

<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.