Configuration for Hibernate Search

In this tutorial we will discuss about the Hibernate Search Configuration so Let’s start with the most basic configuration question – how do I enable Hibernate Search?
Enabling Hibernate Search-
Hibernate Search is enabled out of the box when detected on the classpath by Hibernate Core. If, for some reason you need to disable it, set hibernate.search.autoregister_listeners to false.
<property name="hibernate.search.autoregister_listeners">false</property>

Note: Note that there is no performance penalty when the listeners are enabled but no entities are annotated as indexed.

Automatic indexing-
By default, every time an object is inserted, updated or deleted through Hibernate, Hibernate Search updates the according Lucene index. It is sometimes desirable to disable that features if either your index is read-only or if index updates are done in a batch way.

To disable event based indexing, set

<property name="hibernate.search.indexing_strategy">manual</property>

Configuring the IndexManager
Hibernate Search provides two possible implementations for this interface to choose from.

  • directory-based: the default implementation which uses the Lucene Directory abstraction to manage index files.
  • near-real-time: avoid flushing writes to disk at each commit. This index manager is also Directory based, but also makes uses of Lucene’s NRT functionallity.

To select an alternative you specify the property:

<property name="hibernate.search.[default|<indexname>].indexmanager">near-real-time</property>

Custom – It is also possible to configure a custom IndexManager implementation by specifying the fully qualified class name of your custom implementation. This implementation must have a no-argument constructor:

<property name="hibernate.search.[default|<indexname>].indexmanager">my.corp.myapp.CustomIndexManager</property>

LockFactory configuration-
Lucene Directorys have default locking strategies which work generally good enough for most cases, but it’s possible to specify for each index managed by Hibernate Search a specific LockingFactory you want to use. This is generally not needed but could be useful.

Some of these locking strategies require a filesystem level lock and may be used even on RAM based indexes, this combination is valid but in this case the indexBase configuration option usually needed only for filesystem based Directory instances must be specified to point to a filesystem location where to store the lock marker files.

To select a locking factory, set the hibernate.search.<index>.locking_strategy option to one of simple, native, single or none. Alternatively set it to the fully qualified name of an implementation of org.hibernate.search.store.LockFactoryProvider.

<property name="hibernate.search.default.locking_strategy">none</property>

List of available LockFactory implementations-
1. simple-
Safe implementation based on Java’s File API, it marks the usage of the index by creating a marker file. If for some reason you had to kill your application, you will need to remove this file before restarting it. As does simple this also marks the usage of the index by creating a marker file, but this one is using native OS file locks so that even if the JVM is terminated the locks will be cleaned up.

<property name="hibernate.search.default.locking_strategy">simple</property>

2. native-
This implementation has known problems on NFS, avoid it on network shares. native is the default implementation for the filesystem, filesystem-master and filesystem-slave directory providers. This LockFactory doesn’t use a file marker but is a Java object lock held in memory; therefore it’s possible to use it only when you are sure the index is not going to be shared by any other process.

<property name="hibernate.search.default.locking_strategy">native</property>

3. single-
This is the default implementation for the ram directory provider.

<property name="hibernate.search.default.locking_strategy">single</property>

4. none-
All changes to this index are not coordinated by any lock; test your application carefully and make sure you know what it means.

<property name="hibernate.search.default.locking_strategy">none</property>

Exception Handling Configuration-
Hibernate Search allows you to configure how exceptions are handled during the indexing process. If no configuration is provided then exceptions are logged to the log output by default. It is possible to explicitly declare the exception logging mechanism as seen below:

<property name="hibernate.search.error_handler">log</property>

The default exception handling occurs for both synchronous and asynchronous indexing. Hibernate Search provides an easy mechanism to override the default error handling implementation.

In order to provide your own implementation you must implement the ErrorHandler interface, which provides the handle(ErrorContext context) method. ErrorContext provides a reference to the primary LuceneWork instance, the underlying exception and any subsequent LuceneWork instances that could not be processed due to the primary exception.

public interface ErrorContext {
   List<LuceneWork> getFailingOperations();
   LuceneWork getOperationAtFault();
   Throwable getThrowable();
   boolean hasErrors();
}

To register this error handler with Hibernate Search you must declare the fully qualified classname of your ErrorHandler implementation in the configuration properties:

<property name="hibernate.search.error_handler">CustomerErrorHandler</property>

Directory configuration-
The Directory implementation can be customized and Lucene comes bundled with a file system and an in-memory implementation. DirectoryProvider is the Hibernate Search abstraction around a Lucene Directory and handles the configuration and the initialization of the underlying Lucene resources.

The name of the index is given by the index property of the @Indexed annotation. If the index property is not specified the fully qualified name of the indexed class will be used as name (recommended). Knowing the index name, you can configure the directory provider and any additional options by using the prefix hibernate.search.<indexname>. The name default (hibernate.search.default) is reserved and can be used to define properties which apply to all indexes. Configuring directory providers” shows how hibernate.search.default.directory_provider is used to set the default directory provider to be the filesystem one. hibernate.search.default.indexBase sets then the default base directory for the indexes. As a result the index for the entity Status is created in /usr/lucene/indexes/org.hibernate.example.Status.

Specifying the index name-

package com.dineshonjava.example;

@Indexed
public class Status { ... }

@Indexed(index="Rules")
public class Rule { ... }

@Indexed(index="Actions")
public class Action { ... }

Configuring directory providers

<property name="hibernate.search.default.directory_provider">filesystem</property>
<property name="hibernate.search.default.indexBase">D:dojuploadindex</property>
<property name="hibernate.search.Rules.directory_provider">ram</property>
<property name="hibernate.search.Actions.directory_provider">com.acme.hibernate.CustomDirectoryProvider</property>
<<Previous <<   || Index ||   >>Next >>

Previous
Next