Getting Started with Infinispan.pdf

Getting Started with InfinispanManik Surtani, Mircea Markus, Galder Zamarreo, Pete Muir, and others from the Infinispan community

Table of Contents1. Introduction

1.1. Runtimes1.2. Modes1.3. Interacting with Infinispan

2. Downloading and installing Infinispan2.1. JDK2.2. Maven2.3. Infinispan

2.3.1. Getting Infinispan from Maven2.4. Download the quickstarts

3. Infinispan in action - GUIDemo4. Using Infinispan as an embedded cache in Java SE

4.1. Creating a new Infinispan project4.1.1. Maven users4.1.2. Ant users

4.2. Running Infinispan on a single node4.3. Use the default cache4.4. Use a custom cache

5. Using Infinispan as an embedded data grid in Java SE5.1. Sharing JGroups channels5.2. Running Infinispan in a cluster

5.2.1. Replicated mode5.2.2. Distributed mode

5.3. clustered-cache quickstart architecture5.3.1. Logging changes to the cache5.3.2. Whats going on?

5.4. Configuring the cluster5.4.1. Tweaking the cluster configuration for your network

5.5. Configuring a replicated data-grid5.6. Configuring a distributed data-grid

6. Creating your own Infinispan project6.1. Maven Archetypes

6.1.1. Starting a new project6.1.2. Playing with your new project6.1.3. On the command line6.1.4. Writing a test case for Infinispan6.1.5. On the command line6.1.6. Versions6.1.7. Source Code

7. Using Infinispan as a second level cache for Hibernate8. Accessing an Infinispan data grid remotely

8.1. Using Hot Rod to access an Infinispan data-grid8.2. Using REST to access an Infinipsan data-grid8.3. Using memcached to access an Infinispan data-grid

9. Using Infinispan in JBoss AS 7

10. Using Infinispan in servlet containers (such as Tomcat or Jetty) and other application servers (such as GlassFish)11. Monitoring Infinispan12. Infinispan GUI demo

12.1. Step 1: Start the demo GUI12.2. Step 2: Start the cache12.3. Step 3: Manipulate data12.4. Step 4: Start more cache instances12.5. Step 5: Manipulate more data

13. Example with Groovy13.1. Introduction

13.1.1. Installing Groovy13.1.2. Installing Infinispan13.1.3. Setting the classpath

13.2. Loading the configuration file13.3. Basic cache configuration13.4. Cache with transaction management13.5. Cache with a cache store13.6. Cache with eviction13.7. Cache with eviction and cache store

14. Example with Scala14.1. Environment14.2. Testing Setup14.3. Loading the Configuration file14.4. Basic cache operations14.5. Basic cache operations with TTL14.6. Cache restarts14.7. Transactional cache operations14.8. Persistent stored backed Cache operations14.9. Operating against a size bounded cache14.10. Size bounded caches with persistent store

