Hibernate Search Migration Guide

Hibernate Search 5

Hibernate Search 5.0.0.Alpha2

Mostly a bugfix release with no changes in API or SPI. Some dependencies where cleaned up.

Removal of hibernate-search-analyzers module

The module hibernate-search-analyzers was dropped from the repository and will no longer be included in any release. Technically you don't need it anymore: it has been around for a while only as an empty shell depending on various Solr and Apache Lucene Analyzers: our recommendation is to explicitly depend on the Analyzers you need directly in your projects, which gives you a better control of the dependency graph.

Hibernate Search 5.0.0.Alpha1

The changes in APIs of Hibernate Search packages have been kept to a minimum, still many other important dependencies had major updates so if you where using them you will need to adjust your code.

Apache Lucene 4.6.1

This is a significant change and many APIs of Lucene have changed:

QueryParser(s) changed package: org.apache.lucene.queryParser.QueryParser -> org.apache.lucene.queryparser.classic.QueryParser

many popular Analyzer, TokenFilter, CharFilter  implementations moved in a different package.

In our tests we used the following command to do most of the work:

 

find . -type f -name \*.java -o -name \*.xml | xargs sed -i '' -f ~/sources/Lucene4Migration.sedscript

 

You'll find the Lucene4Migration.sedscript attached to this page.

The Sorting API changed

Where previously you might have used:


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


this should be changed to


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


Dependency to Apache Solr removed

We still provide the same functionality, but most of the utilities we needed from the Apache Solr project where moved into Apache Lucene. Great news for a simplified dependency graph! The downside is that if you where depending on some of these utilities and custom Analyzers directly, you'll need to find the new name.

 

ServiceRegistry

The org.hibernate.search.engine.service.spi.Service evolved: this is an API for extension points, unless you where integrating the framework with custom services this should not affect you. See the Service SPI javadoc for details.

 

Spatial API

The enum value SpatialMode.GRID was renamed to the more suited SpatialMode.HASH .


Hibernate Search 4.5

Hibernate Search 4.5.0.CR1

Improved integration with Infinispan: might reject some Infinispan configurations as there are stricter sanity checks on which caches are acceptable to be used for the purpose of storing indexes.

Metadata SPI was polished: if you used the new Metadata API which was introduced during 4.4, you might need to adapt your code.

MassIndexer: tuning option threadsForSubsequentFetching was deprecated and is now being ignored. You probably want to add the value to the threads used for threadsToLoadObjects: this phase now incorporate both stages.

Hibernate Search 4.5.0.Alpha1

Requires (at least) Hibernate ORM 4.3.0.Beta5 and Infinispan 6.0.0.CR1.

No longer compatible with JBoss 7.1: requires WildFly (because of Hibernate ORM, so it could work on previous JBoss versions if you deploy a custom ORM module).

Hibernate Search 4.4

Hibernate Search 4.4.0.Final

No code changes.

Hibernate Search 4.4.0.CR1

The SPI to integrate a custom MassIndexerFactory changed method signature: see HSEARCH-1428

Hibernate Search 4.4.0.Beta1

Dynamic Sharding is introduced, deprecating previous ShardingStrategy.

Entity annotation @Similarity is deprecated: better to use the configuration properties to pick a custom Similarity implementation.

Hibernate Search 4.4.0.Alpha2

No backwards compatibility changes

Upgraded dependencies: Apache Tika to 1.4, Apache Avro to 1.7.5, JGroups 3.3.4.Final, Hibernate Commons Annotations to 4.0.4.Final, Hibernate ORM 4.2.5.Final

Hibernate Search 4.4.0.Alpha1

No backwards compatibility changes

Upgraded dependencies: Hibernate ORM 4.2.3.Final, Infinispan 5.3.0.Final, JGroups 3.3.2

Hibernate Search 4.3.0.Final

No backwards compatibility changes

Hibernate Search 4.3.0.CR1

No backwards compatibility changes

Hibernate Search 4.3.0.Beta1

No mayor compatibility changes: some dependencies updated, some cleaned up (Guava removed).

Hibernate Search 4.3.0.Alpha1

JGroups backends

 

The JGroups backend would previously always behave as an asynchronous backend, since 4.3.0.Alpha1 this can be configured to be synchronous but the default is potentially different than previous versions, as it depends on the worker.execution option: if it's set to sync, the backend will be sync too. And the default of workers.async has always been sync.

 

Hibernate Search 4.2.0.Final

Hibernate Search 4.2.0.CR1

Apache Lucene 3.6.2

