The idea by this tutorial is to give an introduction in the use of the Infinispan API and its configuration file. As trying to do it in a more interactive fashion, the tutorial makes use of the Groovy dynamic language that will allow to interact with the API by using a console. So your first task should be to create the necessary environment to execute this tutorial, you can find the instructions here.
The tutorial will start by showing the basic usage of the Infinispan API and a use of a simple cache configuration, then it will walk through different configuration scenarios and use cases. By the end of the tutorial you should have a clear understanding of the use the Infinispan API and some of the various configuration options.
The scenarios and use cases shown are:
- Basic cache configuration
- Cache with transaction management configuration
- Cache with a cache store configuration
- Cache with eviction configuration
- Cache with eviction and cache store configuration
- Cache with REPL_SYNC & transaction management configuration.
All the sample configurations are in the sample-configurations.xml file attached to this tutorial, check the environment configuration to know how to make use of this configuration file. Lets get started:
NOTE: This document is part of the Infinispan Interactive Tutorial
The Infinispan tutorial makes use of Groovy to get a more interactive experience when starting to learn about how to use the Infinispan API. So you will need to install a few prerequisites before getting started:
- The Groovy Platform, I used Groovy 1.6.3
- Java and Infinispan
Download those and extract/install where you feel appropriate, depending on your operating system and personal preferences you will either have installers or compressed distributions. You can read more about read installing Java and Infinispan in Installing Infinispan for the tutorials.
You can use the installer or compressed file to install the Groovy Platform, I used the compressed file and decompressed at C:\Program Files\groovy\groovy-1.6.3. Once you have installed the Groovy Platform you should set some environment variables:and add to the PATH environment variable:
test that everything is correct by executing in a Command Shell/Terminal the commands shown:
If you get a similar result as shown, everything went well.
Now you should add the Infinispan libraries to the Groovy Platform so you will able to access the API from the Groovy console. Add the infinispan-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:
and $INFINISPAN_HOME is where you decompressed the Infinispan distribution.
To test the installation, download the attached file infinispantest.groovy and in a Command Shell/Terminal execute
The last thing to do is to add to the CLASSPATH environment variable the sample configuration file, this file contains definitions of cache's that will be used in the tutorial. I created the directory $USER_HOME/.groovy/cp and added it to the classpath
For example, on Windows:
finally add the sample-configurations.xml and infinispan-config-4.0.xsd files(attached) to the directory.
The cache manager is the responsible to manage all the cache's, so you have to start by indicating where to get the cache definitions to the cache manager, remember that the cache definitions are in the sample-configurations.xml file. If no cache definitions are indicated, the cache manager 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 something similar to:
And now, create a cache manager indicating the file with the cache definitions. the cache manager has now the knowledge of all the named caches defined in the configuration file and also has a no named cache that's used by default. You can now access any of the cache's by interacting with the cache manager as shown.
The basic configuration, is the simplest configuration that you can have, its make use of default settings for the properties of the cache configuration, the only thing you have to set is the name of the cache.
So you have seen the basic of the Infinispan API, adding, getting and removing from the cache, there is more, but don't forget that you are working with a cache that are an extension of java.util.ConcurrentHasMap and the rest of the API is as simple as the one shown above, many of the cool things in Infinispan are totally transparent (that's actually the coolest thing about Infinispan) and depends only on the configuration of your cache.
If you check the Infinispan JavaDoc you will see that the Cache#put() method has been overridden several times.
Thats all related to the use of the Infinispan API, now lets check some different behaviors depending on the configuration of the cache.
You are able to specify the cache to use a transaction manager, and even explicitly control the transactions. Start by configuring the cache to use a specific TransactionManagerLookup class. Infinispan implements a couple TransactionManagerLookup classes.
Each use different methods to lookup the transaction manager, depending on the environment you are running Infinispan you should figure out which one to use. Check the JavaDoc for more details.
For the tutorial its enough to use:
As shown in the example, the transaction is controlled explicitly and the changes in the cache wont be reflected until you make the commit.
Infinispan allows you to configure a persistent store that can be used to persist the content of the cache, so if the cache is restarted 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 the cache will start putting the objects in the store to keep the size limit, more on that when looking at the eviction configuration.
Infinispan provides several cache store implementations:
The tutorial uses the FileCacheStore, that saves the objects in files in a configured directory, in this case the /tmp directory. If the directory is not set it defaults to Infinispan-FileCacheStore in the current working directory.
The eviction allow to define policy for removing objects from the cache when it reach its limit, as the true is that the caches doesn't has unlimited size because of many reasons. So the fact is that you normally will set a maximum number of objects in the cache and when that number is reached then the cache has to decide what to do when a new object is added. That's the whole story about eviction, to define the policy of removing object when the cache is full and want to keep putting objects. You have three eviction strategies:
Let check the configuration of the cache:
Now you are sure that your cache wont consume all your memory and hang your system, but its an expensive price you have to pay for it, you are loosing objects in your cache. The good news is that you can mix cache store with the eviction policy and avoid loosing objects.
Ok, the cache has a limited size but you don't want to loose your objects in the cache. Infinispan 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 an object and remove it from the cache, but if you want to recover an object that has been persisted the the cache transparently will bring it to you from the cache store.
The configuration is simple, just combine eviction and cache store configuration