SupportConsoleDevelopersStart a trialContact

Chapter 4. Migrating to Data Grid 8 APIs

Find changes to Data Grid APIs that affect migration to Data Grid 8.

API deprecations and removals

In addition to details in this section, you should also review API deprecations and removals.

See Data Grid Deprecated Features and Functionality (Red Hat Knowledgebase).

4.1. REST API

Data Grid 7.x used REST API v1 which is replaced with REST API v2 in Data Grid 8.

The default context path for REST API v2 is <server_hostname>:11222/rest/v2/. You must update any clients or scripts to use REST API v2.

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

REST operations PUT, POST and DELETE methods now return status 204 (No content) instead of 200 if the request does not return resources.

Additional resources

4.1.1. REST API changes in 8.3

Data Grid 8.3 includes the following changes to the REST API:

Re-indexing caches

The mass-index operation to re-index Data Grid caches is now deprecated. Update your clients to use reindex instead, as in the following example: 

/v2/caches/<cacheName>/search/indexes?action=reindex
Rolling upgrade operations

The following operation is now deprecated: 

POST /v2/caches/<cacheName>?action=disconnect-source

Use the source-connection operation instead: 

DELETE /v2/caches/<cacheName>/rolling-upgrade/source-connection

4.2. Query API

Data Grid 8 brings an updated Query API that is easier to use and has a lighter design. You get more efficient query performance with better results when searching across values in distributed caches, in comparison with Data Grid 7.x.

Note

Because the Data Grid 8 Query API has gone through considerable refactoring, there are several features and functional resources that are now deprecated.

This topic focuses on changes that you need to make to your configuration when migrating from a previous version. Those changes should include planning to remove all deprecated interfaces, methods, or other configuration.

See the Data Grid Deprecations and Removals (Red Hat Knowledgebase) for the complete list of deprecated features and functionality.

Indexing Data Grid caches

The Data Grid Lucene Directory, the InfinispanIndexManager and AffinityIndexManager index managers, and the Infinispan Directory provider for Hibernate Search are deprecated in 8.0 and removed in 8.1.

The auto-config attribute is deprecated in 8.1 and planned for removal.

The index() method that configures the index mode configuration is deprecated. When you enable indexing in your configuration, Data Grid automatically chooses the best way to manage indexing.

Important

Several indexing configuration values are no longer supported and result in fatal configuration errors if you include them.

You should make the following changes to your configuration:

  • Change .indexing().index(Index.NONE) to indexing().enabled(false)
  • Change all other enum values as follows: indexing().enabled(true)

Declaratively, you do not need to specify enabled="true" if your configuration contains other indexing configuration elements. However, you must call the enabled() method if you programmatically configure indexing. Likewise Data Grid configuration in JSON format must explicitly enable indexing, for example: 

"indexing": {
      "enabled": "true"
      ...
      },

Indexed types

You must declare all indexed types in the indexing configuration or Data Grid logs warning messages when undeclared types are used with indexed caches. This requirement applies to both Java classes and Protobuf types.

Enabling indexing in Data Grid 8

  • Declaratively 

    <distributed-cache name="my-cache">
   <indexing>
     <indexed-entities>
       <indexed-entity>com.acme.query.test.Car</indexed-entity>
       <indexed-entity>com.acme.query.test.Truck</indexed-entity>
     </indexed-entities>
   </indexing>
</distributed-cache>

  • Programmatically 

    import org.infinispan.configuration.cache.*;

ConfigurationBuilder config=new ConfigurationBuilder();
config.indexing().enable().addIndexedEntity(Car.class).addIndexedEntity(Truck.class);

Querying values in caches

The org.infinispan.query.SearchManager interface is deprecated in Data Grid 8 and no longer supports Lucene and Hibernate Search native objects.

Removed methods

  • .getQuery() methods that take Lucene Queries. Use the alternative methods that take Ickle queries from the org.infinispan.query.Search entry point instead.

    Likewise it is no longer possible to specify multiple target entities classes when calling .getQuery(). The Ickle query string provides entities instead.

  • .buildQueryBuilderForClass() that builds Hibernate Search queries directly. Use Ickle queries instead.

The org.infinispan.query.CacheQuery interface is also deprecated. You should obtain the org.infinispan.query.dsl.Query interface from the Search.getQueryFactory() method instead.

Note that instances of org.infinispan.query.dsl.Query no longer cache query results and allow queries to be re-executed when calling methods such as list().

Entity mappings

You must now annotate fields that require sorting with @SortableField in all cases.

Additional resources

4.2.1. Query API changes in 8.2

Data Grid upgrades Hibernate and Apache Lucene libraries to improve performance and functionality for the Query API. As part of this upgrade, Data Grid introduces new indexing capabilities and removes several Hibernate and Lucene annotations.

Query statistics