This is a guide to getting started with Innispan. It is meant to be read alongside the morecomplete User Guide (../user_guide/user_guide.html), and as a supplement to the Quickstarts(http://www.innispan.org/documentation) that have been made available.

1. IntroductionThis guide will walk you through downloading, installing and running Innispan for the rst time. It will then introduce tosome of the key features of Innispan.

1.1. RuntimesInnispan can be used in a variety of runtimes:

Java SE, started by your application

an application server which provides Innispan as a service (such as JBoss AS)

bundled as a library in your application, deployed to an application server, and started on by your application (forexample, you could use Innispan with Tomcat or GlassFish)

1.2. ModesInnispan oers four modes of operation, which determine how and where the data is stored: * Local , where entries arestored on the local node only, regardless of whether a cluster has formed. In this mode Innispan is typically operating as alocal cache * Invalidation , where all entries are stored into a cache store (such as a database) only, and invalidated fromall nodes. When a node needs the entry it will load it from a cache store. In this mode Innispan is operating as adistributed cache, backed by a canonical data store such as a database * Replication , where all entries are replicated toall nodes. In this mode Innispan is typically operating as a data grid or a temporary data store, but doesnt oer anincreased heap space * Distribution , where entries are distributed to a subset of the nodes only. In this mode Innispan istypically operating as a data grid providing an increased heap space

Invalidation, Replication and Distribution can all use synchronous or asynchronous communication.

1.3. Interacting with InfinispanInnispan oers two access patterns, both of which are available in any runtime:

Embedded into your application code

As a Remote server accessed by a client (REST, memcached or Hot Rod wire protocols are supported)

This guide will introduce to each of the runtime options, access patterns and modes of operations by walking you throughsimple applications for each.

2. Downloading and installing InfinispanTo run Innispan, youll need

A Java 1.6.0 JDK (a 1.7.0 JDK is required if you wish to recompile Innispan itself. The generated artifacts will howeverbe compatible with JDK 1.6.0)

Maven 3, if you wish to use the quickstart examples or create a new project using Innispan archetype(../getting_started/getting_started.html#_maven_archetypes)

the Innispan distribution zip, if you wish to use Innispan in server mode, or want to use the jars in an ant project

the Innispan Quickstart zip, if you want to follow along with the projects discussed in the guide

If you already have any of these pieces of software, there is no need to install them again!2.1. JDKChoose your Java runtime, and follow their installation instructions. For example, you could choose one of:

OpenJDK (http://openjdk.java.net/install/)

Oracle Java SE (http://www.oracle.com/technetwork/java/javase/index-137561.html)

Oracle JRockit (http://download.oracle.com/docs/cd/E15289_01/doc.40/e15065/toc.htm)

2.2. MavenFollow the ocial Maven installation guide if you dont already have Maven 3 installed. You can check which version ofMaven you have installed (if any) by running mvn --version . If you see a version newer than 3.0.0, you are ready to go.

You can also deploy the examples using your favorite IDE. We provide instructions for using Eclipse only.

2.3. InfinispanFinally, download Innispan from the Innispan downloads (http://www.innispan.org/download) page.

2.3.1. Getting Infinispan from Maven

TODO

2.4. Download the quickstartsThe quickstarts are in GitHub, in https://github.com/innispan/innispan-quickstart(https://github.com/innispan/innispan-quickstart).

Clone this repository using:

$gitclonehttps://github.com/infinispan/infinispanquickstart

3. Infinispan in action - GUIDemoTODO

4. Using Infinispan as an embedded cache in Java SERunning Innispan in embedded mode is very easy. First, well set up a project, and then well run Innispan, and startadding data.

embedded-cache quickstart

All the code discussed in this tutorial is available in the embedded-cache quickstart(https://github.com/infinispan/infinispan-quickstart/tree/master/embedded-cache).

4.1. Creating a new Infinispan projectThe only thing you need to set up Innispan is add its dependencies to your project.

4.1.1. Maven usersIf you are using Maven (or another build system like Gradle or Ivy which can use Maven dependencies), then this is easy.Just add:

pom.xml

org.infinispaninfinispancore${infinispan.version}

to the section of the POM. Youll need to substitute ${infinispan.version} for the version of Innispanyou wish to use.

Which version of Infinispan should I use?

We recommend using the latest stable version of Infinispan. All releases are displayed on the downloadspage (http://www.infinispan.org/download).

Alternatively, you can use the POM (https://raw.github.com/innispan/innispan-quickstart/master/embedded-cache/pom.xml) from the quickstart that accompanies this tutorial.

4.1.2. Ant usersIf you are using Ant, or another build system which doesnt provide declarative dependency management, then theInnispan distribution zip contains a lib/ directory. Add the contents of this to the build classpath.

4.2. Running Infinispan on a single nodeIn order to run Innispan, were going to create a main() method in the Quickstart class. Innispan comes congured torun out of the box; once you have set up your dependencies, all you need to do to start using Innispan is to create a newcache manager and get a handle on the default cache.

Quickstart.java

We now need a way to run the main method! If you are using Maven, the best approach is to copy all the projectdependencies to a directory, and at the same time compile the java classes from our project:

$mvncleancompiledependency:copydependenciesDstripVersion

Having done that, we can run the main method:

$javacptarget/classes/:target/dependency/*Quickstart

You should see Innispan start up, and the version in use logged to the console.

Congratulations, you now have Innispan running as a local cache!

4.3. Use the default cacheInnispan exposes a Map-like, JSR-107-esque interface for accessing and mutating the data stored in the cache. Forexample:

DefaultCacheQuickstart.java

publicclassQuickstart{

publicstaticvoidmain(Stringargs[])throwsException{Cachec=newDefaultCacheManager().getCache();}

}

Innispan oers a thread-safe data-structure:


By default entries are immortal but you can override this on a per-key basis and provide lifespans.


4.4. Use a custom cacheEach cache in Innispan can oer a dierent set of features (for example transaction support, dierent replication modesor support for eviction), and you may want to use dierent caches for dierent classes of data in your application. To get acustom cache, you need to register it with the manager rst:

CustomCacheQuickstart.java

The example above uses Innispans uent conguration, which oers the ability to congure your cacheprogrammatically. However, should you prefer to use XML, then you may. We can create an identical cache to the onecreated with a programmatic conguration:

infinispan.xml

//Addaentrycache.put("key","value");//ValidatetheentryisnowinthecacheassertEqual(1,cache.size());assertTrue(cache.containsKey("key"));//RemovetheentryfromthecacheObjectv=cache.remove("key");//ValidatetheentryisnolongerinthecacheassertEqual("value",v);

//Addanentrywiththekey"key"cache.put("key","value");//Andreplaceitifmissingcache.putIfAbsent("key","newValue");//Validatethatthenewvaluewasnotadded

//Bydefaultentriesareimmortalbutwecanoverridethisonaperkeybasisandprovidelifespans.cache.put("key","value",5,SECONDS);assertTrue(cache.containsKey("key"));Thread.sleep(10000);

publicstaticvoidmain(Stringargs[])throwsException{EmbeddedCacheManagermanager=newDefaultCacheManager();manager.defineConfiguration("customcache",newConfigurationBuilder().eviction().strategy(LIRS).maxEntries(10).build());Cachec=manager.getCache("customcache");}

We then need to load the conguration le, and use the programmatically dened cache:

XmlConfiguredCacheQuickstart.java

5. Using Infinispan as an embedded data grid in Java SEClustering Innispan is simple. Under the covers, Innispan uses JGroups (http://www.jgroups.org) as a network transport,and JGroups handles all the hard work of forming a cluster.

clustered-cache quickstart

All the code discussed in this tutorial is available in the clustered-cache quickstart(https://github.com/infinispan/infinispan-quickstart/tree/master/clustered-cache).

5.1. Sharing JGroups channelsBy default all caches created from a single CacheManager share the same JGroups channel and multiplex RPCmessages over it. In this example caches 1, 2 and 3 all use the same JGroups channel.

5.2. Running Infinispan in a clusterIt is easy set up a clustered cache. This tutorial will show you how to create two nodes in dierent processes on the samelocal machine. The quickstart follows the same structure as the embedded-cache quickstart, using Maven to compile theproject, and a main method to launch the node.

If you are following along with the quickstarts, you can try the examples out. First, compile the project:

$mvncleancompiledependency:copydependenciesDstripVersion

The quickstart contains two examples of a clustered cache, one in replication mode and one distribution mode.

publicstaticvoidmain(Stringargs[])throwsException{Cachec=newDefaultCacheManager("infinispan.xml").getCache("xmlconfiguredcache");}

EmbeddedCacheManagercm=//getCacheManagerfromsomewhereCachecache1=cm.getCache("replSyncCache");Cachecache2=cm.getCache("replAsyncCache");Cachecache3=cm.getCache("invalidationSyncCache");

5.2.1. Replicated modeTo run the replication mode example, we need to launch both nodes from dierent consoles. For the rst node:

$javacptarget/classes/:target/dependency/*org.infinispan.quickstart.clusteredcache.replication.Node0

And for the second node:

$javacptarget/classes/:target/dependency/*org.infinispan.quickstart.clusteredcache.replication.Node1

You should see JGroups and Innispan start up on both consoles, and after about 15s the cache entry log message appearon the console of the rst node.

5.2.2. Distributed modeTo run the distribution mode example, we need to launch three nodes from dierent consoles. For the rst node:

$javacptarget/classes/:target/dependency/*org.infinispan.quickstart.clusteredcache.distribution.Node0

And for the second node:


And for the third node:


You should see JGroups and Innispan start up on both consoles, and after about 15s see the 10 entries added by thirdnode distributed to the rst and second nodes.

5.3. clustered-cache quickstart architecture

5.3.1. Logging changes to the cacheAn easy way to see what is going on with your cache is to log mutated entries. An Innispan listener is notied of anymutations:

Listeners methods are declared using annotations, and receive a payload which contains metadata about the notication.Listeners are notied of any changes. Here, the listeners simply log any entries added or removed.

5.3.2. Whats going on?The replication mode example contains two nodes, each of which are started in a separate process. The nodes are verysimple, Node0 starts up, registers a listener that logs any changes, and waits for the cluster to form. Node1 starts up, waitsfor the cluster to form, and then adds an entry. The interesting work happens in the common super class, examined inConguring a replicated data-grid .

Waiting for the cluster to form

Infinispan only replicates data to nodes which are already in the cluster. If a node is added to the clusterafter an entry is added, it wont be replicated there. In order to see replication take effect, we need to waituntil Both nodes make use of the utility class ClusterValidation (http://github.com/infinispan/infinispan-quickstart/tree/master/clustered-cache/src/main/java/org/infinispan/quickstart/clusteredcache/replication/ClusterValidation.java), callingits waitForClusterToForm method to achieve this. We wont dig into how this works here, but if you areinterested take a look at the code.

importorg.infinispan.notifications.Listener;importorg.infinispan.notifications.cachelistener.annotation.CacheEntryCreated;importorg.infinispan.notifications.cachelistener.annotation.CacheEntryRemoved;importorg.infinispan.notifications.cachelistener.event.CacheEntryCreatedEvent;importorg.infinispan.notifications.cachelistener.event.CacheEntryRemovedEvent;importorg.infinispan.util.logging.Log;importorg.infinispan.util.logging.LogFactory;

/***AnInfinispanlistenerthatsimplylogscacheentriesbeingcreatedand*removed**@authorPeteMuir*/@ListenerpublicclassLoggingListener{

privateLoglog=LogFactory.getLog(LoggingListener.class);

@CacheEntryCreatedpublicvoidobserveAdd(CacheEntryCreatedEventevent){if(!event.isPre())//Sothatmessageisonlyloggedafteroperationsucceededlog.infof("Cacheentrywithkey%saddedincache%s",event.getKey(),event.getCache());}

@CacheEntryRemovedpublicvoidobserveRemove(CacheEntryRemovedEventevent){log.infof("Cacheentrywithkey%sremovedincache%s",event.getKey(),event.getCache());}

}

The distribution mode example contains three nodes, each of which are started in a separate process. The nodes are verysimple, Node0 and Node1 start up, register listeners that logs any changes, and wait for the cluster to form. Node2 startsup, waits for the cluster to form, and then adds 20 entries. Each entry gets distributed to its owners, and you will see someentries add on Node0 and some on Node1 . Youll notice that Node2 gets notied of all adds - this is just because it is thenode which adds the entry, it doesnt reect that the fact that all these entries are stored there! The interesting workhappens in the common super class, examined in Conguring a distributed data-grid .

5.4. Configuring the clusterFirst, we need to ensure that Innispan is cluster aware. Innispan provides a default conguration for a clustered cache:

GlobalConfiguration.getClusteredDefault() is a quick way to get a precongured, cluster-aware GlobalCongurationand can be used as a starting point to ne tuning the conguration.

5.4.1. Tweaking the cluster configuration for your networkDepending on your network setup, you may need to tweak your JGroups set up. JGroups is congured via an XML le; thele to use can be specied via the GlobalConguration:

The JGroups documentation (http://www.jgroups.org/manual/html/index.html) provides extensive advice on gettingJGroups working on your network. If you are new to conguring JGroups, you may get a little lost, so you might want to trytweaking these conguration parameters:

Using the system property Djgroups.bind_addr=127.0.0.1 causes JGroups to bind only to your loopback interface,meaning any rewall you may have congured wont get in the way. Very useful for testing a cluster where all nodes areon one machine.

TODO - add more tips!

You can also congure the JGroups conguration to use in Innispans XML conguration:

5.5. Configuring a replicated data-gridIn replicated mode, Innispan will store every entry on every node in the grid. This oers high durability and availability ofdata, but means the storage capacity is limited by the available heap space on the node with least memory. The cacheshould be congured to work in replication mode (either synchronous or asynchronous), and can otherwise be conguredas normal. For example, if you want to congure the cache programatically:

newConfigurationBuilder().clustering().cacheMode(CacheMode.REPL_SYNC).build()

GlobalConfigurationBuilder.defaultClusteredBuilder().transport().defaultTransport().addProperty("configurationFile","jgroups.xml").build()

You can congure an identical cache using XML:

cfg.xml

along with

5.6. Configuring a distributed data-gridIn distributed mode, Innispan will store every entry on a subset of the nodes in the grid (controlled by the parameternumOwners , which controls how many owners each entry will have). Compared to replication, distribution oersincreased storage capacity, but with reduced availability (increased latency to access data) and durability. Adjusting thenumber of owners allows you to obtain the trade o between space, durability and availability.

Innispan also oers a topology aware consistent hash which will ensure that the owners of entries are located in dierentdata centers, racks and nodes to oer improved durability in case of node or network outages.

The cache should be congured to work in distributed mode (either synchronous or asynchronous), and can otherwise becongured as normal. For example, if you want to congure the cache programatically:

privatestaticEmbeddedCacheManagercreateCacheManagerProgrammatically(){returnnewDefaultCacheManager(GlobalConfigurationBuilder.defaultClusteredBuilder().transport().defaultTransport().addProperty("configurationFile","jgroups.xml").build(),newConfigurationBuilder().clustering().cacheMode(CacheMode.REPL_SYNC).build());}

privatestaticEmbeddedCacheManagercreateCacheManagerFromXml()throwsIOException{returnnewDefaultCacheManager("infinispanreplication.xml");}

You can congure an identical cache using XML:

cfg.xml:

along with

6. Creating your own Infinispan project

6.1. Maven ArchetypesInnispan currently has 2 separate Maven archetypes (http://maven.apache.org/guides/introduction/introduction-to-archetypes.html) you can use to create a skeleton project and get started using Innispan. This is an easy way to getstarted using Innispan as the archetype generates sample code, a sample Maven pom.xml with necessarydependencies, etc.

You dont need to have any experience with or knowledge of Mavens Archetypes to use this! Just followthe simple steps below.6.1.1. Starting a new projectUse the newproject-archetype project. The simple command below will get you started, and

You will be prompted for a few things, including the artifactId , groupId and version of your new project. And thats it - youreready to go!

6.1.2. Playing with your new project

newConfigurationBuilder().clustering().cacheMode(CacheMode.DIST_SYNC).hash().numOwners(2).build()

privatestaticEmbeddedCacheManagercreateCacheManagerFromXml()throwsIOException{returnnewDefaultCacheManager("infinispanreplication.xml");}

$mvnarchetype:generate\DarchetypeGroupId=org.infinispan.archetypes\DarchetypeArtifactId=newprojectarchetype\DarchetypeVersion=1.0.13\DarchetypeRepository=http://repository.jboss.org/nexus/content/groups/public

The skeleton project ships with a sample application class, interacting with Innispan. You should open this new project inyour IDE - most good IDEs such as IntelliJ and Eclipse allow you to import Maven projects, see this guide(http://www.jetbrains.com/idea/webhelp/importing-maven-project.html) and this guide (http://m2eclipse.sonatype.org/) .Once you open your project in your IDE, you should examine the generated classes and read through the comments.

6.1.3. On the command lineTry running

in your newly generated project! This runs the main() method in the generated application class.

6.1.4. Writing a test case for InfinispanThis archetype is useful if you wish to contribute a test to the Innispan project and helps you get set up to use Innispanstesting harness and related tools. Use

As above, this will prompt you for project details and again as above, you should open this project in your IDE. Once youhave done so, you will see some sample tests written for Innispan making use of Innispans test harness and testingtools along with extensive comments and links for further reading.

6.1.5. On the command lineTry running

in your newly generated project to run your tests.

The generated project has a few dierent proles you can use as well, using Mavens -P ag. E.g.,

Available profilesThe proles available in the generated sample project are:

udp: use UDP for network communications rather than TCP

tcp: use TCP for network communications rather than UDP

jbosstm: Use the embedded JBoss Transaction Manager (http://www.jboss.org/jbosstm) rather than Innispans dummytest transaction manager

Contributing tests back to InfinispanIf you have written a functional, unit or stress test for Innispan and want to contribute this back to Innispan, your best betis to fork the Innispan sources on GitHub (https://github.com/innispan/innispan) . The test you would have prototypedand tested in an isolated project created using this archetype can be simply dropped in to Innispans test suite. Make your

$mvninstallPrun

$mvnarchetype:generate\DarchetypeGroupId=org.infinispan.archetypes\DarchetypeArtifactId=testcasearchetype\DarchetypeVersion=1.0.13\DarchetypeRepository=http://repository.jboss.org/nexus/content/groups/public

$mvntest

$mvntestPudp

changes, add your test, prove that it fails even on Innispans upstream source tree and issue a pull request(http://help.github.com/pull-requests/) .

New to working with Infinispan and GitHub? Want to know how best to work with the repositories andcontribute code? Read Infinispan and GitHub (../contributing/contributing.html#_source_control)6.1.6. VersionsThe archetypes generate poms with dependencies to specic versions of Innispan. You should edit these generatedpoms by hand to point to other versions of Innispan that you are interested in.

6.1.7. Source CodeThe source code used to generate these archetypes are on GitHub (https://github.com/innispan/innispan-archetypes) . Ifyou wish to enhance and contribute back to the project, fork away!

7. Using Infinispan as a second level cache for HibernateTODO

8. Accessing an Infinispan data grid remotely

8.1. Using Hot Rod to access an Infinispan data-gridTODO

8.2. Using REST to access an Infinipsan data-gridTODO

8.3. Using memcached to access an Infinispan data-gridTODO

9. Using Infinispan in JBoss AS 7TODO

10. Using Infinispan in servlet containers (such as Tomcat or Jetty) andother application servers (such as GlassFish)TODO

11. Monitoring InfinispanTODO *

12. Infinispan GUI demoThis document walks you through using the Innispan GUI demo that ships with Innispan, and assumes that you havedownloaded (http://www.innispan.org/download) the latest version of Innispan and unzipped the archive. I will refer tothe Innispan directory created by unzipping the archive as ${INFINISPAN_HOME}.

You will need either the -bin.zip or -all.zip version for this demo.12.1. Step 1: Start the demo GUIOpen up a console and type:

$cd${INFINISPAN_HOME}$bin/runGuiDemo.sh

An equivalent runGuiDemo.bat le is also provided for Windows users.

12.2. Step 2: Start the cacheStart the cache in the GUI that starts up, using the Start Cache button.

12.3. Step 3: Manipulate dataIn the Manipulate Data tab, add entries, generate random data, etc.

12.4. Step 4: Start more cache instancesRepeat steps 1 and 2 to launch and start up more caches. Watch cluster formation in the Cluster View tab.

12.5. Step 5: Manipulate more dataAdd and remove data on any of the nodes, and watch state being distributed. Shut nodes down as well to witness datadurability.

13. Example with GroovyThe idea by this tutorial is to give an introduction in the use of the Innispan API(http://docs.jboss.org/innispan/6.0/apidocs/) and its conguration le. As trying to do it in a more interactive fashion, thetutorial makes use of the Groovy (http://groovy.codehaus.org/) dynamic language that will allow to interact with the API byusing a console.

The tutorial will start by showing the basic usage of the Innispan API (http://docs.jboss.org/innispan/6.0/apidocs/) and ause of a simple cache conguration, then it will walk through dierent conguration scenarios and use cases. By the endof the tutorial you should have a clear understanding of the use the Innispan API and some of the various congurationoptions.

The scenarios and use cases shown are:

Basic cache conguration

Cache with transaction management conguration

Cache with a cache store conguration

Cache with eviction conguration

Cache with eviction and cache store conguration

Cache with REPL_SYNC & transaction management conguration.

All the sample congurations are in the sample-congurations.xml le attached to this tutorial, check the environmentconguration (http://docs.jboss.org/innispan/6.0/apidocs/) to know how to make use of this conguration le. Lets getstarted:

13.1. IntroductionThe Innispan tutorial makes use of Groovy to get a more interactive experience when starting to learn about how to usethe Innispan API. So you will need to install a few prerequisites before getting started:

The Groovy Platform, I used Groovy 1.6.3 (http://dist.groovy.codehaus.org/distributions/groovy-binary-1.6.3.zip)

Java and Innispan

Download those and extract/install where you feel appropriate, depending on your operating system and personalpreferences you will either have installers or compressed distributions. You can read more about read installing Java andInnispan in Installing Innispan for the tutorials (https://docs.jboss.org/author/pages/viewpage.action?pageId=3737054) .

13.1.1. Installing GroovyYou can use the installer or compressed le to install the Groovy Platform, I used the compressed le and decompressedat C:Program Filesgroovygroovy-1.6.3. Once you have installed the Groovy Platform you should set some environmentvariables:

and add to the PATH environment variable:

test that everything is correct by executing in a Command Shell/Terminal the commands shown:

GROOVY_HOME=C:\ProgramFiles\groovy\groovy1.6.3

PATH=%PATH%;%GROOVY_HOME%\bin

If you get a similar result as shown, everything went well.

13.1.2. Installing InfinispanNow you should add the Innispan libraries to the Groovy Platform so you will able to access the API from the Groovyconsole. Add the innispan-core.jar and its dependencies to the $USER_HOME/.groovy/lib directory, the jar is located in$INFINISPAN_HOME/modules/core and the dependencies at $INIFINISPAN_HOME/modules/core/lib.

For example, on Windows, you need to copy it to:

or on Linux:

and $INFINISPAN_HOME is where you decompressed the Innispan distribution.

To test the installation, download the attached le innispantest.groovy and in a Command Shell/Terminal execute

13.1.3. Setting the classpathThe last thing to do is to add to the CLASSPATH environment variable the sample conguration le, this le containsdenitions of caches that will be used in the tutorial. I created the directory $USER_HOME/.groovy/cp and added it to theclasspath

For example, on Windows:

or, on Linux:

nally add the sample-congurations.xml and innispan-cong-4.0.xsd les(attached) to the directory.

13.2. Loading the configuration fileThe cache manager (http://docs.jboss.org/innispan/6.0/apidocs/org/innispan/manager/CacheManager.html) is theresponsible to manage all the caches (http://docs.jboss.org/innispan/6.0/apidocs/org/innispan/Cache.html) , so youhave to start by indicating where to get the cache denitions to the cache manager(http://docs.jboss.org/innispan/6.0/apidocs/org/innispan/manager/CacheManager.html) , remember that the cachedenitions are in the sample-congurations.xml le. If no cache denitions are indicated, the cache manager(http://docs.jboss.org/innispan/6.0/apidocs/org/innispan/manager/CacheManager.html) will use a default cache.

Start by open a groovy console by typing groovy.sh in a command shell or terminal. You should now have somethingsimilar to:

$>groovyvGroovyVersion:1.6.3JVM:1.6.0_14

C:\DocumentsandSettings\AlejandroMontenegro\.groovy\lib

/home/amontenegro/.groovy/lib

$>groovyinfinispantest4.0.0.ALPHA5

CLASSPATH=%CLASSPATH%;C:\DocumentsandSettings\AlejandroMontenegro\.groovy\cp

CLASSPATH=$CLASSPATH:/home/amontenegro/.groovy/cp

Groovy Shell (1.6.3, JVM: 1.6.0_14) Type help or \h for help.

Its time to start typing some commands, rst start by importing the necessary libraries

groovy:000> import org.innispan.* === > [import org.innispan.] groovy:000> import org.innispan.manager. ===> [import org.innispan., import org.innispan.manager.]

And now, create a cache manager indicating the le with the cache denitions.

the cache manager has now the knowledge of all the named caches dened in the conguration le and also has a nonamed cache thats used by default. You can now access any of the caches by interacting with the cache manager asshown.

13.3. Basic cache configurationThe basic conguration, is the simplest conguration that you can have, its make use of default settings for the propertiesof the cache conguration, the only thing you have to set is the name of the cache.

Thats all you have to add to the conguration le to have a simple named cache, now its time to interact with the cacheby using the Innispan API. Lets start by getting the named cache and put some objects inside it.

groovy:000>

groovy:000>manager=newDefaultCacheManager("sampleconfigurations.xml")===>org.infinispan.manager.DefaultCacheManager@19cc1b@Address:null

groovy:000>defaultCache=manager.getCache()===>Cache'org.infinispan.manager.DefaultCacheManager.DEFAULT_CACHE_NAME'@7359733//TOGETANAMEDCACHEgroovy:000>cache=manager.getCache("NameOfCache")

So you have seen the basic of the Innispan API, adding, getting and removing from the cache, there is more, but dontforget that you are working with a cache that are an extension of java.util.ConcurrentHasMap and the rest of the API is assimple as the one shown above, many of the cool things in Innispan are totally transparent (thats actually the coolestthing about Innispan) and depends only on the conguration of your cache.

If you check the Innispan JavaDoc you will see that the Cache#put() method has been overridden several times.

//STARTBYGETTINGAREFERENCETOTHENAMEDCACHEgroovy:000>localCache=manager.getCache("Local")===>Cache'Local'@19521418//THEINITIALSIZEIS0groovy:000>localCache.size()===>0//NOWPUTANOBJECTINSIDETHECACHEgroovy:000>localCache.put("aKey","aValue")===>null//NOWTHESIZEIS1groovy:000>localCache.size()===>1//CHECKIFITHASOUROBJECTgroovy:000>localCache.containsKey("aKey")===>true//BYOBTAININGANOBJECTDOESN'TMEANTOREMOVEgroovy:000>localCache.get("aKey")===>aValuegroovy:000>localCache.size()===>1//TOREMOVEASKITEXPLICITLYgroovy:000>localCache.remove("aKey")===>aValuegroovy:000>localCache.isEmpty()===>true

//YOUWILLNEEDTOIMPORTANOTHERLIBRARYgroovy:000>importjava.util.concurrent.TimeUnit===>[importorg.infinispan.*,importorg.infinispan.manager.*,importjava.util.concurrent.TimeUnit]//NOTHINGNEWHEREJUSTPUTTINGANEWOBJECTgroovy:000>localCache.put("bKey","bValue")===>null//WOW!WHATSHAPPENHERE?PUTTEDANEWOBJECTBUTITWILLTIMEOUTAFTERASECONDgroovy:000>localCache.put("timedKey","timedValue",1000,TimeUnit.MILLISECONDS)===>null//LETSCHECKTHESIZEgroovy:000>localCache.size()===>2//NOWTRYTOGETTHEOBJECT,OOPSITSGONE!(IFNOT,IT'SBECAUSEYOUAREASUPERTYPER,CALLGUINNESS!))groovy:000>localCache.get("timedKey")===>null//LETSCHECKTHESIZEAGAIN,ASEXPECTEDTHESIZEDECREASEDBY1groovy:000>localCache.size()===>1

The Innispan API also allows you to manage the life cycle of the cache, you can stop and start a cache but by default youwill loose the content of the cache except if you congure a cache store, more about that later in the tutorial. lets checkwhat happens when you restart the cache

Thats all related to the use of the Innispan API, now lets check some dierent behaviors depending on the congurationof the cache.

13.4. Cache with transaction managementYou are able to specify the cache to use a transaction manager, and even explicitly control the transactions. Start byconguring the cache to use a specic TransactionManagerLookup class. Innispan implements a coupleTransactionManagerLookup classes.

org.innispan.transaction.lookup.DummyTransactionManagerLookup(http://docs.jboss.org/innispan/6.0/apidocs/org/innispan/transaction/lookup/DummyTransactionManagerLookup.html)

org.innispan.transaction.lookup.GenericTransactionManagerLookup(http://docs.jboss.org/innispan/6.0/apidocs/org/innispan/transaction/lookup/GenericTransactionManagerLookup.html)

org.innispan.transaction.lookup.JBossStandaloneJTAManagerLookup(http://docs.jboss.org/innispan/6.0/apidocs/org/innispan/transaction/lookup/JBossStandaloneJTAManagerLookup.html)

org.innispan.transaction.lookup.JBossTransactionManagerLookup(http://docs.jboss.org/innispan/6.0/apidocs/org/innispan/transaction/lookup/JBossTransactionManagerLookup.html)

Each use dierent methods to lookup the transaction manager, depending on the environment you are running Innispanyou should gure out which one to use. Check the JavaDoc for more details.

For the tutorial its enough to use:

Lets check how to interact with the Transaction Manager and to have the control over a transaction

groovy:000>localCache.size()===>1//RESTARTINGCACHEgroovy:000>localCache.stop()===>nullgroovy:000>localCache.start()===>null//DAMN!LOSTTHECONTENTOFTHECACHEgroovy:000>localCache.size()===>0

As shown in the example, the transaction is controlled explicitly and the changes in the cache wont be reected until youmake the commit.

13.5. Cache with a cache storeInnispan allows you to congure a persistent store that can be used to persist the content of the cache, so if the cache isrestarted the cache will be able to keep the content. It can also be used if you want to limit the size of the cache, then thecache will start putting the objects in the store to keep the size limit, more on that when looking at the evictionconguration.

Innispan provides several cache store implementations:

FileCacheStore

JdbcBinaryCacheStore

JdbcMixedCacheStore

JdbcStringBasedCacheStore

JdbmCacheStore

S3CacheStore

BdbjeCacheStore

groovy:000>importjavax.transaction.TransactionManager===>[importorg.infinispan.*,importorg.infinispan.manager.*,importjava.util.concurrent.TimeUnit,importjavax.transaction.TransactionManager]//GETAREFERENCETOTHECACHEWITHTRANSACTIONMANAGERgroovy:000>localTxCache=manager.getCache("LocalTX")===>Cache'LocalTX'@16075230groovy:000>cr=localTxCache.getComponentRegistry()===>org.infinispan.factories.ComponentRegistry@87e9bf//GETAREFERENCETOTHETRANSACTIONMANAGERgroovy:000>tm=cr.getComponent(TransactionManager.class)===>org.infinispan.transaction.tm.DummyTransactionManager@b5d05b//STARTINGANEWTRANSACTIONgroovy:000>tm.begin()===>null//PUTTINGSOMEOBJECTSINSIDETHECACHEgroovy:000>localTxCache.put("key1","value1")===>null//MMMSIZEDOESN'TINCREMENTgroovy:000>localTxCache.size()===>1//LETSTRYAGAINgroovy:000>localTxCache.put("key2","value2")===>null//MMMNOTHING..groovy:000>localTxCache.size()===>2//OH!HASTODOTHECOMMITgroovy:000>tm.commit()===>null//ANDTHESIZEISASEXPECTED..HAPPY!groovy:000>localTxCache.size()===>2

ThetutorialusestheFileCacheStore,thatsavestheobjectsinfilesinaconfigureddirectory,inthiscasethe/tmpdirectory.IfthedirectoryisnotsetitdefaultstoInfinispanFileCacheStoreinthecurrentworkingdirectory.

Now you have a cache with persistent store, lets try it to see how it works

13.6. Cache with evictionThe eviction allow to dene policy for removing objects from the cache when it reach its limit, as the true is that thecaches doesnt has unlimited size because of many reasons. So the fact is that you normally will set a maximum numberof objects in the cache and when that number is reached then the cache has to decide what to do when a new object isadded. Thats the whole story about eviction, to dene the policy of removing object when the cache is full and want tokeep putting objects. You have three eviction strategies:

NONE

//GETTINGTHENEWCACHEgroovy:000>cacheCS=manager.getCache("CacheStore")===>Cache'CacheStore'@23240342//LETSPUTANOBJECTINSIDETHECACHEgroovy:000>cacheCS.put("storedKey","storedValue")===>null//LETSPUTTHESAMEOBJECTINOURBASICCACHEgroovy:000>localCache.put("storedKey","storedValue")===>storedValue//RESTARTBOTHCACHESgroovy:000>cacheCS.stop()===>nullgroovy:000>localCache.stop()===>nullgroovy:000>cacheCS.start()===>nullgroovy:000>localCache.start()===>null//LETSTRYGETTHEOBJECTFROMTHERESTARTEDBASICCACHE..NOLUCKgroovy:000>localCache.get("storedKey")===>null//INTERESTINGCACHESIZEISNOTCEROgroovy:000>cacheCS.size()===>1//WOW!JUSTRESTARTEDTHECACHEANDTHEOBKECTKEEPSSTAYINGTHERE!groovy:000>cacheCS.get("storedKey")===>storedValue

LRU

LIRS

Let check the conguration of the cache:

The strategy has been set to LRU, so the least recently used objects will be removed rst and the maximum number ofobjects are only 2, so it will be easy to show how it works

Now you are sure that your cache wont consume all your memory and hang your system, but its an expensive price youhave to pay for it, you are loosing objects in your cache. The good news is that you can mix cache store with the evictionpolicy and avoid loosing objects.

13.7. Cache with eviction and cache storeOk, the cache has a limited size but you dont want to loose your objects in the cache. Innispan is aware of these issues,so it makes it very simple for you combing the cache store with the eviction policy. When the cache is full it will persist anobject and remove it from the cache, but if you want to recover an object that has been persisted the the cachetransparently will bring it to you from the cache store.

The conguration is simple, just combine eviction and cache store conguration

//GETTINGTHENEWCACHEgroovy:000>evictionCache=manager.getCache("Eviction")===>Cache'Eviction'@5132526//PUTSOMEOBJECTSgroovy:000>evictionCache.put("key1","value1")===>nullgroovy:000>evictionCache.put("key2","value2")===>nullgroovy:000>evictionCache.put("key3","value3")===>null//HEY!JUSTLOSTANOBJECTINMYCACHE..RIGHT,THESIZEISONLYTWOgroovy:000>evictionCache.size()===>2//LETSCHECKWHATOBJECTWASREMOVEDgroovy:000>evictionCache.get("key3")===>value3groovy:000>evictionCache.get("key2")===>value2//COOL!THEOLDESTWASREMOVEDgroovy:000>evictionCache.get("key1")===>null

Nothing new in the conguration, lets check how it works

14. Example with ScalaThis article shows how to use Innispan with Scala language (http://www.scala-lang.org/) . It uses the same commandsand congurations used in the Example with Groovy. For more details about the scenarios and steps please visit aboutpage since here will will only focus on Scala compatibility.

14.1. EnvironmentPreparing the environment is almost similar to one described here, but with a minor dierence that unlike Groovy whichuses ~/.groovy/lib folder to extend initial classpath, we will use classic CLASSPATH environment variable with Scala.Another issue is that with the recent edition of Innispan core jar le is in the root folder of $INIFINISPAN_HOME, hencehere a sample bash script to prepare CLASSPATH for our demo:

//GETTINGTHECACHEgroovy:000>cacheStoreEvictionCache=manager.getCache("CacheStoreEviction")===>Cache'CacheStoreEviction'@6208201//PUTTINGSOMEOBJECTSgroovy:000>cacheStoreEvictionCache.put("cs1","value1")===>value1groovy:000>cacheStoreEvictionCache.put("cs2","value2")===>value2groovy:000>cacheStoreEvictionCache.put("cs3","value3")===>value3///MMMSIZEISONLYTWO,LETSCHECKWHATHAPPENEDgroovy:000>cacheStoreEvictionCache.size()===>2groovy:000>cacheStoreEvictionCache.get("cs3")===>value3groovy:000>cacheStoreEvictionCache.get("cs2")===>value2//WOW!EVENIFTHECACHESIZEIS2,IRECOVEREDTHETHREEOBJECTS..COOL!!groovy:000>cacheStoreEvictionCache.get("cs1")===>value1

exportINFINISPAN_HOME=~/build/infinispan/infinispan4.2.1.CR1forjin$INFINISPAN_HOME/lib/*.jar;doCLASSPATH=$CLASSPATH:$j;doneexportCLASSPATH=$CLASSPATH:$INFINISPAN_HOME/infinispancore.jarexportCLASSPATH=$CLASSPATH:[Pathtofoldercontainingsampleconfigurations.xmlfile]

sample-configurations.xml

14.2. Testing SetupThe following code shows how to start an Scala console that will allow commands to be entered interactively. To verifythat the Innispan classes have been imported correctly, an import for all Innispan classes will be attempted and then arequest will be made to print the version of Innispan:

14.3. Loading the Configuration fileIn this next example, a new cache manager will be created using the conguration le downloaded earlier:

Retrieving cache instances from cache manager

In this example, the default cache is retrieved expecting keys and values to be of String type:

In this next example, a named cache is retrieved, again with keys and values expected to be String:

14.4. Basic cache operationsIn this section, several basic operations will be executed against the cache that show how it can be populated with data,how data can be retrieved and size can be checked, and nally how after removing the data entered, the cache is empty:

[z@dnb:~/Go/demos/interactiveinfinispanscala]%./scalaWelcometoScalaversion2.8.1.final(JavaHotSpot(TM)64BitServerVM,Java1.6.0_22).Typeinexpressionstohavethemevaluated.Type:helpformoreinformation.

scala>importorg.infinispan._importorg.infinispan._

scala>println(Version.version)4.2.1.CR1

scala>importorg.infinispan.manager._importorg.infinispan.manager._

scala>valmanager=newDefaultCacheManager("sampleconfigurations.xml")manager:org.infinispan.manager.DefaultCacheManager=org.infinispan.manager.DefaultCacheManager@38b58e73@Address:null

scala>valdefaultCache=manager.getCache[String,String]()defaultCache:org.infinispan.Cache[String,String]=Cache'___defaultcache'@1326840752

scala>valnamedCache=manager.getCache[String,String]("NameOfCache")namedCache:org.infinispan.Cache[String,String]=Cache'NameOfCache'@394890130

14.5. Basic cache operations with TTLWhen a cache entry is stored, a maximum lifespan for the entry can be provided. So, when that time is exceeded, the entrywill dissapear from the cache:

14.6. Cache restartsWhen caches are local and not congured with a persistent store, restarting them means that the data is gone. To avoidthis issue you can either congure caches to be clustered so that if one cache dissapears, the data is not completelygone, or congure the cache with a persistent cache store. The latter option will be explained later on.

scala>vallocalCache=manager.getCache[String,String]("Local")localCache:org.infinispan.Cache[String,String]=Cache'Local'@420875876

scala>localCache.size()res0:Int=0

scala>localCache.put("aKey","aValue")res1:String=null//Thisnullwasreturnedbyput()indicatingthat//thekeywasnotassociatedwithanypreviousvalue.


scala>localCache.containsKey("aKey")res3:Boolean=true

scala>localCache.get("aKey")res4:String=aValue


scala>localCache.remove("aKey")res6:String=aValue

scala>localCache.isEmpty()res7:Boolean=true

scala>localCache.put("bKey","bValue")res8:String=null

scala>importjava.util.concurrent.TimeUnitimportjava.util.concurrent.TimeUnit

scala>localCache.put("timedKey","timedValue",1000,TimeUnit.MILLISECONDS)res9:String=null


scala>localCache.get("timedKey")res11:String=null


14.7. Transactional cache operationsInnispan caches can be operated within a transaction, in such way that operations can be grouped in order to beexecuted atomically. The key thing to understand about transactions is that within the transactions changes are visible,but to other non-transactional operations, or other transactions, these are not visible until the transaction is committed.The following example shows how within a transaction an entry can be stored but outside the transaction, thismodication is not yet visible, and that once the transaction is committed, the modication is visible to all:


scala>localCache.stop()

scala>localCache.start()


Note how this example shows a very interesting characteristic of the Scala console. Every operations return value isstored in a temporary variable which can be referenced at a later stage, even if the user forgets to assign the result of aoperation when the code was executed.

14.8. Persistent stored backed Cache operationsWhen a cache is backed by a persistent store, restarting the cache does not lead to data being lost. Upon restart, thecache can retrieve in lazy or prefetched fashion cache entries stored in the backend persistent store:

scala>importjavax.transaction.TransactionManagerimportjavax.transaction.TransactionManager

scala>vallocalTxCache=manager.getCache[String,String]("LocalTX")localTxCache:org.infinispan.Cache[String,String]=Cache'LocalTX'@955386212

scala>valtm=localTxCache.getAdvancedCache().getTransactionManager()tm:javax.transaction.TransactionManager=org.infinispan.transaction.tm.DummyTransactionManager@81ee8c1

scala>tm.begin()

scala>localTxCache.put("key1","value1")res1:String=null

scala>localTxCache.size()res2:Int=1

scala>tm.suspend()res3:javax.transaction.Transaction=DummyTransaction{xid=DummyXid{id=1},status=0}


scala>localTxCache.get("key1")res5:String=null

scala>tm.resume(res3)


scala>localTxCache.get("key1")res8:String=value1

scala>tm.commit()


scala>localTxCache.get("key1")res11:String=value1

14.9. Operating against a size bounded cacheInnispan caches can be congured with a max number of entries, so if this is exceeded certain cache entries are evictedfrom in-memory cache. Which cache entries get evicted is dependant on the eviction algorithm chosen. In this particularexample, FIFO algorithm has been congured, so when a cache entry needs to be evicted, those stored rst will go rst:

scala>valcacheWithStore=manager.getCache[String,String]("CacheStore")cacheWithStore:org.infinispan.Cache[String,String]=Cache'CacheStore'@2054925789

scala>cacheWithStore.put("storedKey","storedValue")res21:String=null

scala>localCache.put("storedKey","storedValue")res22:String=null

scala>cacheWithStore.stop()

scala>localCache.stop()

scala>cacheWithStore.start()

scala>localCache.start()

scala>localCache.get("storedKey")res27:String=null

scala>cacheWithStore.size()res28:Int=1

scala>cacheWithStore.get("storedKey")res29:String=storedValue

scala>valevictionCache=manager.getCache[String,String]("Eviction")evictionCache:org.infinispan.Cache[String,String]=Cache'Eviction'@882725548

scala>evictionCache.put("key1","value1")res30:String=null



scala>evictionCache.size()res33:Int=2

scala>evictionCache.get("key3")res34:String=value3

scala>evictionCache.get("key2")res35:String=value2

scala>evictionCache.get("key1")res36:String=null

14.10. Size bounded caches with persistent storeWhen caches congured with eviction are congured with a persistent store as well, when the cache exceeds certain size,apart from removing the corresponding cache entries from memory, these entries are stored in the persistent store. So, iftheyre requested by cache operations, these are retrieved from the cache store:

scala>valcacheStoreEvictionCache=manager.getCache[String,String]("CacheStoreEviction")cacheStoreEvictionCache:org.infinispan.Cache[String,String]=Cache'CacheStoreEviction'@367917752

scala>cacheStoreEvictionCache.put("cs1","value1")res37:String=null



scala>cacheStoreEvictionCache.size()res40:Int=2

scala>cacheStoreEvictionCache.get("cs3")res41:String=value3



Last updated 2014-01-28 21:21:29 UTC