With Hibernate Search 4.2.0.CR1 we now build using - and recommend using - Apache Lucene version 3.6.2; it is still compatible with Lucene 3.6 and 3.6.1 so you have the choice to keep the older version. As always if you upgrade Lucene, it is recommended to rebuild the indexes.

Hibernate Search 4.2.0.Beta2

JMS backend

Improvements on the JMSBackendQueueProcessor broke possible subclasses; it should be easier to extend now to use a custom lookup strategy for the Queues, but still remember this class being in an .impl package it's API might change at any time in future.

IndexingInterceptor applied to MassIndexer

The MassIndexer now applies any IndexingInterceptor you might have enabled on your entities.

ServiceManager SPI changes

The recommended way to use the ServiceManager is now to use BuildContext.getServiceManager(). Methods BuildContext.requestService() and BuildContext.releaseService() are deprecated and will be removed.

 

Hibernate Search 4.2.0.Beta1

Lucene 3.6

Apache Lucene was updated, as always that means some care is needed as the index might not be completely compatible: we suggest to rebuild the index. This version is not compatible with Apache Lucene 3.5 and previous versions.

Hibernate Search 4.1.1.Final

The method org.hibernate.search.cfg.SearchMapping#getFullTextFilerDefs had a typo and was fixed as SearchMapping#getFullTextFilterDefs.

Before this release the SearchMapping was considered experimental, so the older method wasn't deprecated but just removed.

Hibernate Search 4.1.0.CR3 and 4.1.0.Final

JGroups integration and configuration

JGroups channels where initialized one-per-index. Now a Channel is initialized as a shared service across any index using JGroups master or slave configurations, hence the configuration properties changed.

 

Configuration options as configurationString and configurationXml, which where embedding the JGroups configuration in the Search configuration, are no longer supported. Use either configurationFile or providedChannel.

 

Also, configuration is NOT scoped to the index anymore, so the following property is invalid, and will produce a configuration exception at initialization:

 

hibernate.search.[indexname].worker.backend.jgroups.configurationFile

 

Configuration should now use the global service scope:

 

hibernate.search.services.jgroups.configurationFile = jgroups-configuration.xml

 

No changes where made in the way an index is configured as a master or slave node, only the JGroups channel configuration attributes where moved.

 

Hibernate Search 4.1.0.Beta2

MassIndexer API

The configuration method threadsForIndexWriter is deprecated and not affecting the MassIndexer anywmore. The implementation sends index changes to the same backend as usual, so the number of threads working on the index is determined by the number of backend workers; see worker.thread_pool.size configuration property, which is specific for each index.

Hibernate Search 4.1.0.Beta1

Several versions updated

  • Infinispan 5.1.x
  • JGroups 3.0.x
  • Lucene 3.5

 

Hibernate Search 4.0.0.Final

 

Aligns with Hibernate Core 4.0.0.Final and Hibernate Commons Annotations 4.0.1.

 


Hibernate Search 4.0.0.CR2

Only minor updates and bug fixes.

 


Hibernate Search 4.0.0.CR1

Only minor updates in components and backwards compatible improvements and bugfixes.

 


Hibernate Search 4.0.0.Beta2

New jars, Maven modules reorganization

The existing jar (and Maven artifact id) known as hibernate-search was split in two modules: hibernate-search-engine which contains most of the Query logic and all the nice Lucene resource management, and hibernate-search-orm which contains the integration with Hibernate Core and Hibernate EntityManager.

The new hibernate-search-engine does not depend on Hibernate Core, and so can be reused to integrate Apache Lucene in other projects.

If you're migrating a project using hibernate-search it should still work without changes as we created an empty project depending on hibernate-search-orm, or you could depend on hibernate-search-orm.

The hibernate-search-orm depends on both hibernate-search-engine and hibernate-core, optionally on hibernate-entitymanager if you use JPA.

 

ErrorHandler notifications from MassIndexer failures

Previously you could configure an ErrorHandler to manage eventual exceptions in the backend; this same ErrorHandler will now be notified for errors happening during a MassIndexer run, if any.

 

Lucene 3.4

Again we keep Search up to date with the latest Apache Lucene release. There where no significant code changes needed, so it's expected to work fine with Lucene 3.3 too if you can't upgrade.

 


Hibernate Search 4.0.0.Beta1

New parameter list for o.h.s.annotations.Field

Prior to Beta1 the @Field annotation mixed the concept of whether a property is analyzed and whether norms are stored in the index by specifying a single value for the index paramter (NO, TOKENIZED, UN_TOKENIZED and NO_NORMS). The terminology was also using the term tokenizing instead of analyzing and there was no option for analyzed indexing without storing norms.

 

