From bb36132b7a2a15b644d77f4487b2e09634ced9c9 Mon Sep 17 00:00:00 2001 From: Infinispan Date: Thu, 30 Jan 2025 11:03:02 +0000 Subject: [PATCH] Synchronized core docs from refs/heads/main --- .../dev/cheat-sheets/cache-configuration.html | 2 +- docs/dev/index.html | 2 +- docs/dev/titles/cli/cli.html | 2 +- docs/dev/titles/configuring/configuring.html | 2 +- .../dev/titles/contributing/contributing.html | 2 +- docs/dev/titles/developing/developing.html | 2 +- docs/dev/titles/embedding/embedding.html | 2 +- docs/dev/titles/encoding/encoding.html | 2 +- .../getting_started/getting_started.html | 2 +- docs/dev/titles/hibernate/hibernate.html | 2 +- docs/dev/titles/hotrod_java/hotrod_java.html | 2 +- .../hotrod_protocol/hotrod_protocol.html | 2 +- docs/dev/titles/memcached/memcached.html | 2 +- docs/dev/titles/query/query.html | 54 +- docs/dev/titles/resp/resp-endpoint.html | 2 +- docs/dev/titles/rest/rest.html | 2 +- docs/dev/titles/security/security.html | 2 +- docs/dev/titles/server/server.html | 2 +- docs/dev/titles/spring/spring.html | 2 +- docs/dev/titles/spring_boot/starter.html | 2 +- docs/dev/titles/tuning/tuning.html | 2 +- docs/dev/titles/upgrading/upgrading.html | 3510 ++++++++++++++++- docs/dev/titles/xsite/xsite.html | 2 +- 23 files changed, 3573 insertions(+), 33 deletions(-) diff --git a/docs/dev/cheat-sheets/cache-configuration.html b/docs/dev/cheat-sheets/cache-configuration.html index 124224c9c1..10eb305340 100644 --- a/docs/dev/cheat-sheets/cache-configuration.html +++ b/docs/dev/cheat-sheets/cache-configuration.html @@ -1196,7 +1196,7 @@

< diff --git a/docs/dev/index.html b/docs/dev/index.html index e82be91ca2..46613f55a3 100644 --- a/docs/dev/index.html +++ b/docs/dev/index.html @@ -634,7 +634,7 @@

Developing app diff --git a/docs/dev/titles/cli/cli.html b/docs/dev/titles/cli/cli.html index 139a9e8b98..c03ab89257 100644 --- a/docs/dev/titles/cli/cli.html +++ b/docs/dev/titles/cli/cli.html @@ -6539,7 +6539,7 @@

9.44.4. SEE ALSO< diff --git a/docs/dev/titles/configuring/configuring.html b/docs/dev/titles/configuring/configuring.html index 6f25b0f0ae..0675465e55 100644 --- a/docs/dev/titles/configuring/configuring.html +++ b/docs/dev/titles/configuring/configuring.html @@ -13161,7 +13161,7 @@

Asynchronous thread pool

diff --git a/docs/dev/titles/contributing/contributing.html b/docs/dev/titles/contributing/contributing.html index b0647423eb..719971281f 100644 --- a/docs/dev/titles/contributing/contributing.html +++ b/docs/dev/titles/contributing/contributing.html @@ -3632,7 +3632,7 @@

-Last updated 2025-01-29 12:58:56 UTC +Last updated 2025-01-30 11:00:15 UTC
diff --git a/docs/dev/titles/developing/developing.html b/docs/dev/titles/developing/developing.html index fe5b5c0a03..7e7e07f6df 100644 --- a/docs/dev/titles/developing/developing.html +++ b/docs/dev/titles/developing/developing.html @@ -548,7 +548,7 @@

Infinispan Developer Guide

diff --git a/docs/dev/titles/embedding/embedding.html b/docs/dev/titles/embedding/embedding.html index edd51b36ba..28a7795117 100644 --- a/docs/dev/titles/embedding/embedding.html +++ b/docs/dev/titles/embedding/embedding.html @@ -7444,7 +7444,7 @@

diff --git a/docs/dev/titles/encoding/encoding.html b/docs/dev/titles/encoding/encoding.html index 1151e80444..999206f5d3 100644 --- a/docs/dev/titles/encoding/encoding.html +++ b/docs/dev/titles/encoding/encoding.html @@ -2624,7 +2624,7 @@

-Last updated 2025-01-29 12:58:56 UTC +Last updated 2025-01-30 11:00:15 UTC
diff --git a/docs/dev/titles/getting_started/getting_started.html b/docs/dev/titles/getting_started/getting_started.html index 9e5af07f00..7df0f85da3 100644 --- a/docs/dev/titles/getting_started/getting_started.html +++ b/docs/dev/titles/getting_started/getting_started.html @@ -758,7 +758,7 @@

1.2. Genera diff --git a/docs/dev/titles/hibernate/hibernate.html b/docs/dev/titles/hibernate/hibernate.html index 5640465e5f..c882deeaec 100644 --- a/docs/dev/titles/hibernate/hibernate.html +++ b/docs/dev/titles/hibernate/hibernate.html @@ -1485,7 +1485,7 @@

1.6 diff --git a/docs/dev/titles/hotrod_java/hotrod_java.html b/docs/dev/titles/hotrod_java/hotrod_java.html index 070416e763..8d9bb29351 100644 --- a/docs/dev/titles/hotrod_java/hotrod_java.html +++ b/docs/dev/titles/hotrod_java/hotrod_java.html @@ -3627,7 +3627,7 @@

-Last updated 2025-01-29 12:58:56 UTC +Last updated 2025-01-30 11:00:15 UTC
diff --git a/docs/dev/titles/hotrod_protocol/hotrod_protocol.html b/docs/dev/titles/hotrod_protocol/hotrod_protocol.html index b04b8806e3..ceccce9cdc 100644 --- a/docs/dev/titles/hotrod_protocol/hotrod_protocol.html +++ b/docs/dev/titles/hotrod_protocol/hotrod_protocol.html @@ -8939,7 +8939,7 @@

diff --git a/docs/dev/titles/memcached/memcached.html b/docs/dev/titles/memcached/memcached.html index 0cf23b305e..881fe75eca 100644 --- a/docs/dev/titles/memcached/memcached.html +++ b/docs/dev/titles/memcached/memcached.html @@ -701,7 +701,7 @@

< diff --git a/docs/dev/titles/query/query.html b/docs/dev/titles/query/query.html index e228881a39..6045794b56 100644 --- a/docs/dev/titles/query/query.html +++ b/docs/dev/titles/query/query.html @@ -542,7 +542,11 @@

