Upgrading Infinispan deployments

The optional IndexedQueryMode parameter has been removed from queries in library mode, CLI, Hot Rod and REST. Since 12.0, Infinispan ignores this parameter since it detects the optimal way of performing indexed queries.

Including file-store persistence in cache configuration now creates a soft index file-based cache store, SoftIndexFileStore, instead of a single-file cache store, SingleFileStore. In previous versions SingleFileStore was the default for file-based cache stores.

Any file-store configuration with a schema version of 13 is automatically migrated to a SoftIndexFileStore after upgrading to Infinispan 13.

The currentNumberOfEntries statistics now return -1 by default as the calculation is expensive. Accurate values can be restored using the following configuration:

When upgrading Infinispan to 12.1, caches that include a SingleFileStore persistence configuration can encounter an issue that leads to data corruption.

This issue affects upgrades to Infinispan 12.1.0.Final through 12.1.4.Final only. As of Infinispan 12.1.5.Final this issue no longer occurs during upgrade.

If you have already upgraded from 11.x to 12.1, you should do the following as soon as possible:

After successful upgrade, Infinispan recovers any corrupted data and restores the Single File Store on first start.

For caches that backup to other clusters via cross-site replication, you should perform a state transfer after upgrading to 12.1.

From the Infinispan CLI use the site push-site-state command as follows:

A new CREATE permission has been introduced, with the following effects: * users now require the CREATE permission to be able to create/remove caches/counters/locks instead of the ADMIN permission * it supersedes the internal _schema_manager role, which has now been deprecated. It is required in order to add/remove schemas. * it supersedes the internal _script_manager role, which has now been deprecated. It is required in order to add/remove scripts.

The trust store configuration is now part of the server identity to allow client certificate validation without requiring authentication. Adding a truststore-realm will reference the identity’s trust store.

Conversions of cache data between application/x-java-object and application/json are deprecated and will be removed in a future version. For JSON support, it is recommend to configure the cache with application/x-protostream encoding.

Support for OSGi was deprecated and has been removed.

Some operations that previously supported both GET and POST now support only POST:

have been deprecated and will be removed in a future version.

Users should migrate to the /v2/caches/{cacheName}/search/stats endpoint. Please consult the REST API docs for more details.

A new status FAILED has been added to the cache health, to indicate that a cache failed to start with the provided configuration. The possible statuses of the cache health are now HEALTHY, HEALTHY_REBALANCING, DEGRADED and FAILED.

The GenericJBossMarshaller is no longer automatically configured if the infinispan-jboss-marshalling module is on the classpath. If jboss-marshalling is required, it’s necessary for the aforementioned jar to be on the classpath and for the org.infinispan.jboss.marshalling.commons.GenericJBossMarshaller to be explicitly configured when creating the RemoteCacheManager.

The Wildfly modules are now deprecated. The jgroups, infinispan and endpoint extensions have been removed and all the components are now in a single org.infinispan module.

Total Order transaction protocol was deprecated in 10.0 and now it is removed.

The default stacks now now use system property jgroups.bind.address to configure the bind address. System properties jgroups.tcp.address and jgroups.udp.address still work, but they are considered deprecated and will be removed.

OSGi support has been deprecated and will be removed in a future release.

The ThreadGroup configuration setting has been removed and only thread group name is allowed now. This configuration was inconsistent between programmatic and declarative configuration and is now consistent.

The LAZY_RETRIEVAL option utilises the now deprecated ClusterLoader and consequently has also been deprecated. It will be removed in a future release with no direct replacement.

Maximum idle expiration has been changed to improve data consistency with clustered cache modes when Infinispan nodes fail.

See Maximum Idle Expiration for complete details.

The following configurations were removed from the REST store: append-cache-name-to-path and path.

To specify the remote server endpoint path, a single configuration cache-name should be used.

The Infinispan Lucene directory is now deprecated and will be removed in a future release. Consequently, the Infinispan Directory provider for Hibernate Search will also be discontinued, with no replacement.

Both IndexManagers that rely on the Lucene Directory are also deprecated, the InfinispanIndexManager and the AffinityIndexManager. Users are encouraged to reconfigure their indexes as non-shared, using the Near Real Time IndexManager, with file system storage:

Queries need to be adjusted to use the BROADCAST runtime option.

