Hibernate Search

The Hibernate Search artifacts can be found in Maven's central repository but are released first in the JBoss maven repository. So it's not a requirement but we recommend to add this repository to your settings.xml file (see also Maven Getting Started for more details).

This is all you need to add to your pom.xml to get started:

<dependency>

   <groupId>org.hibernate</groupId>

   <artifactId>hibernate-search</artifactId>

   <version>4.4.6.Final</version>

</dependency>

<dependency>

<!-- If using JPA (2), add: -->

<dependency>

   <groupId>org.hibernate</groupId>

   <artifactId>hibernate-entitymanager</artifactId>

   <version>4.2.7.SP1</version>

</dependency>

<!-- Additional Analyzers: -->

<dependency>

   <groupId>org.hibernate</groupId>

   <artifactId>hibernate-search-analyzers</artifactId>

   <version>4.4.6.Final</version>

</dependency>

<!-- Infinispan integration: -->

<dependency>

   <groupId>org.hibernate</groupId>

   <artifactId>hibernate-search-infinispan</artifactId>

   <version>4.4.6.Final</version>

</dependency>

Once you have downloaded and added all required dependencies to your application you have to add a couple of properties to your hibernate configuration file. If you are using Hibernate directly this can be done in hibernate.properties or hibernate.cfg.xml. If you are using Hibernate via JPA you can also add the properties to persistence.xml. The good news is that for standard use most properties offer a sensible default. An example persistence.xml configuration could look like this:

...

<property name="hibernate.search.default.directory_provider" 

          value="filesystem"/> 



<property name="hibernate.search.default.indexBase" 

          value="/var/lucene/indexes"/> 

...    

First you have to tell Hibernate Search which DirectoryProvider to use. This can be achieved by setting the hibernate.search.default.directory_provider property. Apache Lucene has the notion of a Directory to store the index files. Hibernate Search handles the initialization and configuration of a Lucene Directory instance via a DirectoryProvider. In this tutorial we will use a a directory provider storing the index in the file system. This will give us the ability to physically inspect the Lucene indexes created by Hibernate Search (eg via Luke). Once you have a working configuration you can start experimenting with other directory providers (see Section 3.3, “Directory configuration”). Next to the directory provider you also have to specify the default base directory for all indexes via hibernate.search.default.indexBase.

Lets assume that your application contains the Hibernate managed classes example.Book and example.Author and you want to add free text search capabilities to your application in order to search the books contained in your database.

package example;

...

@Entity

public class Book {


  @Id

  @GeneratedValue

  private Integer id; 


  private String title;  


  private String subtitle; 


  @ManyToMany 

  private Set<Author> authors = new HashSet<Author>();


  private Date publicationDate;

  

  public Book() {} 

  

  // standard getters/setters follow here

  ...

}

package example;

...

@Entity

public class Author {


  @Id

  @GeneratedValue

  private Integer id;


  private String name;


  public Author() {} 

 

  // standard getters/setters follow here

  ...

}

Next you have to mark the fields you want to make searchable. Let's start with title and subtitle and annotate both with @Field. The parameter index=Index.YES will ensure that the text will be indexed, while analyze=Analyze.YES ensures that the text will be analyzed using the default Lucene analyzer. Usually, analyzing means chunking a sentence into individual words and potentially excluding common words like 'a' or 'the'. We will talk more about analyzers a little later on. The third parameter we specify within @Field, store=Store.NO, ensures that the actual data will not be stored in the index. Whether this data is stored in the index or not has nothing to do with the ability to search for it. From Lucene's perspective it is not necessary to keep the data once the index is created. The benefit of storing it is the ability to retrieve it via projections ( see Section 5.1.3.5, “Projection”).

Without projections, Hibernate Search will per default execute a Lucene query in order to find the database identifiers of the entities matching the query critera and use these identifiers to retrieve managed objects from the database. The decision for or against projection has to be made on a case to case basis. The default behaviour is recommended since it returns managed objects whereas projections only return object arrays.

Note that index=Index.YES, analyze=Analyze.YES and store=Store.NO are the default values for these paramters and could be ommited.

After this short look under the hood let's go back to annotating the Book class. Another annotation we have not yet discussed is @DateBridge. This annotation is one of the built-in field bridges in Hibernate Search. The Lucene index is purely string based. For this reason Hibernate Search must convert the data types of the indexed fields to strings and vice versa. A range of predefined bridges are provided, including the DateBridge which will convert a java.util.Date into a String with the specified resolution. For more details see Section 4.4, “Bridges”.

This leaves us with @IndexedEmbedded. This annotation is used to index associated entities (@ManyToMany, @*ToOne, @Embedded and @ElementCollection) as part of the owning entity. This is needed since a Lucene index document is a flat data structure which does not know anything about object relations. To ensure that the authors' name will be searchable you have to make sure that the names are indexed as part of the book itself. On top of @IndexedEmbedded you will also have to mark all fields of the associated entity you want to have included in the index with @Indexed. For more details see Section 4.1.3, “Embedded and associated objects”.

These settings should be sufficient for now. For more details on entity mapping refer to Section 4.1, “Mapping an entity”.

package example;

...

@Entity
@Indexed

