org.axonframework.eventhandling
Class TransactionStatus

java.lang.Object
  org.axonframework.eventhandling.TransactionStatus

public class TransactionStatus
extends Object

Provides details about the current status of an event handling transaction. This method is typically accessed through the beforeTransaction and afterTransaction methods on TransactionManager, but may also be obtained through the static current() method.

All instance methods in this class are meant to be used in a single thread and are therefore not thread-safe. The static methods are thread-safe.

Since:

0.3

Author:

Allard Buijze

Constructor Summary

protected

TransactionStatus() Initialize a TransactionStatus instance with default settings.

Method Summary

protected static void	clear() Clears the TransactionStatus related to the current thread.
static TransactionStatus	current() Returns the TransactionStatus object related to a transaction running on the current thread.
int	getEventsProcessedInTransaction() Returns the number of events processed (so far) in the current transaction.
int	getEventsProcessedSinceLastYield() Returns the number of events processed (so far) since the scheduler last yielded to other threads.
Throwable	getException() Returns the exception that caused the transaction to be marked as failed.
int	getMaxTransactionSize() Returns the maximum number of events that may be processed inside the current transaction.
long	getRetryInterval() Returns the current retry interval.
RetryPolicy	getRetryPolicy() Returns the retry policy for the current transaction
YieldPolicy	getYieldPolicy() Returns the YieldPolicy applicable to the current transaction.
boolean	isSuccessful() Indicates whether the current transactional batch is executed successfully.
protected boolean	isTransactionSizeReached() Indicates whether or not the maximum amount of events have been processed in this transaction.
protected void	markFailed(Throwable cause) Mark the current transaction as failed.
protected void	recordEventProcessed() Record the fact that an event has been processed.
void	requestImmediateCommit() Requests the EventProcessingScheduler to commit the transaction immediately.
void	requestImmediateYield() Forces the EventProcessingScheduler to immediately yield to other schedulers after processing this event.
protected void	resetTransactionStatus() Resets the event count for current transaction to 0 and sets the YieldPolicy to the default value (YIELD_AFTER_TRANSACTION).
protected static void	set(TransactionStatus newStatus) Sets the TransactionStatus object related to the transaction running in the current thread.
void	setMaxTransactionSize(int maxTransactionSize) Sets the maximum number of events to process inside the current transaction.
void	setRetryInterval(long retryInterval) Sets the retry interval for the current transaction. his is the number of milliseconds processing should wait before retrying this transaction.
void	setRetryPolicy(RetryPolicy retryPolicy) Sets the retry policy for the current transaction.
void	setYieldPolicy(YieldPolicy yieldPolicy) Sets the YieldPolicy for the current transaction.

Methods inherited from class java.lang.Object

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

Constructor Detail

TransactionStatus

protected TransactionStatus()

Initialize a TransactionStatus instance with default settings.

Method Detail

current

public static TransactionStatus current()

Returns the TransactionStatus object related to a transaction running on the current thread. Returns null if no transaction is running on the current thread.

Returns:

the currently active TransactionStatus, or null if none is present.

clear

protected static void clear()

Clears the TransactionStatus related to the current thread.

set

protected static void set(TransactionStatus newStatus)

Sets the TransactionStatus object related to the transaction running in the current thread. If a previous value exists, it is overwritten.

Parameters:

newStatus - The TransactionStatus for the current transaction

getEventsProcessedInTransaction

public int getEventsProcessedInTransaction()

Returns the number of events processed (so far) in the current transaction.

Returns:

the number of events processed (so far) in the current transaction.

getEventsProcessedSinceLastYield

public int getEventsProcessedSinceLastYield()

Returns the number of events processed (so far) since the scheduler last yielded to other threads. If the scheduler never yielded, it indicates the total number of events processed.

Returns:

the number of events processed (so far) since the scheduler last yielded

setYieldPolicy

public void setYieldPolicy(YieldPolicy yieldPolicy)

Sets the YieldPolicy for the current transaction. Defaults to YIELD_AFTER_TRANSACTION.

Parameters:

yieldPolicy - The YieldPolicy to use for the current transaction

getYieldPolicy

