org.compass.gps.device.jpa
Class JpaGpsDevice

java.lang.Object
  org.compass.gps.device.AbstractGpsDevice
      org.compass.gps.device.support.parallel.AbstractParallelGpsDevice
          org.compass.gps.device.jpa.JpaGpsDevice

All Implemented Interfaces:

CompassGpsDevice, MirrorDataChangesGpsDevice, PassiveMirrorGpsDevice

public class JpaGpsDevice
extends AbstractParallelGpsDevice
implements PassiveMirrorGpsDevice

A Java Persistence API Gps Device (EJB3 Persistence).

The jpa device provides support for using jpa to index a database. The path can be viewed as: Database <-> EntityManager(JPA) <-> Objects <-> Compass::Gps <-> Compass::Core (Search Engine). What it means is that for every object that has both jpa and compass mappings, you will be able to index it's data, as well as real time mirroring of data changes.

When creating the object, an EntityManagerFactory must be provided to the Device.

Indexing uses JpaEntitiesLocator to locate all the entities that can be indexed (i.e. entities that have both Compass and JPA mappings). Most of the time the DefaultJpaEntitiesLocator is enough, but special JPA implementation one can be provided. If none is provided, the device will use the JpaEntitiesLocatorDetector to auto detect the correct locator (which defaults to the (DefaultJpaEntitiesLocator).

The indexing process itself is done through an implementation of JpaIndexEntitiesIndexer. There are several implemenations for it including a default one that uses plain JPA APIs. Specific implementations (such as Hibernate and OpenJPA) are used for better performance.

Mirroring can be done in two ways. The first one is using JPA official API, implemeting an Entity Lifecycle listener and specifing it for each entity class via annotations. Compass comes with helper base clases for it, AbstractCompassJpaEntityListener and AbstractDeviceJpaEntityListener. As far as integrating Compass with JPA for mirroring, this is the less preferable way. The second option for mirroring is to use the JpaEntityLifecycleInjector, which will use the internal JPA implementation to inject global lifecycle event listerens (sadly, there is no option to do that with the EntityManagerFactory API). If the setInjectEntityLifecycleListener(boolean) is set to true (defaults to false), the device will try to use the injector to inject global event listeners. If no JpaEntityLifecycleInjector is defined, the device will try to autodetect the injector based on the current support for specific JPA implementations using the JpaEntityLifecycleInjectorDetector. See its javadoc for a list of the current JPA implementations supported.

Mirroring can be turned off using the setMirrorDataChanges(boolean) to false. It defaults to true.

The device allows for NativeJpaExtractor to be set, for applications that use a framework or by themself wrap the actual EntityManagerFactory implementation.

For advance usage, the device allows for EntityManagerWrapper to be set, allowing to control the creation of EntityManagers, and transactions. The DefaultEntityManagerWrapper should suffice for most cases.

The device extends the parallel device provinding supprot for parallel indexing.

Author:

kimchy

Field Summary

Fields inherited from class org.compass.gps.device.AbstractGpsDevice

compassGps, log

Constructor Summary

JpaGpsDevice()
Creates a new JpaGpsDevice.

JpaGpsDevice(String name, javax.persistence.EntityManagerFactory entityManagerFactory)
Creates a new device with a specific name and an entity manager factory.

Method Summary

protected IndexEntity[]	doGetIndexEntities() Returns all the indexed entities for this device.
protected IndexEntitiesIndexer	doGetIndexEntitiesIndexer() Returns an index entities indexer that knows how to index indexable entities.
protected void	doStart() Derived devices can implement it in case of start event notification.
protected void	doStop() Derived devices can implement it in case of stop event notification.
javax.persistence.EntityManagerFactory	getEntityManagerFactory()
EntityManagerWrapper	getEntityManagerWrapper() Returns the Entity Manager factory wrapper to control the entity manager operations.
int	getFetchCount() Returns the fetch count for the indexing process.
javax.persistence.EntityManagerFactory	getNativeEntityManagerFactory()
NativeJpaExtractor	getNativeJpaExtractor() Returns the native extractor.
boolean	isMirrorDataChanges() Should the device perform real time data mirroring.
void	refresh() A no op.
void	setEntitiesIndexer(JpaIndexEntitiesIndexer entitiesIndexer) Sets a custom entities indexer that will be used to index the data.
void	setEntitiesLocator(JpaEntitiesLocator entitiesLocator) Sets a specific enteties locator, which is responsible for locating enteties that need to be indexed.
void	setEntityManagerFactory(javax.persistence.EntityManagerFactory entityManagerFactory) Sets the Jpa EntityManagerFactory.
void	setEntityManagerWrapper(EntityManagerWrapper entityManagerWrapper) Sets the Entity Manager factory wrapper to control the entity manager operations.
void	setFetchCount(int fetchCount) Sets the fetch count for the indexing process.
void	setIndexEntityInfo(JpaIndexEntityInfo indexEntityInfo) Sets an index entity info that will control how the given entity will be indexed.
void	setIndexQueryProvider(Class<?> entityClass, JpaQueryProvider queryProvider) Sets a specific query provider for the index process of the given entity class.
void	setIndexQueryProvider(String entityName, JpaQueryProvider queryProvider) Sets a specific query provider for the index process of the given entity name.
void	setIndexSelectQuery(Class<?> entityClass, String selectQuery) Sets a specific select statement for the index process of the given entity class.
void	setIndexSelectQuery(String entityName, String selectQuery) Sets a specific select statement for the index process of the given entity name.
void	setInjectEntityLifecycleListener(boolean injectEntityLifecycleListener) Sets if the device should try and automatically inject global entity lifecycle listeners using either the provided JpaEntityLifecycleInjector, or if not set, using the JpaEntityLifecycleInjectorDetector.
void	setLifecycleInjector(JpaEntityLifecycleInjector lifecycleInjector) If the setLifecycleInjector(org.compass.gps.device.jpa.lifecycle.JpaEntityLifecycleInjector) is set to true, the global lifecycle injector that will be used to inject global lifecycle event listerens to the underlying implementation of the EntityManagerFactory.
void	setMirrorDataChanges(boolean mirrorDataChanges) Sets if the device will perform real time data changes mirroring.
void	setNativeExtractor(NativeJpaExtractor nativeJpaExtractor) Sets a specialized native entity manager factory extractor.

Methods inherited from class org.compass.gps.device.support.parallel.AbstractParallelGpsDevice

doIndex, index, setIndexEntitiesPartitioner, setParallelIndexExecutor, start

Methods inherited from class org.compass.gps.device.AbstractGpsDevice

buildMessage, getGps, getName, injectGps, isFilteredForIndex, isPerformingIndexOperation, isRunning, setFilteredEntitiesForIndex, setName, shouldMirrorDataChanges, stop

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.compass.gps.CompassGpsDevice

getGps, getName, index, injectGps, isPerformingIndexOperation, isRunning, setName, shouldMirrorDataChanges, start, stop

Constructor Detail

JpaGpsDevice

public JpaGpsDevice()

Creates a new JpaGpsDevice. Note that its name (AbstractGpsDevice.setName(String) and entity manager factory (setEntityManagerFactory(javax.persistence.EntityManagerFactory) must be set.

JpaGpsDevice

public JpaGpsDevice(String name,
                    javax.persistence.EntityManagerFactory entityManagerFactory)

Creates a new device with a specific name and an entity manager factory.

Method Detail

doStart

protected void doStart()
                throws CompassGpsException

Description copied from class: AbstractGpsDevice

Derived devices can implement it in case of start event notification.

Overrides:

doStart in class AbstractGpsDevice

Throws:

CompassGpsException

doStop

protected void doStop()
               throws CompassGpsException

Description copied from class: AbstractGpsDevice

Derived devices can implement it in case of stop event notification.

Overrides:

doStop in class AbstractGpsDevice

Throws:

CompassGpsException

refresh

public void refresh()
             throws CompassGpsException

Description copied from class: AbstractGpsDevice

A no op. Subclasses should overide only if needed.

Specified by:

refresh in interface CompassGpsDevice

Overrides:

refresh in class AbstractGpsDevice

Throws:

CompassGpsException

doGetIndexEntities

protected IndexEntity[] doGetIndexEntities()
                                    throws CompassGpsException

Description copied from class: AbstractParallelGpsDevice

Returns all the indexed entities for this device.

Specified by:

doGetIndexEntities in class AbstractParallelGpsDevice

Throws:

CompassGpsException

doGetIndexEntitiesIndexer

protected IndexEntitiesIndexer doGetIndexEntitiesIndexer()

Description copied from class: AbstractParallelGpsDevice

Returns an index entities indexer that knows how to index indexable entities.

Specified by:

doGetIndexEntitiesIndexer in class AbstractParallelGpsDevice

getEntityManagerFactory

public javax.persistence.EntityManagerFactory getEntityManagerFactory()

getNativeEntityManagerFactory

public javax.persistence.EntityManagerFactory getNativeEntityManagerFactory()

isMirrorDataChanges

public boolean isMirrorDataChanges()

Description copied from interface: MirrorDataChangesGpsDevice

Should the device perform real time data mirroring.

Specified by:

isMirrorDataChanges in interface MirrorDataChangesGpsDevice

Returns:

true if the device mirror data changes

See Also:

MirrorDataChangesGpsDevice.isMirrorDataChanges()

setMirrorDataChanges

public void setMirrorDataChanges(boolean mirrorDataChanges)

Description copied from interface: MirrorDataChangesGpsDevice

Sets if the device will perform real time data changes mirroring.

Specified by:

setMirrorDataChanges in interface MirrorDataChangesGpsDevice

Parameters:

mirrorDataChanges - Should the device mirror data changes

See Also:

MirrorDataChangesGpsDevice.setMirrorDataChanges(boolean)

setEntityManagerFactory

public void setEntityManagerFactory(javax.persistence.EntityManagerFactory entityManagerFactory)

Sets the Jpa EntityManagerFactory. This is manadatory for the Jpa device.

Parameters:

entityManagerFactory - The entity manager factory the device will use.

setEntityManagerWrapper

public void setEntityManagerWrapper(EntityManagerWrapper entityManagerWrapper)

Sets the Entity Manager factory wrapper to control the entity manager operations. This is optional since the device has sensible defaults for it.

Parameters:

entityManagerWrapper - The entity manager wrapper to control the manager operations.

getEntityManagerWrapper

public EntityManagerWrapper getEntityManagerWrapper()

Returns the Entity Manager factory wrapper to control the entity manager operations.

setNativeExtractor

public void setNativeExtractor(NativeJpaExtractor nativeJpaExtractor)

Sets a specialized native entity manager factory extractor. For applications that use a framework or by themself wrap the actual EntityManagerFactory implementation. The native extractor is mainly used for specialized JpaEntityLifecycleInjector and JpaEntitiesLocator.

getNativeJpaExtractor

public NativeJpaExtractor getNativeJpaExtractor()

Returns the native extractor.

setInjectEntityLifecycleListener

public void setInjectEntityLifecycleListener(boolean injectEntityLifecycleListener)

Sets if the device should try and automatically inject global entity lifecycle listeners using either the provided JpaEntityLifecycleInjector, or if not set, using the JpaEntityLifecycleInjectorDetector. Defaults to false.

setLifecycleInjector

public void setLifecycleInjector(JpaEntityLifecycleInjector lifecycleInjector)

If the setLifecycleInjector(org.compass.gps.device.jpa.lifecycle.JpaEntityLifecycleInjector) is set to true, the global lifecycle injector that will be used to inject global lifecycle event listerens to the underlying implementation of the EntityManagerFactory. If not set, the JpaEntitiesLocatorDetector will be used to auto-detect it.

setEntitiesLocator

public void setEntitiesLocator(JpaEntitiesLocator entitiesLocator)

Sets a specific enteties locator, which is responsible for locating enteties that need to be indexed. Not a required parameter, since will use the JpaEntitiesLocatorDetector to auto detect that correct one.

setFetchCount

public void setFetchCount(int fetchCount)

Sets the fetch count for the indexing process. A large number will perform the indexing faster, but will consume more memory. Defaults to 200.

getFetchCount

public int getFetchCount()

Returns the fetch count for the indexing process. A large number will perform the indexing faster, but will consume more memory. Default to 200.

setIndexSelectQuery

public void setIndexSelectQuery(Class<?> entityClass,
                                String selectQuery)

Sets a specific select statement for the index process of the given entity class. The same as setIndexQueryProvider(Class,JpaQueryProvider) using DefaultJpaQueryProvider.

Certain JPA implementations have specific query providers with possible enhanced functionality in regards to indexing. When using this method instead of providing their specific implementation might mean less functionality from the indexer.

Note, this information is used when the device starts.

Parameters:

entityClass - The Entity class to associate the select query with

selectQuery - The select query to execute when indexing the given entity

setIndexSelectQuery

public void setIndexSelectQuery(String entityName,
                                String selectQuery)

Sets a specific select statement for the index process of the given entity name. The same as setIndexQueryProvider(String,JpaQueryProvider) using DefaultJpaQueryProvider.

Certain JPA implementations have specific query providers with possible enhanced functionality in regards to indexing. When using this method instead of providing their specific implementation might mean less functionality from the indexer.

Note, this information is used when the device starts.

Parameters:

entityName - The entity name to associate the select query with

selectQuery - The select query to execute when indexing the given entity

setIndexQueryProvider

public void setIndexQueryProvider(Class<?> entityClass,
                                  JpaQueryProvider queryProvider)

Sets a specific query provider for the index process of the given entity class.

Note, this information is used when the device starts.

Parameters:

entityClass - The Entity class to associate the query provider with

queryProvider - The query provider to execute when indexing the given entity

setIndexQueryProvider

public void setIndexQueryProvider(String entityName,
                                  JpaQueryProvider queryProvider)

Sets a specific query provider for the index process of the given entity name.

Note, this information is used when the device starts.

Parameters:

entityName - The Entity name to associate the query provider with

queryProvider - The query provider to execute when indexing the given entity

setIndexEntityInfo

public void setIndexEntityInfo(JpaIndexEntityInfo indexEntityInfo)

Sets an index entity info that will control how the given entity will be indexed.

setEntitiesIndexer

public void setEntitiesIndexer(JpaIndexEntitiesIndexer entitiesIndexer)

Sets a custom entities indexer that will be used to index the data. By default will be detected automatically based on the actual implemenation of JPA used and will try to use it.