BoxLang 🚀 A New JVM Dynamic Language Learn More...

EHCache Provider for Cachebox

v2.0.1+0000039 Modules

EHCache Cachebox Provider with JGroups clustering

On Forgebox

Build Status

This module makes EHCache 3.7 available as a Cachebox provider, with clustering support using cbjgroups. The project supports the following features:

  • Configuration of heap, offheap or disk storage
  • Configuration of cache timeouts
  • Configuration of resource limits
  • Configuration of a jGroups cluster to replicate caches

No tiered resources or Terracota clustering are currently available. These could come in a later release pending demand.

Get involved

Contribution is very welcome. You can get involved by:

  • Raising issues in Github, both ideas and bugs welcome
  • Creating pull requests in Github

Or search out the authors for anything else. You can generally find us on Preside slack:


Caches are configured in your Cachebox.cfc as per the Cachebox documentation. The following example shows all the default settings:

caches.mycache = {
      provider   = "cbehcache.models.EhCacheProvider"
    , properties = {
		  storage                        = "heap"
		, persistent                     = false
		, objectDefaultTimeout           = 60
		, objectDefaultLastAccessTimeout = 0
		, useLastAccessTimeouts          = false
		, maxObjects                     = 1000
		, maxSizeInMb                    = 0
		, keyClass                       = "java.lang.String"
		, valueClass                     = "java.lang.Object"
		, cluster                        = false
		, clusterName                    = "cbehcache"
		, propagateDeletes               = true
		, propagatePuts                  = false
		, lowerCaseKeys                  = false

Configuration notes


Can be either heap (default), nonheap or disk. The persistent setting applies only to disk storage. Setting to true will mean that a restart of the application will not reset the cache in disk if it already exists.

Note: Nonheap is a special memory based cache that does not require GC so can save overhead. It will, however, incur serialization and deserialization overhead and is advised to be used only for very large caches.


The cache can use either time to live (TTL) or time to idle (TTI) timeouts. These modes correspond to objectDefaultTimeout (TTL) and objectDefaultLastAccessTimeout (TTI). To use TTI, ensure that useLastAccessTimeouts is set to true.

Set a value of 0 to have no timeouts.

Note: The semantics here have been chosen to keep as close to the default Coldbox cachebox provider properties as possible.

Resource limits

The maxObjects and maxSizeInMb properties define the resource limits for your cache. For heap storage, you can define either one (not both). A value of zero will mean no limit.

For nonheap and disk storage, only maxSizeInMb is possible.

Key and Value classes

For serialization of caches (nonheap and disk storages), the cache requires that you define the class used for both keys and values in the cache. If you know that you will always be storing strings in the cache, set the valueClass to java.lang.String. For CFML types, you can use struct, array or query for the corresponding types.

The lowerCaseKeys property allows you to force all cache object keys to lower case.


The minimal configuration required is to set clustering=true to enable clustering. This will:

  • propagate cache deletes across the system
  • setup a cluster named cbehcache with the default jgroups cluster settings of automatically detecting peers using UDP multicast discovery

See the cbjgroups project documentation for full cluster configuration details. You can either configure a cbehcache cluster, or provide your own cluster IDs with their own configuration.

Set propagatePuts to true to have any additions to the cache on any node to be replicated across all nodes (default is false).



  • Reinstate logic to defend against bad application restarts that leave "abandoned" cache managers that block startup (effects local development only for the most part)


  • Rewrite of java layer. Using a java proxy service and building our own OSGi bundle. This reduces/eliminates class loader issues and makes for more efficient CFML.


  • Update dependency on cbjgroups with latest hotfix


  • Fix #14 - More liberal error catching to make more robust cache system


  • Fix #13 - Catch correct exception for already existing cache under race conditions


  • Fix #11 - issue with cache creation race conditions throwing errors


Migrate to github actions


  • Upgrade cbjgroups with fix for memory leak in kubernetes


  • Upgrade cbjgroups with fix for running cfml in app context on cluster membership change events


  • Add config option to allow all object keys to be forced to lower-case


  • Upgrade to cbjgroups 0.3.0


  • Upgrade to cbjgroups 0.2.4 to fix issue with 0.2.3


  • Remove debug output


  • Update to cbjgroups 0.2.3 to fix issue with limitation on size of cache objects that can be sent to other cluster nodes


  • Adding working logic for cache.getKeys() method. Thanks to Florindo Lopez.


  • Update cbjgroups dependency version


  • Update dependency on cbjgroups to add k8s support


  • #6 Fix issue with cbehcache mapping not always being available for path resolution


  • #4 Add some debugging to illegalstate exceptions when registering caches


  • #2 Allow the use of CFML struct, query and array types for the 'ValueClass' for non-heap storage.


  • #1 Improve performance of cluster cache operations that potentially fail when the cache does not (yet) exist in the listening cluster node. Ignore missing caches and do not go to wirebox each time to fetch the cache.


  • Fix for clear by key snippet not being possible (just have to clear all for now!)


  • Fix for hardcoded path accidentally left in while local testing


  • Added support for clustering using jGroups (cbjgroups)


  • Added support for nonheap and disk storage
  • Added support for both TTL and TTI expiry models
  • Added working statistics
  • Added documentation in README


  • Build fixes


Initial proof of concept with with:

  • Only Heapspace resource configurable
  • Working with existing Coldbox cachebox provider config
  • Timeouts not settable per individual entry
  • No statistics

$ box install cbehcache

No collaborators yet.
  • {{ getFullDate("2019-07-10T17:28:27Z") }}
  • {{ getFullDate("2023-07-21T12:35:06Z") }}
  • 3,102
  • 48,836