The new @Field signature is: @Field(index=Index.YES|NO, analyze=Analyze.YES|NO, norms=Norms.YES|NO, ...)


Hibernate Search 4.0.0.Alpha2

Serialization protocol

The serialization protocol has changed, make sure to purge your JMS or JGroups messages and upgrade you cluster at once.

Query

Mixing Lucene queries and a Criteria query with restrictions (ie where clause) is now supported but query.getResultSize() will raise an exception in this particular case. You must use query.list().size() (or query.getResultList().size()).

Hibernate Core 4.0.0.CR2

We now depend on Hibernate 4.0.0.CR2, make sure to upgrade.


Hibernate Search 4.0.0.Alpha1

This is the first milestone for the next mayor release, hence the changes are quite consistent in the internal architecture, but there are so far no changes in the way the index mapping is defined, so don't be scared by the long list of improvements:

Hibernate Core 4.0.0.CR1

Hibernate Search 4 will depend on Hibernate Core 4; specifically Hibernate Search 4.0.0.Alpha1 was compiled and tested against Hibernate Core 4.0.0.CR1.

Java 6

As Hibernate Core 4 depends on Java 6, so is now Hibernate Search.

Lucene 3.3.0

As usual we target the latest Apache Lucene version available at the time of release. When migrating from an older version this means, atop of API changes, that some Analyzers might expose different behaviour: restults from fulltext queries might contain unexpected values or fail to return some matching value.

Options:

  • We can force Lucene's Analyzers to behave as a limited set of previous releases by using the hibernate.search.lucene_version property.
  • You rebuild your index using the MassIndexer. This is always better when possible, as it gives the best compatibility guarantees.

Other upgraded dependencies

For a detailed list we recommend to inspect the pom.xml files, the most notable changes are:

  • Logging framework now uses JBoss Logger 3, which delegates as slf4j also did to JDK logging or Log4j but provides better performance and trackable identifiers for errors and warnings. Should make it easier to find references to issues.
  • Infinispan integration now depends on Infinispan version 5.0.0.FINAL, with an update JGroups 2.12.1.3.Final.

Getting an IndexReader

An IndexReader for one or more entities can now be obtained directly from the SearchFactory using org.hibernate.search.SearchFactory.openIndexReader(Class<?>...);

Always close an IndexReader obtained in such a way by using the corresponding

org.hibernate.search.SearchFactory.closeIndexReader(IndexReader);

These two methods are experimental and likely to be revisited before Hibernate Search 4.0.0 Final.

Multiple Backends

Previously while it was possible to configure different DirectoryProviders for each index, they had all to share the same backend. This implied that all writing operations had to be handled by either the Lucene backend, or one of the clustering options as JMS or JGroups.

The backend subsystem is now split on a per-index base, and each one can be configured completely independently, including different options for each shard for the same entity:

  • Backend type (JMS, JGroups, Lucene, Blackhole).
  • Sync/Async options. You can enable a synchronous backend where you need it, and keeping the better performing async option for the other entities which don't strictly need it.
  • Executor options (number of threads concurrently writing the index, queue sizes).
  • ReaderProvider: different indexes can use a different ReaderProvider implementation.

As usual all these components can be overriden with custom implementations.

 

Impact on configuration

Previously only DirectoryProvider options where index scoped, while backend options where global. So the previous configuration

 

hibernate.search.default.directory_provider filesystem

hibernate.search.max_queue_length 5

hibernate.search.worker.backend infinispan

 

Should now be written as:

 

hibernate.search.default.directory_provider filesystem

hibernate.search.default.max_queue_length 5

hibernate.search.default.worker.backend jgroupsSlave

 

And of course you can then add overrides on a per index or per-shard base:

hibernate.search.Animals.worker.backend blackhole

hibernate.search.Animals.2.worker.thread_pool.size 10


ReaderProvider

The usual strategies are available, but the interface changed and it should be simpler now to implement your own strategy as you'll have to deal with a single index.

Serialization framework

A serialization API was introduced; in the past the components from Lucene we needed to Serialize for clustering support implemented Serializable, but this approach is now being dropped in newer releases, so we need now alternative strategies.

In this release we use Apache Avro to serialize the LuceneWork needed to send update operations to clustering backends, before version 4 Final we might make this a pluggable component as usual.

This means that now it's possible to use NumericField even in a clustered environment, which was not serializable.

Exclusive Index enabled by default

The existing option exclusive_index_use defaulted to false in previous releases, this is now true as it significantly improves performance and as a needed step for further optimisations coming in version 4. This also means it's especially important you don't forget to close the SessionFactory or EntityManagerFactory, or the Lucene index will not be unlocked.