The security role mapper implementations have been moved from the org.infinispan.security.impl package to the org.infinispan.security.mappers package:

The security audit logger implementations have been moved from the org.infinispan.security.impl package to the org.infinispan.security.audit package:

The Memcached protocol server is now deprecated and will be removed in a future release. This is being done because Infinispan only implements the very dated text-only protocol instead of the binary protocol which means no security (authentication / encryption), no support for some new Memcached features and no integration with Infinispan features like single-port. If someone in the community wishes to implement the binary protocol, we would revert the decision.

The default Hot Rod client authentication mechanism has been changed from DIGEST-MD5 to SCRAM-SHA-512. If you are using property user realms, you must make sure you are using plain-text storage.

The Map implementation EntryVersionsMap has been removed and replaced with a Map<Object, IncrementalEntryVersion>. If the old EntryVersionsMap#merge logic is required, it can be replaced with org.infinispan.transaction.impl.WriteSkewHelper#mergeEntryVersions, however users should not rely on this code as it could be removed in the future without notice,

The internal marshalling capabilities of Infinispan have undergone a significant refactoring in 10.0. The marshalling of internal Infinispan objects and user objects are now truly isolated. This means that it’s now possible to configure Marshaller implementations in embedded mode or on the server, without having to handle the marshalling of Infinispan internal classes. Consequently, it’s possible to easily change the marshaller implementation, in a similar manner to how users of the HotRod client are accustomed.

As a consequence of the above changes, the default marshaller used for marshalling user types is no longer based upon JBoss Marshalling. Instead we now utilise the ProtoStream library to store user types in the language agnostic Protocol Buffers format. It is still possible to utilise the old default, JBossUserMarshaller, however it’s necessary to add the org.infinispan:infinispan-jboss-marshalling artifact to your application’s classpath.

Caches created through the CacheContainerAdmin API will now be PERMANENT by default. Use the VOLATILE flag to obtain the previous behaviour.

Older versions of the Hot Rod protocol treated expiration values greater than the number of milliseconds in 30 days as Unix time. Starting with Hot Rod 3.0 this adjustment no longer happens and expiration is taken literally.

Total Order transaction protocol is going to be removed in a future release. Use the default protocol (2PC).

The infinispan.server.hotrod.workerThreads property was introduced as a hack to work around the fact that the configuration did not expose it. The property has been removed and endpoint worker threads must now be exclusively configured using the worker-threads attribute.

AtomicMapLookup, AtomicMap and FineGrainedAtomicMap have been removed. Please see FunctionalMaps or Cache#Merge for similar functionality.

The previously deprecated Delta and DeltaAware interfaces have been removed.

The previously deprecated Compatibility Mode has been removed.

The default cache must now be named explicitly via the GlobalConfigurationBuilder#defaultCacheName() method.

The previously deprecated DistributedExecutor is now removed. References should be updated to use ClusterExecutor.

TreeCache has been unsupported for a long time and was only intended as a quick stopgap for JBossCache users. The module has now been removed completely.

Previously the JDBC PooledConnectionFactory provided c3p0 and HikariCP based connection pools. From 10.0 we only provide a PooledConnectionFactory based upon the Agroal project. This means that it is no longer possible to utilise c3p0.properties and hikari.properties files to configure the pool, instead an agroal compatiblet properties file can be provided.

Several configuration elements and attributes that were deprecated since 9.0 have been removed:

The xsite state transfer chunk size (<backup><state-transfer chunk-size="X"/></backup>) can no longer be >= 0, same as the regular state transfer chunk size. Previously a value <= 0 would transfer the entire cache in a single batch, which is almost always a bad idea.

SKIP_LISTENER_NOTIFICATION notification flag has been added in the hotrod client. This flag only works when the client and the server version is 9.4.15 or higher. Spring Session integration uses this flag when a session id has changed. If you are using Spring Session with Infinispan 9.4, consider upgrading the client and the server.

The performAsync header was removed from the REST server. Clients that want to perform async operations with the REST server should manage the request and response on their side to avoid blocking.

REST operations that don’t return resources and are used with PUT, POST and DELETE methods now return status 204 (No content) instead of 200.

With the introduction of inline XML JGroups stacks in the configuration, two default stacks are always enabled: udp and tcp. If you are declaring your own stacks with the same names, an exception reporting the conflict will be thrown. Simply rename your own configurations to avoid the conflict.

