com.ibm.websphere.wsba

Interface UserBusinessActivity

public interface UserBusinessActivity

This interface allows the application programmer to access the Business Activity on the current thread. This API allows the user to pass compensation data to the runtime that will be used later by the CompensationHandler or serializable.CompensationHandler on completion of the Business Activity. The application programmer can also modify or check the completion direction of the current Business Activity.

Method Summary

Methods

Modifier and Type	Method and Description
java.lang.String	getId() Returns a unique identifier for the BusinessActivity currently associated with the calling thread.
boolean	isCompensateOnly() Returns true if the Business Activity has previously been marked compensate only or the underlying unit of work (UOW) has been marked the fail only, otherwise returns false.
void	setCompensateOnly() Calling setCompensateOnly will force the Business Activity to compensate all active CompensationHandlers that have been added.
void	setCompensationDataAtCommit(commonj.sdo.DataObject compensationData) Invoked to configure the CompensationHandler or serializable.CompensationHandler behaviour on completion of the underlying Business Activity.
void	setCompensationDataAtCommit(java.io.Serializable compensationData) Invoked to configure the CompensationHandler or serializable.CompensationHandler behaviour on completion of the underlying Business Activity.
void	setCompensationDataImmediate(commonj.sdo.DataObject compensationData) Invoked to configure the CompensationHandler or serializable.CompensationHandler behaviour on completion of the underlying Business Activity.
void	setCompensationDataImmediate(java.io.Serializable compensationData) Invoked to configure the CompensationHandler or serializable.CompensationHandler behaviour on completion of the underlying Business Activity.

Method Detail

setCompensateOnly

void setCompensateOnly()
                       throws java.lang.IllegalStateException

Calling setCompensateOnly will force the Business Activity to compensate all active CompensationHandlers that have been added. This will occur upon the completion of the current Business Activity. Once setCompensateOnly() has been called, the Business Activity can will never complete successfully.

Throws:

java.lang.IllegalStateException - if there is no Business Activity available on the thread

isCompensateOnly

boolean isCompensateOnly()
                         throws java.lang.IllegalStateException

Returns true if the Business Activity has previously been marked compensate only or the underlying unit of work (UOW) has been marked the fail only, otherwise returns false.

Returns:

a boolean value, true if the Business Activity has previously been called to setCompensateOnly() or the underlying UOW has been marked to fail only (e.g. setRollbackOnly() has been called on a JTA transaction), false otherwise.

Throws:

java.lang.IllegalStateException - if there is no BusinessActivity available on the thread or if data of type SDO DataObject is not used when the compensation handler is of type CompensationHandler.

setCompensationDataAtCommit

void setCompensationDataAtCommit(commonj.sdo.DataObject compensationData)
                                 throws java.lang.IllegalStateException,
                                        java.io.NotSerializableException

Invoked to configure the CompensationHandler or serializable.CompensationHandler behaviour on completion of the underlying Business Activity. When this method is called for the first time any compensation handler configured by the calling component will be associated with the underlying Business Activity. The compensation data passed in as a parameter will be logged.

A compensation handler, either using Serializable data or using SDO DataObject compensation data, can be in one of two states; active or inactive. Only active compensation handlers are driven as part of the completion process of a Business Activity.

If there is a global transaction present when this method is called then the compensation handler will be inactive until the global transaction commits, when it will be made active. If the global transaction rolls back, the compensation handler will be discarded and never driven to compensate or close.

If a global transaction is not present, the compensation handler will be marked as active immediately and will be driven to compensate or close upon completion of the Business Activity.

Subsequent calls to this method or setCompensationDataAtCommit(Serializable) from within the same application component and Business Activity cause any previous compensation data to be updated with the compensation data passed in on this invocation.

A new CompensationHandler or serializable.CompensationHandler will not be added every time this method is invoked. Any compensation handler added using this method will never be overwritten by the setCompensationDataImmediate method. If both methods are called within the same application component and Business Activity, two compensation handlers will be added.

If null is passed as a parameter, the CompensationHandler or serializable.CompensationHandler will be removed from the Business Activity and not driven to close or compensate during completion of the Business Activity.

Parameters:

compensationData - the data logged at runtime to be used at the time of Business Activity completion by the compensation handler. This is in the form of an SDO DataObject.

Compensation data class implementations should consider using the static serialVersionUID member as described in Serializable.

Throws:

java.lang.IllegalStateException - if there is no Business Activity available on thread.

java.io.NotSerializableException - if the compensationData cannot be serialized.

setCompensationDataImmediate

void setCompensationDataImmediate(commonj.sdo.DataObject compensationData)
                                  throws java.lang.IllegalStateException,
                                         java.io.NotSerializableException

Invoked to configure the CompensationHandler or serializable.CompensationHandler behaviour on completion of the underlying Business Activity. When this method is called for the first time any compensation handler configured by the calling component will be associated with the underlying Business Activity. The compensation data passed in as a parameter will be logged.

A compensation handler, either using Serializable data or using SDO DataObject compensation data, can be in one of two states; active or inactive. Only active compensation handlers are driven as part of the completion process of a Business Activity.

Any compensation handler added to a Business Activity through this method will be marked active immediately. This guarantees that the compensation handler added will be driven to compensate or close upon completion of the Business Activity.

