Hibernate Search Changes in JBoss EAP 7

From JBoss EAP 7.1 Migration Guide:

5.8. Hibernate Search Changes

The version of Hibernate Search that ships with JBoss EAP 7 has changed. The previous release of JBoss EAP shipped with Hibernate Search 4.6.x. JBoss EAP 7 ships with Hibernate Search 5.5.x.

Hibernate Search 5.5 is built upon Apache Lucene 5.3.1. If you use any native Lucene APIs, be sure to align with this version. The Hibernate Search 5.5 API wraps and hides the complexity of many of the Lucene API changes made between version 3 and version 5; however, some classes are now deprecated, renamed, or repackaged. This section describes how these changes might impact your application code.

Hibernate Search Mapping Changes

Indexing of id Fields of Embedded Relations

When using an @IndexedEmbedded annotation to include fields from a related entity, the id of the related entity is no longer included. You can enable the inclusion of the id by using the includeEmbeddedObjectId attribute of the @IndexedEmbedded annotation.

Example: @IndexedEmbedded Annotation

@IndexedEmbedded(includeEmbeddedObjectId=true)
Number and Date Index Formatting Changes

Numbers and dates are now indexed as numeric fields by default. Properties of type int, long, float, double, and their corresponding wrapper classes are no longer indexed as strings. Instead, they are now indexed using Lucene’s appropriate numeric encoding. The id fields are an exception to this rule. Even when they are represented by a numeric type, they are still indexed as a string keyword by default. The use of @NumericField is now obsolete unless you want to specify a custom precision for the numeric encoding. You can keep the old string-based index format by explicitly specifying a string encoding field bridge. In the case of integers, this is the org.hibernate.search.bridge.builtin.IntegerBridge. Check the org.hibernate.search.bridge.builtin package for other publicly available field bridges.

Date and Calendar are no longer indexed as strings. Instead, instances are encoded as long values representing the number of milliseconds since January 1, 1970, 00:00:00 GMT. You can switch the indexing format by using the new EncodingType enum. For example:

Example: @DateBridge and @CalendarBridge Annotation

@DateBridge(encoding=EncodingType.STRING)
@CalendarBridge(encoding=EncodingType.STRING)
The encoding change for numbers and dates is important and can have a big impact on application behavior. If you have a query that targets a field that was previously string-encoded, but is now encoded numerically, you must update the query. Numeric fields must be searched with a NumericRangeQuery. You must also make sure that all fields targeted by faceting are string encoded. If you use the Search query DSL, the correct query should be created automatically for you.

Miscellaneous Hibernate Search Changes

Sorting options have improved and field encoding specified incorrectly for sorting options now results in runtime exceptions. Lucene also offers more performant sorting if the fields used in the sort are known up front. Hibernate Search 5.5 provides the new @SortableField annotation and its multi-valued companion @SortableFields. See the Migration Guide from Hibernate Search 5.4 to 5.5 for more information.
The Lucene SortField API requires the following application code change.

In the previous release of JBoss EAP, you set the type of the sort field in the query as follows.

fulltextQuery.setSort(new Sort(new SortField("title", SortField.STRING)));
The following is an example of how you set it in JBoss EAP 7.

fulltextQuery.setSort(new Sort(new SortField("title", SortField.Type.STRING)));
Since SearchFactory should only be used by ORM integration, it was moved from the hibernate-search-engine module to the hibernate-search-orm module. Other integrators should depend exclusively on SearchIntegrator, which replaces the deprecated SearchFactoryIntegrator.
The enum value SpatialMode.GRID was renamed to SpatialMode.HASH.
FullTextIndexEventListener is now a final class. If you currently extend this class, you must find an alternate solution to achieve the same functionality.
The hibernate-search-analyzers module was removed. The recommended approach is to directly use the appropriate Lucene artifact, for example org.apache.lucene:lucene-analyzers-common.
The JMS controller API has changed. The JMS back-end dependency on Hibernate ORM was removed so that it could be used in other non-ORM environments. A consequence is that implementors of org.hibernate.search.backend.impl.jms.AbstractJMSHibernateSearchController must adjust to the new signature. This class is an internal class and it is recommended to use it as an example instead of extending it.
The org.hibernate.search.spi.ServiceProvider SPI was refactored. If you were integrating with the old service contract, refer to the Hibernate Search 5.5 Javadoc of ServiceManager, Service, Startable and Stoppable for details about the new contract.
If you have kept indexes generated by Lucene 3.x and have not rebuilt them with Hibernate Search 5.0 or later, you will get an IndexFormatTooOldException. It is recommended that you rebuild the indexes with the mass indexer. If you are not able to do that, try to use Lucene’s IndexUpgrader. You must carefully update the Hibernate Search mappings in case the default behavior has changed. For more information, see the Apache Lucene Migration Guide.
Apache Lucene was upgraded from 3.6 to 5.3 in JBoss EAP 7. If your code imports Lucene code directly, see the Apache Lucene Migration Guide for details of the changes. Additional information can also be found in the Lucene Change Log.
When using @Field(indexNullAs=) to encode a null marker value in the index, the type of the marker must be compatible with all other values that are indexed in that same field. For example, it was previously possible to encode a null value for numeric fields using a string "null". This is no longer allowed. Instead, you must choose a number to represent the null value, such as -1.
Significant improvements were made to the faceting engine. Most of the changes do not affect the API. The one notable exception is that you must now annotate any fields you intend to use for faceting with the @Facet or @Facets annotation.
Hibernate Search Renamed and Repackaged Classes

The following is a list of Hibernate Search classes that were repackaged or renamed.

Previous Package and Class New Package and Class
org.hibernate.search.Environment

org.hibernate.search.cfg.Environment

org.hibernate.search.FullTextFilter

