Chapter 17. Embedded Hibernate

17.1. Introduction

Compass allows for embedded integration with Hibernate and Hibernate JPA. Using simple configuration, Compass will automatically perform mirroring operations (mirroring changes done through Hibernate to the search engine), as well as allow to simply index the content of the database using Hibernate.

The integration involves few simple steps. The first is enabling Embedded Compass within Hibernate. If Hibernate Annotations or Hibernate EntityManager (JPA) are used, just dropping Compass jar file to the classpath will enable it (make sure you don't have Hibernate Search in the classpath, as it uses the same event class name :) ). If Hibernate Core is used, the following event listeners need to be configured:

  <!-- ... -->
  <event type="post-update">
      <listener class="org.compass.gps.device.hibernate.embedded.CompassEventListener"/>
  <event type="post-insert">
      <listener class="org.compass.gps.device.hibernate.embedded.CompassEventListener"/>
  <event type="post-delete">
      <listener class="org.compass.gps.device.hibernate.embedded.CompassEventListener"/>
  <event type="post-collection-recreate">
      <listener class="org.compass.gps.device.hibernate.embedded.CompassEventListener"/>
  <event type="post-collection-remove">
      <listener class="org.compass.gps.device.hibernate.embedded.CompassEventListener"/>
  <event type="post-collection-update">
      <listener class="org.compass.gps.device.hibernate.embedded.CompassEventListener"/>

Now that Compass is enabled with Hibernate there is one required Compass property in order to configure it which is the location of where the search engine index will be stored. This is configured as a Hibernate property configuration using the key compass.engine.connection (for example, having the value file://tmp/index). When it is configured, Compass will automatically use the mapped Hibernate classes and check if one of them is searchable. If there is at least one, then the listener will be enabled. That is it!. Now, every operation done using Hibernate will be mirrored to the search engine.

Direct access to the Compass (for example to execute search operations), either the HibernateHelper (when using pure Hibernate) or HibernateJpaHelper (when using Hibernate JPA) can be used to access it. For example:

Compass compass = HibernateHelper.getCompass(sessionFactory);
CompassSession session = compass.openSession();
CompassTransaction tr = session.beginTransaction();

CompassHits hits = session.find("search something")


In order to completely reindex the content of the database based on both the Hibernate and Compass mappings, a Compass Gps can be created. Here is an example of how to do it:

CompassGps gps = HibernateHelper.getCompassGps(sessionFactory);

17.2. Configuration

The basic configuration of embedded Hibernate is explained in the introduction section. Within the Hibernate (or JPA persistance xml) configuration, the Compass instance used for mirroring and searching can be configured using Compass usual properties (using the compass. prefix). If configuring Compass using external configuration is needed, the compass.hibernate.config can be used to point to Compass configuration file.

An implementation of HibernateMirrorFilter can also be configured in order to allow for filtering out specific objects from the index (for example, based on their specific content). The compass.hibernate.mirrorFilter property should be configured having the fully qualified class name of the mirroring filter implementation.

The Compass instance created automatically for the indexing operation can be also configured using specific properties. This properties should have the prefix of gps.index.. This is usually configured to have specific parameters for the indexing Compass, for example, having a different index storage location for it while indexing.

17.3. Transaction Management

Compass will integrate with Hibernate transaction management (using whichever transaction management it does) by default. When configuring Compass to work with JTA Sync or XA, Compass will integrate with these transaction management.