public class Book {


  @Id

  @GeneratedValue

  private Integer id;

  

  @Field(index=Index.YES, analyze=Analyze.YES, store=Store.NO)

  private String title;

  

  @Field(index=Index.YES, analyze=Analyze.YES, store=Store.NO)

  private String subtitle; 


  @Field(index = Index.YES, analyze=Analyze.NO, store = Store.YES)
  @DateBridge(resolution = Resolution.DAY)

  private Date publicationDate;


  @IndexedEmbedded

  @ManyToMany 

  private Set<Author> authors = new HashSet<Author>();

  

  public Book() {

  } 

  

  // standard getters/setters follow here

  ... 

}

package example;

...

@Entity

public class Author {


  @Id

  @GeneratedValue

  private Integer id;


  @Field

  private String name;


  public Author() {

  } 

 

  // standard getters/setters follow here

  ...

}

Hibernate Search will transparently index every entity persisted, updated or removed through Hibernate Core. However, you have to create an initial Lucene index for the data already present in your database. Once you have added the above properties and annotations it is time to trigger an initial batch index of your books. You can achieve this by using one of the following code snippets (see also Section 6.3, “Rebuilding the whole index”):

FullTextSession fullTextSession = Search.getFullTextSession(session);

fullTextSession.createIndexer().startAndWait();

EntityManager em = entityManagerFactory.createEntityManager();

FullTextEntityManager fullTextEntityManager = Search.getFullTextEntityManager(em);

fullTextEntityManager.createIndexer().startAndWait();

After executing the above code, you should be able to see a Lucene index under /var/lucene/indexes/example.Book. Go ahead an inspect this index with Luke. It will help you to understand how Hibernate Search works.

Now it is time to execute a first search. The general approach is to create a Lucene query, either via the Lucene API (Section 5.1.1, “Building a Lucene query using the Lucene API”) or via the Hibernate Search query DSL (Section 5.1.2, “Building a Lucene query with the Hibernate Search query DSL”), and then wrap this query into a org.hibernate.Query in order to get all the functionality one is used to from the Hibernate API. The following code will prepare a query against the indexed fields, execute it and return a list of Books.

FullTextSession fullTextSession = Search.getFullTextSession(session);

Transaction tx = fullTextSession.beginTransaction();


// create native Lucene query unsing the query DSL

// alternatively you can write the Lucene query using the Lucene query parser

// or the Lucene programmatic API. The Hibernate Search DSL is recommended though

QueryBuilder qb = fullTextSession.getSearchFactory()

    .buildQueryBuilder().forEntity(Book.class).get();

org.apache.lucene.search.Query query = qb

  .keyword()

  .onFields("title", "subtitle", "authors.name")

  .matching("Java rocks!")

  .createQuery();


// wrap Lucene query in a org.hibernate.Query

org.hibernate.Query hibQuery = 

    fullTextSession.createFullTextQuery(query, Book.class);


// execute search

List result = hibQuery.list();

  

tx.commit();

session.close();

EntityManager em = entityManagerFactory.createEntityManager();

FullTextEntityManager fullTextEntityManager = 

    org.hibernate.search.jpa.Search.getFullTextEntityManager(em);

em.getTransaction().begin();


// create native Lucene query unsing the query DSL

// alternatively you can write the Lucene query using the Lucene query parser

// or the Lucene programmatic API. The Hibernate Search DSL is recommended though

QueryBuilder qb = fullTextEntityManager.getSearchFactory()

    .buildQueryBuilder().forEntity(Book.class).get();

org.apache.lucene.search.Query query = qb

  .keyword()

  .onFields("title", "subtitle", "authors.name")

  .matching("Java rocks!")

  .createQuery();


// wrap Lucene query in a javax.persistence.Query

javax.persistence.Query persistenceQuery = 

    fullTextEntityManager.createFullTextQuery(query, Book.class);


// execute search

List result = persistenceQuery.getResultList();


em.getTransaction().commit();

em.close();

Let's make things a little more interesting now. Assume that one of your indexed book entities has the title "Refactoring: Improving the Design of Existing Code" and you want to get hits for all of the following queries: "refactor", "refactors", "refactored" and "refactoring". In Lucene this can be achieved by choosing an analyzer class which applies word stemming during the indexing as well as the search process. Hibernate Search offers several ways to configure the analyzer to be used (see Section 4.3.1, “Default analyzer and analyzer by class”):

When using the @Analyzer annotation one can either specify the fully qualified classname of the analyzer to use or one can refer to an analyzer definition defined by the @AnalyzerDef annotation. In the latter case the Solr analyzer framework with its factories approach is utilized. To find out more about the factory classes available you can either browse the Solr JavaDoc or read the corresponding section on the Solr Wiki.

In the example below a StandardTokenizerFactory is used followed by two filter factories, LowerCaseFilterFactory and SnowballPorterFilterFactory. The standard tokenizer splits words at punctuation characters and hyphens while keeping email addresses and internet hostnames intact. It is a good general purpose tokenizer. The lowercase filter lowercases the letters in each token whereas the snowball filter finally applies language specific stemming.

Generally, when using the Solr framework you have to start with a tokenizer followed by an arbitrary number of filters.