API interfaces

Since we're preparing for a mayor release, some other interfaces changed; most importantly we moved in ".impl" packages those interfaces that we consider for internal use, and that application should not import directly.

 

IndexManager and DirectoryProvider

Previously a Lucene index would be abstracted by it's DirectoryProvider. Direct access to the DirectoryProvider is now discouraged, and resources for each index are organized in an IndexManager, which collects the backend, the ReaderProvider, and the DirectoryProvider if one is used. This change was done so that we will be able to plug in IndexManagers which are not necessarily based on a Lucene Directory contract: all what is needed by the core engine is a way to provide a reference to an IndexReader and a way to apply updates to the index, so now you're welcome to contribute integrations to other Lucene based engines.


Hibernate Search 3.4.0.Final

No changes compared to 3.4.0.CR2

Hibernate Search 3.4.0.CR2

Lucene 3.1.0

Hibernate Search now requires Lucene 3.1, leveraging all the great improvements from the Lucene team. In terms of Search API nothing changed, Search takes care of hiding the Lucene API changes.

Lucene and Solr changed packaging, some advanced analyzers have been moved into different jars. In case you use Maven to manage your dependencies, this has been taking care for you just depending on the usual hibernate-search-analyzers updating our transitive dependencies; in case you don't use Maven, make sure to locate the new jar names in case some Analyzer is not found on classpath.

max_field_length configuration option ignored

This configuration option is being ignored since it's deprecated in Lucene 3.1. No harm should be done if you don't change your configuration. To properly limit the size of indexed fields use a LimitTokenCountAnalyzer to decorate another analyzer.

 


Hibernate Search 3.4.0.Alpha1

Field Cache enabled

Lucene's field caching features are now enabled by default on the ProjectionConstants.OBJECT_CLASS field as it is expected that this will improve overall performance. This might require more memory, if you run in performance issues due to memory constraints make sure to read the new reference documentation on how to disable this: Reference documentation.


Hibernate Search 3.3.0.Final


Hibernate Search 3.3.0.Beta3

Sorting full-text queries

Lucene's org.apache.lucene.search.SortField constructor now requires a second parameter to define the kind of desired Sort. Valid values are listed as public constants in SortField, such as SortField.STRING_VAL.


Hibernate Search 3.3.0.Beta2

Solr Analyzers

Some analyzer and filter factories of the framework require additional libriaries (lucene-snowball, lucene-collation, commons-io, commons-codec). These additional libraries are now optional dependencies and have to be added explicitly. Refer to the online documentation to see which analyzer/filter needs which additional dependency.


Hibernate Search 3.3.0.Beta1

 

3.3 is largely backward compatible with the 3.2 series. However if you implement custom versions of:
  • ReaderProvider
  • DirectoryProvider
  • OptimizerStrategy
  • BackendQueueProcessorFactory
  • Worker
Read on.

DirectoryProvider#initialize

The initialize method no longer receives a SearchFactoryImplementor but a BuildContext. BuildContext provides data useful for initialization.
It also provides access to an uninitialized SearchFactoryImplementor instance that should not be used until after Hibernate Search is fully initialized: the initialize and start method can keep a reference to it but not use it. Methods called after initialize and start can use this reference safely.

BackendQueueProcessorFactory#initialize

The initialize method no longer receives a SearchFactoryImplementor but a WorkerBuildContext. WorkerBuildContext provides data useful for initialization.
It also provides access to an uninitialized SearchFactoryImplementor instance that should not be used until after Hibernate Search is fully initialized: the initialize method can keep a reference to it but not use it. Methods called after initialize can use this reference safely.
If you have an implementation of BackendQueueProcessorFactory, we highly recommend you to also implement UpdatableBackendQueueProcessorFactory: it allows support for mutable SearchFactory (this API is experimental however).

OptimizerStrategy#initialize

The initialize method no longer receives a SearchFactoryImplementor but a BuildContext. BuildContext provides data useful for initialization.
It also provides access to an uninitialized SearchFactoryImplementor instance that should not be used until after Hibernate Search is fully initialized: the initialize method can keep a reference to it but not use it. Methods called after initialize can use this reference safely.

ReaderProvider#initialize

The initialize method no longer receives a SearchFactoryImplementor but a BuildContext. BuildContext provides data useful for initialization.
It also provides access to an uninitialized SearchFactoryImplementor instance that should not be used until after Hibernate Search is fully initialized: the initialize method can keep a reference to it but not use it. Methods called after initialize can use this reference safely.

Worker#initialize

