Chapter 4. Migrating to Data Grid 8 APIs
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 Data Grid REST API 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: Rolling upgrade operations The following operation is now deprecated: Use the source-connection operation instead: 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 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 Data Grid Query API Data Grid Deprecations and Removals 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: Remove indexing configuration that uses the property element or .addProperty() method. 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 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">USD{java.io.tmpdir}/baseDir</property> </indexing> Data Grid 8.2: <indexing storage="filesystem" path="USD{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 Data Grid Query API Data Grid Deprecations and Removals Hibernate Search Migration Guide: Annotation mapping 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 Querying Data Grid Caches Data Grid Query API Data Grid Deprecations and Removals 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 annotations Indexing attributes Data Grid native annotations Description @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 Querying Data Grid Caches Data Grid Query API
/v2/caches/<cacheName>/search/indexes?action=reindex POST /v2/caches/<cacheName>?action=disconnect-source DELETE /v2/caches/<cacheName>/rolling-upgrade/source-connection "indexing": { "enabled": "true" }, <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> import org.infinispan.configuration.cache.*; ConfigurationBuilder config=new ConfigurationBuilder(); config.indexing().enable().addIndexedEntity(Car.class).addIndexedEntity(Truck.class); <replicated-cache name="myReplicatedCache" statistics="true"> <!-- Cache configuration goes here. --> </replicated-cache> <indexing> <property name="default.indexmanager">near-real-time</property> </indexing> <indexing enabled="true"/> <indexing> <property name="default.reader.async_refresh_period_ms">1000</property> </indexing> <indexing> <index-reader refresh-interval="1000"/> </indexing> <indexing> <property name="default.worker.execution">async</property> <property name="default.index_flush_interval">500</property> </indexing> <indexing> <index-writer commit-interval="500"/> </indexing> <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> <indexing> <index-writer ram-buffer-size="256"> <index-merge factor="30" max-size="1024"/> </index-writer> </indexing> <indexing> <property name="default.directory_provider">filesystem</property> <property name="default.indexBase">USD{java.io.tmpdir}/baseDir</property> </indexing> <indexing storage="filesystem" path="USD{java.io.tmpdir}/baseDir"/> <indexing> <property name="default.directory_provider">local-heap</property> </indexing> <indexing storage="local-heap"> </indexing>