@Entity

@Indexed
@AnalyzerDef(name = "customanalyzer",
  tokenizer = @TokenizerDef(factory = StandardTokenizerFactory.class),
  filters = {
    @TokenFilterDef(factory = LowerCaseFilterFactory.class),
    @TokenFilterDef(factory = SnowballPorterFilterFactory.class, params = {
      @Parameter(name = "language", value = "English")
    })
  })

public class Book {


  @Id

  @GeneratedValue

  @DocumentId

  private Integer id;

  

  @Field

  @Analyzer(definition = "customanalyzer")

  private String title;

  

  @Field

  @Analyzer(definition = "customanalyzer")

  private String subtitle; 


  @IndexedEmbedded

  @ManyToMany 

  private Set<Author> authors = new HashSet<Author>();


  @Field(index = Index.YES, analyze = Analyze.NO, store = Store.YES)

  @DateBridge(resolution = Resolution.DAY)

  private Date publicationDate;

  

  public Book() {

  } 

  

  // standard getters/setters follow here

  ... 

}

The above paragraphs helped you getting an overview of Hibernate Search. The next step after this tutorial is to get more familiar with the overall architecture of Hibernate Search (Chapter 2, Architecture) and explore the basic features in more detail. Two topics which were only briefly touched in this tutorial were analyzer configuration (Section 4.3.1, “Default analyzer and analyzer by class”) and field bridges (Section 4.4, “Bridges”). Both are important features required for more fine-grained indexing. More advanced topics cover clustering (Section 3.4.1, “JMS Master/Slave back end”, Section 3.3.1, “Infinispan Directory configuration”) and large index handling (Section 10.4, “Sharding indexes”).

Hibernate Search consists of an indexing component as well as an index search component. Both are backed by Apache Lucene.

Each time an entity is inserted, updated or removed in/from the database, Hibernate Search keeps track of this event (through the Hibernate event system) and schedules an index update. All these updates are handled without you having to interact with the Apache Lucene APIs directly (see Section 3.1, “Enabling Hibernate Search and automatic indexing”). Instead, the interaction with the underlying Lucene indexes is handled via so called IndexManagers.

Each Lucene index is managed by one index manager which is uniquely identified by name. In most cases there is also a one to one relationship between an indexed entity and a single IndexManager. The exceptions are the use cases of index sharding and index sharing. The former can be applied when the index for a single entity becomes too big and indexing operations are slowing down the application. In this case a single entity is indexed into multiple indexes each with its own index manager (see Section 10.4, “Sharding indexes”). The latter, index sharing, is the ability to index multiple entities into the same Lucene index (see Section 10.5, “Sharing indexes”).

The index manager abstracts from the specific index configuration. In the case of the default index manager this includes details about the selected backend, the configured reader strategy and the chosen DirectoryProvider. These components will be discussed in greater detail later on. It is recommended that you start with the default index manager which uses different Lucene Directory types to manage the indexes (see Section 3.3, “Directory configuration”). You can, however, also provide your own IndexManager implementation (see Section 3.2, “Configuring the IndexManager”).

Once the index is created, you can search for entities and return lists of managed entities saving you the tedious object to Lucene Document mapping. The same persistence context is shared between Hibernate and Hibernate Search. As a matter of fact, the FullTextSession is built on top of the Hibernate Session so that the application code can use the unified org.hibernate.Query or javax.persistence.Query APIs exactly the same way a HQL, JPA-QL or native query would do.

To be more efficient Hibernate Search batches the write interactions with the Lucene index. This batching is the responsibility of the Worker. There are currently two types of batching. Outside a transaction, the index update operation is executed right after the actual database operation. This is really a no batching setup. In the case of an ongoing transaction, the index update operation is scheduled for the transaction commit phase and discarded in case of transaction rollback. The batching scope is the transaction. There are two immediate benefits:

You can think of those two batch modes (no scope vs transactional) as the equivalent of the (infamous) autocommit vs transactional behavior. From a performance perspective, the in transaction mode is recommended. The scoping choice is made transparently. Hibernate Search detects the presence of a transaction and adjust the scoping (see Section 3.4, “Worker configuration”).

Hibernate Search offers the ability to let the batched work being processed by different back ends. Several back ends are provided out of the box and you have the option to plugin your own. It is important to understand that in this context back end encompasses more than just the configuration option hibernate.search.default.worker.backend. This property just specifies a implementation of the BackendQueueProcessor interface which is a part of a back end configuration. In most cases, however, additional configuration settings are needed to successfully configure a specific backend setup, like for example the JMS back end.

2.2.1. Lucene

In this mode, all index update operations applied on a given node (JVM) will be executed to the Lucene directories (through the directory providers) by the same node. This mode is typically used in non clustered environment or in clustered environments where the directory store is shared.

Lucene back end configuration.

This mode targets non clustered applications, or clustered applications where the Directory is taking care of the locking strategy.

The main advantage is simplicity and immediate visibility of the changes in Lucene queries (a requirement in some applications).

An alternative back end viable for non-clustered and non-shared index configurations is the near-real-time backend.

2.2.2. JMS