Because of changes in AWS’s access policy regarding signatures, S3_PING will not work in newer regions and will stop working in older regions too. For this reason, you should migrate to using NATIVE_S3_PING instead.

Listeners in the past that were sync, always ran in the thread that caused the event. We now allow a Listener method to be non-blocking in that it will still fire in the original thread, under the assumption that it will return immediately. Please read the Listener Javadoc for information and examples on this.

Distributed Streams has parts rewritten to utilize non blocking reactive streams based operations. As such null values are not supported as values from operations as per the reactive streams spec. Please utilize other means to denote a null value.

The infinispan-cloud module has been removed and the kubernetes, ec2, google and azure default configurations have been included in infinispan-core and can be referenced as default named JGroups configurations.

Almost as soon as GUARANTEED_DELIVERY was added, UNICAST3 and NAKACK2.resend_last_seqno removed the need for it. It was always documented as experimental, so we removed it without deprecation and we also removed the RSVP protocol from the default JGroups stacks.

The possible statuses of the cache health are now HEALTHY, HEALTHY_REBALANCING and DEGRADED to better reflect the fact that rebalancing doesn’t mean a cluster is unhealthy.

When using multi-tenancy in the WildFly based server, it’s necessary to specify the content-path for each of the REST connectors, to match the prefix element under multi-tenancy\rest\prefix.

Off Heap memory containers now will dynamically resize based on number of entries in the container. Due to this the address count configuration value is now deprecated for APIs and has been removed from the xml parser.

The deprecated methods keySet, values, entrySet and executeTask has been removed.

The AdvancedCacheLoader SPI has been enhanced to provide an alternative method to process and instead allows reactive streams based publishKeys and publishEntries methods which provide benefits in performance, threading and ease of use. Note this change will only affect you if you wish take advantage of it in any custom CacheLoaders you may have implemented.

In 9.3 the default MergePolicy is now MergePolicy.NONE, opposed to MergePolicy.PREFERRED_ALWAYS.

We have reverted the stat changes introduced in 9.1, so average values for read, write and removals are once again returned as milliseconds.

Several new event log messages have been added, and one message has been removed (ISPN100013).

The max idle entry expiration information is sent between owners in the cluster. However when an entry expires via max idle on a given node, this was not replicated (only removing it locally). Max idle has been enhanced to now expire an entry across the entire cluster, instead of per node. This includes ensuring that max idle expiration is applied across all owners (meaning if another node has accessed the entry within the given time it will prevent that entry from expiring on other nodes that didn’t have an access).

Max idle in a transactional clustered cache does not remove expired entries on access (although it will not be returned). These entries are only removed via the expiration reaper.

Iteration in a clustered cache will still show entries that are expired via maxIdle to ensure good performance, but could be removed at any point due to expiration reaper.

The Infinispan WildFly modules are now located in the system/add-ons/ispn dir as per the WildFly module conventions.

Deserialization of content sent by clients to the server are no longer allowed by default. This applies to JSON, XML, and marshalled byte[] that, depending on the cache configuration, will cause the server to convert it to Java Objects either to store it or to perform any operation that cannot be done on a byte[] directly.

The deserialization needs to be enabled using system properties, ether by class name or regular expressions:

The latest version of Kubernetes Ping uses unified environmental variables for both Kubernetes and OpenShift. Some of them were shortened for example OPENSHIFT_KUBE_PING_NAMESPACE was changed to KUBERNETES_NAMESPACE. Please refer to Kubernetes Ping documentation.

Average values for read, write and removals are now returned in Nanoseconds, opposed to Milliseconds.

Infinispan now contains a new implementation of both AtomicMap and FineGrainedAtomicMap, but the semantics has been preserved. The new implementation does not use DeltaAware interface but the Functional API instead.

There are no changes needed for AtomicMap, but it now supports non-transactional use case as well.

FineGrainedAtomicMap now uses the Grouping API and therefore you need to enable groups in configuration. Also it holds entries as regular cache entries, plus one cache entry for cached key set (the map itself). Therefore the cache size or iteration/streaming results may differ. Note that fine grained atomic maps are still supported on transactional caches only.

RemoteCache now implements all of the collection backed methods from Map interface. Previously keySet was implemented, however it was a deep copy. This has now changed and it is a backing set. That is that the set retrieves the updated values on each invocation or updates to the backing remote cache for writes. The entrySet and values methods are also now supported as backing variants as well.

