Compass has "native" integration with OpenJPA by working in an "embedded" mode within it. OpenJPA can be used with Chapter 18, JPA (Java Persistence API) and Compass has specific indexer and lifecycle for it, but Compass can also work from within OpenJPA and have OpenJPA control Compass creation and configuration.

Embedded Compass OpenJPA integration provides support for database indexing and mirroring through the use of the OpenJPA, an implementation of the EJB3 standard.

Compass OpenJPA integration utilizes Compass::Core OSEM feature (Object to Search Engine Mappings) and Jpa feature (Object to Relational Mappings) to provide simple database indexing. As well as OpenJPA support for life-cycle event based system to provide real time mirroring of data changes done through Jpa (see notes about real time mirroring later on). The path data travels through the system is: Database -- Jpa (Entity Manager) -- Objects -- Compass::Gps -- Compass::Core (Search Engine).

The Compass OpenJPA uses under the cover Chapter 18, JPA (Java Persistence API) and all configuration options apply when using it. The JPA Gps Device extends Compass Gps AbstractParallelGpsDevice and supports parallel index operations. It is discussed in more detail here: Section 14.5, “Parallel Device”.

Configuration of Embedded Compass OpenJPA integration is done within the persistence xml file (or programmatic Map configuration) using Compass support for properties based configuration. Here is the most simplest example of enabling Compass within OpenJPA (note, just having Compass jars within the classpath enable it!):

<persistence xmlns="http://java.sun.com/xml/ns/persistence" 
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
	xsi:schemaLocation="http://java.sun.com/xml/ns/persistence persistence_1_0.xsd" version="1.0">
	
	<persistence-unit name="embeddedopenjpa" transaction-type="RESOURCE_LOCAL">
	    <provider>org.apache.openjpa.persistence.PersistenceProviderImpl</provider>
	    <class>eg.Test</class>
	    <exclude-unlisted-classes>true</exclude-unlisted-classes>
	    <properties>
	        <property name="openjpa.jdbc.DBDictionary" value="hsql" />
	        <property name="openjpa.ConnectionDriverName" value="org.hsqldb.jdbcDriver" />
	        <property name="openjpa.ConnectionURL" value="jdbc:hsqldb:mem:test" />
	        <property name="openjpa.ConnectionUserName" value="sa" />
	        <property name="openjpa.ConnectionPassword" value="" />
	
			<!-- This will enable Comapss, this is also the single Compass configuration required -->
	        <property name="compass.engine.connection" value="target/test-index" />
	    </properties>
	</persistence-unit
</persistence>

Embedded Compass OpenJpa provides the ability to index a database (through the use of the JPA device). Indexing the database is simple and can be done using:

	OpenJPAHelper.getCompassGps(entityManagerFactory).index();

Specific configuration for the Compass index instance can be done using gps.index.compass. prefix. Internally the CompassGps implementation used is SingleCompassGps.

Several special properties can also be used. The first, compass.openjpa.reindexOnStartup (defaults to false) will cause Compass to reindex the database when it starts up. Another important configuration option is compass.openjpa.indexQuery.[entity name/class] which allows to plug a custom query string for indexing.

The embedded Compass OpenJPA integration will automatically register with OpenJPA for lifecycle events and mirror any operation performed using OpenJPA to the database. It also, automatically, integrates with OpenJPA transactions and commits/rollbacks a transaction when OpenJPA transaction commits/rollbacks.

OpenJPAHelper can be used to obtain the current open CompassSession and a Compass instance. Both can be obtained from an EntityManagerFactory or an EntityManager. Prime use case for obtaining a Compass session is to query the index. Note, when querying the index, the returned Objects are not "attached" to JPA, and loaded from the index. This is done for performance reasons as usually they will be used to display results to the user. Attaching them can be done simply by using JPA API.