All index update operations applied on a given node are sent to a JMS queue. A unique reader will then process the queue and update the master index. The master index is then replicated on a regular basis to the slave copies. This is known as the master/slaves pattern. The master is the sole responsible for updating the Lucene index. The slaves can accept read as well as write operations. However, they only process the read operation on their local index copy and delegate the update operations to the master.

JMS back end configuration.

This mode targets clustered environments where throughput is critical, and index update delays are affordable. Reliability is ensured by the JMS provider and by having the slaves working on a local copy of the index.

When executing a query, Hibernate Search interacts with the Apache Lucene indexes through a reader strategy. Choosing a reader strategy will depend on the profile of the application (frequent updates, read mostly, asynchronous index update etc). See also Section 3.5, “Reader strategy configuration”

Let's start with the most basic configuration question - how do I enable Hibernate Search?

hibernate.search.indexing_strategy = manual

The role of the index manager component is described in Chapter 2, Architecture. Hibernate Search provides two possible implementations for this interface to choose from.

To select an alternative you specify the property:

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

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

As we have seen in Section 3.2, “Configuring the IndexManager” the default index manager uses Lucene's notion of a Directory to store the index files. 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. Table 3.1, “List of built-in DirectoryProvider” shows the list of the directory providers available in Hibernate Search together with their corresponding options.

To configure your DirectoryProvider you have to understand that each indexed entity is associated to a Lucene index (except of the case where multiple entities share the same index - Section 10.5, “Sharing indexes”). 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. Example 3.2, “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.

The index for the Rule entity, however, is using an in-memory directory, because the default directory provider for this entity is overridden by the property hibernate.search.Rules.directory_provider.

Finally the Action entity uses a custom directory provider CustomDirectoryProvider specified via hibernate.search.Actions.directory_provider.

package org.hibernate.example;


@Indexed

public class Status { ... }


@Indexed(index="Rules")

public class Rule { ... }


@Indexed(index="Actions")

public class Action { ... }

hibernate.search.default.directory_provider = filesystem
hibernate.search.default.indexBase = /usr/lucene/indexes
hibernate.search.Rules.directory_provider = ram
hibernate.search.Actions.directory_provider = com.acme.hibernate.CustomDirectoryProvider

<dependency>

   <groupId>org.hibernate</groupId>

   <artifactId>hibernate-search</artifactId>

   <version>4.4.6.Final</version>

</dependency>

<dependency>

   <groupId>org.hibernate</groupId>

   <artifactId>hibernate-search-infinispan</artifactId>

   <version>4.4.6.Final</version>

</dependency>

hibernate.search.[default|<indexname>].directory_provider = infinispan

hibernate.search.infinispan.cachemanager_jndiname = [jndiname]

hibernate.search.infinispan.configuration_resourcename = [infinispan configuration filename]

It is possible to refine how Hibernate Search interacts with Lucene through the worker configuration. There exist several architectural components and possible extension points. Let's have a closer look.

First there is a Worker. An implementation of the Worker interface is responsible for receiving all entity changes, queuing them by context and applying them once a context ends. The most intuitive context, especially in connection with ORM, is the transaction. For this reason Hibernate Search will per default use the TransactionalWorker to scope all changes per transaction. One can, however, imagine a scenario where the context depends for example on the number of entity changes or some other application (lifecycle) events. For this reason the Worker implementation is configurable as shown in Table 3.2, “Scope configuration”.

Once a context ends it is time to prepare and apply the index changes. This can be done synchronously or asynchronously from within a new thread. Synchronous updates have the advantage that the index is at all times in sync with the databases. Asynchronous updates, on the other hand, can help to minimize the user response time. The drawback is potential discrepancies between database and index states. Lets look at the configuration options shown in Table 3.3, “Execution configuration”.

So far all work is done within the same Virtual Machine (VM), no matter which execution mode. The total amount of work has not changed for the single VM. Luckily there is a better approach, namely delegation. It is possible to send the indexing work to a different server by configuring hibernate.search.default.worker.backend - see Table 3.4, “Backend configuration”. Again this option can be configured differently for each index.

3.4.1. JMS Master/Slave back end

This section describes in greater detail how to configure the Master/Slave Hibernate Search architecture.

JMS back end configuration.

3.4.1.1. Slave nodes

Every index update operation is sent to a JMS queue. Index querying operations are executed on a local index copy.

Example 3.4. JMS Slave configuration

### slave configuration

## DirectoryProvider
# (remote) master location
hibernate.search.default.sourceBase = /mnt/mastervolume/lucenedirs/mastercopy

# local copy location
hibernate.search.default.indexBase = /Users/prod/lucenedirs

# refresh every half hour
hibernate.search.default.refresh = 1800

# appropriate directory provider
hibernate.search.default.directory_provider = filesystem-slave

## Backend configuration
hibernate.search.default.worker.backend = jms
hibernate.search.default.worker.jms.connection_factory = /ConnectionFactory
hibernate.search.default.worker.jms.queue = queue/hibernatesearch
#optionally authentication credentials:
hibernate.search.default.worker.jms.login = myname
hibernate.search.default.worker.jms.password = wonttellyou
#optional jndi configuration (check your JMS provider for more information)