If you wish to have a copy like was provided before it is recommended to copy the contents into a in memory local set such as

Interfaces DeltaAware, Delta and CopyableDeltaAware have been deprecated. Method AdvancedCache.applyDelta() has been deprecated and the implementation does not allow custom set of locked keys. ApplyDeltaCommand and its uses in interceptor stack are deprecated.

Any partial updates to an entry should be replaced using the Functional API.

The configuration property directory_provider now accepts a new value local-heap. This value replaces the now deprecated ram, and as its predecessor will cause the index to be stored in a org.apache.lucene.store.RAMDirectory.

The configuration value ram is still accepted and will have the same effect, but failing to replace ram with local-heap will cause a warning to be logged. We suggest to perform this replacement, as the ram value will no longer be recognised by Infinispan in a future version.

This change was made as the team believes the local-heap name better expresses the storage model, especially as this storage method will not allow real-time replication of the index across multiple nodes. This index storage option is mostly useful for single node integration testing of the query functionality.

TableManipulation::batchSize and JpaStoreConfiguration::batchSize have been deprecated and replaced by the higher level AbstractStoreConfiguration::maxBatchSize.

In Infinispan 9.1 partition handling has been improved to allow for automatic conflict resolution on partition merges. Consequently, PartitionHandlingConfiguration::enabled has been deprecated in favour of PartitionHandlingConfiguration::whenSplit. Configuring whenSplit to the DENY_READ_WRITES strategy is equivalent to setting enabled to true, whilst specifying ALLOW_READ_WRITES is equivalent to disabling partition handling (default).

Furthermore, during a partition merge with ALLOW_READ_WRITES, the default EntryMergePolicy is MergePolicies.PREFERRED_ALWAYS which provides a deterministic way of tie-breaking CacheEntry conflicts. If you require the old behaviour, simply set the merge-policy to null.

The default configuration for transactional caches changed from READ_COMMITTED and OPTIMISTIC locking to REPEATABLE_READ and OPTIMISTIC locking with write-skew enabled.

Also, using the REPEATABLE_READ isolation level and OPTIMISTIC locking without write-skew enabled is no longer allowed. To help with the upgrade, write-skew will be automatically enabled in this case.

The following configuration has been deprecated:

Both were deprecated since version 5.1. eagerLocking(true) can be replaced with lockingMode(LockingMode.PESSIMISTIC), and eagerLockingSingleNode() does not need a replacement because it was a no-op.

Asynchronous mode is no longer supported in transactional caches and it will automatically use the synchronous cache mode. In addition, the second phase of a transaction commit is done synchronously. The following methods (and related) are deprecated:

The following classes have been deprecated and they will be removed in the future:

The mode attribute in the XML declaration of clustered caches is no longer mandatory. It defaults to SYNC.

Up to Infinispan 8.x, the default cache always implicitly existed, even if not declared in the XML configuration. Additionally, the default cache configuration affected all other cache configurations, acting as some kind of base template. Since 9.0, the default cache only exists if it has been explicitly configured. Additionally, even if it has been specified, it will never act as base template for other caches.

Internally Infinispan 9.x has introduced many improvements to its marshalling codebase in order to improve performance and allow for greater flexibility. Consequently, data marshalled and persisted by Infinispan 8.x is no longer compatible with Infinispan 9.0. To aid you in migrating your existing stores to 9.0, we have provided a Store Migrator, however at present this only allows the migration of JDBC stores.

In Infinispan 8.x, cloud related configuration were added to infinispan-core module. Since 9.0 they were moved to infinispan-cloud module.

The entry retriever feature has been removed. Please update to use the new Streams feature detailed in the User Guide. The org.infinispan.filter.CacheFilters class can be used to convert KeyValueFilter and Converter instances into proper Stream operations that are able to be marshalled.

Map reduce has been removed in favor of the new Streams feature which should provide more features and performance. There are no bridge classes to convert to the new streams and all references must be rewritten.

Spring 4 is no longer supported.

The class SerializableSupplier has moved from the org.infinispan.stream package to the org.infinispan.util.function package.

The class CloseableSupplier has moved from the org.infinispan.util package to the org.infinispan.util.function package.