org.hibernate.search.filter.FullTextFilter

org.hibernate.search.ProjectionConstants

org.hibernate.search.engine.ProjectionConstants

org.hibernate.search.SearchException

org.hibernate.search.exception.SearchException

org.hibernate.search.Version

org.hibernate.search.engine.Version

Lucene - Renamed and Repackaged Classes

Query parsers were moved to a new module, resulting in a packaging change from org.apache.lucene.queryParser.QueryParser to org.apache.lucene.queryparser.classic.QueryParser.

Many of the Lucene analyzers were refactored, resulting in packaging changes. See the Apache Lucene Documentation to find the replacement packages.

Some Apache Solr utility classes, for example TokenizerFactory or TokenFilterFactory, were moved into Apache Lucene. If your application uses those utilities or custom analyzers, you must find the new package name in Apache Lucene.

See the Apache Lucene Migration Guide for more information.

Hibernate Search Deprecated APIs

For the complete list of Hibernate Search deprecated interfaces, classes, enums, annotation types, methods, constructors, and enum constants, see the Hibernate Search Deprecated API document.

Hibernate Search Deprecated Interfaces

Interface Description
org.hibernate.search.store.IndexShardingStrategy

Deprecated as of Hibernate Search 4.4. Might be removed in Search 5. Use ShardIdentifierProvider instead.

org.hibernate.search.store.Workspace

This interface will be moved and should be considered non-public API. For more information, see HSEARCH-1915.

Hibernate Search Deprecated Classes

Class Description
org.hibernate.search.filter.FilterKey

Custom filter keys are deprecated and are scheduled for removal in Hibernate Search 6. As of Hibernate Search 5.1, keys for caching Lucene filters are calculated automatically based on the given filter parameters.

org.hibernate.search.filter.StandardFilterKey

Custom filter keys are deprecated and are scheduled for removal in Hibernate Search 6. As of Hibernate Search 5.1, keys for caching Lucene filters are calculated automatically based on the given filter parameters.

Hibernate Search Deprecated Enums

Enum Description
org.hibernate.search.annotations.FieldCacheType

Remove the CacheFromIndex annotation as it is deprecated. See Hibernate Search Deprecated Annotations.

Hibernate Search Deprecated Annotations

Annotation Description
org.hibernate.search.annotations.CacheFromIndex

Remove the annotation. No alternative replacement is necessary.

org.hibernate.search.annotations.Key

Custom filter cache keys are a deprecated feature and are scheduled to be removed in Hibernate Search 6. As of Hibernate Search 5.1, the filter cache keys are determined automatically based on the filter parameters so it is no longer required to provide a key object.

Hibernate Search Deprecated Methods

Method Description
org.hibernate.search.FullTextSharedSessionBuilder.autoClose()

No replacement

org.hibernate.search.FullTextSharedSessionBuilder.autoClose(boolean)

No replacement

org.hibernate.search.cfg.IndexedMapping.cacheFromIndex(FieldCacheType…​)

This will be removed with no replacement.

org.hibernate.search.cfg.EntityDescriptor.getCacheInMemory()

This will be removed with no replacement.

org.hibernate.search.cfg.ContainedInMapping.numericField()

Invoke field().numericField() instead.

org.hibernate.search.cfg.EntityDescriptor.setCacheInMemory(Map<String, Object>)

This will be removed with no replacement.

org.hibernate.search.MassIndexer.threadsForSubsequentFetching(int)

This method will be removed.

org.hibernate.search.query.dsl.FuzzyContext.withThreshold(float)

Use FuzzyContext.withEditDistanceUpTo(int).

Hibernate Search Deprecated Constructors

Constructor Description
org.hibernate.search.cfg.NumericFieldMapping(PropertyDescriptor, EntityDescriptor, SearchMapping)

Use NumericFieldMapping.NumericFieldMapping(String, PropertyDescriptor, EntityDescriptor, SearchMapping) instead.

Changes Impacting Advanced Integrators

This section describes changes that are not part of the public API. They should not impact the average developer as these artifacts should only be accessed by integrators who extend the Hibernate Search framework.

The IndexWriterSetting.MAX_THREAD_STATES and IndexWriterSetting.TERM_INDEX_INTERVAL enum constants are deprecated. They affect which properties are read from the configuration, so the fact they they are missing means that configuration properties such as hibernate.search.Animals.2.indexwriter.term_index_interval = default are now ignored. The only side effect is that the property is not applied.
The SearchFactoryIntegrator interface is now deprecated. You should immediately migrate all code to use SearchIntegrator.
The SearchFactoryBuilder class is now deprecated. Use SearchIntegrationBuilder instead.
The HSQuery.getExtendedSearchIntegrator() method has been deprecated. It might be possible to use SearchIntegrator, but it is preferable to remove it altogether.
The DocumentBuilderIndexedEntity.getFieldCacheOption() method has been deprecated. There is no replacement.
The BuildContext.getIndexingStrategy() method is deprecated. Use BuildContext.getIndexingMode() instead.
The DirectoryHelper.getVerifiedIndexDir(String, Properties, boolean) method is deprecated. Use DirectoryHelper.getVerifiedIndexPath(java.lang.String, java.util.Properties, boolean) instead.
The following is a list of Hibernate Search classes that were repackaged or renamed.

Previous Package and Class New Package and Class
org.hibernate.search.engine.impl.SearchMappingBuilder
org.hibernate.search.engine.spi.SearchMappingHelper
org.hibernate.search.indexes.impl.DirectoryBasedIndexManager
org.hibernate.search.indexes.spi.DirectoryBasedIndexManager
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

A new set of RHAMT Rules should be added to address the app migration issues detailed above. Please let me know if you need further info for the "when"s and "perform"s.