Querying Infinispan caches

  • 1.1. Configuring Infinispan to index caches
  • 1.2. Infinispan native indexing annotations
    • @@ -910,7 +914,7 @@
    Index path
    -
    Index startup mode
    +
    Index startup mode

    When Infinispan starts caches it can perform operations to ensure the index is consistent with data in the cache. By default it:

    @@ -1006,6 +1010,49 @@
    Index startup mode
    </distributed-cache>
    +
    +
    Automatic strategy and shared cache stores
    +
    +

    In case of:

    +
    +
    +
      +
    1. +

      A shared storage is configured

      +
      2. +
    2. +

      The indexes are persistent on file system

      +
      3. +
    +
    +
    +

    The AUTO startup mode will apply the REINDEX strategy. +This is done in order to not miss potential updates in case of crash and recovery of an indexed node.

    +
    +
    +

    Thus AUTO in this case may penalize the average user using a shared cache store that does not do any eviction, +since more reindex than necessary will be triggered. +For this reason if:

    +
    +
    +
      +
    1. +

      A shared storage is configured

      +
      2. +
    2. +

      The indexes are persistent on file system

      +
      3. +
    3. +

      Automatic evictions are not possible: cache memory max-size and max-count are not used

      +
      4. +
    4. +

      Manual eviction using the embedded API cache.eviction() is not used

      +
      5. +
    +
    +
    +

    to use NONE in place of AUTO as the index startup strategy.

    +
    Indexing mode

    indexing-mode controls how cache operations are propagated to the indexes.

    @@ -1229,6 +1276,7 @@
    Index sharding
    +

    1.2. Infinispan native indexing annotations

    @@ -4398,7 +4446,7 @@

    diff --git a/docs/dev/titles/resp/resp-endpoint.html b/docs/dev/titles/resp/resp-endpoint.html index 7a2fd4aee3..6b73d2c08e 100644 --- a/docs/dev/titles/resp/resp-endpoint.html +++ b/docs/dev/titles/resp/resp-endpoint.html @@ -1377,7 +1377,7 @@

    -Last updated 2025-01-29 12:58:56 UTC +Last updated 2025-01-30 11:00:15 UTC

    diff --git a/docs/dev/titles/rest/rest.html b/docs/dev/titles/rest/rest.html index ab486d1684..0e81d9eda2 100644 --- a/docs/dev/titles/rest/rest.html +++ b/docs/dev/titles/rest/rest.html @@ -7650,7 +7650,7 @@

    -Last updated 2025-01-29 12:58:56 UTC +Last updated 2025-01-30 11:00:15 UTC

    diff --git a/docs/dev/titles/security/security.html b/docs/dev/titles/security/security.html index 0f15dea0f8..7987d25232 100644 --- a/docs/dev/titles/security/security.html +++ b/docs/dev/titles/security/security.html @@ -6150,7 +6150,7 @@

    Cross-site replication

    diff --git a/docs/dev/titles/server/server.html b/docs/dev/titles/server/server.html index bf17f2e835..ab000a88c6 100644 --- a/docs/dev/titles/server/server.html +++ b/docs/dev/titles/server/server.html @@ -13716,7 +13716,7 @@

    -Last updated 2025-01-29 12:58:56 UTC +Last updated 2025-01-30 11:00:15 UTC
    diff --git a/docs/dev/titles/spring/spring.html b/docs/dev/titles/spring/spring.html index f1fce553e6..76eb4a369e 100644 --- a/docs/dev/titles/spring/spring.html +++ b/docs/dev/titles/spring/spring.html @@ -1006,7 +1006,7 @@

    -Last updated 2025-01-29 12:58:56 UTC +Last updated 2025-01-30 11:00:15 UTC
    diff --git a/docs/dev/titles/spring_boot/starter.html b/docs/dev/titles/spring_boot/starter.html index b839117c9f..44b862ca56 100644 --- a/docs/dev/titles/spring_boot/starter.html +++ b/docs/dev/titles/spring_boot/starter.html @@ -1221,7 +1221,7 @@

    -Last updated 2025-01-29 12:58:56 UTC +Last updated 2025-01-30 11:00:15 UTC
    diff --git a/docs/dev/titles/tuning/tuning.html b/docs/dev/titles/tuning/tuning.html index a8e6ba171c..842119c588 100644 --- a/docs/dev/titles/tuning/tuning.html +++ b/docs/dev/titles/tuning/tuning.html @@ -2673,7 +2673,7 @@

    Use simple cache for diff --git a/docs/dev/titles/upgrading/upgrading.html b/docs/dev/titles/upgrading/upgrading.html index c9d23d5f6c..b8f1f54fd1 100644 --- a/docs/dev/titles/upgrading/upgrading.html +++ b/docs/dev/titles/upgrading/upgrading.html @@ -538,7 +538,411 @@

    Upgrading Infinispan deployments

    Table of Contents
      -
    • 1. Infinispan Version Details
      • +
    • 1. Infinispan Version Details + +
    • 2. Performing rolling upgrades for Infinispan Server clusters
      • 2.1. Setting up target Infinispan clusters
        • @@ -582,8 +986,3096 @@

        1. Infinispan Version

        Learn about changes in Infinispan versions before you upgrade.

        +
        +

        1.1. Upgrading from 15.1 to 15.2

        +
        +

        1.1.1. Native Server

        +
        +

        The native server and its associated quay.io/infinispan/server-native images are no longer provided. User should +use the JVM based server instead as it provides significant performance issues over its native counterpart, without +compromising on features, and is fully supported.

        +
        +
        +
        +

        1.1.2. Default Index startup mode is now AUTO

        +
        +

        The default used to be NONE, meaning that no actions at cache startup time are taken in case +potential index data inconsistencies are detected from the cache configuration. +With AUTO, for instance, a purge is automatically triggered if the cache is not persistent while the indexes are. +For complete detail see Index startup mode.

        +
        +
        +
        +
        +

        1.2. Upgrading from 15.0 to 15.1

        +
        +

        1.2.1. Java HotRod Client Changes

        +
        +
        New client connection handler
        +
        +

        A new client has been introduced that only keeps a single connection per server it is connected to and supports +pipelining by batching concurrent requests into a single flush operation. +The new approach requires less system resources (file descriptors/threads) and also uses less CPU to submit the same task. +The existing client that used a connection pool to handle concurrent requests has been moved to a new module hotrod-client-legacy.

        +
        +
        +

        The new client is effectively a drop in replacement. The only exceptions were if you were referencing some internal classes +such as the ChannelFactory (non-public API), which have been removed since they related to the underlying channel.

        +
        +
        +

        The connection pool configuration is deprecated and no longer used.

        +
        +
        +
        +
        RemoteCache withFlags no longer uses ThreadLocal
        +
        +

        Previously a RemoteCache would store its Flag settings in a ThreadLocal +which was then cleared when an invocation of the cache was done. +This does not work with Virtual Threads and is very error prone if the +same RemoteCache is shared between threads.

        +
        +
        +

        Instead, now withFlags will return a new instance if new flags are applied +and the previous instance will be untouched. +This allows for thread and virtual thread safety.

        +
        +
        +
        +
        +
        +

        1.3. Server templates

        +
        +

        The internal server templates have been removed.

        +
        +
        +
        +

        1.4. Upgrading from 14.0 to 15.0

        +
        +

        1.4.1. Deprecations, removals and moved classes

        +
        +
        Moved
        +
        +
          +
        • +

          The org.infinispan.util.TimeoutException has been moved to org.infinispan.commons.TimeoutException

          +
          • +
        • +

          org.infinispan.util.concurrent.IsolationLevel has been moved to org.infinispan.configuration.IsolationLevel

          +
          • +
        +
        +
        +
        +
        Removed
        +
        +
          +
        • +

          All: Parsing of configuration files with schema < 10.0

          +
          • +
        • +

          Commons: Start.priority and Stop.priority

          +
          • +
        • +

          Core: AdvancedCache.with(ClassLoader), AdvancedCache.getEvictionManager(), AdvancedCache.getAsyncInterceptorChain(), AdvancedCache.getComponentRegistry()

          +
          • +
        • +

          Core: AnyScopeComponentFactory.construct(Class)

          +
          • +
        • +

          Core: Cache.getListeners()

          +
          • +
        • +

          Core: ConfigurationBuilder.classLoader(), ConfigurationBuilder.customInterceptors()

          +
          • +
        • +

          Core: DataRehashedEvent.getUnionConsistentHash()

          +
          • +
        • +

          Core: EmbeddedCacheManager.getListeners(), EmbeddedCacheManager.getTransport(), EmbeddedCacheManager.removeCache(String), EmbeddedCacheManager.getGlobalComponentRegistry()

          +
          • +
        • +

          Core: FlagAffectedCommand.setFlags, FlagAffedctedCommand.addFlags, FlagAffectedCommand.hasFlag

          +
          • +
        • +

          Core: IntCacheStream.filterKeySegments(Set<Integer>)

          +
          • +
        • +

          Core: JMXStatisticsConfiguration

          +
          • +
        • +

          Core: GlobalConfiguration.DEFAULT_MARSHALL_VERSION

          +
          • +
        • +

          Core; LocalizedCacheTopology.getDistributionForSegment(int)

          +
          • +
        • +

          Core: NamedComponentFactory

          +
          • +
        • +

          Core: PersistenceUtil.loadAndStoreInDataContainer

          +
          • +
        • +

          Core: TopologyChangedEvent.getConsistentHashAtStart() and TopologyChangedEvent.getConsistentHashAtEnd()

          +
          • +
        • +

          Core: Transport.invokeRemotely() Transport.waitForView() Transport.backupRemotely() AbstractTransport

          +
          • +
        • +

          Core: ValueMatcher.nonExistentEntryCanMatch

          +
          • +
        • +

          Core: WriteCommand.updateStatusFromRemoteResponse

          +
          • +
        • +

          Core: state transfer pool

          +
          • +
        • +

          Counters: SyncStrongCounter and SyncWeakCounter

          +
          • +
        • +

          Hot Rod client: org.infinispan.client.hotrod.marshall.ProtoStreamMarshaller

          +
          • +
        • +

          Server and clients: keystore certificate password

          +
          • +
        • +

          RocksDB Store: expiry queue size

          +
          • +
        • +

          Remote Store: transport factory and maxIdle

          +
          • +
        +
        +
        +
        +
        +

        1.4.2. Metrics

        +
        +

        The JGroups and cross-site metrics name changed when names-as-tags is set to true, +where the cluster’s name and the site’s name are no longer present in the metrics name but as a tag.

        +
        +
        +

        As an example, when you set names-as-tags to false, metrics are named based on the channel, resulting in multiple metrics for the same purpose:

        +
        +
        +
        +
        # TYPE vendor_jgroups_xsite_frag4_get_number_of_sent_fragments gauge
+# HELP vendor_jgroups_xsite_frag4_get_number_of_sent_fragments Number of sent fragments
+vendor_jgroups_xsite_frag4_get_number_of_sent_fragments{cluster="xsite",node="..."} 0.0
+# TYPE vendor_jgroups_cluster_frag4_get_number_of_sent_fragments gauge
+# HELP vendor_jgroups_cluster_frag4_get_number_of_sent_fragments Number of sent fragments
+vendor_jgroups_cluster_frag4_get_number_of_sent_fragments{cluster="cluster",node="..."} 2.0
        +
        +
        +
        +

        When you set names-as-tags to true, metrics are simplified, and cluster and site names appear as tags:

        +
        +
        +
        +
        # TYPE vendor_jgroups_frag4_get_number_of_sent_fragments gauge