## Optional asynchronous execution strategy
# hibernate.search.default.worker.execution = async
# hibernate.search.default.worker.thread_pool.size = 2
# hibernate.search.default.worker.buffer_queue.max = 50

Tip

A file system local copy is recommended for faster search results.

3.4.1.2. Master node

Every index update operation is taken from a JMS queue and executed. The master index is copied on a regular basis.

Example 3.5. JMS Master configuration

### master configuration

## DirectoryProvider
# (remote) master location where information is copied to
hibernate.search.default.sourceBase = /mnt/mastervolume/lucenedirs/mastercopy

# local master location
hibernate.search.default.indexBase = /Users/prod/lucenedirs

# refresh every half hour
hibernate.search.default.refresh = 1800

# appropriate directory provider
hibernate.search.default.directory_provider = filesystem-master

## Backend configuration
#Backend is the default lucene one

Tip

It is recommended that the refresh period be higher than the expected copy time; if a copy operation is still being performed when the next refresh triggers, the second refresh is skipped: it's safe to set this value low even when the copy time is not known.

In addition to the Hibernate Search framework configuration, a Message Driven Bean has to be written and set up to process the index works queue through JMS.

Example 3.6. Message Driven Bean processing the indexing queue

@MessageDriven(activationConfig = {

      @ActivationConfigProperty(propertyName="destinationType", 

                                propertyValue="javax.jms.Queue"),

      @ActivationConfigProperty(propertyName="destination", 

                                propertyValue="queue/hibernatesearch"),

      @ActivationConfigProperty(propertyName="DLQMaxResent", propertyValue="1")

   } )

public class MDBSearchController extends AbstractJMSHibernateSearchController 

                                 implements MessageListener {

    @PersistenceContext EntityManager em;

    

    //method retrieving the appropriate session

    protected Session getSession() {

        return (Session) em.getDelegate();

    }


    //potentially close the session opened in #getSession(), not needed here

    protected void cleanSessionIfNeeded(Session session) 

    }

}

This example inherits from the abstract JMS controller class available in the Hibernate Search source code and implements a JavaEE MDB. This implementation is given as an example and can be adjusted to make use of non Java EE Message Driven Beans. For more information about the getSession() and cleanSessionIfNeeded(), please check AbstractJMSHibernateSearchController's javadoc.

### slave configuration
hibernate.search.default.worker.backend = jgroupsSlave     

### master configuration
hibernate.search.default.worker.backend = jgroupsMaster   

### automatic configuration
hibernate.search.default.worker.backend = jgroups  

hibernate.search.services.jgroups.clusterName = My-Custom-Cluster-Id

import org.hibernate.search.backend.impl.jgroups.JGroupsChannelProvider;


org.jgroups.JChannel channel = ...

Map<String,String> properties = new HashMap<String,String)(1);

properties.put( JGroupsChannelProvider.CHANNEL_INJECT, channel );

EntityManagerFactory emf = Persistence.createEntityManagerFactory( "userPU", properties );

The different reader strategies are described in Reader strategy. Out of the box strategies are:

The default reader strategy is shared. This can be adjusted:

hibernate.search.[default|<indexname>].reader.strategy = not-shared

Adding this property switches to the not-shared strategy.

Or if you have a custom reader strategy:

hibernate.search.[default|<indexname>].reader.strategy = my.corp.myapp.CustomReaderProvider

where my.corp.myapp.CustomReaderProvider is the custom strategy implementation.

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:

hibernate.search.error_handler = log

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:

hibernate.search.error_handler = CustomerErrorHandler

Even though Hibernate Search will try to shield you as much as possible from Lucene specifics, there are several Lucene specifics which can be directly configured, either for performance reasons or for satisfying a specific usecase. The following sections discuss these configuration options.

hibernate.search.[default|<indexname>].indexwriter.<parameter_name>

hibernate.search.Animals.2.indexwriter.max_merge_docs = 10
hibernate.search.Animals.2.indexwriter.merge_factor = 20
hibernate.search.Animals.2.indexwriter.term_index_interval = default
hibernate.search.default.indexwriter.max_merge_docs = 100
hibernate.search.default.indexwriter.ram_buffer_size = 64

hibernate.search.[default|<indexname>].worker.backend blackhole

//to be fairly confident no files grow above 15MB, use:
hibernate.search.default.indexwriter.ram_buffer_size = 10
hibernate.search.default.indexwriter.merge_max_optimize_size = 7
hibernate.search.default.indexwriter.merge_max_size = 7

hibernate.search.default.locking_strategy = simple
hibernate.search.Animals.locking_strategy = native
hibernate.search.Books.locking_strategy = org.custom.components.MyLockingFactory

hibernate.search.lucene_version = LUCENE_30

