This is an update for Infinispan REST tutorial which is based on the latest Infinispan 8,9 releases.
So when downloading Infinispan Server release you get the rest service automatically available so you don't need any more to download an external Web application for it:
15:51:49,815 INFO [org.infinispan.server.endpoint] (MSC service thread 1-2) DGENDPT10000: REST starting 15:51:50,332 INFO [org.infinispan.rest.embedded.netty4.NettyRestServer] (MSC service thread 1-2) ISPN012003: REST server starting, listening on 127.0.0.1:8080 15:51:50,333 INFO [org.infinispan.server.endpoint] (MSC service thread 1-2) DGENDPT10002: REST mapped to rest/rest 15:51:50,452 INFO [org.jboss.as] (Controller Boot Thread) WFLYSRV0060: Http management interface listening on http://127.0.0.1:9990/management 15:51:50,453 INFO [org.jboss.as] (Controller Boot Thread) WFLYSRV0051: Admin console listening on http://127.0.0.1:9990 15:51:50,453 INFO [org.jboss.as] (Controller Boot Thread) WFLYSRV0025: Infinispan Server 9.0.0.Final (WildFly Core 2.2.0.Final) started in 3918ms - Started 150 of 161 services (47 services are lazy, passive or on-demand)
The supported HTTP methods in the REST API for entities are as follows:
- HEAD : This retrieves a cache entry, but you'll receive exactly the same content that you have stored, which means that if you have stored a binary object, you will need to deserialize the content yourself
- GET: This retrieves a cache entry or a list of keys
- POST: This creates a new cache entry
- DELETE: This deletes an entry
- PUT: This updates a cache entry
HTTP GET and HEAD are similar methods and can be used to read data from the cache. The HTTP GET method is used to retrieve a cache entry. If the cache entry exists, the GET will return a representation of the data that was stored in the cache and a response code of 200 ( OK ). Otherwise, if the requested cache key does not exist, it will return a 404 ( NOT FOUND ) or 400 ( BAD REQUEST ) response code.
If your goal is just to test the REST services, the simplest option is to use existing tools, such as the cURL library, which is a well known command line tool developed for transferring files using a URL syntax, and it supports protocols such as HTTP, HTTPS, FTP, and FTPS, among others.
So let's say you want to store in Infinispan the following XML under the key 156211:
<catalog> <book id="book01"> <author>Gambardella, Matthew</author> <title>XML Developer's Guide</title> <genre>Computer</genre> <price>44.95</price> <publish_date>2000-10-01</publish_date> <description>An in-depth look at creating applications with XML.</description> </book> </catalog>
First of all, we'll need to create an application user so that we are allowed to access the rest application:
$ ./add-user.sh -a -u myuser -p "qwer1234!" -ro supervisor,reader,writer
Next, let's use cURL to insert an entry with a POST:
$ curl -X POST -i -u "myuser:qwer1234!" -H "Content-type:application/xml" -d "<catalog> > <book id="book01"> > <author>Gambardella, Matthew</author> > <title>XML Developer's Guide</title> > <genre>Computer</genre> > <price>44.95</price> > <publish_date>2000-10-01</publish_date> > <description>An in-depth look at creating applications > with XML.</description> > </book> > </catalog>" http://localhost:8080/rest/default/156211
Now you can use an HTTP GET to retrieve the XML document for the key 156211:
$ curl -i -u "myuser:qwer1234!" -H "Accept:application/xml" http://localhost:8080/rest/default/156211
Since the release of Infinispan 5.3, you can obtain additional information for a given cache key by appending the extended parameter on the query string, as follows:
$ curl -i -u "myuser:qwer1234!" -H "Accept:application/xml" http://localhost:8080/rest/default/156211?extended
Here's the information which will be returned along with the XML file:
HTTP/1.1 200 OK Connection: keep-alive Cluster-Node-Name: localhost ETag: "application/xml-1890166279" Cluster-Server-Address: [127.0.0.1:55200] Cluster-Primary-Owner: localhost Last-Modified: Thu, 1 Jan 1970 01:00:00 +0100 Content-Type: application/xml transfer-encoding: chunked
As you can see, the GET operation returns the following custom headers:
- Cluster-Primary-Owner: This is the name of the node that is the primary owner of the key
- Cluster-Node-Name: This is the name of the node that handled the request in JGroups
- Cluster-Physical-Address: This is the physical address of the JGroups cluster that handled the request
If you want to delete an item from the Cache, you can use the HTTP DELETE method as follows:
$ curl -i -u "myuser:qwer1234!" -X DELETE http://localhost:8080/rest/default/156211
Finally, if you want to update an existing key, you can use the PUT HTTP method as follows:
$ curl -i -u "myuser:qwer1234!" -X PUT -H "Content-type:application/xml" "<catalog> > <book id="book01"> > <author>Gambardella, Matthew</author> > <title>XML Developer's Guide</title> > <genre>Computer</genre> > <price>48.95</price> > <publish_date>2000-10-01</publish_date> > <description>An in-depth look at creating applications > with XML.</description> > </book> > </catalog>" http://localhost:8080/rest/default/156211
Other useful options you can append to your query string
- performAsync: If defined, performAsync will perform asynchronous requests and the operation will return without waiting for data replication.
- timeToLiveSeconds is the number of seconds before this entry is automatically deleted. If omitted, Infinispan assumes -1 as the default value and the cache entry will not expire.
- maxIdleTimeSeconds is the number of seconds between the last usage of this entry and the time it will automatically be deleted. If omitted, Infinispan assumes -1 as the default value and the cache entry will not expire as a result of idle time.
Older Infinispan releases (4,5)
If you need to access the Infinispan 4,5 data grid from any kind of client (which is able to consume a RESTful service), then Infinispan REST server is what you need !
Download Infinispan server-rest application from here
This tutorial has been tested with the release 4.2.1 of Infinispan and JBoss AS 6
Now unzip the file infinispan-4.2.1.FINAL-server-rest.zip and extract the file infinispan.war which will be deployed on JBoss AS 6.
Please note, due to issues with the VFS of JBoss AS 6, some libraries (namely scala-library-2.8.1.jar) cause the application deployment to fail. In order to solve this issue you can add to your WEB-INF folder of infinispan.war a JBoss AS metadata file (jboss-scanning.xml) which excludes scala library from the deployment.
<scanning xmlns="urn:jboss:scanning:1.0"> <path name="WEB-INF/lib/scala-library-2.8.1.jar"> <exclude name="scala" recurse="true"/> </path> </scanning>
This is how your infinispan.war archive will look like:
Ok. Now launch JBoss AS 6 and point your browser to the infinispan REST server:
You will hit a welcome page which describes how basically the REST server works:
In order to insert elements in the cache, you can issue an HTTP PUT and POST request.
In order to retrieve elements from the cache you can use HTTP GET request:
In order to delete elements from the cache you can issue an HTTP DELETE request:
By default infinispan has just the "___defaultcache" registered, so if you want to try out of the box the REST server, just create a REST client.
Following here is a jQuery client which puts an entry in the cache:
And here's the corresponding page which performs a get on the bucket1 key:
Do I need to download jQuery to run this sample ? no at all. jQuery is accessed on the cloud via <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.5/jquery.min.js"></script>. If you cannot reach the web from there, of course download jquery.js and place it on the server's path.
Using a custom Infinispan cache configuration
Out of the box, Inifinispan uses a default cache configuration. To set a custom configuration, create an Infinispan XML configuration file and set the PATH to it in your web.xml file, under the key infinispan.config.
The infinispan configuration file is dictated by the Init Servlet which contains the name and the path where the configuration is stored:
<servlet> <servlet-name>InitServlet</servlet-name> <servlet-class>org.infinispan.rest.StartupListener</servlet-class> <!-- Specify your cache configuration file --> <init-param> <param-name>infinispan.config</param-name> <param-value>infinispan.xml</param-value> </init-param> . . . . . </servlet>
As it is, drop the following infinispan.xml file into WEB-INF/classes of your application:
<infinispan xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:infinispan:config:4.2 http://www.infinispan.org/schemas/infinispan-config-4.2.xsd" xmlns="urn:infinispan:config:4.2"> <namedCache name="cacheX" /> </infinispan>
So now you can reference cacheX from your RESTful clients.
Last minute addition:
var url = "http://localhost:8080/infinispan/rest/cacheX/bucket1"; var representationOfDesiredState = "Adding this to the cache"; var client = new XMLHttpRequest(); client.open("PUT", url, false); client.setRequestHeader("Content-Type", "text/plain"); client.send(representationOfDesiredState); if (client.status == 200) alert("The request succeeded!\n\nThe response representation was:\n\n" + client.responseText) else alert("The request did not succeed!\n\nThe response status was: " + client.status + " " + client.statusText + ".");