+# HELP vendor_jgroups_frag4_get_number_of_sent_fragments Number of sent fragments
+vendor_jgroups_frag4_get_number_of_sent_fragments{cache_manager="default",cluster="xsite",node="..."} 0.0
+vendor_jgroups_frag4_get_number_of_sent_fragments{cache_manager="default",cluster="cluster",node="..."} 2.0
        +
        +
        +
        +
        +

        1.4.3. SecurityManager

        -

        include::../topics/upgrading.adoc

        +

        Aligning with the deprecation for removal of the SecurityManager since JDK 17, we no longer support integration with a +SecurityManager.

        +
        +
        +
        +

        1.4.4. Jakarta and Java EE

        +
        +
          +
        • +

          Infinispan has been updated to use jakarta.* packages only.

          +
          • +
        • +

          If you require the legacy javax.* packages, you should utilise Infinispan 14.0.x.

          +
          • +
        • +

          The transitional -jakarta jars, which included both jakarta. and javax.* packages, have been removed.

          +
          • +
        +
        +
        +
        +

        1.4.5. Removals

        +
        +
          +
        • +

          The Kryo and Protostuff marshallers have been removed.

          +
          • +
        • +

          Extended Statistics module have been removed.

          +
          • +
        • +

          JCache support.

          +
          • +
        • +

          Spring 5.x and Spring Boot 2.x support.

          +
          • +
        • +

          Wildfly modules are no longer provided.

          +
          • +
        +
        +
        +
        +

        1.4.6. Hot Rod client defaults

        +
        +

        Infinispan introduced changes to the properties of the Hot Rod client.

        +
        +
        +
        ssl_hostname_validation
        +

        A new property, ssl_hostname_validation with a default value of true. +This property enables TLS hostname validation based on RFC 2818 rules. +Additionally, setting the sni_host_name is now required when hostname validation is enabled.

        +
        + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
        Table 1. Default property changes
        PropertyInfinispan 15Previous versions

        connect_timeout

        2000 ms / 2 seconds

        60000 ms / 60 seconds

        socket_timeout

        2000 ms / 2 seconds

        60000 ms / 60 seconds

        max_retries

        3

        10

        min_evictable_idle_time

        180000 ms / 3 minutes

        1800000 ms / 30 minutes

        sasl_mechanism

        SCRAM-SHA-256

        SCRAM-SHA-512

        +
        +
        +

        1.4.7. RESP Endpoint

        +
        +
          +
        • +

          Default expiration may be applied to the cache configuration used by the RESP endpoint

          +
          • +
        +
        +
        +
        + +
        +
        Indexing
        +
        +
          +
        • +

          The property attribute has been removed.

          +
          • +
        • +

          The auto-config attribute has been removed.

          +
          • +
        • +

          The index attribute has been removed.

          +
          • +
        +
        +
        +
        +
        +

        1.4.9. Indexing annotations

        +
        +
          +
        • +

          The support for the old Hibernate Search 5 annotations have been removed

          +
          • +
        • +

          @ProtoDoc, no longer required since 14.0, is now deprecated

          +
          • +
        +
        +
        +
        +

        1.4.10. Security

        +
        +

        The principal role mapper now applies only to groups instead of both groups and user principals. +Use the cache-manager.security.authorization.group-only-mapping=false configuration to use the old behavior.

        +
        +
        +
        +

        1.4.11. Scattered cache removal

        +
        +

        The scattered cache mode have been removed. Use Distributed caches instead.

        +
        +
        +
        +

        1.4.12. Global State

        +
        +

        Infinispan will now refuse to start if a dangling lock file is found in the persistent global state, indicating +an unclean shutdown. The behavior can be changed by configuring the global state unclean-shutdown-action setting.

        +
        +
        +
        +

        1.4.13. Persistence

        +
        +

        The default availability-interval has been increased to 30 seconds. The previous default was 1 second.

        +
        +
        +
        SoftIndexFileStore
        +
        +

        The index segment configuration is no longer used and instead the number of segments is determined solely by the number of cache segments.

        +
        +
        +
        +
        +

        1.4.14. RESP endpoint

        +
        +

        The RESP endpoint cache now requires the key storage media type to be +application/octet-stream.

        +
        +
        +
        +

        1.4.15. Client listeners remove events

        +
        +

        Client listeners remove events will now be propagated even if the remove did not remove a value. +This is required to properly support new changes around the new includeOldValue method on CacheEventConverter. +NOTE: Remote events do not include any values by default

        +
        +
        +
        +

        1.4.16. NearCache SPI

        +
        +

        Due to inconsistency issues with concurrent updates the NearCache SPI needed to be updated to have concurrent +based methods to prevent an issue where a stale entry may have been saved in the near cache. +For more information please see ISPN-13612

        +
        +
        +
        +
        +

        1.5. Upgrading from 13.0 to 14.0

        +
        +

        1.5.1. Security authorization SPI

        +
        +

        org.infinispan.security.PrincipalRoleMapperContext is deprecated in 14.0 and replaced by org.infinispan.security.AuthorizationMapperContext.

        +
        +
        +
        +

        1.5.2. Scattered cache deprecation

        +
        +

        The scattered cache mode is deprecated in 14.0 and will be removed in 16.0.

        +
        +
        +
        +

        1.5.3. Cross Site Replication

        +
        +
        Asynchronous backup strategy logging
        +
        +

        By default, the asynchronous backup strategy logs exceptions that occur on remote sites. +To disable exceptions for async backup operations, set failure-policy="IGNORE" in your configuration as follows:

        +
        +
        +
        +
        <backup site="NYC" strategy="ASYNC" failure-policy="IGNORE" />
        +
        +
        +
        +
        +
        +

        1.5.4. Store properties

        +
        +

        Store provided properties are no longer allowed to override store explicit configuration.

        +
        +
        +

        For example the below configuration would set the read only configuration of the store to true.

        +
        +
        +
        +
        <persistence>
+  <file-store>
+    <index path="testCache/index" />
+    <data path="testCache/data" />
+    <property name="readOnly">true</property>
+  </file-store>
+</persistence>
        +
        +
        +
        +

        Now the readOnly property is only provided to the store itself and does not affect the store explicit configuration. +The same configuration should be changed to the following instead.

        +
        +
        +
        +
        <persistence>
+  <file-store read-only="true">
+    <index path="testCache/index" />
+    <data path="testCache/data" />
+  </file-store>
+</persistence>
        +
        +
        +
        +
        +

        1.5.5. Fetch Persistent State Remove

        +
        +

        The store property named fetch-persistent-state has been deprecated and removed from xml configuration. +Instead, the first configured non-shared store that allows for bulk loading will be used for state transfer of entries. +This reduces configuration complexity and does not allow for a configuration that could lose data due to not +transferring entries stored in a store.

        +
        +
        + + + + + +
        + + +This change has no effect for shared stores +
        +
        +
        +
        +

        1.5.6. RocksDB store

        +
        +

        The RocksDB implementation is no longer included by default with the server. It can be installed via the CLI:

        +
        +
        +
        +
        cli.sh install org.rocksdb:rocksdbjni:6.22.1.1
        +
        +
        +
        +
        +

        1.5.7. JDBC Store database versions configuration deprecated

        +
        +

        Previously, we allowed a user to specify the database major and minor versions when configuring the database parameters. +These two options are now deprecated and ignored as we always retrieve them from the JDBC metadata directly. +This affects all three of the JDBC based stores (string-keyed-jdbc-store, table-jdbc-store and query-jdbc-store).

        +
        +
        +
        +

        1.5.8. Micrometer Metrics

        +
        +

        Microprofile metrics are no longer supported, available output metrics are now Prometheus and OpenMetrics.

        +
        +
        +

        The implementation relies on Micrometer library, for more information see +the Configuring Infinispan metrics.

        +
        +
        +
        +

        1.5.9. Jakarta EE compatible jars available

        +
        +

        We now distribute Jakarta EE based jars for users. +This is in addition to the javax compatible jars.

        +
        +
        +

        Some modules that have Jakarta based jars are the following (note there are quite a few more, just some prime examples)

        +
        +
        +
          +
        • +

          infinispan-commons

          +
          • +
        • +

          infinispan-core

          +
          • +
        • +

          infinispan-multimap

          +
          • +
        • +

          infinispan-query

          +
          • +
        • +

          infinispan-client-hotrod

          +
          • +
        • +

          infinispan-api

          +
          • +
        +
        +
        +

        If your application requires using the jakarta instead of javax namespace all you need to do is to append your dependencies with -jakarta.

        +
        +
        +
        +
        <dependency>
+   <groupId>org.infinispan</groupId>
+   <artifactId>infinispan-client-hotrod-jakarta</artifactId>
+</dependency>
        +
        +
        +
        +
        +

        1.5.10. Hibernate 6.0 2LC Update

        +
        +

        Hibernate 6.0 is now supported and is the only implementation supported moving forward. +If Hibernate 5.3 support is needed, you must use an older version of Infinispan.

        +
        +
        +
        +

        1.5.11. JPAStore has been removed

        +
        +

        The JPAStore has been removed in Infinispan 14.0. +It is suggested instead to use the new SQL Table or Query Stores that were added in Infinispan 13.0.

        +
        +
        +
        +

        1.5.12. Query API

        +
        +
        Infinispan native annotations
        +
        +

        This release introduces new indexing annotations: @Indexed, @Basic, @Decimal, @Keyword, @Text, and @Embedded. +Each of the annotations supports a set of attributes that you can use to further describe how the entity is indexed.

        +
        +
        +

        These new annotations replaced Hibernate Search annotations which means that you are no longer required to annotate your Java classes with the @ProtoDoc annotation for remote caches. +Any annotations will be copied as comments to the generated .proto files.

        +
        +
        +

        The following table summarizes the mapping of fields between Hibernate Search 5 (HS5) annotations and Infinispan native annotations:

        +
        + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
        HS5 annotationsIndexing attributesInfinispan native annotationsDescription

        @Field(index=Index.YES)

        searchable

        @Basic, @Decimal, @Keyword, @Text

        Fields previously marked as indexed are now searchable.

        @Field(store = Store.YES)

        projectable = true

        @Basic, @Decimal, @Keyword, @Text

        Fields previously marked as stored are now projectable.

        type String && @Field(analyze = Analyze.YES)

        analyzer = "<definition>"

        @Text

        String fields that were marked with analyzer definitions remain being analyzed during indexing.

        @Field(analyze = Analyze.NO) && (@Field(store = Store.YES) OR @Field(sortable = Sortable.YES))

        sortable = true

        @Basic, @Decimal, @Keyword

        Fields that were not analyzed but were either stored in the index or marked as sortable are now considered sortable.

        N/A

        aggregable = true

        @Basic, @Decimal, @Keyword

        Performing aggregation operations using the Hibernate 5 Search annotations was not possible.

        N/A

        normalizer = "lowercase"

        @Keyword

        Mapping fields that were analyzed or normalized is not possible due to the potential data loss in the process.

        +
        +
        +
        +

        1.5.13. Query efficiency

        +
        +

        The default for maximum results returned by a query that was present in Infinispan 12.1.5.Final and earlier versions has been restored. +You can now change the default limit by setting the default-max-results cache property. +The default value of default-max-results is 100. +Limiting the number of results returned by a query significantly improves performance of queries that don’t have an explicit limit set.

        +
        +
        +
        +

        1.5.14. The (undocumented) server filesystem-realm has been removed

        +
        +

        The filesystem-realm, an experimental feature which has never been documented, has been removed.

        +
        +
        +
        +
        +

        1.6. Upgrading from 12.1 to 13.0

        +
        +

        1.6.1. Search

        +
        +

        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.

        +
        +
        +
        +

        1.6.2. REST

        +
        +
        Indexer
        +
        +

        The mass-index operation from the cache resource has been deprecated. +Use reindex instead:

        +
        +
        +
        +
        /rest/v2/caches/{cacheName}/search/indexes?action=reindex
        +
        +
        +
        +
        +
        Rolling Upgrades
        +
        +

        The following operation has been deprecated:

        +
        +
        +
          +
        • +

          POST /rest/v2/caches/{cacheName}?action=disconnect-source

          +
          • +
        +
        +
        +

        Use the substitute:

        +
        +
        +
          +
        • +

          DELETE /rest/v2/caches/{cacheName}/rolling-upgrade/source-connection

          +
          • +
        +
        +
        +
        +
        +

        1.6.3. File-Based Cache Store (file-store) Configuration Defaults to SoftIndexFileStore

        +
        +

        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.

        +
        +
        +
        Schema changes
        +
        +

        The following changes apply to the Infinispan 13 configuration schemas:

        +
        +
        +
          +
        • +

          The urn:infinispan:config:store:soft-index namespace is no longer available.

          +
          • +
        • +

          The file-store element in the urn:infinispan:config namespace now defaults to soft-index file stores.

          +
          • +
        • +

          The single-file-store element has been added to the urn:infinispan:config namespace if you want to configure a single file store, which is deprecated.

          +
          • +
        • +

          The endpoints element in the urn:infinispan:server namespace is no longer a repeating element, but a wrapper for 0 or more endpoint elements.

          +
          • +
        +
        +
        +
        +
        Migrating Soft-Index File Stores
        +
        +
        Declarative
        +
        +

        If you are upgrading to Infinispan 13 from a previous version, and your caches include any configuration with the soft-index-file-store element, you should convert that configuration to use the file-store element instead.

        +
        +
        +
        Infinispan 12.1 and earlier
        +
        +
        <persistence>