public YieldPolicy getYieldPolicy()

Returns the YieldPolicy applicable to the current transaction.

Returns:

the YieldPolicy applicable to the current transaction

requestImmediateYield

public void requestImmediateYield()

Forces the EventProcessingScheduler to immediately yield to other schedulers after processing this event. The current transaction will be closed normally.

requestImmediateCommit

public void requestImmediateCommit()

Requests the EventProcessingScheduler to commit the transaction immediately. Note that if this method is called before any events have been processed, the transaction will close without processing any events.

getMaxTransactionSize

public int getMaxTransactionSize()

Returns the maximum number of events that may be processed inside the current transaction.

Returns:

the maximum number of events in the current transaction

setMaxTransactionSize

public void setMaxTransactionSize(int maxTransactionSize)

Sets the maximum number of events to process inside the current transaction. The scheduler will commit a transaction if this number (or more) events have been processed inside the current transaction.

Defaults to the number of events in the queue at the moment the transaction started.

Parameters:

maxTransactionSize - The number of events to process in the current transaction

setRetryPolicy

public void setRetryPolicy(RetryPolicy retryPolicy)

Sets the retry policy for the current transaction. Is set to SKIP_FAILED_EVENT by default.

Typically, exceptions are caused by programming errors or the underlying processing environment that the event handler uses, such as a database. In the former, there is no point in retrying the event processing. It would cause an unlimited loop in event processing, making an application vulnerable to a poisonous message attack. In the latter case, the event listener should identify which exception is transitive (i.e. might make a chance when retried), and which is not. If an exception is transitive, either RETRY_TRANSACTION or RETRY_LAST_EVENT should be chosen.

Furthermore, the policy choice should be based on the effect of a transaction rollback. Some data sources, such as databases, roll back the entire transaction. In that case, choose RETRY_TRANSACTION policy. If a rollback on the underlying data source only rolls back the last modification, choose RETRY_LAST_EVENT.

If failed events should be ignored altogether, choose the SKIP_FAILED_EVENT policy.

These policies may be set in both the beforeTransaction() and afterTransaction methods. The latter would allow you to change policy based on the exact type of exception encountered.

Parameters:

retryPolicy - the retry policy to apply when a transaction fails.

getRetryPolicy

public RetryPolicy getRetryPolicy()

Returns the retry policy for the current transaction

Returns:

the retry policy for the current transaction

See Also:

setRetryPolicy(RetryPolicy)

recordEventProcessed

protected void recordEventProcessed()

Record the fact that an event has been processed. This will increase the number of events processed in current transaction as well as the number of events since last yield.

resetTransactionStatus

protected void resetTransactionStatus()

Resets the event count for current transaction to 0 and sets the YieldPolicy to the default value (YIELD_AFTER_TRANSACTION).

isTransactionSizeReached

protected boolean isTransactionSizeReached()

Indicates whether or not the maximum amount of events have been processed in this transaction.

Returns:

true if the maximum amount of events was handled, otherwise false.

getRetryInterval

public long getRetryInterval()

Returns the current retry interval. This is the number of milliseconds processing should wait before retrying this transaction. Defaults to 5000 milliseconds.

Note that negative values will result in immediate retries, making them practically equal to a value of 0.

Returns:

the current retry interval

setRetryInterval

public void setRetryInterval(long retryInterval)

Sets the retry interval for the current transaction. his is the number of milliseconds processing should wait before retrying this transaction. Defaults to 5000 milliseconds.

Parameters:

retryInterval - the number of milliseconds to wait before retrying the transaction

isSuccessful

public boolean isSuccessful()

Indicates whether the current transactional batch is executed successfully. If a batch is currently in progress, this will indicate if an error has been discovered so far.

Returns:

whether the current transaction is successful or not.

getException

public Throwable getException()

Returns the exception that caused the transaction to be marked as failed. Returns null if transaction is successful. Use isSuccessful() to find out if transaction was successful or not.

Returns:

the exception that caused the transaction to fail

markFailed

protected void markFailed(Throwable cause)

Mark the current transaction as failed.

Parameters:

cause - the exception that caused the transaction to fail