After looking at all these different configuration options, it is time to have a look at an API which allows you to prorgammatically access parts of the configuration. Via the metadata API you can determine the indexed types and also how they are mapped (see Chapter 4, Mapping entities to the index structure) to the index structure. The entry point into this API is the SearchFactory. It offers two methods, namely getIndexedTypes() and getIndexedTypeDescriptor(Class<?>). The former returns a set of all indexed type, where as the latter allows to retrieve a so called IndexedTypeDescriptorfor a gven type. This descriptor allows you determine whether the type is indexed at all and, if so, whether the index is for example sharded or not (see Section 10.4, “Sharding indexes”). It also allows you to determine the static boost of the type (see Section 4.2.1, “Static index time boosting”) as well as its dynamic boost strategy (see Section 4.2.2, “Dynamic index time boosting”). Most importantly, however, you get information about the indexed properties and generated Lucene Document fields. This is exposed via PropertyDescriptors respectively FieldDescriptors. The easiest way to get to know the API is to explore it via the IDE or its javadocs.

Provided you're deploying on JBoss AS 7.x or JBoss EAP 6.x, there is an additional way to add the search dependencies to your application.

In JBoss AS 7 class loading is based on modules that have to define explicit dependencies on other modules. Modules allow to share the same artifacts across multiple applications getting you smaller and quicker deployments.

More details about modules are described in Class Loading in AS7.

You can download the pre-packaged Hibernate Search modules from:

Unpack the modules in your JBoss AS modules directory: this will create modules for Hibernate Search, Apache Lucene and some useful Solr libraries. The Hibernate Search modules are:

There are two ways to include the dependencies in your project:

In Chapter 1, Getting started you have already learned that all the metadata information needed to index entities is described through annotations. There is no need for xml mapping files. You can still use Hibernate mapping files for the basic Hibernate configuration, but the Hibernate Search specific configuration has to be expressed via annotations.

@Entity
@Indexed
public class Essay {
    ...
}

public class BigDecimalNumericFieldBridge extends NumericFieldBridge {

   private static final BigDecimal storeFactor = BigDecimal.valueOf(100);


   @Override

   public void set(String name, Object value, Document document, LuceneOptions luceneOptions) {

      if ( value != null ) {

         BigDecimal decimalValue = (BigDecimal) value;

         Long indexedValue = Long.valueOf( decimalValue.multiply( storeFactor ).longValue() );

         luceneOptions.addNumericFieldToDocument( name, indexedValue, document );

      }

   }


    @Override

    public Object get(String name, Document document) {

        String fromLucene = document.get( name );

        BigDecimal storedBigDecimal = new BigDecimal( fromLucene );

        return storedBigDecimal.divide( storeFactor );

    }


}

@Entity

@Indexed

public static class Item {

    @Id

    @GeneratedValue

    private int id;


    @Field

    @NumericField

    @FieldBridge(impl = BigDecimalNumericFieldBridge.class)

    private BigDecimal price;


    public int getId() {

        return id;

    }


    public BigDecimal getPrice() {

       return price;

    }


    public void setPrice(BigDecimal price) {

        this.price = price;

    }

}

@Entity

@Indexed

public class Essay {

    ...


    @Id

    @DocumentId

    public Long getId() { return id; }


    @Field(name="Abstract", store=Store.YES)

    public String getSummary() { return summary; }


    @Lob

    @Field

    public String getText() { return text; }


    @Field 
    @NumericField(precisionStep = 6)

    public float getGrade() { return grade; }

}

@Entity

@Indexed(index = "Book")

public class Book {

    @Fields( {

            @Field,

            @Field(name = "summary_forSort", analyze = Analyze.NO, store = Store.YES)

            } )

    public String getSummary() {

        return summary;

    }


    ...

}

@Entity

@Indexed

public class Place {

    @Id

    @GeneratedValue

    @DocumentId

    private Long id;


    @Field

    private String name;


    @OneToOne(cascade = { CascadeType.PERSIST, CascadeType.REMOVE })

    @IndexedEmbedded

    private Address address;

    ....

}


@Entity

public class Address {

    @Id

    @GeneratedValue

    private Long id;


    @Field

    private String street;


    @Field

    private String city;


    @ContainedIn

    @OneToMany(mappedBy="address")

    private Set<Place> places;

    ...

}

@Entity

@Indexed

public class Place {

    @Id

    @GeneratedValue

    @DocumentId

    private Long id;


    @Field

    private String name;


    @OneToOne(cascade = { CascadeType.PERSIST, CascadeType.REMOVE })

    @IndexedEmbedded

    private Address address;

    ....

}


@Entity

public class Address {

    @Id

    @GeneratedValue

    private Long id;


    @Field

    private String street;


    @Field

    private String city;


    @IndexedEmbedded(depth = 1, prefix = "ownedBy_")

    private Owner ownedBy;


    @ContainedIn

    @OneToMany(mappedBy="address")

    private Set<Place> places;

    ...

}


@Embeddable

public class Owner {

    @Field

    private String name;

   ...

}

@Entity

@Indexed

public class Address {

    @Id

    @GeneratedValue

    @DocumentId

    private Long id;


    @Field

    private String street;


    @IndexedEmbedded(depth = 1, prefix = "ownedBy_", targetElement = Owner.class)

    @Target(Owner.class)

    private Person ownedBy;


    ...

}


@Embeddable

public class Owner implements Person { ... }

@Entity

@Indexed

public class Person {


   @Id

   public int getId() {

      return id;

   }


   @Field

   public String getName() {

      return name;

   }


   @Field

   public String getSurname() {

      return surname;

   }