+  <soft-index-file-store xmlns="urn:infinispan:config:soft-index:12.1">
+    <index path="testCache/index" />
+    <data path="testCache/data" />
+  </soft-index-file-store>
+</persistence>
        +
        +
        +
        +
        Infinispan 13 and later
        +
        +
        <persistence>
+  <file-store>
+    <index path="testCache/index" />
+    <data path="testCache/data" />
+  </file-store>
+</persistence>
        +
        +
        +
        +
        +
        Programmatic
        +
        +
        Infinispan 12.1 and earlier
        +
        +
        ConfigurationBuilder b = new ConfigurationBuilder()
+   .persistence()
+      .addStore(SoftIndexFileStoreConfigurationBuilder.class)
+        .indexLocation("testCache/index")
+        .dataLocation("testCache/data");
        +
        +
        +
        +
        Infinispan 13 and later
        +
        +
        ConfigurationBuilder b = new ConfigurationBuilder()
+   .persistence()
+      .addSoftIndexFileStore()
+        .indexLocation("testCache/index")
+        .dataLocation("testCache/data");
        +
        +
        +
        +
        +
        +
        Migrating Single File Stores
        +
        +

        To use SingleFileStore as a file-based cache store with Infinispan 13 or later, do one of the following:

        +
        +
        +
        Declarative
        +
        +
        <persistence passivation="false">
+  <single-file-store shared="false"
+                     preload="true"
+                     read-only="false"/>
+</persistence>
        +
        +
        +
        +
        Programmatic
        +
        +
        ConfigurationBuilder b = new ConfigurationBuilder()
+   .persistence()
+      .addSingleFileStore();
        +
        +
        +
        +

        However, Infinispan does not recommend using SingleFileStore. +Instead you should use SoftIndexFileStore for file-based cache stores because it offers better scalability.

        +
        +
        +

        Find out more details about configuring file-based cache stores in the Configuration Guide.

        +
        +
        +
        +
        +

        1.6.4. Accurate size metrics

        +
        +

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

        +
        +
        +
        Declarative
        +
        +
        <cache-container>
+  <metrics accurate-size="true"/>
+</cache-container>
        +
        +
        +
        +
        Programmatic
        +
        +
        GlobalConfigurationBuilder b = new GlobalConfigurationBuilder()
