API

1. The cache and cache manager hierarchies have changed slightly in 5.1 with the introduction of BasicCache and BasicCacheContainer, which are parent classes of existing Cache and CacheContainer classes respectively. What's important is that Hot Rod clients must now code against BasicCache and BasicCacheContainer rather than Cache and CacheContainer. So previous code that was written like this will no longer compile.

import org.infinispan.Cache;
import org.infinispan.manager.CacheContainer;
import org.infinispan.client.hotrod.RemoteCacheManager;
...
CacheContainer cacheContainer = new RemoteCacheManager();
Cache cache = cacheContainer.getCache();

Instead, if Hot Rod clients want to continue using interfaces higher up the hierarchy from the remote cache/container classes, they'll have to write:

import org.infinispan.BasicCache;
import org.infinispan.manager.BasicCacheContainer;
import org.infinispan.client.hotrod.RemoteCacheManager;
...
BasicCacheContainer cacheContainer = new RemoteCacheManager();
BasicCache cache = cacheContainer.getCache();

Previous code that interacted against the RemoteCache and RemoteCacheManager should work as it used to:

import org.infinispan.client.hotrod.RemoteCache;
import org.infinispan.client.hotrod.RemoteCacheManager;
...
RemoteCacheManager cacheContainer = new RemoteCacheManager();
RemoteCache cache = cacheContainer.getCache();

Eviction and Expiration

1. The eviction XML element no longer defines the wakeUpInterval attribute. This is now configured via the expiration element:

   <expiration wakeUpInterval="60000"... />

2. Eviction's maxEntries is used as guide for the entire cache, but eviction happens on a per cache segment, so when the segment is full, the segment is evicted. That's why maxEntries is a theoretical limit but in practical terms, it'll be a bit less than that. This is done for performance reasons.

Transactions

1. A cache marked as TRANSACTIONAL cannot be accessed outside of a transaction, and a NON_TRANSACTIONAL cache cannot be accessed within a transaction. In 5.0, a transactional cache would support non-transactional calls as well. This change was done to be in-line with expectations set out in JSR-107 as well as to provide more consistent behavior.

2. In 5.0, commit and rollback phases were asynchronous by default. Starting with 5.1, these are now synchronous by default, to provide the guarantees required by a single lock-owner model.

State transfer

One of the big changes we made in 5.1 was to use the same push-based state transfer we introduced in 5.0 both for rehashing in distributed mode and for state retrieval in replicated mode. We even borrow the consistent hash concept in replicated mode to transfer state from all previous cache members at once in order to speed up transfer.

As a consequence we've unified the state transfer configuration as well, there is now a stateTransfer element holding a simplified state transfer configuration. The corresponding attributes in the stateRetrieval and hash elements have been deprecated, as have been some attributes that are no longer used.

Configuration

If you use XML to configure Infinispan, you shouldn't notice any change, except a much faster startup, courtesy of the Stax based parser. However, if you use programmatic configuration, read on for the important differences.

Configuration is now packaged in org.infinispan.configuration, and you must use a builder style:

Configuration c1 = new ConfigurationBuilder()  
   // Adjust any configuration defaults you want  
   .clustering()  
      .l1()  
         .disable()  
      .mode(DIST_SYNC)  
      .hash()  
         .numOwners(5)  
   .build();  

The old bean style configuration is now deprecated and will be removed in a later version.

Configuration properties which can be safely changed at runtime are mutable, and all others are immutable.

To copy a configuration, use the read() method on the builder, for example:

Configuration c2 = new ConfigurationBuilder()  
   // Read in C1 to provide defaults  
   .read(c1)  
   .clustering()  
      .l1()  
         .enable()  
   // This cache is DIST_SYNC, will have 5 owners, with L1 cache enabled  
   .build();  

This completely replaces the old system of defining a set of overrides on bean properties. Note that this means the behaviour of Infinispan configuration is somewhat different when used programmatically. Whilst before, you could define a default configuration, and any overrides would be applied on top of your defaults when defined, now you must explicitly read in your defaults to the builder. This allows for much greater flexibility in your code (you can have a as many "default" configurations as you want), and makes your code more explicit and type safe (finding references works).

The schema is unchanged from before. Infinispan 4.0 configurations are currently not being parsed. To upgrade, just change the schema definition from:

<infinispan  
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  
     xsi:schemaLocation="urn:infinispan:config:4.1 http://www.infinispan.org/schemas/infinispan-config-4.1.xsd"  
     xmlns="urn:infinispan:config:4.1">  

to

<infinispan  
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  
     xsi:schemaLocation="urn:infinispan:config:5.1 http://www.infinispan.org/schemas/infinispan-config-5.1.xsd"  
     xmlns="urn:infinispan:config:5.1">  

The schema documentation has changed format, as it is now produced using the standard tool xsddoc. This should be a significant improvement, as better navigation is offered. Some elements and attributes are missing docs right now, we are working on adding this. As an added benefit, your IDE should now show documentation when an xsd referenced (as above)

We are in the process of adding in support for this configuration style for modules (such as cache stores). In the meantime, please use the old configuration or XML if you require support for cache store module configuration.

Flags and ClassLoaders

The Flags and ClassLoaders API has changed. In the past, the following would work:

cache.withFlags(f1, f2);
cache.withClassLoader(cl);
cache.put(k, v);

In 5.1.0, these withX() methods return a new instance and not the cache itself, so thread locals are avoided and the code above will not work. If used in a fluent manner however, things still work:

cache.withFlags(f1, f2).withClassLoader(cl).put(k, v);

The above pattern has always been the intention of this API anyway.

JGroups Bind Address

Since upgrading to JGroups 3.x, -Dbind.address is ignored. This should be replaced with -Djgroups.bind_addr.