org.compass.gps.device.jpa
Class JpaGpsDevice

java.lang.Object
  extended by org.compass.gps.device.AbstractGpsDevice
      extended by org.compass.gps.device.support.parallel.AbstractParallelGpsDevice
          extended by 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.



Copyright (c) 2004-2009 The Compass Project.