   @OneToMany

   @IndexedEmbedded(includePaths = { "name" })

   public Set<Person> getParents() {

      return parents;

   }


   @ContainedIn

   @ManyToOne

   public Human getChild() {

      return child;

   }


    ...//other fields omitted

@Entity

@Indexed

public class Human {


   @Id

   public int getId() {

      return id;

   }


   @Field

   public String getName() {

      return name;

   }


   @Field

   public String getSurname() {

      return surname;

   }


   @OneToMany

   @IndexedEmbedded(depth = 2, includePaths = { "parents.parents.name" })

   public Set<Human> getParents() {

      return parents;

   }


   @ContainedIn

   @ManyToOne

   public Human getChild() {

      return child;

   }


    ...//other fields omitted

Lucene has the notion of boosting which allows you to give certain documents or fields more or less importance than others. Lucene differentiates between index and search time boosting. The following sections show you how you can achieve index time boosting using Hibernate Search.

@Entity
@Indexed
@Boost(1.7f)
public class Essay {
    ...

    @Id
    @DocumentId
    public Long getId() { return id; }

    @Field(name="Abstract", store=Store.YES, boost=@Boost(2f))
    @Boost(1.5f)
    public String getSummary() { return summary; }

    @Lob
    @Field(boost=@Boost(1.2f))
    public String getText() { return text; }

    @Field
    public String getISBN() { return isbn; }

}        

public enum PersonType {

    NORMAL,

    VIP

}


@Entity

@Indexed
@DynamicBoost(impl = VIPBoostStrategy.class)

public class Person {

    private PersonType type;   

    

    // ....

}


public class VIPBoostStrategy implements BoostStrategy {

    public float defineBoost(Object value) {

        Person person = ( Person ) value;

        if ( person.getType().equals( PersonType.VIP ) ) {

            return 2.0f;

        }

        else {

            return 1.0f;

        }

    }

}

Analysis is the process of converting text into single terms (words) and can be considered as one of the key features of a fulltext search engine. Lucene uses the concept of Analyzers to control this process. In the following section we cover the multiple ways Hibernate Search offers to configure the analyzers.

@Entity

@Indexed
@Analyzer(impl = EntityAnalyzer.class)

public class MyEntity {

    @Id

    @GeneratedValue

    @DocumentId

    private Integer id;


    @Field

    private String name;


    @Field

    @Analyzer(impl = PropertyAnalyzer.class)

    private String summary;


    @Field(analyzer = @Analyzer(impl = FieldAnalyzer.class)

    private String body;


    ...

}

<dependency>
   <groupId>org.hibernate</groupId>
   <artifactId>hibernate-search-analyzers</artifactId>
   <version>4.4.6.Final</version>
<dependency>

@AnalyzerDef(name="customanalyzer",

  charFilters = {

    @CharFilterDef(factory = MappingCharFilterFactory.class, params = {

      @Parameter(name = "mapping",

        value = "org/hibernate/search/test/analyzer/solr/mapping-chars.properties")

    })

  },

  tokenizer = @TokenizerDef(factory = StandardTokenizerFactory.class),

  filters = {

    @TokenFilterDef(factory = ISOLatin1AccentFilterFactory.class),

    @TokenFilterDef(factory = LowerCaseFilterFactory.class),

    @TokenFilterDef(factory = StopFilterFactory.class, params = {

      @Parameter(name="words",

        value= "org/hibernate/search/test/analyzer/solr/stoplist.properties" ),

      @Parameter(name="ignoreCase", value="true")

    })

})

public class Team {

    ...

}

@AnalyzerDef(name="customanalyzer",

  charFilters = {

    @CharFilterDef(factory = MappingCharFilterFactory.class, params = {

      @Parameter(name = "mapping",

        value = "org/hibernate/search/test/analyzer/solr/mapping-chars.properties")

    })

  },

  tokenizer = @TokenizerDef(factory = StandardTokenizerFactory.class),

  filters = {

    @TokenFilterDef(factory = ISOLatin1AccentFilterFactory.class),

    @TokenFilterDef(factory = LowerCaseFilterFactory.class),

    @TokenFilterDef(factory = StopFilterFactory.class, params = {

      @Parameter(name="words",

        value= "org/hibernate/search/test/analyzer/solr/stoplist.properties" ),

      @Parameter(name="resource_charset", value = "UTF-16BE"),

      @Parameter(name="ignoreCase", value="true")

  })

})

public class Team {

    ...

}

@Entity

@Indexed

@AnalyzerDef(name="customanalyzer", ... )

public class Team {

    @Id

    @DocumentId

    @GeneratedValue

    private Integer id;


    @Field

    private String name;


    @Field

    private String location;


    @Field 

    @Analyzer(definition = "customanalyzer")