Subsequent calls to this method or setCompensationDataImmediate(Serializable) from within the same application component and Business Activity cause any previous compensation data to be updated with the compensation data passed in on this invocation.

A new CompensationHandler or serializable.CompensationHandler will not be added every time this method is invoked. Any compensation handler added using this method will never be overwritten by the setCompensationDataAtCommit method. If both methods are called within the same application component and Business Activity, two compensation handlers will be added.

If null is passed as a parameter, the CompensationHandler or serializable.CompensationHandler will be removed from the Business Activity and not driven to close or compensate during completion of the Business Activity.

Parameters:

compensationData - the data logged at runtime to be used at the time of Business Activity completion by the compensation handler. This is in the form of an SDO DataObject.

Compensation data class implementations should consider using the static serialVersionUID member as described in Serializable.

Throws:

java.lang.IllegalStateException - if there is no Business Activity available on thread.

java.io.NotSerializableException - if the compensationData cannot be serialized.

setCompensationDataAtCommit

void setCompensationDataAtCommit(java.io.Serializable compensationData)
                                 throws java.lang.IllegalStateException,
                                        java.io.NotSerializableException,
                                        BASystemException

Invoked to configure the CompensationHandler or serializable.CompensationHandler behaviour on completion of the underlying Business Activity. When this method is called for the first time any compensation handler configured by the calling component will be associated with the underlying Business Activity. The compensation data passed in as a parameter will be logged.

A compensation handler, either using Serializable data or using SDO DataObject compensation data, can be in one of two states; active or inactive. Only active compensation handlers are driven as part of the completion process of a Business Activity.

If there is a global transaction present when this method is called then the compensation handler will be inactive until the global transaction commits, when it will be made active. If the global transaction rolls back, the compensation handler will be discarded and never driven to compensate or close.

If a global transaction is not present, the compensation handler will be marked as active immediately and will be driven to compensate or close upon completion of the Business Activity.

Subsequent calls to this method or setCompensationDataAtCommit(DataObject) from within the same application component and Business Activity cause any previous compensation data to be updated with the compensation data passed in on this invocation.

A new CompensationHandler or serializable.CompensationHandler will not be added every time this method is invoked. Any compensation handler added using this method will never be overwritten by the setCompensationDataImmediate method. If both methods are called within the same application component and Business Activity, two compensation handlers will be added.

If null is passed as a parameter, the CompensationHandler or serializable.CompensationHandler will be removed from the Business Activity and not driven to close or compensate during completion of the Business Activity.

Parameters:

compensationData - the data logged at runtime to be used at the time of Business Activity completion by the compensation handler. This is in the form of an SDO DataObject or Serializable. This parameter must be of type SDO DataObject if the CompensationHandler interface is used for the compensation handler.

Compensation data class implementations should consider using the static serialVersionUID member as described in Serializable.

Throws:

java.lang.IllegalStateException - if there is no Business Activity available on the thread

BASystemException - if the CompensationHandler interface is used for the compensation handler but the compensationData does not implement the DataObject interface.

java.io.NotSerializableException - if the compensationData cannot be serialized.

setCompensationDataImmediate

void setCompensationDataImmediate(java.io.Serializable compensationData)
                                  throws java.lang.IllegalStateException,
                                         java.io.NotSerializableException,
                                         BASystemException

Invoked to configure the CompensationHandler or serializable.CompensationHandler behaviour on completion of the underlying Business Activity. When this method is called for the first time any compensation handler configured by the calling component will be associated with the underlying Business Activity. The compensation data passed in as a parameter will be logged.

A compensation handler, either using Serializable data or using SDO DataObject compensation data, can be in one of two states; active or inactive. Only active compensation handlers are driven as part of the completion process of a Business Activity.

Any compensation handler added to a Business Activity through this method will be marked active immediately. This guarantees that the compensation handler added will be driven to compensate or close upon completion of the Business Activity.

Subsequent calls to this method or setCompensationDataImmediate(DataObject) from within the same application component and Business Activity cause any previous compensation data to be updated with the compensation data passed in on this invocation.

A new CompensationHandler or serializable.CompensationHandler will not be added every time this method is invoked. Any compensation handler added using this method will never be overwritten by the setCompensationDataAtCommit method. If both methods are called within the same application component and Business Activity, two compensation handlers will be added.

If null is passed as a parameter, the CompensationHandler or serializable.CompensationHandler will be removed from the Business Activity and not driven to close or compensate during completion of the Business Activity.

Parameters:

compensationData - the data logged at runtime to be used at the time of Business Activity completion by the compensation handler. This is in the form of an SDO DataObject or Serializable. This parameter must be of type SDO DataObject if the CompensationHandler interface is used for the compensation handler.

Compensation data class implementations should consider using the static serialVersionUID member as described in Serializable.

Throws:

java.lang.IllegalStateException - if there is no Business Activity available on the thread

BASystemException - if the CompensationHandler interface is used for the compensation handler but the compensationData does not implement the DataObject interface.

java.io.NotSerializableException - if the compensationData cannot be serialized.

getId

java.lang.String getId()

Returns a unique identifier for the BusinessActivity currently associated with the calling thread. If no Business Activity is associated with the calling thread null is returned.

Returns:

a unique identifier for the Business Activity currently associated with the calling thread