com.ibm.websphere.objectgrid.jpa
Class JPATxCallback

java.lang.Object
  com.ibm.websphere.objectgrid.jpa.JPATxCallback

All Implemented Interfaces:

EventListener, ObjectGridEventGroup.ShardEvents, ObjectGridEventListener, TransactionCallback

public class JPATxCallback
extends Object
implements TransactionCallback, ObjectGridEventListener, ObjectGridEventGroup.ShardEvents

This transaction callback implementation is used for ObjectGrid built-in Java Persistence API (JPA) loaders. It coordinates ObjectGrid transactions and JPA entity manager transactions.

An instance of JPATxCallback works with JPALoader or JPAEntityLoader and place a JPA entity manager object in the slot on the TxID object that Loaders can obtain. JPATxCallback is required to be configured on the ObjectGrid when JPALoader or JPAEntityLoader is used. Otherwise, a LoaderException will be thrown.

When the ObjectGrid transaction commits or rollbacks, this transaction callback will receive the events and commit or rollback the corresponding JPA entity manager transactions.

A JPATxCallback has to be configured with the persistence unit name and optionally a JPAPropertyFactory to create a JPA EntityManagerFactory. The JPAPropertyFactory is used to create a JPA property map to override the default persistence properties.

This transaction callback can have an inner transaction callback which is used for a different purpose. This transaction callback will pass the transaction callback events, such as initialize, begin, commit, and rollback, to the inner transaction callback instance. When an inner transaction callback is used, users have to use spring to configure the inner transaction callback instance and then set it on the JPATxCallback instance. Here is an example:

   <bean id="innerTxCallback" class="...">
   </bean>
   <bean id="jpaPropFactory" class=".." scope="shard">
   </bean>
     <bean id="jpaTxCallback" class="com.ibm.websphere.objectgrid.jpa.JPATxCallback" scope="shard" >
       <property name="persistenceUnitName" value="employeePU"/>
       <property name="innerTransactionCallback" ref="innerTxCallback"/>
       <property name="JPAPropertyFactory" ref ="jpaPropFactory"/>
     </bean>
 

For better mapping a generic javax.persitence.PersistenceException to a more consumable exception, an implementation of the ExceptionMapper can be configured as an attribute of this JPATxCallback object. This ExceptionMapper instance will also be used by the JPALoader or JPAEntityLoader to map JPA exceptions. If there are attributes need to be set on the ExceptionMapper object, spring-style configuration has to be used.

Since:

WAS XD 6.1.0.3

See Also:

JPALoader, JPAEntityLoader, JPAPropertyFactory, ExceptionMapper

Nested Class Summary

Nested classes/interfaces inherited from interface com.ibm.websphere.objectgrid.plugins.TransactionCallback

TransactionCallback.BeforeCommit

Field Summary

protected TransactionCallback

nestedCB

Constructor Summary

JPATxCallback()
The default constructor

Method Summary

void	begin(TxID txid) This method is called when the ObjectGrid transaction is started.
void	commit(TxID txid) Commit the entity manager transaction if one is enlisted in this ObjectGrid transaction.
void	destroy() Called when the ObjectGrid associated with this listener is destroyed.
EntityManager	getEntityManager(TxID txid) Get the JPA entity manager associated with this ObjectGrid transaction.
String	getPersistenceUnitName() Retrieve the JPA Persistence Unit name
void	initialize(ObjectGrid objectGrid) reserve a slot for the JPA entity manager during the ObjectGrid initialization.
void	initialize(Session session) Invoked when an ObjectGrid is initialized.
boolean	isExternalTransactionActive(Session session) Check whether there is an active external transaction.
void	rollback(TxID txid) Rollback the JPA entity manager transaction if one is enlisted in this ObjectGrid transaction.
void	setExceptionMapper(ExceptionMapper exceptionMapper) Set the ExceptionMapper.
void	setInnerTransactionCallback(TransactionCallback inner) Set the inner transaction callback instance.
void	setJPAPropertyFactory(JPAPropertyFactory jpaPropertyFactory) Set the JPAPropertyFactory instance.
void	setPersistenceUnitName(String punitName) Set the JPA persistence unit name
void	shardActivated(ObjectGrid grid) This is called when a shard is promoted to a primary.
void	shardDeactivate(ObjectGrid grid) This is called when a primary shard is demoted to a replica.
void	transactionBegin(String txid, boolean isWriteThroughEnabled) Signals the beginning of a Session transaction.
void	transactionEnd(String txid, boolean isWriteThroughEnabled, boolean committed, Collection changes) Signals the ending of a Session transaction.

