Hibernate Search

Migration Guide from Hibernate Search 4.x to 5.0

Upgrade to Hibernate Search 5.0.0.Final

The aim of this guide is to assist you migrating an existing application based on a fairly recent version of Hibernate Search 4, such as 4.4.x and 4.5.x, to Hibernate Search 5.

If you’re upgrading from older versions, please migrate to 4.5.3.Final first.
This document provides pointers for a migration. It refers to Hibernate Search 5.0.0.Final. If you think something is missing or something does not work, please contact us. If you’re looking to migrate different versions see Hibernate Search migration guides.

Requirements

The most important upfront. Hibernate Search 5 requires now Java 7. Support for Java 6 has been dropped.

Hibernate Search 5 also builds now upon Lucene 4 (more specifically 4.10.2). If you are using any native Lucene APIs make sure to align with this version. Refer also to the Lucene Migration Guide.

Hibernate Search is compatible with Hibernate ORM 4.3.7.Final and Infinispan 7.0.2.Final.

API changes

Even though the Lucene API changes between version 3 and 4 are rather big, we were able to hide most of the complexities behind the Hibernate Search API. Some changes, however, trickle all the way through.

Sorting query results

Lucene’s SortField API has changed. Instead of

fulltextQuery.setSort( new Sort( new SortField( "title", SortField.STRING ) ) );

you now need to use:

fulltextQuery.setSort( new Sort( new SortField( "title", SortField.Type.STRING ) ) );

Class re-names and re-locations

Between Hibernate Search 4 and 5 several classes have changes names or package. This happened within the Search API as well as within the Lucene API. The following is a list of the most important changes.

  • SearchFactory was moved from the module hibernate-search-engine to hibernate-search-orm as it should only be used by the ORM integration. Other integrators should depend exclusively on SearchIntegrator (former SearchFactoryIntegrator)

  • The following classes got re-located:

    • 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

  • The enum value SpatialMode.GRID was renamed to SpatialMode.HASH

Within Apache Lucene

  • Lucene’s QueryParser changed package from org.apache.lucene.queryParser.QueryParser to org.apache.lucene.queryparser.classic.QueryParser

  • Many popular Analyzer, TokenFilter and CharFilter classes moved. Refer to the Lucene API docs to find the appropriate replacement.

  • Solr utilities classes, for example TokenizerFactory or TokenFilterFactory, were moved into Apache Lucene. For this reason we could remove the dependency to Apache Solr. Good news is a simplified dependency graph! The bad news, if you depend on some of these utilities or custom analyzers, you’ll need to find the new (package) name

Mapping

Id fields of embedded relations no longer indexed by default

When using an @IndexedEmbedded annotation to include fields from a related entity, we would include the 'id' of the related entity. These 'id' fields are no longer included by default, but you can enable the inclusion by using the includeEmbeddedObjectId attribute of the @IndexedEmbedded annotation.

@IndexedEmbedded(includeEmbeddedObjectId=true)

Number and date index format

Numbers and dates now indexed as numeric fields by default.

Properties of type Date, Calendar as well as int, long, float, double and their corresponding wrappers, 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 these are represented by a numeric type, they will still be indexed as a string keyword by default.

Date and Calendar instances are encoded as long value representing the number of milliseconds since January 1, 1970, 00:00:00 GMT.
The use of @NumericField becomes now obsolete, unless you want to specify a custom precision for the numeric encoding.

You can still keep the old (string based) index format by explicitly specifying a string encoding field bridge. In the case of integers for example org.hibernate.search.bridge.builtin.IntegerBridge. Check the package org.hibernate.search.bridge.builtin for other publicly available field bridges.

For dates and calendars you can switch the indexing format via the new EncodingType enum, for example @DateBridge(encoding=EncodingType.STRING) resp. @CalendarBridge(encoding=EncodingType.STRING).

The change of encoding for number and dates is probably the most important user facing change. If you have any query which targets a previously string encoded field, but is not encoded numerically, you will need to update the query. Numeric fields must be searched with a NumericRangeQuery (if you are using the Search query DSL, the right query should be created for you). Also make sure that all fields targeted by faceting need for now be string encoded.

Misc

FullTextIndexEventListener now final

FullTextIndexEventListener is now a final class. If you are extending this class, you need to find an alternative approach for what you want to achieve. Maybe you can use an EntityIndexingInterceptor? If you cannot find a way to implement your use case - contact us.

hibernate-search-analyzers module removed

The module hibernate-search-analyzers was dropped from the repository and will no longer be included in upcoming release. It is obsolete and we recommend to depend on the appropriate Lucene artifact directly, for example org.apache.lucene:lucene-analyzers-common.

JMS controller API changed

The JMS backend was depending to Hibernate ORM. This dependency was removed, so that the backend can be used in other (non ORM) environments as well. A consequence is that implementors of org.hibernate.search.backend.impl.jms.AbstractJMSHibernateSearchController will need to adjust to the new signature. This class is really considered internal. We suggest to take this class as an example instead of extending it.

ServiceRegistry API updated

The org.hibernate.search.engine.service.spi.Service SPI got refactored. If you where integrating with the old service contract, refer to the javadoc of ServiceManager, Service, Startable and Stoppable for details about the new contract.

Back to top