+   .metrics()
+     .accurateSize(true);
        +
        +
        +
        +
        +
        +

        1.7. Upgrading from 11.x or 12.0 to 12.1

        +
        +
        +
        If you are upgrading from 11.x to 12.1, you should also review the 11.0 to 12.0 upgrade notes.
        +
        +
        +
        +

        1.7.1. Upgrading Deployments with Single File Cache Store Persistence

        +
        +

        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:

        +
        +
        +
          +
        1. +

          Back up any $ISPN_HOME/server/data/*.dat files.

          +
          2. +
        2. +

          Upgrade to Infinispan 12.1.5.Final or later.

          +
          3. +
        +
        +
        +

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

        +
        +
        +
        Cross-site replication state transfer
        +

        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:

        +
        +
        +
        +
        [//containers/default]> site push-site-state --cache=cacheName --site=NYC
        +
        +
        +
        +
        +

        1.7.2. JGroups configuration changes

        +
        +
        Message bundler
        +
        +

        The default JGroups bundler has changed from +"no-bundler" (a thread sending a message writes it to the TCP socket or sends the UDP datagram directly) to +"transfer-queue" (a thread sending a message only adds the message to a queue, and a separate +bundler thread groups the messages in "batches" then sends the batches).

        +
        +
        +
        +
        +

        1.7.3. Encoding

        +
        +
          +
        • +

          org.infinispan.commons.dataconversion.Encoder has been deprecated and will be removed in a future version.

          +
          • +
        +
        +
        +
        +

        1.7.4. Authorization

        +
        +

        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.

        +
        +
        +
        Server
        +
        +

        Authorization is now enabled out-of-the-box in the default server configuration. +Authorization only applies to "global" operations (administrative and management), so normal cache usage is unaffected. +You can revert to the previous behavior by removing the <authorization> element from the <cache-container> configuration.

        +
        +
        +

        The default logging configuration now includes an audit logging which is disabled by default.

        +
        +
        +
        +
        +

        1.7.5. Server Trust Store

        +
        +

        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.

        +
        +
        +
        +
        <!-- 12.0 -->
+<security-realm name="default">
+   <server-identities>
+      <ssl>
+         <keystore path="server.pfx"
+                   keystore-password="password" alias="server"/>
+      </ssl>
+   </server-identities>
+   <truststore-realm path="trust.pfx" password="secret"/>
+</security-realm>
        +
        +
        +
        +
        +
        <!-- 12.1 -->
+<security-realm name="default">
+   <server-identities>
+      <ssl>
+         <keystore path="server.pfx"
+                   keystore-password="password" alias="server"/>
+         <truststore path="trust.pfx" password="secret"/>
+      </ssl>
+   </server-identities>
+   <truststore-realm/>
+</security-realm>
        +
        +
        +
        +
        +
        +

        1.8. Upgrading from 11.0 to 12.0

        +
        +

        1.8.1. Encoding

        +
        +

        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.

        +
        +
        +
        +

        1.8.2. OSGi

        +
        +

        Support for OSGi was deprecated and has been removed.

        +
        +
        +
        +

        1.8.3. REST

        +
        +

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

        +
        +
        +
          +
        • +

          /v2/caches/{cacheName}?action=clear

          +
          • +
        • +

          /v2/caches/{cacheName}?action=sync-data

          +
          • +
        • +

          /v2/caches/{cacheName}?action=disconnect-source

          +
          • +
        • +

          /v2/cluster?action=stop

          +
          • +
        • +

          /v2/counters/{counterName}?action=reset

          +
          • +
        • +

          /v2/counters/{counterName}?action=increment

          +
          • +
        • +

          /v2/counters/{counterName}?action=decrement

          +
          • +
        • +

          /v2/counters/{counterName}?action=add

          +
          • +
        • +

          /v2/counters/{counterName}?action=compareAndSet

          +
          • +
        • +

          /v2/counters/{counterName}?action=compareAndSwap

          +
          • +
        • +

          /v2/caches/{cacheName}/search/indexes?action=mass-index

          +
          • +
        • +

          /v2/caches/{cacheName}/search/indexes?action=clear

          +
          • +
        • +

          /v2/caches/{cacheName}/search/query/stats?action=clear

          +
          • +
        • +

          /v2/server/?action=stop

          +
          • +
        • +

          /v2/tasks/{taskName}?action=exec

          +
          • +
        • +

          /v2/caches/{cacheName}/x-site/local/?action=clear-push-state-status

          +
          • +
        • +

          /v2/caches/{cacheName}/x-site/backups/{site}?action=take-offline

          +
          • +
        • +

          /v2/caches/{cacheName}/x-site/backups/{site}?action=bring-online

          +
          • +
        • +

          /v2/caches/{cacheName}/x-site/backups/{site}?action=start-push-state

          +
          • +
        • +

          /v2/caches/{cacheName}/x-site/backups/{site}?action=cancel-push-state

          +
          • +
        • +

          /v2/caches/{cacheName}/x-site/backups/{site}?action=cancel-receive-state

          +
          • +
        • +

          /v2/cache-managers/{name}/x-site/backups/{site}?action=bring-online

          +
          • +
        • +

          /v2/cache-managers/{name}/x-site/backups/{site}?action=take-offline

          +
          • +
        • +

          /v2/cache-managers/{name}/x-site/backups/{site}?action=start-push-state

          +
          • +
        • +

          /v2/cache-managers/{name}/x-site/backups/{site}?action=cancel-push-state

          +
          • +
        • +

          The following query statistics operation:

          +
          +
            +
          • +

            /v2/caches/{cacheName}/search/query/stats

            +
            • +
          • +

            /v2/caches/{cacheName}/search/indexes/stats

            +
            • +
          +
          +
          • +
        +
        +
        +

        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.

        +
        +
        +
        +

        1.8.4. Search

        +
        +
          +
        • +

          It’s not possible anymore to enable or disable search statistics via JMX. Query and Index statistics are only exposed when the cache "statistics" configuration is enabled.

          +
          • +
        • +

          MassIndexer, CacheQuery and SearchManager were deprecated and are now removed.

          +
          • +
        • +

          Indexed type names must be declared for all indexed caches, regardless of their storage format. +This requirement was introduced in 11 in a more lenient form and failing to comply just logged a warning. +Starting with version 12 this results in a fatal error preventing the cache to start. +Please update your configurations accordingly.

          +
          • +
        +
        +
        +
        Indexing configuration
        +
        +

        Configuring indexing using the property element is deprecated and will be removed in a future version. +Use the <index-reader> and <index-writer> configuration elements to define indexing behaviour. +For the programmatic configuration, use builder.indexing().reader() and builder.indexing().writer().

        +
        +
        +

        To migrate your configuration, please refer to the sections below:

        +
        +
        +
        Storage
        +
        +
        Memory Storage
        +
        +
        <!-- 11.0 -->
+<indexing>
+ <property name="default.directory_provider">local-heap</property>
+</indexing>
        +
        +
        +
        +
        +
        <!-- 12.0 -->
+<indexing storage="local-heap">
+</indexing>
        +
        +
        +
        +
        Filesystem storage
        +
        +
        <!-- 11.0 -->
+<indexing>
+  <property name="default.directory_provider">filesystem</property>
+  <property name="default.indexBase">${java.io.tmpdir}/baseDir</property>
+</indexing>
        +
        +
        +
        +
        +
        <!-- 12.0 -->
+<indexing storage="filesystem" path="${java.io.tmpdir}/baseDir"/>
        +
        +
        +
        +
        +
        Reader refresh
        +
        +
        +
        <!-- 11.0 -->
+<indexing>
+  <property name="default.reader.async_refresh_period_ms">1000</property>
+</indexing>
        +
        +
        +
        +
        +
        <!-- 12.0 -->
+<indexing>
+  <index-reader refresh-interval="1000"/>
+</indexing>
        +
        +
        +
        +
        +
        IndexManager
        +
        +

        From 12.0, near-real-time is the default index manager and no configuration is needed:

        +
        +
        +
        +
        <!-- 11.0 -->
+<indexing>
+  <property name="default.indexmanager">near-real-time</property>
+</indexing>
        +
        +
        +
        +
        +
        <!-- 12.0 -->
+<indexing enabled="true"/>
        +
        +
        +
        +
        +
        Worker sync/async
        +
        +

        The default.worker.execution is redundant as the indexing process is async by default:

        +
        +
        +
        +
        <!-- 11.0 -->
+<indexing>
+   <property name="default.worker.execution">async</property>
+   <property name="default.index_flush_interval">500</property>
+</indexing>
        +
        +
        +
        +
        +
        <!-- 12.0 -->
+<indexing>
+   <index-writer commit-interval="500"/>
+</indexing>
        +
        +
        +
        +
        +
        Low level Lucene options
        +
        +

        The properties used previously to tune the Lucene index directly are now +available under the <index-writer> element.

        +
        +
        +
        +
        <!-- 11.0 -->
+<indexing>
+   <property name="default.indexwriter.merge_factor">30</property>
+   <property name="default.indexwriter.merge_max_size">1024</property>
+   <property name="default.indexwriter.ram_buffer_size">256</property>
+</indexing>
        +
        +
        +
        +
        +
        <!-- 12.0 -->
+<indexing>
+   <index-writer ram-buffer-size="256">
+       <index-merge factor="30" max-size="1024"/>
+   </index-writer>
+</indexing>
        +
        +
        +
        +
        +
        Supporting older indexes
        +
        +

        The property lucene_version is deprecated and will not be supported in a future version. It is recommended to re-index when migrating from older Infinispan versions instead of reusing the underlying indexes on disk created +in an older Lucene version.

        +
        +
        +
        +
        Sharding
        +
        +

        Configuration of sharding through the property default.sharding_strategy.nbr_of_shards is deprecated and will be removed in a future version.

        +
        +
        +
        +
        Maximum boolean clauses
        +
        +

        The property infinispan.query.lucene.max-boolean-clauses is now only supported when used via JVM property. Support for using +it inside the <property> element of the index configuration was removed.

        +
        +
        +
        +
        +
        +

        1.8.5. Cache Health

        +
        +

        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.

        +
        +
        +
        +

        1.8.6. Marshalling

        +
        +
        Kryo and Protostuff marshaller deprecation
        +
        +

        The Kryo and Protostuff marshallers have been deprecated and will be removed in Infinispan 15.0

        +
        +
        +
        +
        Infinispan includes an upgraded version of the ProtoStream API that can
        +
        +

        affect upgrade from previous Infinispan versions.

        +
        +
        +

        In previous versions, the ProtoStream API did not correctly nest message types +with the result that the messages were generated as top-level only. For this +reason, if you have Protobuf messages in a persistent cache store and upgrade +to Infinispan 12, then you should modify Java classes so that Protobuf +annotations are at top-level. This ensures that the nesting in your persisted +messages matches the nesting in your Java classes, otherwise data +incompatibility issues can occur.

        +
        +
        +
        +
        Allow lists
        +
        +

        All occurrences of "white list" have been renamed to "allow list".

        +
        +
        +
        +
        +

        1.8.7. Persistence

        +
        +
        JdbcStringBasedStore
        +
        +

        The JDBC string based store now creates an additional _META to ensure that any database content is compatible with +the current Infinispan version and configuration.

        +
        +
        +
        +
        Rest Store
        +
        +

        The rest-store has been removed. Users should utilise the HotRod based remote-store for reading/writing to Infinispan clusters.

        +
        +
        +
        +
        Hot Rod client
        +
        +

        The trust_store_path property has been deprecated. Use trust_store_filename instead and specify pem in trust_store_type.

        +
        +
        +
        +
        +
        +

        1.9. Upgrading from 10.1 to 11.0

        +
        +

        1.9.1. HotRod Client

        +
        +

        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.

        +
        +
        +
        +

        1.9.2. Wildfly modules

        +
        +

        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.

        +
        +
        +
        +

        1.9.3. Cross Site Replication

        +
        +
          +
        • +

          The org.infinispan.xsite.CustomFailurePolicy interface has been deprecated and it will be replaced by +org.infinispan.configuration.cache.CustomFailurePolicy.

          +
          • +
        • +

          Cross Site Replication was disabled for local caches. They are unable to send or receive updates.

          +
          • +
        +
        +
        +
        +

        1.9.4. Total Order transaction protocol removed

        +
        +

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

        +
        +
        +
        +

        1.9.5. JGroups configuration system property changes

        +
        +

        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.

        +
        +
        +
        +

        1.9.6. OSGi

        +
        +

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

        +
        +
        +
        +

        1.9.7. Search

        +
        +
        Indexing
        +
        +
          +
        • +

          The Infinispan Lucene Directory, the InfinispanIndexManager and AffinityIndexManager index managers, and the Infinispan Directory provider for Hibernate Search were deprecated and are now removed.

          +
          • +
        • +

          The auto-config attribute is deprecated and will be removed in a future version.

          +
          • +
        • +

          The index mode configuration index() is no longer necessary. The system will automatically choose the best +way to manage indexing once it is enabled and several previously supported values are no longer supported and will +result in a fatal configuration error when used. +The following substitutions should be done:

          +
          +
            +
          • +

            .indexing().index(Index.NONE) → indexing().enabled(false)

            +
            • +
          • +

            All the other enum values → indexing().enabled(true)

            +
            • +
          +
          +
          • +
        +
        +
        +

        In the XML configuration it is possible to omit enabled="true" if the configuration contains others sub-elements. Programmatic and JSON configurations must use it.

        +
        +
        +

        It is forbidden to use both the .indexing().enabled( ) and the deprecated .indexing().index( ) configuration.

        +
        +
        +
          +
        • +

          Indexed types required: starting with version 11 it is mandatory to declare all indexed types in the indexing configuration or else warnings will be logged when the undeclared type is firstly used. +This requirement exists solely for indexed caches and applies to both Java classes and protobuf types. +Please consider updating your cache configurations in order to avoid these warnings now. +Starting with version 12 such incomplete configurations will be considered invalid and will result in a fatal error at cache startup time.

          +
          • +
        +
        +
        +
        +
        Querying
        +
        +
          +
        • +

          The SearchManager has been deprecated and no longer supports Lucene and Hibernate Search native objects:

          +
          +
            +
          • +

            .getQuery() methods that take a Lucene Query have been removed. The alternative methods that take an Ickle query from the org.infinispan.query.Search entry point should be used instead.

            +
            • +
          • +

            .buildQueryBuilderForClass(), that allows to build Hibernate Search queries directly has been removed. Ickle queries should be used instead.

            +
            • +
          • +

            It is not possible anymore to specify multiple target entity(ies) class(es) when calling .getQuery(). The entity will come from the Ickle query string, so multi-entity queries are not supported anymore.

            +
            • +
          +
          +
          • +
        • +

          CacheQuery has been deprecated and org.infinispan.query.dsl.Query obtained from Search.getQueryFactory() should be used instead.

          +
          • +
        • +

          Instances of org.infinispan.query.dsl.Query don’t cache query results anymore and allow queries to be re-executed when +calling methods such as list().

          +
          • +
        +
        +
        +
        Entity Mappings
        +
        +
          +
        • +

          It is now required to annotate a field that requires sorting with @SortableField, both for embedded and remote queries.

          +
          • +
        • +

          Several features have been deprecated:

          +
          +
            +
          • +

            Custom bridges, declared with @FieldBridge and @ClassBridge

            +
            • +
          • +

            Analyzer definitions, declared with @AnalyzerDef and @NormalizerDef

            +
            • +
          • +

            Dynamic selection of analyzers based on a discriminator, declared with @AnalyzerDiscriminator

            +
            • +
          • +

            Index time boosting, declared as an attribute of the @Field annotation

            +
            • +
          • +

            Definition of a default analyzer, either using the configuration property hibernate.search.analyzer or using the @Analyzer annotation

            +
            • +
          • +

            indexNullAs, used as an attribute in the @Field declaration

            +
            • +
          • +

            The configuration hibernate.search.index_uninverting_allowed, that allows regular @Field to be sortable by un-inverting them at runtime

            +
            • +
          +
          +
          • +
        +
        +
        +
        +
        +
        +

        1.9.8. ThreadFactoryConfiguration changes

        +
        +

        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.

        +
        +
        +
        +

        1.9.9. Persistence

        +
        +
        Single File Store
        +
        +

        The <file-store relative-to="""> attribute has been removed. This attribute will be ignored in pre 11.0 schemas with +only the path attribute being taking into account when configuring the stores location.

        +
        +
        +
        +
        ClusterLoader
        +
        +

        The ClusterLoader has been deprecated and will be removed in a future release with no direct replacement.

        +
        +
        +
        +
        +

        1.9.10. HotRod

        +
        +

        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.

        +
        +
        +
        +

        1.9.11. Memory configuration changes

        +
        +
          +
        • +

          The BINARY storage has been deprecated, and will no longer store primitives and String mixed with byte[], but only byte[].

          +
          • +
        • +

          The child elements <object>, <binary> and <off-heap> are also deprecated. The following config changes should be done:

          +
          +
            +
          • +

            On heap storage:

            +
            • +
          +
          +
          • +
        +
        +
        +
        +
        <!--  10.1 -->
+<memory>
+   <object size="1000000" strategy="REMOVE"/>
+</memory>
        +
        +
        +
        +
        +
        <!--  11.0 -->
+<memory max-count="1000000" when-full="REMOVE"/>
        +
        +
        +
        +
          +
        • +

          Binary, on heap storage:

          +
          • +
        +
        +
        +
        +
        <!--  10.1 -->
+<cache>
+   <memory>
+      <binary size="500000000" strategy="EXCEPTION" eviction="MEMORY"/>
+   </memory>
+</cache>
        +
        +
        +
        +
        +
        <!--  11.0 -->
+<cache>
+   <!-- Or any other binary format -->
+   <encoding media-type="application/x-protostream"/>
+   <!-- Sizes are human-readable, e.g.: "1 GB", "0.5TB" -->
+   <memory max-size="500 MB" when-full="EXCEPTION"/>
+</cache>
        +
        +
        +
        +
          +
        • +

          Off-heap:

          +
          • +
        +
        +
        +
        +
        <!--  10.1 -->
+<cache>
+   <memory>
+      <off-heap size="10000000" eviction="COUNT"/>
+   </memory>
+</cache>
        +
        +
        +
        +
        +
        <!--  11.0 -->
+<memory storage="OFF_HEAP" max-count="10000000"/>
        +
        +
        +
        +
          +
        • +

          Due to the changes above, cache configurations serialized to XML or JSON (for example, when using REST) will always be in the new format.

          +
          • +
        +
        +
        +
        +

        1.9.12. Encoding in Server Caches

        +
        +
          +
        • +

          Server caches should configure the MediaType for keys and values, or else a WARN will be logged. +Usage of operations that require data conversion or indexing will not be supported for caches without encoding +configuration in a future version. These operations include search, task execution, remote filters/converter/listeners, +REST/Hot Rod reading/writing in different data formats

          +
          • +
        +
        +
        +
        +

        1.9.13. Security

        +
        +
        Server security
        +
        +

        The server is now secure by default. Use the user-tool to add users or remove the security realm attribute from the endpoint to allow anonymous connections.

        +
        +
        +
        +
        Cache authorization roles
        +
        +

        If you do not explicitly specify roles when enabling cache authorization, all roles declared in the global configuration apply.

        +
        +
        +
        +
        +

        1.9.14. REST

        +
        +
          +
        • +

          REST API calls that have the extra URL parameter ?action to perform operations with side effects now also +support the POST method (returning 200 when the response has content or 204 otherwise). +Support for using GET method on those calls will be removed in a future version.

          +
          • +
        +
        +
        +
        +
        +

        1.10. Upgrading from 10.0 to 10.1 and 10.0 to 11.0

        +
        +

        1.10.1. Maximum Idle Timeouts with Clustered Cache Modes

        +
        +

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

        +
        +
        + + + + + +
        + + +
        +
          +
        • +

          Cache.get() calls do not return until the touch commands complete. This +synchronous behavior increases latency of client requests and reduces +performance.

          +
          • +
        • +

          Maximum idle expiration, max-idle, does not currently work with entries +stored in off-heap memory.

          +
          • +
        • +

          Likewise, max-idle does not work if caches use cache stores as a persistence +layer.

          +
          • +
        +
        +
        +
        +
        +

        See Maximum Idle Expiration for complete details.

        +
        +
        +
        +
        +

        1.11. Upgrading from 10.0 to 10.1

        +
        +

        1.11.1. REST Store

        +
        +

        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.

        +
        +
        +
        +

        1.11.2. Infinispan Lucene Directory is deprecated

        +
        +

        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:

        +
        +
        +
        +
        <distributed-cache name="default">
+    <indexing index="PRIMARY_OWNER">
+        <property name="default.indexmanager">near-real-time</property>
+        <property name="default.indexBase">/opt/infinispan/server/data/indexes</property>
+    </indexing>
+</distributed-cache>
        +
        +
        +
        +

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

        +
        +
        +
        +

        1.11.3. Security role mappers and audit loggers

        +
        +

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

        +
        +
        +
          +
        • +

          org.infinispan.security.impl.CommonNameRoleMapper ⇒ org.infinispan.security.mappers.CommonNameRoleMapper

          +
          • +
        • +

          org.infinispan.security.impl.ClusterRoleMapper ⇒ org.infinispan.security.mappers.ClusterRoleMapper

          +
          • +
        • +

          org.infinispan.security.impl.IdentityRoleMapper ⇒ org.infinispan.security.mappers.IdentityRoleMapper

          +
          • +
        +
        +
        +

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

        +
        +
        +
          +
        • +

          org.infinispan.security.impl.LoggingAuditLogger ⇒ org.infinispan.security.audit.LoggingAuditLogger

          +
          • +
        • +

          org.infinispan.security.impl.NullAuditLogger ⇒ org.infinispan.security.audit.NullAuditLogger

          +
          • +
        +
        +
        +
        +

        1.11.4. Memcached protocol server is deprecated

        +
        +

        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.

        +
        +
        +
        +

        1.11.5. Hot Rod client default mechanism changed to SCRAM-SHA-512

        +
        +

        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.

        +
        +
        +
        +

        1.11.6. Transactions

        +
        +

        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,

        +
        +
        +
        +
        +

        1.12. Upgrading from 9.4 to 10.0

        +
        +

        1.12.1. Marshalling

        +
        +

        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.

        +
        +
        +
        Externalizer Deprecations
        +
        +

        The following interfaces/annotations have been deprecated as a consequence of the marshalling refactoring:

        +
        +
        + +
        +
        +

        For cluster communication any configured Externalizer's +are still utilised to marshall objects, however they are ignored when persisting data to cache stores unless the +JBossUserMarshaller is explicitly configured +via the global SerializationConfiguration.

        +
        +
        +

        It’s highly recommended to migrate from the old Externalizer and JBoss marshalling approach to the new ProtoStream based +marshalling, as the interfaces listed above and the JBossUserMarshaller implementation will be removed in future versions.

        +
        +
        +
        +
        Store Migration
        +
        +

        Unfortunately, the extensive marshalling changes mean that the binary format used by Infinispan stores in 9.4.x is no +longer compatible with 10.0.x. Therefore, it’s necessary for any existing stores to be migrated to the new format via +the StoreMigrator tool.

        +
        +
        + + + + + +
        + + +Whilst we regret that 9.4.x stores are no longer binary compatible, these extensive changes should ensure binary +compatibility across future major versions. +
        +
        +
        +
        +
        Store Defaults
        +
        +

        Stores now default to being segmented if the property is not configured. Some stores do not support +being segmented, which will result in a configuration exception being thrown at startup. The moving forward +position is to use segmented stores when possible to increase cache wide performance and reduce memory +requirements for various operations including state transfer.

        +
        +
        +

        The file based stores (SingleFileStore and SoftIndexFileStore) both support being segmented, but their +current implementation requires opening file descriptors based on how many segments there are. This may +cause issues in some configurations and users should be aware. Infinispan will print a single WARN message +when such a configuration is found.

        +
        +
        +
        +
        +

        1.12.2. CacheContainterAdmin

        +
        +

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

        +
        +
        +
        +

        1.12.3. Hot Rod 3.0

        +
        +

        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.

        +
        +
        +
        +

        1.12.4. Total Order transaction protocol is deprecated

        +
        +

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

        +
        +
        +
        +

        1.12.5. Removed the infinispan.server.hotrod.workerThreads system property

        +
        +

        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.

        +
        +
        +
        +

        1.12.6. Removed AtomicMap and FineGrainedAtomicMap

        +
        +

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

        +
        +
        +
        +

        1.12.7. Removed Delta and DeltaAware

        +
        +

        The previously deprecated Delta and DeltaAware interfaces have been removed.

        +
        +
        +
        +

        1.12.8. Removed compatibility mode

        +
        +

        The previously deprecated Compatibility Mode has been removed.

        +
        +
        +
        +

        1.12.9. Removed the implicit default cache

        +
        +

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

        +
        +
        +
        +

        1.12.10. Removed DistributedExecutor

        +
        +

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

        +
        +
        +
        +

        1.12.11. Removed the Tree module

        +
        +

        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.

        +
        +
        +
        +

        1.12.12. The JDBC PooledConnectionFactory now utilises Agroal

        +
        +

        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.

        +
        +
        +
        +

        1.12.13. XML configuration changes

        +
        +

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

        +
        +
        +
          +
        • +

          <eviction> - replaced with memory

          +
          • +
        • +

          <versioning> - automatically enabled

          +
          • +
        • +

          <data-container> - no longer customizable

          +
          • +
        • +

          deadlock-detection-spin - always disabled

          +
          • +
        • +

          write-skew - enabled automatically

          +
          • +
        +
        +
        +

        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.

        +
        +
        +
        +

        1.12.14. RemoteCache Changes

        +
        +
        Marshalling Changes
        +
        +

        The default marshaller is no longer GenericJbossMarshaller. We now utilise the ProtoStream +library as the default. If Java Serialization is required by clients, we strongly recommend utilising the +link:JavaSerializationMarshaller instead. +However if the GenericJbossMarshaller must be used, it’s necessary to add the org.infinispan:infinispan-jboss-marshalling +artifact to your client’s classpath and for the GenericJbossMarshaller to be configured as the marshaller.

        +
        +
        +
        +
        The getBulk methods have been removed
        +
        +

        The getBulk method is an expensive method as it requires holding all keys in memory at once and requires a possibly very single result +to populate it. The new retrieveEntries, entrySet, keySet and values methods handle this in a much more efficient way. Therefore the +getBulk methods have been removed in favor of them.

        +
        +
        +
        +
        +

        1.12.15. Persistence changes

        +
        +
          +
        • +

          File-based cache stores (SingleFileStore, SoftIndexFileStore, RocksDBStore) filesystem layout has been normalized so that they will use the GlobalStateConfiguration persistent location as a default location. Additionally, all stores will now use the cache name as part of the data file/directory naming allowing multiple stores to avoid conflicts and ambiguity.

          +
          • +
        • +

          The CLI loader (infinispan-persistence-cli) has been removed.

          +
          • +
        • +

          The LevelDB store (infinispan-cachestore-leveldb) has been removed. Use the RocksDB store instead, as it is fully backwards compatible.

          +
          • +
        • +

          The deprecated singleton store configuration option and the wrapper class SingletonCacheWriter have been removed.

          +
          +

          Using shared=true is enough, as only the primary owner of each key will write to a shared store.

          +
          +
          • +
        +
        +
        +
        +

        1.12.16. Client/Server changes

        +
        +
          +
        • +

          The Hot Rod client and server only support protocol versions 2.0 and higher. Support for Hot Rod versions 1.0 to 1.3 has been dropped.

          +
          • +
        +
        +
        +
        +

        1.12.17. SKIP_LISTENER_NOTIFICATION flag

        +
        +

        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.

        +
        +
        +
        +

        1.12.18. performAsync header removed from REST

        +
        +

        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.

        +
        +
        +
        +

        1.12.19. REST status code change

        +
        +

        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.

        +
        +
        +
        +

        1.12.20. Default JGroups stacks in the XML configuration

        +
        +

        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.

        +
        +
        +
        +

        1.12.21. JGroups legacy S3_PING replaced with aws.S3_PING

        +
        +

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

        +
        +
        +
        +

        1.12.22. Cache and Cache Manager Listeners can now be configured to be non blocking

        +
        +

        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.

        +
        +
        +
        +

        1.12.23. Distributed Streams operations no longer support null values

        +
        +

        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.

        +
        +
        +
        +

        1.12.24. Removed the infinispan-cloud module

        +
        +

        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.

        +
        +
        +
        +

        1.12.25. Removed experimental flag GUARANTEED_DELIVERY

        +
        +

        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.

        +
        +
        +
        +

        1.12.26. Cache Health

        +
        +

        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.

        +
        +
        +
        +

        1.12.27. Multi-tenancy

        +
        +

        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.

        +
        +
        +
        +

        1.12.28. OffHeap Automatic Resizing

        +
        +

        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.

        +
        +
        +
        +

        1.12.29. Deprecated methods from DataContainer removed

        +
        +

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

        +
        +
        +
        +
        +

        1.13. Upgrading from 9.3 to 9.4

        +
        +

        1.13.1. Client/Server changes

        +
        +
        Compatibility mode deprecation
        +
        +

        Compatibility mode has been deprecated and will be removed in the next Infinispan version.

        +
        +
        +

        To use a cache from multiple endpoints, it is recommended to store data in binary format and to configure the MediaType for keys and values.

        +
        +
        +

        If storing data as unmarshalled objects is still desired, the equivalent of compatibility mode is to configure keys and values to store object content:

        +
        +
        +
        +
        <encoding>
+   <key media-type="application/x-java-object"/>
+   <value media-type="application/x-java-object"/>
+</encoding>
        +
        +
        +
        +
        +
        Memcached storage
        +
        +

        For better interoperability between endpoints, the Memcached server no longer stores keys as java.lang.String, but as UTF-8 byte[].

        +
        +
        +

        If using memcached, it’s recommended to run a rolling upgrade from 9.3 to store data in the new format, or reload the data in the cache.

        +
        +
        +
        +
        Scripts Response
        +
        +

        Distributed scripts with text-based data type no longer return null when the result from each server is null. The response is now a JSON array with each individual result, e.g. "[null, null]"

        +
        +
        +
        +
        WebSocket endpoint removal
        +
        +

        The WebSocket endpoint has been unmaintained for several years. It has been removed.

        +
        +
        +
        +
        Hot Rod client connection pool properties
        +
        +

        Since the Hot Rod client was overhauled in 9.2, the way the connection pool configuration is handled has changed. +Infinispan 9.4 introduces a new naming scheme for the connection pool properties which deprecates the old commons-pool +names. For a complete reference of the available configuration options for the properties file please refer to +remote client configuration javadoc.

        +
        +
        +
        +
        Server thread pools
        +
        +

        The threads that handle the child Netty event loops have been renamed from *-ServerWorker to *-ServerIO

        +
        +
        +
        +
        +

        1.13.2. Persistence Changes

        +
        +
        Shared and Passivation
        +
        +

        A store cannot be configured as both shared and having passivation enabled. +Doing so can cause data inconsistencies as there is no way to synchronize +data between all the various nodes. As such this configuration will now +cause a startup exception. Please update your configuration as appropriate.

        +
        +
        +
        +
        +

        1.13.3. Query changes

        +
        +
        AffinityIndexManager
        +
        +

        The default number of shards is down to 4, it was previously equals to the number of segments in the cache.

        +
        +
        +
        +
        +
        +

        1.14. Upgrading from 9.2 to 9.3

        +
        +

        1.14.1. AdvancedCacheLoader changes

        +
        +

        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.

        +
        +
        +
        +

        1.14.2. Partition Handling Configuration

        +
        +

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

        +
        +
        +
        +

        1.14.3. Stat Changes

        +
        +

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

        +
        +
        +
        +

        1.14.4. Event log changes

        +
        +

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

        +
        +
        +
        +

        1.14.5. Max Idle Expiration Changes

        +
        +

        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.

        +
        +
        +
        +

        1.14.6. WildFly Modules

        +
        +

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

        +
        +
        +
        +

        1.14.7. Deserialization Allow list

        +
        +

        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:

        +
        +
        +
        +
        // Comma separated list of fully qualified class names
+-Dinfinispan.deserialization.allowlist.classes=java.time.Instant,com.myclass.Entity
+
+// Regex expression
+-Dinfinispan.deserialization.allowlist.regexps=.*
        +
        +
        +
        +
        +
        +

        1.15. Upgrading from 9.0 to 9.1

        +
        +

        1.15.1. Kubernetes Ping changes

        +
        +

        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.

        +
        +
        +
        +

        1.15.2. Stat Changes

        +
        +

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

        +
        +
        +
        +

        1.15.3. (FineGrained)AtomicMap reimplemented

        +
        +

        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.

        +
        +
        +
        +

        1.15.4. RemoteCache keySet/entrySet/values

        +
        +

        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 an in-memory local set such as

        +
        +
        +
        +
        Set<K> keysCopy = remoteCache.keySet().stream().collect(Collectors.toSet());
        +
        +
        +
        +
        +

        1.15.5. DeltaAware deprecated

        +
        +

        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.

        +
        +
        +
        +

        1.15.6. Infinispan Query Configuration

        +
        +

        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.

        +
        +
        +
        +

        1.15.7. Store Batch Size Changes

        +
        +

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

        +
        +
        +
        +

        1.15.8. Partition Handling changes

        +
        +

        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.

        +
        +
        +
        +
        +

        1.16. Upgrading from 8.x to 9.0

        +
        +

        1.16.1. Default transaction mode changed

        +
        +

        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:

        +
        +
        +
          +
        • +

          write-skew: as said, it is automatically enabled.

          +
          • +
        • +

          <versioning> and its attributes. It is automatically enabled and configured when needed.

          +
          • +
        +
        +
        +
        +

        1.16.2. Removed eagerLocking and eagerLockingSingleNode configuration settings

        +
        +

        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.

        +
        +
        +
        +

        1.16.3. Removed async transaction support

        +
        +

        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:

        +
        +
        +
          +
        • +

          TransactionConfigurationBuilder.syncCommitPhase(boolean)

          +
          • +
        • +

          TransactionConfigurationBuilder.syncRollbackPhase(boolean)

          +
          • +
        +
        +
        +
        + +
        +

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

        +
        +
        +
          +
        • +

          DummyBaseTransactionManager: replaced by EmbeddedBasedTransactionManager;

          +
          • +
        • +

          DummyNoXaXid and DummyXid: replaced by EmbeddedXid;

          +
          • +
        • +

          DummyTransaction: replaced by EmbeddedTransaction;

          +
          • +
        • +

          DummyTransactionManager: replaced by EmbeddedTransactionManager;

          +
          • +
        • +

          DummyTransactionManagerLookup and RecoveryDummyTransactionManagerLookup: replaced by EmbeddedTransactionManagerLookup;

          +
          • +
        • +

          DummyUserTransaction: replaced by EmbeddedUserTransaction;

          +
          • +
        +
        +
        +
        +

        1.16.5. Clustering configuration changes

        +
        +

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

        +
        +
        +
        +

        1.16.6. Default Cache changes

        +
        +

        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.

        +
        +
        +
        +

        1.16.7. Marshalling Enhancements and Store Compatibility

        +
        +

        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.

        +
        +
        +
        +

        1.16.8. New Cloud module for library mode

        +
        +

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

        +
        +
        +
        +

        1.16.9. Entry Retriever is now removed

        +
        +

        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 can be marshalled.

        +
        +
        +
        +

        1.16.10. Map / Reduce is now removed

        +
        +

        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.

        +
        +
        +
        +

        1.16.11. Spring 4 support is now removed

        +
        +

        Spring 4 is no longer supported.

        +
        +
        +
        +

        1.16.12. Function classes have moved packages

        +
        +

        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.

        +
        +
        +
        +

        1.16.13. SegmentCompletionListener interface has moved

        +
        +

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

        +
        +
        +
        +

        1.16.14. Spring module dependency changes

        +
        +

        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:

        +
        +
        +
        +
        <dependencies>
+   <dependency>
+      <groupId>org.infinispan</groupId>
+      <artifactId>infinispan-embedded</artifactId>
+   </dependency>
+   <dependency>
+      <groupId>org.infinispan</groupId>
+      <artifactId>infinispan-spring5-embedded</artifactId>
+   </dependency>
+   <dependency>
+      <groupId>org.springframework</groupId>
+      <artifactId>spring-context</artifactId>
+   </dependency>
+   <dependency>
+      <groupId>org.springframework.session</groupId>
+      <artifactId>spring-session</artifactId>
+   </dependency>
+</dependencies>
        +
        +
        +
        +

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

        +
        +
        +
        +

        1.16.15. Total order executor is now removed

        +
        +

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

        +
        +
        +
        +

        1.16.16. HikariCP is now the default implementation for JDBC PooledConnectionFactory

        +
        +

        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.

        +
        +
        +
        +

        1.16.17. RocksDB in place of LevelDB

        +
        +

        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.

        +
        +
        +
        +

        1.16.18. JDBC Mixed and Binary stores removed

        +
        +

        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.

        +
        +
        +
        +

        1.16.19. @Store Annotation Introduced

        +
        +

        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.

        +
        +
        +
        +

        1.16.20. Server authentication changes

        +
        +

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

        +
        +
        +
        +

        1.16.21. Package org.infinispan.util.concurrent.jdk8backported has been removed

        +
        +
        Moved classes
        +
        +

        Classes regarding EntrySizeCalculator have now been moved down to the org.infinispan.util package.

        +
        +
        +
        +
        Removed classes
        +
        +

        The ConcurrentHashMapV8 classes and their supporting classes have all been removed. The +CollectionFactory#makeBoundedConcurrentMap method should be used if you desire to have a +bounded ConcurrentMap.

        +
        +
        +
        +
        +

        1.16.22. Store as Binary is deprecated

        +
        +

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

        +
        +
        +
        +

        1.16.23. DataContainer collection methods are deprecated

        +
        +

        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.

        +
        +
        +
        +
        +

        1.17. Upgrading from 8.1 to 8.2

        +
        +

        1.17.1. Entry Retriever is deprecated

        +
        +

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

        +
        +
        +
        +

        1.17.2. Map / Reduce is deprecated

        +
        +

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

        +
        +
        +
        +
        +

        1.18. Upgrading from 8.x to 8.1

        +
        +

        1.18.1. Packaging changes

        +
        +
        CDI module split
        +
        +

        CDI module (GroupId:ArtifactId org.infinispan:infinispan-cdi) has been split into org.infinispan:infinispan-cdi-embedded and org.infinispan:infinispan-cdi-remote. Please make sure that you use proper artifact.

        +
        +
        +
        +
        Spring module split
        +
        +

        Spring module (GroupId:ArtifactId org.infinispan:infinispan-spring5) has been split into org.infinispan:infinispan-spring5-embedded and org.infinispan:infinispan-spring5-remote. Please make sure that you use proper artifact.

        +
        +
        +
        +
        +

        1.18.2. Spring 3 support is deprecated

        +
        +

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

        +
        +
        +
        +
        +

        1.19. Upgrading from 7.x to 8.0

        +
        +

        1.19.1. Configuration changes

        +
        +
        Removal of Async Marshalling
        +
        +

        Async marshalling has been entirely dropped since it was never reliable enough. The "async-marshalling" attribute has been removed from the 8.0 XML schema and will be ignored when parsing 7.x configuration files. The programmatic configuration methods related to asyncMarshalling/syncMarshalling are now deprecated and have no effect aside from producing a WARN message in the logs.

        +
        +
        +
        +
        Re-enabling of isolation level configurations in server
        +
        +

        Because of the inability to configure write skew in the server, the isolation level attribute was ignored and defaulted to READ_COMMITTED. Now, when enabling REPEATABLE_READ together with optimistic locking, write skew is enabled by default in local and synchronous configurations.

        +
        +
        +
        +
        Subsystem renaming in server
        +
        +

        In order to avoid conflict and confusion with the similar subsystems in WildFly, we have renamed the following subsystems in server: +* infinispan → datagrid-infinispan +* jgroups → datagrid-jgroups +* endpoint → datagrid-infinispan-endpoint

        +
        +
        +
        +
        Server domain mode
        +
        +

        We no longer support the use of standalone mode for running clusters of servers. Domain mode (bin/domain.sh) should be used instead.

        +
        +
        +
        +
        +
        +

        1.20. Upgrading from 6.0 to 7.0

        +
        +

        1.20.1. API Changes

        +
        +
        Cache Loader
        +
        +

        To be more inline with JCache and java.util.collections interfaces we have changed the first argument type for the CacheLoader.load and CacheLoader.contains methods to be Object from the generic type K.

        +
        +
        +
        +
        Cache Writer
        +
        +

        To be more inline with JCache and java.util.collections interfaces we have changed the first argument type for the CacheWriter.delete method to be Object from type K.

        +
        +
        +
        +
        Filters
        +
        +

        Over time Infinispan added 2 interfaces with identical names and almost identical methods. The org.infinispan.notifications.KeyFilter and org.infinispan.persistence.spi.AdvancedCacheLoader$KeyFilter interfaces.

        +
        +
        +

        Both of these interfaces are used for the sole purpose of filtering an entry by its given key. Infinispan 7.0 has also introduced the KeyValueFilter which is similar to both but also can filter on the entries value and/or metadata.

        +
        +
        +

        As such all of these classes have been moved into a new package org.infinispan.filter and all of their related helper classes.

        +
        +
        +

        The new org.infinispan.filter.KeyFilter interface has replaced both of the previous interfaces and all previous references use the new interface.

        +
        +
        +
        +
        +

        1.20.2. Declarative configuration

        +
        +

        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.

        +
        +
        +
        +
        +

        1.21. Upgrading from 5.3 to 6.0

        +
        +

        1.21.1. Declarative configuration

        +
        +

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

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

        1.21.2. Deprecated API removal

        +
        +
          +
        • +

          Class org.infinispan.persistence.remote.wrapperEntryWrapper.

          +
          • +
        • +

          Method ObjectOutput startObjectOutput(OutputStream os, boolean isReentrant) from class +org.infinispan.commons.marshall.StreamingMarshaller.

          +
          • +
        • +

          Method CacheEntry getCacheEntry(Object key, EnumSet<Flag> explicitFlags, ClassLoader explicitClassLoader) from class +org.infinispan.AdvancedCache. +Please use instead: AdvanceCache.withFlags(Flag…​ flags).with(ClassLoader classLoader).getCacheEntry(K key).

          +
          • +
        • +

          Method AtomicMap<K, V> getAtomicMap(Cache<MK, ?> cache, MK key, FlagContainer flagContainer) from class +org.infinispan.atomic.AtomicMapLookup. +Please use instead AtomicMapLookup.getAtomicMap(cache.getAdvancedCache().withFlags(Flag…​ flags), MK key).

          +
          • +
        • +

          Package org.infinispan.config (and all methods involving the old configuration classes). +All methods removed has an overloaded method which receives the new configuration classes as parameters.

          +
          • +
        +
        +
        + + + + + +
        + + +This only affects the programmatic configuration. +
        +
        +
        +
          +
        • +

          Class org.infinispan.context.FlagContainer.

          +
          • +
        • +

          Method boolean isLocal(Object key) from class org.infinispan.distribution.DistributionManager. +Please use instead DistributionManager.getLocality(Object key).

          +
          • +
        • +

          JMX operation void setStatisticsEnabled(boolean enabled) from class org.infinispan.interceptors.TxInterceptor +Please use instead the statisticsEnabled attribute.

          +
          • +
        • +

          Method boolean delete(boolean synchronous) from class org.infinispan.io.GridFile. +Please use instead GridFile.delete().

          +
          • +
        • +

          JMX attribute long getLocallyInterruptedTransactions() from class +org.infinispan.util.concurrent.locks.DeadlockDetectingLockManager.

          +
          • +
        +
        +
        +
        +
        +

        1.22. Upgrading from 5.2 to 5.3

        +
        +

        1.22.1. Declarative configuration

        +
        +

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

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

        1.23. Upgrading from 5.1 to 5.2

        +
        +

        1.23.1. Declarative configuration

        +
        +

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

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

        1.23.2. Transaction

        +
        +

        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:

        +
        +
        +
        +
        <transaction useSynchronization="false">
+   <recovery enabled="false"/>
+</transaction>
        +
        +
        +
        +

        or the programmatic configuration equivalent:

        +
        +
        +
        +
        ConfigurationBuilder builder = new ConfigurationBuilder().
+   transaction().useSynchronization(false).recovery().enabled(false);
        +
        +
        +
        +
        +

        1.23.3. Cache Loader and Store configuration

        +
        +

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

        +
        +
        +
        +

        1.23.4. Virtual Nodes and Segments

        +
        +

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

        +
        +
        +
        +
        +

        1.24. Upgrading from 5.0 to 5.1

        +
        +

        1.24.1. API

        +
        +

        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.

        +
        +
        +
        WontCompile.java
        +
        +
        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:

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

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

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

        1.24.2. Eviction and Expiration

        +
        +
          +
        • +

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

          +
          • +
        +
        +
        +
        +
        <expiration wakeUpInterval="60000" />
        +
        +
        +
        +

        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.

        +
        +
        +
        +

        1.24.3. Transactions

        +
        +
          +
        • +

          A cache marked as TRANSACTIONAL cannot be accessed outside 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.

          +
          • +
        • +

          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.

          +
          • +
        +
        +
        +
        +

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

        +
        +
        +
        +

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

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

          The old javabean 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 https://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 https://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.

        +
        +
        +
        +

        1.24.6. Flags and ClassLoaders

        +
        +

        The Flags and ClassLoader 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.

        +
        +
        +
        +

        1.24.7. JGroups Bind Address

        +
        +

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

        +
        +

    @@ -1288,7 +4780,7 @@

    -Table 1. Cache Store Type Property +Table 2. Cache Store Type Property @@ -1318,7 +4810,7 @@

    -Table 2. Common Properties +Table 3. Common Properties @@ -1370,7 +4862,7 @@

    -Table 3. JDBC Properties +Table 4. JDBC Properties @@ -1502,7 +4994,7 @@

    -Table 4. RocksDB Properties +Table 5. RocksDB Properties @@ -1538,7 +5030,7 @@

    -Table 5. SingleFileStore Properties +Table 6. SingleFileStore Properties @@ -1568,7 +5060,7 @@

    -Table 6. SoftIndexFileStore Properties +Table 7. SoftIndexFileStore Properties @@ -1636,7 +5128,7 @@

    -Last updated 2025-01-29 12:58:56 UTC +Last updated 2025-01-30 11:00:15 UTC
    diff --git a/docs/dev/titles/xsite/xsite.html b/docs/dev/titles/xsite/xsite.html index 2d8969ba2d..229776a2b0 100644 --- a/docs/dev/titles/xsite/xsite.html +++ b/docs/dev/titles/xsite/xsite.html @@ -2878,7 +2878,7 @@