    private String description;

}

Analyzer analyzer = fullTextSession.getSearchFactory().getAnalyzer("customanalyzer");

@Entity

@Indexed

@AnalyzerDefs({

  @AnalyzerDef(name = "en",

    tokenizer = @TokenizerDef(factory = StandardTokenizerFactory.class),

    filters = {

      @TokenFilterDef(factory = LowerCaseFilterFactory.class),

      @TokenFilterDef(factory = EnglishPorterFilterFactory.class

      )

    }),

  @AnalyzerDef(name = "de",

    tokenizer = @TokenizerDef(factory = StandardTokenizerFactory.class),

    filters = {

      @TokenFilterDef(factory = LowerCaseFilterFactory.class),

      @TokenFilterDef(factory = GermanStemFilterFactory.class)

    })

})

public class BlogEntry {


    @Id

    @GeneratedValue

    @DocumentId

    private Integer id;


    @Field

    @AnalyzerDiscriminator(impl = LanguageDiscriminator.class)

    private String language;

    

    @Field

    private String text;

    

    private Set<BlogEntry> references;


    // standard getter/setter

    ...

}

public class LanguageDiscriminator implements Discriminator {


    public String getAnalyzerDefinitionName(Object value, Object entity, String field) {

        if ( value == null || !( entity instanceof Article ) ) {

            return null;

        }

        return (String) value;


    }

}

org.apache.lucene.queryParser.QueryParser parser = new QueryParser(

    "title", 

    fullTextSession.getSearchFactory().getAnalyzer( Song.class )

);


org.apache.lucene.search.Query luceneQuery = 

    parser.parse( "title:sky Or title_stemmed:diamond" );


org.hibernate.Query fullTextQuery = 

    fullTextSession.createFullTextQuery( luceneQuery, Song.class );


List result = fullTextQuery.list(); //return a list of managed objects

When discussing the basic mapping for an entity one important fact was so far disregarded. In Lucene all index fields have to be represented as strings. All entity properties annotated with @Field have to be converted to strings to be indexed. The reason we have not mentioned it so far is, that for most of your properties Hibernate Search does the translation job for you thanks to a set of built-in bridges. However, in some cases you need a more fine grained control over the translation process.

@Entity

@Indexed

public class Song {

    @Id

    @GeneratedValue

    long id;


    @Field

    @TikaBridge(metadataProcessor = Mp3TikaMetadataProcessor.class)

    String mp3FileName;


    [...]

}

QueryBuilder queryBuilder = fullTextSession.getSearchFactory()

    .buildQueryBuilder()

    .forEntity( Song.class )

    .get();

Query query = queryBuilder.keyword()

    .onField( "mp3FileName" )

    .ignoreFieldBridge()   //mandatory

    .matching( "Apes" )

    .createQuery();

List result = fullTextSession.createFullTextQuery( query ).list();

/**

 * Padding Integer bridge.

 * All numbers will be padded with 0 to match 5 digits

 *

 * @author Emmanuel Bernard

 */

public class PaddedIntegerBridge implements StringBridge {


    private int padding = 5;


    public String objectToString(Object object) {

        String rawInteger = ((Integer) object).toString();

        if (rawInteger.length() > padding)

            throw new IllegalArgumentException("Number too big to be padded");

        StringBuilder paddedInteger = new StringBuilder();

        for (int padIndex = rawInteger.length(); padIndex < padding; padIndex++) {

            paddedInteger.append('0');

        }

        return paddedInteger.append( rawInteger ).toString();

    }

}                

@FieldBridge(impl = PaddedIntegerBridge.class)

private Integer length;                

public class PaddedIntegerBridge implements StringBridge, ParameterizedBridge {


    public static String PADDING_PROPERTY = "padding";

    private int padding = 5; //default


    public void setParameterValues(Map<String,String> parameters) {

        String padding = parameters.get( PADDING_PROPERTY );

        if (padding != null) this.padding = Integer.parseInt( padding );

    }


    public String objectToString(Object object) {

        String rawInteger = ((Integer) object).toString();

        if (rawInteger.length() > padding) 

            throw new IllegalArgumentException("Number too big to be padded");

        StringBuilder paddedInteger = new StringBuilder( );

        for (int padIndex = rawInteger.length(); padIndex < padding; padIndex++) {

            paddedInteger.append('0');

        }

        return paddedInteger.append(rawInteger).toString();

    }

}


//on the property:

@FieldBridge(impl = PaddedIntegerBridge.class,

             params = @Parameter(name="padding", value="10")

            )

private Integer length;                

public class PaddedIntegerBridge implements TwoWayStringBridge, ParameterizedBridge {


    public static String PADDING_PROPERTY = "padding";

    private int padding = 5; //default


    public void setParameterValues(Map parameters) {

        Object padding = parameters.get(PADDING_PROPERTY);

        if (padding != null) this.padding = (Integer) padding;

    }


    public String objectToString(Object object) {

        String rawInteger = ((Integer) object).toString();

        if (rawInteger.length() > padding) 

            throw new IllegalArgumentException("Number too big to be padded");

        StringBuilder paddedInteger = new StringBuilder();

        for (int padIndex = rawInteger.length(); padIndex < padding ; padIndex++) {

            paddedInteger.append('0');

        }

        return paddedInteger.append(rawInteger).toString();

    }


    public Object stringToObject(String stringValue) {

        return new Integer(stringValue);

    }

}


//On an id property:

@DocumentId

@FieldBridge(impl = PaddedIntegerBridge.class,

             params = @Parameter(name="padding", value="10") 

private Integer id;