ehcache

Overview

Ehcache is a pure Java, in-process cache with the following features:

Fast
Simple
Acts as a pluggable cache for Hibernate 2.1.
Small foot print. Both in terms of size and memory requirements.
Minimal dependencies.
Fully documented. See the online Documentation, FAQ and the online JavaDoc.
Comprehensively Test Coverage. See the clover test report.
Scalable to hundreds of caches and large multi-cpu servers.
Available under the Apache 1.1 license. Ehcache's copyright and licensing has been reviewed and approved by the Apache Software Foundation, making ehcache suitable for use in Apache projects.
Production tested. All versions of ehcache are production tested for several weeks on a large and very busy eCommerce site before release.

News

23 November 2004 ehcache 1.1 released. This version splits out the constructs package into a separate sub-project. This simplifies ehcache for those using it in Hibernate or directly. It also moves the constructs to a separate jar and release cycle. There is only 1 minor bug fix but then there was only one bug reported.

See the release notes and full changelog here.

23 November 2004 Announcing ehcache-constructs-0.5. A subproject of ehcache, ehcache-constructs builds on top of ehcache to create implementations for common caching patterns. All implementations use ehcache as the backing cache. They also share a common purpose - to create very high performance Java applications.

At present ehcache-constructs contains:

General Purpose Caching

BlockingCache - a cache which blocks subsequent threads until the first read thread populates a cache entry
SelfPopulatingCache - a read-through cache. A cache that populates elements as they are requested without requiring the caller to know how the entries are populated. It also enables refreshes of cache entries without blocking reads on the same entries.
UpdatingSelfPopulatingCache - a read-through cache. A cache that populates elements as they are requested without requiring the caller to know how the entries are populated. The cache entry is automatically updated on subsequent reads.
SelfPopulatingCollectionsCache - a SelfPopulatingCache that adds threading safety where it is known in advance that all entries will be collections.

Web Caching

Servlet 2.3 caching filters that cache HTTP/S responses:

CachingFilter - an abstract, extensible caching filter.
SimplePageCachingFilter - a concrete implementation which caches pages based on the request URI and Query String.
SimplePageFragmentCachingFilter - a concrete implementation which caches page fragments based on the request URI and Query String.

See the ehcache-constructs subsite for and overview, documentation, javadoc, clover test coverage and more.

28 September 2004 ehcache 1.0 released. This is a major milestone for ehcache - the 1.0 release. It has several bug fixes and a few important new features. They are:

Added SelfPopulatingCacheManager to the constructs package.
Added a new diskExpiryThreadIntervalSeconds configuration option to ehcache.xml, to allow tuning of the expiry thread per cache.
Added a new persistent option for the DiskStore. When enabled, diskPersistent makes Caches persistent between JVM restarts. It enables very long held caches to be configured, useful for very expensive and/or long lived cache entries.
Improved code coverage. See clover coverage report.
New checkstyle rules, using checkstyle 3.4. Many additional checks have been added and code cleanups done to make ehcache more standards compliant and understandable than ever.

See the release notes and full changelog here.

5 July 2004 ehcache 0.9 released. This is a large release. It fixes several bugs and adds many new features including:

ehcache.xml cache definitions can now omit timeToIdle and/or timeToLive, which have been made optional attributes.
This will make cache config easier to read for eternal caches. Either omitting the attributes or setting them to 0 causes them not to be considered when calculating expiry. Earlier versions of ehcache would have immediately expired all elements if either attribute was set to 0, so this change should not break any existing code.
Added getQuiet and putQuiet methods to Cache. These methods are the same as get and put but do not affect statistics.
Implemented an Element clone method.
Added calculateInMemorySize() method to Cache to measure the approximate size of a cache's memory footprint.
Added a new constructs package. Blocking, self populating and self populating collections cache implementations are provided. They are useful where the cost of creating a cache entry is high, and you want to make request threads block until the first one creates the entry. While new to ehcache, the package is based on code that has been in production for almost a year, and is now ready for a wider audience.

See the release notes and full changelog here.

15 May 2004 ehcache 0.8 released. Changes include:

Fix to a rare null pointer exception.
Added Clover test coverage. Many thanks to cortex for the free license. Note that Clover is not included in the packaged binary code and no license is required to use EHCache. It is a development tool only.
Modifed some errors in the Apache license to enable its inclusion in the Apache Cocoon project.

2 Jan 2004 ehcache 0.7 released. Bug fixes.
11 Dec 2003 EHCache is made the recommended process cache for Hibernate 2.1
8 Dec 2003 ehcache 0.6 released. Bug fixes.
18 Nov 2003 ehcache 0.5 released. Now supports JDK1.2 and JDK1.3 as well as JKD1.4
13 Nov 2003 ehcache 0.4 released.

Downloads

Download here.

Uses

ehcache is suitable for the following purposes:

Hibernate

ehcache is the recommended cache for Hibernate. From 2.1, Hibernate supports pluggable caches.

General Use

ehcache can be used whenever you want a memory or disk cache. Only serializable objects can be spooled to the disk cache.

A replacement for JCS

ehcache started out as some patches for JCS to correct threading and memory leak problems. The decision to separate from JCS was because:

JCS has several plugins marked experimental in the code base which complicate the code base and lead to uncertainty on the reliability of same.

JCS is an implementation of JCACHE (JSR 107) and as such, has a necessarily broad scope, which conflicts with the simplicity goal.

JCS does not appear to be actively maintained

ehcache is faster than JCS. Here are sombe benchmarks from MemoryStoreTest.

Speed compared to JCS
Benchmark	EHCache	JCS	Difference
insert 5 million typical CacheElements. Then get each of them by key.	22.704s	42.176s	79% faster
insert 5,000,000 typical CacheElements. Then remove them one at a time by key	14.999s	44.536s	293% faster

Contributions

The ehcache project gratefully acknowledges the contribution of wotif.com, who granted a license to the authors to in respect of code developed at wotif.com for the purpose of making it available to the community under an Apache open source license.

Thanks also to:

ThoughtWorks for free legal assistance in formalising the granting of code from wotif.com to the open source community. Copies of the executed deeds are available should anyone need to audit the grant.
Cenqua for the free open source license of the test coverage tool Clover.
Atlassian for the free open source licenses of JIRA, an issue tracking tool and Confluence, a wiki.

Finally, thanks to those who have contributed to the project. Those people are acknowledged in the traditional way with an @author tag in the source code.

About the ehcache Name and Logo

ehcache is a palindrome: it reads the same left to right, and right to left. The logo is similarly symmetrical, and is evocative of the diagram symbol for a doubly-linked list. The JDK1.4 LinkedHashMap, and Apache's LRUMap are a HashMap with a doubly-linked list running through all of its entries. These structures lie at the heart of ehcache.