1. Introduction

The Grails Cache Ehcache plugin extends the Cache plugin and uses Ehcache as the storage provider for cached content. It replaces the core plugin’s grailsCacheManager bean with one that uses an Ehcache backend.

Version 3.0.0 of this plugin is a complete rewrite from previous versions. The version of Ehcache has been upgraded to version 3. If you are upgrading from a previous version of this plugin, it will require a change in your configuration. The configuration XML from Ehcache 2 is not compatible with version 3. Configuration for caches via *Config.groovy files or the standard Grails 3 configuration files is no longer supported. See the sections on configuration and customization for more information.

2. Installation

To start using this plugin, add it to your build.gradle like the example below.

build.gradle
 dependencies {
     ...
     compile "org.grails.plugins:cache-ehcache:3.0.0"
 }

3. Usage

Although this plugin uses a different backing store than the core plugin, its usage is the same. You annotate service methods, taglib closures, etc with the three caching annotations. See the core plugin docs for general usage information.

4. Configuration

This configuration options this plugin provides will be under the grails.cache.ehcache key.

grails{
   cache {
      ehcache {
         ehcacheXmlLocation = 'classpath:ehcache.xml'
         lockTimeout = 200 // In milliseconds
      }
   }
}

  • ehcacheXmlLocation optionally specifies where the XML configuration file can be found.

  • lockTimeout allows you to specify the maximum amount of time the cache manager will wait to acquire a lock on the cache.

If you are using hibernate-ehcache, it will by default use the ehcache.xml file on your classpath. Since hibernate-ehcache is still using Ehcache 2, it will throw an error if the XML is designed to be used by Ehcache 3. It is recommended to name the file something different that won’t be picked up automatically by hibernate-ehcache.

4.1. Caches

By default, the only provided configuration strategy supports reading an XML file to configure Ehcache. Set the ehcacheXmlLocation setting above to provide a file to be passed to Ehcache. See the section in the Ehcache user guide on creating an XML file.

To configure Ehcache via their configuration builder, or any other means, see the section on customization.

5. Customization

5.1. Configuration

To configure Ehcache yourself, define a bean called ehcacheConfiguration that implements EhcacheConfiguration. The configuration returned from getConfiguration will be passed to the cache manager. See the section in the Ehcache documentation on programmatic configuration for more information.

5.2. Cache Manager

To customize how the Ehcache manager gets created, define a bean called grailsCacheManager that extends GrailsEhcacheCacheManager. You can override the createDefaultManager method to return an Ehcache manager in any way you like.

Ehcache 3 requires a key type and a value type when creating a cache. If a cache is specified in your code that is not specifically configured, the key and value type will be Object. To change this behavior or to further configure the default cache, extend the grailsCacheManager as explained above and override the createDefaultCache method.