Data Grid 8.2 exposes statistics for queries and indexes only if you enable statistics declaratively in the cache configuration as follows: 

<replicated-cache name="myReplicatedCache" statistics="true">
  <!-- Cache configuration goes here. -->
</replicated-cache>

Enabling statistics for queries and indexes through JMX is no longer possible.

Indexing Data Grid caches

Declaring indexed types

Data Grid 8.1 allowed undeclared types in the indexing configuration. As of Data Grid 8.2, you must declare all indexed types in the configuration. This requirement applies to both Java classes and Protobuf types. See the 8.1 migration details for more information on declaring indexed types.

Index manager

Data Grid 8.2 uses near-real-time as the default index manager and no longer requires configuration.

  • Data Grid 8.1: 

    <indexing>
  <property name="default.indexmanager">near-real-time</property>
</indexing>

  • Data Grid 8.2: 

    <indexing enabled="true"/>
Index reader and writer

Data Grid 8.2 introduces an index reader and an index writer, both of which are internal components for creating indexes.

To adapt your configuration, you should:

  1. Remove indexing configuration that uses the property element or .addProperty() method.

  2. Configure indexing behavior in one of the following ways:

    • Declaratively: Add the <index-reader> and <index-writer> elements.
    • Programmatically: Add the builder.indexing().reader() and builder.indexing().writer() methods.

Reader refresh

Use the refresh-interval attribute added in 8.2 to configure the refresh period for the index reader.

  • Data Grid 8.1: 

    <indexing>
  <property name="default.reader.async_refresh_period_ms">1000</property>
</indexing>

  • Data Grid 8.2: 

    <indexing>
  <index-reader refresh-interval="1000"/>
</indexing>

Writer commit interval

Use the commit-interval attribute added in 8.2 to configure the interval at which the index writer commits to index storage. In Data Grid 8.2 indexing is asynchronous by default and the default.worker.execution property is no longer used.

  • Data Grid 8.1: 

    <indexing>
   <property name="default.worker.execution">async</property>
   <property name="default.index_flush_interval">500</property>
</indexing>

  • Data Grid 8.2: 

    <indexing>
   <index-writer commit-interval="500"/>
</indexing>

Lucene index tuning properties

Data Grid 8.2 adds a ram-buffer-size attribute and an index-merge element with factor and max-size attributes that replace properties for tuning indexes.

  • Data Grid 8.1: 

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

  • Data Grid 8.2: 

    <indexing>
   <index-writer ram-buffer-size="256">
       <index-merge factor="30" max-size="1024"/>
   </index-writer>
</indexing>
Index storage

Data Grid 8.2 includes a storage attribute that replaces the property element configuration in previous versions. The storage attribute lets you configure whether to store indexes in JVM heap or on the host file system.

File system storage

  • Data Grid 8.1: 

    <indexing>
  <property name="default.directory_provider">filesystem</property>
  <property name="default.indexBase">${java.io.tmpdir}/baseDir</property>
</indexing>

  • Data Grid 8.2: 

    <indexing storage="filesystem" path="${java.io.tmpdir}/baseDir"/>

JVM heap storage

  • Data Grid 8.1: 

    <indexing>
 <property name="default.directory_provider">local-heap</property>
</indexing>

  • Data Grid 8.2: 

    <indexing storage="local-heap">
</indexing>
Adapting index properties

When migrating your indexing configuration to Data Grid 8.2, you should also make the following changes:

  • Remove the lucene_version property.

    Important

    Do not use indexes that you created with older Lucene versions with Data Grid 8.2.

    After you adapt your indexing configuration, you should rebuild the index when you start Data Grid for the first time to complete the migration to Data Grid 8.2.

  • Remove the default.sharding_strategy.nbr_of_shards property.
    This property is deprecated without a replacement.
  • Remove the infinispan.query.lucene.max-boolean-clauses property.
    As of Data Grid 8.2 you should set this as a JVM property.
Hibernate and Lucene annotations

For information about migrating Hibernate and Lucene annotations, such as @Field, @Indexed, @SortableField, and others, refer to the Annotation mapping section of the Hibernate Search Migration Guide.

Additional resources

4.2.2. Query API changes in 8.3

Data Grid 8.3 removes the IndexedQueryMode parameter. Data Grid automatically detects the optimal mode for querying caches and ignored this optional parameter in earlier versions.

Additional resources

4.2.3. Query API changes in 8.4

Data Grid native annotations

Data Grid 8.4 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 an 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. All annotations are copied as comments to the generated .proto files.

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

HS5 annotationsIndexing attributesData Grid 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 continue to be 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 sortable.

N/A

aggregable = true

@Basic, @Decimal, @Keyword

Performing aggregation operations by using the Hibernate Search 5 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.

Query efficiency

You can limit the number of returned results for a query instance by using 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 the performance of queries that don’t have an explicit limit set.

Additional resources

Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.