The classes TriConsumer, CloseableSupplier, SerializableRunnable, SerializableFunction & SerializableCallable have all been moved from the org.infinispan.util package to the org.infinispan.util.function package.

The interface SegmentCompletionListener has moved from the interface org.infinispan.CacheStream to the new org.infinispan.BaseCacheStream.

All Infinispan, Spring and Logger dependencies are now in the provided scope. One can decide whether to use small jars or uber jars but they need to be added to the classpath of the application. It also gives one freedom in choosing Spring (or Spring Boot) version.

Here is an example:

Additionally there is no Logger implementation specified (since this may vary depending on use case).

The total order protocol now uses the remote-command-executor. The attribute total-order-executor in <container> tag is removed.

HikariCP offers superior performance to c3p0 and is now the default implementation. Additional properties for HikariCP can be provided by placing a hikari.properties file on the classpath or by specifying the path to the file via PooledConnectionFactoryConfiguration.propertyFile or properties-file in the connection pool’s xml config. N.B. a properties file specified explicitly in the configuration is loaded instead of the hikari.properties file on the class path and Connection pool characteristics which are explicitly set in PooledConnectionFactoryConfiguration always override the values loaded from a properties file.

Support for c3p0 has been deprecated and will be removed in a future release. Users can force c3p0 to be utilised as before by providing the system property -Dinfinispan.jdbc.c3p0.force=true.

The LevelDB cache store was replaced with a RocksDB. RocksDB is a fork of LevelDB which provides superior performance in high concurrency scenarios. The new cache store can parse old LevelDB configurations but will always use the RocksDB implementation.

The JDBC Mixed and Binary stores have been removed due to the poor performance associated with storing entries in buckets. Storing entries in buckets is non-optimal as each read/write to the store requires an existing bucket for a given hash to be retrieved, deserialised, updated, serialised and then re-inserted back into the db. If you were previously using one of the removed stores, we have provided a migrator tool to assist in migrating data from an existing binary table to a JDBC string based store.

A new annotation, @Store, has been added for persistence stores. This allows a store’s properties to be explicitly defined and validated against the provided store configuration. Existing stores should be updated to use this annotation and the store’s configuration class should also declare the @ConfigurationFor annotation. If neither of these annotations are present on the store or configuration class, then a your store will continue to function as before, albeit with a warning that additional store validation cannot be completed.

The no-anonymous policy is now automatically enabled for Hot Rod authentication unless explicitly specified.

Store as Binary configuration is now deprecated and will be removed in a future release. This is replaced by the new memory configuration.

The keySet, entrySet and values methods on DataContainer have been deprecated. These behavior of these methods are very inconsistent and will be removed later. It is recommended to update references to use iterator or iteratorIncludingExpired methods instead.

Entry Retriever is now deprecated and will be removed in Infinispan 9. This is replaced by the new Streams feature.

Map reduce is now deprecated and will be removed in Infinispan 9. This is replaced by the new Streams feature.

Spring 3 support (GroupId:ArtifactId org.infinispan:infinispan-spring) is deprecated. Please consider migrating into Spring 4 support.

The XML schema for the embedded configuration has changed to more closely follow the server configuration. Use the config-converter.sh or config-converter.bat scripts to convert an Infinispan 6.0 to the current format.

In order to use all of the latest features, make sure you change the namespace declaration at the top of your XML configuration files as follows:

In order to use all of the latest features, make sure you change the namespace declaration at the top of your XML configuration files as follows:

In order to use all of the latest features, make sure you change the namespace declaration at the top of your XML configuration files as follows:

The default transaction enlistment model has changed ( ISPN-1284 ) from XAResource to Synchronization. Also now, if the XAResource enlistment is used, then recovery is enabled by default.

In practical terms, if you were using the default values, this should not cause any backward compatibility issues but an increase in performance of about 5-7%. However in order to use the old configuration defaults, you need to configure the following:

or the programmatic configuration equivalent:

Cache Loader and Store configuration has changed greatly in Infinispan 5.2.

The concept of Virtual Nodes doesn’t exist anymore in Infinispan 5.2 and has been replaced by Segments.

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.

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:

However, previous code that interacted against the RemoteCache and RemoteCacheManager will work as it used to:

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.

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 containing 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.

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 fluent, builder style:

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:

to

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.

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

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:

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

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

Configure source and target cache stores in a StoreMigrator properties.