Chapter 22. Embedded EclipseLink

22.1. Introduction

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

The integration involves few simple steps. The first is enabling Embedded Compass within EclipseLink. Within the persistence configuration (or when passing properties) a custom Compass EclipseLink session customizer needs to be defined:

<persistence-unit name="test" transaction-type="RESOURCE_LOCAL">
    <!-- ... (other properties) -->
    <property name="eclipselink.session.customizer" 
         value="org.compass.gps.device.jpa.embedded.eclipselink.CompassSessionCustomizer" />

Now that Compass is enabled with EclipseLink 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 Persistence Unit 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 EclipseLink classes and check if one of them is searchable. If there is at least one, then the it will be enabled. That is it!. Now, every operation done using EclipseLink will be mirrored to the search engine.

Direct access to Compass (for example to execute search operations), can be done using EclipseLinkHelper. For example:

Compass compass = EclipseLinkHelper.getCompass(entityManagerFactory);
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 EclipseLink and Compass mappings, a Compass Gps can be accessed. Here is an example of how to do it:

CompassGps gps = EclipseLinkHelper.getCompassGps(entityManagerFactory);

22.2. Configuration

The basic configuration of embedded EclipseLink is explained in the introduction section. Within the persistence 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.eclipselink.config can be used to point to Compass configuration file.

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.

22.3. Transaction Management

Compass will integrate with EclipseLink transaction management (using whichever transaction management it does) by default. If no Compass transaction factory is configured, Compass local transaction factory will be used when using JPA RESOURCE LOCAL transaction type, and JTA sync transaction factory will be used with JPA JTA one.