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

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

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

Now that Compass is enabled with TopLink 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 TopLink 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 TopLink will be mirrored to the search engine.

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

Compass compass = TopLinkHelper.getCompass(entityManagerFactory);
CompassSession session = compass.openSession();
CompassTransaction tr = session.beginTransaction();

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

tr.commit();
session.close();

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

CompassGps gps = TopLinkHelper.getCompassGps(entityManagerFactory);
gps.index();

The basic configuration of embedded TopLink Essentials 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.toplink.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.

Compass will integrate with TopLink 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.