-
Language:
English
-
Language:
English
Migration Guide
For use with Red Hat JBoss Data Grid 7.0
Abstract
Chapter 1. Introduction
- Schemaless key-value store – JBoss Data Grid is a NoSQL database that provides the flexibility to store different objects without a fixed data model.
- Grid-based data storage – JBoss Data Grid is designed to easily replicate data across multiple nodes.
- Elastic scaling – Adding and removing nodes is simple and non-disruptive.
- Multiple access protocols – It is easy to access the data grid using REST, Memcached, Hot Rod, or simple map-like API.
1.1. About the Migration Guide
Chapter 2. Product Changes
2.1. Library Mode Configuration Update
Procedure 2.1. 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.batutility, passing in the name of the existinginfinispan_6.0.xmlconfiguration 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.xmlhas 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 2.2. 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.shutility, passing in the name of the existinginfinispan_6.0.xmlconfiguration file and the destination as arguments:./config-converter.sh /path/to/infinispan_6.0.xml /path/to/infinispan-new.xml
- Ensure that
infinispan-new.xmlhas been created with the new Library mode configurations. This file may now be used in Library mode applications with JBoss Data Grid 7.0.
Note
infinispan-new.xml in the above examples, the utility will instead display the converted xml to the console.
2.2. CLI Commands
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.
2.3. Server Managment
9990.
2.4. JGroups ENCRYPT Protocol Deprecated
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:
Example 2.1. SYM_ENCRYPT Configuration Example
<SYM_ENCRYPT sym_algorithm="AES"
encrypt_entire_message="true"
keystore_name="defaultStore.keystore"
store_password="changeit"
alias="myKey"/>Example 2.2. ASYM_ENCRYPT Configuration Example
<ASYM_ENCRYPT encrypt_entire_message="true"
sym_keylength="128"
sym_algorithm="AES/ECB/PKCS5Padding"
asym_keylength="512"
asym_algorithm="RSA"/>Chapter 3. Application Changes
3.1. NotifyingFuture replaced by CompletableFuture
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.
NotifyingFuture will need to be replaced with CompletableFuture to function correctly with JBoss Data Grid 7.0.
3.2. JBoss Modules CDI Dependency
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.
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.3. Spring 3 support removed
3.4. RemoteCache Deprecated Methods
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.5. Interceptors Deprecated
3.6. Map/Reduce replaced by Distributed Streams
3.7. Hibernate Search
Important
3.7.1. Hibernate Search Class Name and Package Updates
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.7.2. Hibernate Search Additions
- 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.7.3. Hibernate Search Lucene Updates
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.
Note
Date and Calendar instances are encoded as a long value, representing the number of milliseconds since January 1, 1970, 00:00:00 GMT.
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.
@NumericField is now obsolete, unless a custom precision for the numeric encoding is explicitly specified.
org.hibernate.search.bridge.builtin.IntegerBridge; other publicly available field bridges may be found in the org.hibernate.search.bridge.builtin package.
EncodingType enum; for example, @DateBridge(encoding=EncodingType.STRING) or @CalendarBridge(encoding=EncodingType.STRING).
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)
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 ) ) );
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.
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.
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.
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.
TokenizerFactory or TokenFilterFactory were moved into Apache Lucene. Any applications using these classes should also be updated using the Lucene's API documentation.
3.7.4. Hibernate Search Deprecated Classes
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.
Appendix A. Revision History
| Revision History | ||||
|---|---|---|---|---|
| Revision 7.0.0-1 | Mon 18 Jul 2016 | Christian Huffman | ||
| ||||
| Revision 7.0.0-0 | Wed 3 Feb 2016 | Christian Huffman | ||
| ||||