Methods inherited from class java.lang.Object

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

Field Detail

nestedCB

protected TransactionCallback nestedCB

Constructor Detail

JPATxCallback

public JPATxCallback()

The default constructor

Method Detail

begin

public void begin(TxID txid)
           throws TransactionCallbackException

This method is called when the ObjectGrid transaction is started. The inner transaction callback, if any, will be notified with this begin event.

Specified by:

begin in interface TransactionCallback

Parameters:

txid - the ObjectGrid transaction context ID

Throws:

TransactionCallbackException - if an error occurs during processing

See Also:

TransactionCallback.begin(TxID)

commit

public void commit(TxID txid)
            throws TransactionCallbackException

Commit the entity manager transaction if one is enlisted in this ObjectGrid transaction.

The inner transaction callback, if any, will also be notified with this commit event.

Specified by:

commit in interface TransactionCallback

Parameters:

txid - the ObjectGrid transaction context ID

Throws:

TransactionCallbackException - if an error occurs during processing

See Also:

TransactionCallback.commit(TxID)

initialize

public void initialize(ObjectGrid objectGrid)
                throws TransactionCallbackException

reserve a slot for the JPA entity manager during the ObjectGrid initialization.

The inner transaction callback, if any, will also be notified with this initialize event.

Specified by:

initialize in interface TransactionCallback

Parameters:

objectGrid - A reference to the ObjectGrid.

Throws:

TransactionCallbackException - if an error occurs during processing

See Also:

TransactionCallback.initialize(ObjectGrid)

isExternalTransactionActive

public boolean isExternalTransactionActive(Session session)

Check whether there is an active external transaction.

This method will call the same method on the inner transaction callback, if any, to check whether there is an active external transaction. If no inner transaction callback exists, a false is returned.

Specified by:

isExternalTransactionActive in interface TransactionCallback

Parameters:

session - the ObjectGrid Session instance

Returns:

true if an external transaction is active

See Also:

TransactionCallback.isExternalTransactionActive(Session)

rollback

public void rollback(TxID txid)
              throws TransactionCallbackException

Rollback the JPA entity manager transaction if one is enlisted in this ObjectGrid transaction.

The inner transaction callback, if any, will also be notified with this rollback event.

Specified by:

rollback in interface TransactionCallback

Parameters:

txid - the ObjectGrid transaction context ID

Throws:

TransactionCallbackException - if an error occurs during processing

See Also:

TransactionCallback.rollback(TxID)

getPersistenceUnitName

public String getPersistenceUnitName()

Retrieve the JPA Persistence Unit name

Returns:

the JPA persistence unit name

setPersistenceUnitName

public void setPersistenceUnitName(String punitName)

Set the JPA persistence unit name

Parameters:

punitName - the persistence unit name

getEntityManager

public EntityManager getEntityManager(TxID txid)

Get the JPA entity manager associated with this ObjectGrid transaction.

If no JPA entity manager is associated with this ObjectGrid transaction context ID. An instance will be created and associated ith the ObjectGrid transaction context ID.

Parameters:

txid - the ObjectGrid transaction context id

Returns:

the JPA entity manager

setInnerTransactionCallback

public void setInnerTransactionCallback(TransactionCallback inner)

Set the inner transaction callback instance.

Parameters:

inner - the inner transaction callback instance.

destroy

public void destroy()

Description copied from interface: ObjectGridEventListener

Called when the ObjectGrid associated with this listener is destroyed.

This method is the opposite of the initialize method. When it is called, the listener can free up any resources it uses.

Specified by:

destroy in interface ObjectGridEventListener

See Also:

ObjectGrid.destroy()

initialize

public void initialize(Session session)