The initialize method no longer receives a SearchFactoryImplementor but a WorkerBuildContext. WorkerBuildContext provides data useful for initialization.
It also provides access to an uninitialized SearchFactoryImplementor instance that should not be used until after Hibernate Search is fully initialized: the initialize method can keep a reference to it but not use it. Methods called after initialize can use this reference safely.

 


Hibernate Search 3.2.0


Hibernate Search 3.2.0.Beta1

Discriminator interface changes

  • The  getAnanyzerDefinitionName method name in org.hibernate.search.analyzer.Discriminator contained a typo and is now called getAnalyzerDefinitionName.

 

IndexWriter tuning configuration changes

  • Until  previous version any configuration option set as  indexwriter.transaction.<parameter_name> would also affect the  batch version of it, unless indexwriter.batch.<parameter_name> was  explicitly set. This was leading to confusion and now to set a batch  parameter you have to explicitly set it.

 


Hibernate Search 3.1.0.GA

Make sure to  review the migration guides from the 3.1.x intermediate releases.

 


Hibernate Search 3.1.0.CR1

Projection

  • As part of this release we  removed calls to deprecated methods and classes in the Lucene 2.4 API.  This includes the usage of the deprecated Hits class. This  implies that projected Lucene scored won't be normalized anymore.

 


Hibernate Search 3.1.0.Beta2

APIs

  • Most APIs have been properly  generified. For example, They now accept Class<?> rather  than the raw type. You might need to recompile your code and fix a few  warnings.
  • ReaderProvider has a  new method destroy()


Dependencies

  • This version makes use of  Lucene 2.4.0.

 

Filter

  • The Filter definition declaration  has changed a bit. Use @FullTextFilterDef.cache now receives FilterCacheModeType enums and is the only cache related configuration. It defaults to cache  filter instances and BitSet results.

 


Hibernate Search 3.1.0.Beta1

Dependencies

  • Hibernate Search 3.1 depends  on Hibernate Core 3.3, and is integrated with Hibernate Annotations 3.4
  • The  logging system has moved to slf4j
  • The Lucene version must be 2.3  and above

Configuration

  • Optimizations features  involving Lucene tuning are now under hibernate.search.[default|<indexname>].indexwriter.[transaction|batch]

 

Query

  • FullTextQuery.BOOST is now  deprecated, it always returned 1 and had no concrete usage
  • Search.createFullTextSession and Search.createFullTextEntityManager are deprecated and  replaced by Search.getFullTextSession and Search.getFullTextEntityManager


Index

  • hibernate.search.worker.batch_size is deprecated in favor to the fullTextSession.flushToIndexes();
  • Calling  fullTextSession.index / purge: raises an exception if the entity is not  indexable rather than the previous noop.

 

Bridge

  • If you implement org.hibernate.search.bridge.FieldBridge or org.hibernate.search.bridge.TwoWayFieldBridge, the method set() has evolved to the following signature void set(String name, Object  value, Document document, LuceneOptions luceneOptions)

 


Hibernate Search 3.0.0.GA

Query

  • query.setIndexProjection has been  removed (after deprecation), the replaced method is query.setProjection

 


Hibernate Search 3.0.0.CR1

DirectoryProvider

  • DirectoryProvider has a new method start()

Mappings

  • @Text, @Keyword and @Unstored have  been removed

 


Hibernate Search 3.0.0.Beta4

Mappings

  • @Text, @Keyword etc have been  deprecated for a while, they will be removed in the next release.

Query

  • fullTextQuery.setIndexProjection()  has been renamed fullTextQuery.setProjection()
  • The default reader  strategy is now shared (this should not affect the  compatibility though)

SearchFactory

  • ContextHelper.getSearchFactory  is deprecated, prefer fullTextSession.getSearchFactory();
  • searchFactory.getDirectoryProvider(Class)  is now searchFactory.getDirectoryProviders(Class)

Dependencies

  • Lucene Core 2.2 is now used: your  index structure will be automatically migrated by Lucene.

 


Hibernate Search 3.0.0.Beta2

Query

  • All org.hibernate.search.query.FullTextQueryImpl casting should be replaced by org.hibernate.search.FullTextQuery casting
  • resultSize() has been renamed getResultSize()
  • Queries  restricting to one entity now use one SQL query rather than depending  on @BatchSize() when list() is used, the major impact is that  it's going to be faster
  • Query query = fullTextSession.createFullTextQuery(luceneQuery, book.class);
  • query.list();

Indexing

  • The build phase for Lucene  Documents is now done in the beforeCompletion phase of a  transaction, making the process insensible to LazyInitializationException.  There should be no impact to users that did not hit the bug.