Ehcache Guide and Reference is available as a book. The price for the high quality bound edition is USD49.95 plus shipping. The price for the downloadable print-ready version is USD37.50. The book has 154 pages.
Many people have asked for a format for the documentation where it can be printed out as a book and even where they can get it. Of course, full documentation in the HTML single page and multi-page versions will always remain available on the site.
Buy it online from Lulu Books.
Ehcache now comes with a Cache Server, available as a WAR for most web containers, or as a standalone server. The Cache Server has two APIs: RESTful resource oriented, and SOAP. Both support clients in any programming language.
A Note on terminology: Leonard Richardson and Sam Ruby have done a great job of clarifying the different Web Services architectures and distinguishing them from each other. We use their taxonomy in describing web services. See http://www.oreilly.com/catalog/9780596529260/ .
Roy Fielding coined the acronym REST, denoting Representational State Transfer, in his PhD thesis .
The ehcache implementation strictly follows the RESTful resource-oriented architecture style.
Specifically:
Roy is on the JSR311 expert group. JSR311 and Jersey, the reference implementation, are used to deliver RESTful web services in ehcache server.
The Ehcache RESTFul Web Services API exposes the singleton CacheManager, which typically has been configured in ehcache.xml or an IoC container. Multiple CacheManagers are not supported.
Resources are identified using a URI template. The value in parentheses should be substituted with a literal to specify a resource.
Response codes and response headers strictly follow HTTP conventions.
Retrieves the WADL for describing the available CacheManager operations.
Lists the Caches in the CacheManager.
Retrieves the WADL describing the available Cache operations.
Retrieves the same metadata a GET would receive returned as HTTP headers. There is no body returned.
Gets a cache.
Creates a Cache using the defaultCache configuration.
Deletes the Cache.
Retrieves the WADL describing the available Element operations.
Retrieves the same metadata a GET would receive returned as HTTP headers. There is no body returned.
Gets the element value.
Gets the element's metadata.
Puts an element into the Cache.
Deletes the element from the cache.
We deal with resource representations rather than resources themselves.
When Elements are PUT into the cache, a MIME Type should be set in the request header. The MIME Type is preserved for later use.
The new MimeTypeByteArray is used to store the byte[] and the MimeType in the value field of Element .
Some common MIME Types which are expected to be used by clients are:
| text/plain | Plain text |
| text/xml | Extensible Markup Language. Defined in RFC 3023 |
| application/json | JavaScript Object Notation JSON. Defined in RFC 4627 |
| application/x-java-serialized-object | A serialized Java object |
Because ehcache is a distributed Java cache, in some configurations the Cache server may contain Java objects that arrived at the Cache server via distributed replication. In this case no MIME Type will be set and the Element will be examined to determine its MIME Type.
Because anything that can be PUT into the cache server must be Serializable, it can also be distributed in a cache cluster i.e. it will be Serializable.
These are RESTful code samples in multiple languages.
These samples use the popular curl command line utility.
This example shows how calling OPTIONS causes ehcache server to respond with the WADL for that resource
curl --request OPTIONS http://localhost:8080/ehcache/rest/sampleCache2/2
The server responds with:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<application xmlns="http://research.sun.com/wadl/2006/10">
<resources base="http://localhost:8080/ehcache/rest/">
<resource path="sampleCache2/2">
<method name="HEAD"><response><representation mediaType="
...
</resource>
</resources>
</application>
curl --head http://localhost:8080/ehcache/rest/sampleCache2/2
The server responds with:
HTTP/1.1 200 OK X-Powered-By: Servlet/2.5 Server: GlassFish/v3 Last-Modified: Sun, 27 Jul 2008 08:08:49 GMT ETag: "1217146129490" Content-Type: text/plain; charset=iso-8859-1 Content-Length: 157 Date: Sun, 27 Jul 2008 08:17:09 GMT
echo "Hello World" | curl -S -T - http://localhost:8080/ehcache/rest/sampleCache2/3
The server will put Hello World into sampleCache2 using key 3 .
curl http://localhost:8080/ehcache/rest/sampleCache2/2
The server responds with:
<?xml version="1.0"?> <oldjoke> <burns>Say <quote>goodnight</quote>, Gracie.</burns> <allen><quote>Goodnight, Gracie.</quote></allen> <applause/>
require 'rubygems'
require 'open-uri'
require 'rexml/document'
response = open('http://localhost:8080/ehcache/rest/sampleCache2/2')
xml = response.read
puts xml
The server responds with:
<?xml version="1.0"?> <oldjoke> <burns>Say <quote>goodnight</quote>, Gracie.</burns> <allen><quote>Goodnight, Gracie.</quote></allen> <applause/> </oldjoke>
import urllib2
f = urllib2.urlopen('http://localhost:8080/ehcache/rest/sampleCache2/2')
print f.read()
The server responds with:
<?xml version="1.0"?> <oldjoke> <burns>Say <quote>goodnight</quote>, Gracie.</burns> <allen><quote>Goodnight, Gracie.</quote></allen> <applause/> </oldjoke>
The W3C (http://www.w3.org/ is a standards body that defines Web Services as
The World Wide Web is more and more used for application to application communication. The programmatic interfaces made available are referred to as Web services.
They provide a set of recommendations for achieving this. See http://www.w3.org/2002/ws/ .
An interoperability organisation, WS-I http://www.ws-i.org/ , seeks to achieve interoperabilty between W3C Web Services. The W3C specifications for SOAP and WSDL are required to meet the WS-I definition.
Ehcache is using Glassfish's libraries to provide it's W3C web services. The project known as Metro follows the WS-I definition.
Finally, OASIS (http://oasis-open.org ), defines a Web Services Security specification for SOAP: WS-Security. The current version is 1.1. It provides three main security mechanisms: ability to send security tokens as part of a message, message integrity, and message confidentiality.
Ehcache's W3C Web Services support the stricter WS-I definition and use the SOAP and WSDL specfications.
Specifically:
The Ehcache RESTFul Web Services API exposes the singleton CacheManager, which typically has been configured in ehcache.xml or an IoC container. Multiple CacheManagers are not supported.
The API definition is as follows:
By default no security is configured. Because it is simply a Servlet 2.5 web application, it can be secured in all the usual ways by configuration in the web.xml.
In addition the cache server supports the use of XWSS 3.0 to secure the Web Service. See https://xwss.dev.java.net/ . All required libraries are packaged in the war for XWSS 3.0.
A sample, commented out server_security_config.xml is provided in the WEB-INF directory. XWSS automatically looks for this configuration file.
A simple example, based on an XWSS example, net.sf.ehcache.server.soap.SecurityEnvironmentHandler , which looks for a password in a System property for a given username is included. This is not recommended for production use but is handy when you are getting started with XWSS.
To use XWSS:
Add configuration in accordance with XWSS to the server_security_config.xml file. Create a class which implements the CallbackHandler interface and provide its fully qualified path in the SecurityEnvironmentHandler element.
The integration test EhcacheWebServiceEndpoint test shows how to use the XWSS client side. On the client side, configuration must be provided in a file called client_security_config.xml must be in the root of the classpath.
To add client credentials into the SOAP request do:
cacheService = new EhcacheWebServiceEndpointService().getEhcacheWebServiceEndpointPort();
//add security credentials
((BindingProvider)cacheService).getRequestContext().put(BindingProvider.USERNAME_PROPERTY, "Ron");
((BindingProvider)cacheService).getRequestContext().put(BindingProvider.PASSWORD_PROPERTY, "noR");
String result = cacheService.ping();
Java 5 or 6
The standalone server comes with its own embedded Glassfish web container.
The web container must support the Servlet 2.5 specification.
The following web container configuration have been tested:
The server is available as follows:
Download here .
There are two tarball archives in tar.gz format:
The Ehcache Server is in the central Maven repository packaged as type jar . Use the following Maven pom snippet:
<dependency>
<groupId>net.sf.ehcache</groupId>
<artifactId>ehcache-server</artifactId>
<version>0.1</version>
<type>war</type>
</dependency>
Use your Web Container's instructions to install the WAR or include the WAR in your project with Maven's war plugin.
Web Container specific configuration is provided in the WAR as follows:
Tomcat V6 passes all integration tests. It does not require a specific configuration.
Expand the WAR.
Edit the web.xml.
Comment out the RESTful web service section.
Comment out the RESTful web service section.
The ehcache.xml configuration file is located in WEB-INF/classes/ehcache.xml.
Follow the instructions in this config file, or the core ehcache instructions to configure.
The WAR also comes packaged with a standalone server, based on Glassfish V3 Embedded.
The quick start is:
See the INSTALL.txt that comes with the tarball for detailed instructions.
Configuration is by editing the war/web.xml file as per the instructions for the WAR packaging.
jsvc creates a daemon which returns once the service is started. jsvc works on all common Unix-based operating systems including Linux, Solaris and Mac OS X.
It creates a pid file in the pid directory.
This is a Unix shell script that starts the server as a daemon.
To use jsvc you must install the native binary jsvc from the Apache Commons Daemon project. The source for this is distributed in the bin directory as jsvc.tar.gz. Untar it and follow the instructions for building it or download a binary from the Commons Daemon project.
Convenience shell scripts are provided as follows:
start - daemon_start.sh
stop - daemon_stop.sh
jsvc is designed to integrate with Unix System 5 initialization scripts. (/etc/rc.d)
You can also send Unix signals to it. Meaningful ones for the Ehcache Standalone Server are:
| No | Meaning |
| 1 | HUP |
| 2 | INT |
| 9 | KILL |
| 15 | TERM |
The server is also packaged as an executable jar for developer convenience which will work on all operating systems.
A convenience shell script is provided as follows:
start - startup.sh
From the bin directory you can also invoke the following command directly:
unix - java -jar ../lib/ehcache-standalone-server-0.1.jar 8080 ../war
windows - java -jar ..\lib\ehcache-standalone-server-0.1.jar 8080 ..\war