Description copied from interface: ObjectGridEventListener

Invoked when an ObjectGrid is initialized.

A usable Session instance is passed to this listener to provide all of the necessary access to the various ObjectGrid objects.

Specified by:

initialize in interface ObjectGridEventListener

Parameters:

session - a Session instance that this listener is associated with.

See Also:

ObjectGrid.initialize()

transactionBegin

public void transactionBegin(String txid,
                             boolean isWriteThroughEnabled)

Description copied from interface: ObjectGridEventListener

Signals the beginning of a Session transaction.

A stringified version of the TxID is provided for correlating with the end of the transaction, if so desired. The type of transaction is also provided by the isWriteThroughEnabled boolean parameter.

Specified by:

transactionBegin in interface ObjectGridEventListener

Parameters:

txid - Stringified version of the TxID

isWriteThroughEnabled - boolean flag indicating whether the Session transaction was started using the Session.beginNoWriteThrough(). method. false is passed if beginNoWriteThrough() was used.

See Also:

Session.begin(), Session.beginNoWriteThrough()

transactionEnd

public void transactionEnd(String txid,
                           boolean isWriteThroughEnabled,
                           boolean committed,
                           Collection changes)

Description copied from interface: ObjectGridEventListener

Signals the ending of a Session transaction.

A string version of the TxID is provided for correlating with the begin of the transaction, if so desired. Map changes are also reported with the collection of LogSequences passed to this method. Typical uses of this event are for customers doing custom peer invalidation or peer commit push. This event listener gives them the changes. Calls to this method are made after commit and are sequenced so that they are delivered one by one, not in parallel. The event order is the commit and rollback order.

For an ObjectGridEventListener receiving changes in an ObjectMap that is configured to use a OutputFormat.RAW for the keys or values, the keys and values objects in the LogSequences will be SerializedKey or SerializedValue objects respectively. If required, you can use the SerializedEntry.getObject() method to retrieve (possibly inflating the serialized object) the original key or value object.

To override the map's output format configuration, use the PluginOutputFormat annotation in the implementation class.

Specified by:

transactionEnd in interface ObjectGridEventListener

Parameters:

txid - string version of the TxID

isWriteThroughEnabled - boolean flag indicating whether the Session transaction was started using the Session.beginNoWriteThrough(). method. false is passed if beginNoWriteThrough() was used.

committed - a boolean flag indicating whether the transaction was committed (true) or rolled back (false)

changes - a Collection of LogSequences representing the changes that were committed or rolled back.

See Also:

LogSequence.isRollback(), Session.begin(), Session.beginNoWriteThrough(), Session.commit(), Session.rollback()

shardActivated

public void shardActivated(ObjectGrid grid)

Description copied from interface: ObjectGridEventGroup.ShardEvents

This is called when a shard is promoted to a primary.

Specified by:

shardActivated in interface ObjectGridEventGroup.ShardEvents

Parameters:

grid - This is a local reference to the shard containing the primary data.

shardDeactivate

public void shardDeactivate(ObjectGrid grid)

Description copied from interface: ObjectGridEventGroup.ShardEvents

This is called when a primary shard is demoted to a replica. This can happen is the balancer decides the primary is better placed in a different container. Replication is still active until this method returns to the caller. If any application controlled transactions are in flight then they should be stopped before returning. Once this method returns then any remaining transactions will fail.

Specified by:

shardDeactivate in interface ObjectGridEventGroup.ShardEvents

Parameters:

grid - A reference to the shard.

setJPAPropertyFactory

public void setJPAPropertyFactory(JPAPropertyFactory jpaPropertyFactory)

Set the JPAPropertyFactory instance. The JPAPropertyFactory instance can be used to plug in specific persistence property map to the JPATxCallback object.

Parameters:

jpaPropertyFactory -

setExceptionMapper

public void setExceptionMapper(ExceptionMapper exceptionMapper)

Set the ExceptionMapper. The ExceptionMapper instance can be used to plug in JPA-specific or database-specific exception mapping functionalities.

Parameters:

exceptionMapper - the ExceptionMapper instance

Since:

7.0

See Also:

ExceptionMapper