Here we are helping you migrate your existing Hibernate Search application to the latest and greatest.
- Upgrade to Hibernate Search 5.0.0.Final
- API changes
- Class re-names and re-locations
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.|
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.
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.
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.
Within Hibernate Search
SearchFactorywas moved from the module
hibernate-search-ormas it should only be used by the ORM integration. Other integrators should depend exclusively on
The following classes got re-located:
The enum value
SpatialMode.GRIDwas renamed to
Within Apache Lucene
QueryParserchanged package from
CharFilterclasses moved. Refer to the Lucene API docs to find the appropriate replacement.
Solr utilities classes, for example
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
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
Number and date index format
Numbers and dates now indexed as numeric fields by default.
Properties of type
Calendar as well as
double and their corresponding
wrappers, are no longer indexed as strings. Instead, they are now indexed using Lucene’s appropriate
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.
The use of
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
Check the package
other publicly available field bridges.
For dates and calendars you can switch the indexing format via the new
enum, for example
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
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
org.hibernate.search.engine.service.spi.Service SPI got refactored. If you where integrating
with the old service contract, refer to the javadoc of
for details about the new contract.