-
Language:
English
-
Language:
English
Chapter 3. Migrating to JBoss Data Grid 7.0
3.1. Product Changes
3.1.1. Library Mode Configuration Update
The XML schema for Library mode configurations has been changed to be more consistent with the remote client-server schema. This results in several changes that must be made to the configuration file.
To assist in these configurations a tool is provided in the library distribution. The following steps discuss using this tool to automatically convert existing infinispan configuration files to the latest supported schema.
Procedure: Windows Instructions for Using the Library Mode Configuration Converter
- Open a command prompt.
Navigate to the bin\ directory of the library distribution:
cd C:\path\to\jboss-datagrid-${jdg-version}-library\bin\- If any custom classes were referenced in the original configuration then the .jar files containing these classes must be placed in the C:\path\to\jboss-datagrid-${jdg-version}-library\ directory. If no custom classes were referenced then this step may be skipped.
Execute the config-converter.bat utility, passing in the name of the existing infinispan_6.0.xml configuration file and the destination as arguments:
config-converter C:\path\to\infinispan_6.0.xml C:\path\to\infinispan-new.xml
- Ensure that infinispan-new.xml has been created with the new Library mode configurations. This file may now be used in Library mode applications with JBoss Data Grid 7.0.
Procedure: Linux Instructions for Using the Library Mode Configuration Converter.
- Open a console to execute the following commands.
Navigate to the bin/ directory of the library distribution:
cd /path/to/jboss-datagrid-${jdg-version}-library/bin/- If any custom classes were referenced in the original configuration then the .jar files containing these classes must be placed in the /path/to/jboss-datagrid-${jdg-version}-library/ directory. If no custom classes were referenced then this step may be skipped.
Execute the config-converter.sh utility, passing in the name of the existing infinispan_6.0.xml configuration file and the destination as arguments:
./config-converter.sh /path/to/infinispan_6.0.xml /path/to/infinispan-new.xml
- Ensure that infinispan-new.xml has been created with the new Library mode configurations. This file may now be used in Library mode applications with JBoss Data Grid 7.0.
If no destination file is specified, such as infinispan-new.xml in the above examples, the utility will instead display the converted xml to the console.
3.1.2. CLI Commands
The following CLI commands have been changed for JBoss Data Grid 7.0:
-
clear- This command has been replaced byclearcache. -
help $COMMAND- Instead of executinghelpper command, each command now has a built in--helpflag that is used instead.
3.1.3. Server Managment
The default JBoss Data Grid server management port has been changed to 9990.
3.1.4. JGroups ENCRYPT Protocol Deprecated
The JGroups ENCRYPT protocol has been deprecated, and should be replaced with either the SYM_ENCRYPT or ASYM_ENCRYPT protocols. Both of these protocols must be placed directly under NAKACK2. Configuration details are provided in the Administration and Configuration Guide ; however, example configurations for each protocol are shown below:
SYM_ENCRYPT Configuration Example
<SYM_ENCRYPT sym_algorithm="AES"
encrypt_entire_message="true"
keystore_name="defaultStore.keystore"
store_password="changeit"
alias="myKey"/>
ASYM_ENCRYPT Configuration Example
<ASYM_ENCRYPT encrypt_entire_message="true"
sym_keylength="128"
sym_algorithm="AES/ECB/PKCS5Padding"
asym_keylength="512"
asym_algorithm="RSA"/>
3.2. Application Changes
3.2.1. NotifyingFuture replaced by CompletableFuture
The NotifyingFuture interface has been removed in JBoss Data Grid 7.0 and replaced with CompletableFuture. This class was replaced due to CompletableFuture being included as a standard class in Java 8, allowing for additional features such as chaining, implementing constructs such as conditionals, and timeouts to be utilized without introducing additional custom code.
Due to this change any applications utilizing NotifyingFuture will need to be replaced with CompletableFuture to function correctly with JBoss Data Grid 7.0.
3.2.2. JBoss Modules CDI Dependency
JBoss Modules CDI Dependencies
The package containing the CDI classes has changed. All of these classes have moved from org.infinispan.cdi to org.infinispan.cdi.embedded, and any applications utilizing CDI should have their imports updated to use the new packages.
Configuration of CDI/JCache
CDI Extensions have been split into two separate types of classes:
-
CDI Classes that begin with
Injectedbefore the classname, such asorg.infinispan.jcache.annotation.InjectedCacheResultInterceptor. These classes are intended for use in managed environments, such as JBoss EAP. -
CDI classes without
Injectedbefore the classname, such asorg.infinispan.jcache.annotation.CacheResultInterceptor- This class should be used in standalone environments.
3.2.3. Spring 3 support removed
Spring 3 support has been removed in JBoss Data Grid 7.0. Any applications will need to be rewritten to use Spring 4.
3.2.4. RemoteCache Deprecated Methods
The following methods have been deprecated in JBoss Data Grid 7.0:
-
remoteCache.getVersioned- This method has been replaced byremoteCache.getWithMetadata(Object). -
remoteCache.getBulk, getBulk(size)- Both of these methods have proven expensive for large data sets. TheremoteCache.retrieveEntries*methods offer a lazy, pull-style, approach which retrieves bulk data more efficiently.
3.2.5. Interceptors Deprecated
Support for custom interceptors is being deprecated in JBoss Data Grid 7.0. A new method of executing custom interceptors is expected to be introduced in JBoss Data Grid 7.1. In addition, the interceptor stack is part of JBoss Data Grid’s internal API, and is subject to change from release to release. Due to this it is not recommended to use custom interceptors directly from your application.
3.2.6. Map/Reduce replaced by Distributed Streams
Map/Reduce has been removed in JBoss Data Grid 7.0.0. This feature has been replaced by Distributed Streams, which were shown to have better performance.
3.2.7. Hibernate Search
3.2.7.1. Hibernate Search
The underlying Hibernate Search modules have been upgraded from 4.6 to 5.6, and as such there have been significant changes to this component. The following sections walk through all updates necessary to use the new version.
As the Hibernate Search modules have been updated, it is necessary to delete all existing indexes and rebuild the index, as indexes produced by previous versions are not compatible with the new version in use by JBoss Data Grid 7.0. Instructions for rebuilding the index are found in the Developer Guide .
3.2.7.2. Hibernate Search Class Name and Package Updates
Several classes have been relocated to a different package than their previous package; the following table includes the original class name and package along with the new location.
Table 3.1. Hibernate Search Class Package Updates
| JDG 6.x Location | JDG 7.0 Location |
|---|---|
| org.hibernate.search.engine.impl.SearchMappingBuilder | org.hibernate.search.engine.spi.SearchMappingBuilder |
| org.hibernate.search.Environment | org.hibernate.search.cfg.Environment |
| org.hibernate.search.FullTextFilter | org.hibernate.search.filter.FullTextFilter |
| org.hibernate.search.indexes.impl.DirectoryBasedIndexManager | org.hibernate.search.indexes.spi.DirectoryBasedIndexManager |
| org.hibernate.search.infinispan.impl.InfinispanDirectoryProvider | org.hibernate.search.infinispan.spi.InfinispanDirectoryProvider |
| org.hibernate.search.ProjectionConstants | org.hibernate.search.engine.ProjectionConstants |
| org.hibernate.search.SearchException | org.hibernate.search.exception.SearchException |
| org.hibernate.search.spi.MassIndexerFactory | org.hibernate.search.batchindexing.spi.MassIndexerFactory |
| org.hibernate.search.spi.SearchFactoryBuilder | org.hibernate.search.spi.SearchIntegratorBuilder |
| org.hibernate.search.spi.SearchFactoryIntegrator | org.hibernate.search.spi.SearchIntegrator |
| org.hibernate.search.Version | org.hibernate.search.engine.Version |
| org.apache.lucene.queryParser.QueryParser | org.apache.lucene.queryparser.classic.QueryParser |
Table 3.2. Hibernate Search Class Name Updates
| JDG 6.x Name | JDG 7.0 Name |
|---|---|
| SpatialMode.GRID | SpatialMode.HASH |
3.2.7.3. Hibernate Search Additions
The following additions have been made to the Hibernate Search modules:
-
A new method,
getShardIdentifiersForDeletion(), has been added toorg.hibernate.search.store.ShardIdentifierProvider. Any existing implementations which were not derived fromShardIdentifierProviderTemplateshould be updated. -
The Faceting engine has been significantly updated; however, a
@Facetor@Facetsannotation must be used on any fields intended for faceting.
3.2.7.4. Hibernate Search Lucene Updates
Number and Date Index Format
Numbers and dates are now indexed as numeric fields by default. Properties of type Date, Calendar, int, long, float, double, and their corresponding wrappers, are no longer indexed as strings; instead, they use Lucene’s appropriate numeric encoding. If any query previously targeted a string encoded field, but is not encoded numerically, it will need to be updated. Numeric fields must be searched with a NumericRangeQuery; however, if the Search query DSL is in use it should generate the correct query. In addition, any fields targeted by faceting should now be string encoded.
Date and Calendar instances are encoded as a long value, representing the number of milliseconds since January 1, 1970, 00:00:00 GMT.
Any id fields are an exception to this rule. Even when these fields are represented by a numeric type they will continue to be indexed as a string keyword by default.
The changes mean the use of @NumericField is now obsolete, unless a custom precision for the numeric encoding is explicitly specified.
Previous, string based, index format may be used by specifying a string encoding field bridge. For integers this is org.hibernate.search.bridge.builtin.IntegerBridge; other publicly available field bridges may be found in the org.hibernate.search.bridge.builtin package.
For dates and calendars the indexing format may be changed via the EncodingType enum; for example, @DateBridge(encoding=EncodingType.STRING) or @CalendarBridge(encoding=EncodingType.STRING).
Id fields of embedded relations are no longer indexed by default
When using an @IndexedEmbedded annotation to include fields from a related entity, previously the id of the related entity was included. These fields are no longer included by default, but may be enabled by using the includeEmbeddedObjectId attriubte of the @IndexedEmbedded annotation, as seen below:
@IndexedEmbedded(includeEmbeddedObjectId=true)
Sorting Query Results
The SortField API has been modified to use SortField.Type.${CLASSNAME} instead of the previous SortField.${CLASSNAME}. This behavior is highlighted below:
// Previous API call fulltextQuery.setSort( new Sort( new SortField( "title", SortField.STRING ) ) ); // New API call fulltextQuery.setSort( new Sort( new SortField( "title", SortField.Type.STRING ) ) );
Any applications not precisely matching the Lucene field encoding for sorting options in Lucene 4 would have worked without error; however, the new version of Lucene 5 now correctly catches these errors and will report a runtime exception. The expected field encoding must be matched according to its type. A field indexed as a String requires a single term, even after analysis, a numeric field encoded as an Integer must match SortField.Type.INT, a numeric field encoded as a Long must be sorted with SortField.Type.LONG, and so forth.
Faceting on Numeric Fields
Similar to Sorting Query Results, each target field must match an appropriate kind of Faceting Query. For instance, a Numeric Facet Query must match a field that was indexed exclusively via the matching Numeric type.
Null value tokens for Numeric Fields
When using @Field(indexNullAs=) to encode a null marker value in the index, the type of marker must be compatible with all other values which are indexed in the same field. Previously a string keyword, such as null, could be encoded with numeric fields; however, this is no longer allowed. A number must now be used to represent the null value, such as -1.
Lucene Classes Moved
Many of the Analyzer, TokenFilter, and CharFilter classes have been moved, and it is recommended to examine Lucene’s API documentation to find the correct replacement.
Similarly, many of the Solr utility classes, such as TokenizerFactory or TokenFilterFactory were moved into Apache Lucene. Any applications using these classes should also be updated using the Lucene’s API documentation.
Due to this refactoring the Solr dependencies are now incorporated within Lucene, and no longer need to be specified; any applications that previously had Solr dependencies defined should remove them and only use the Lucene dependencies.
3.2.7.5. Hibernate Search Deprecated Classes
The following list are deprecated classes within the Hibernate Search modules:
-
org.hibernate.search.annotations.Key- there is no replacement for this class; however, it is no longer required for users to provide aKeyobject. -
ContainedInMapping#numericField()- Usefield().numericField()instead.
