Package com.gruelbox.transactionoutbox

Class TransactionOutbox

java.lang.Object

com.gruelbox.transactionoutbox.TransactionOutbox

public class TransactionOutbox
extends Object

An implementation of the Transactional Outbox pattern for Java. See README for usage instructions.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	TransactionOutbox.ParameterizedScheduleBuilder
static class	TransactionOutbox.TransactionOutboxBuilder	Builder for TransactionOutbox.

Method Summary

Modifier and Type	Method	Description
static TransactionOutbox.TransactionOutboxBuilder	builder()
boolean	flush()	Identifies any stale tasks queued using schedule(Class) (those which were queued more than attemptFrequency ago and have been tried less than blacklistAfterAttempts times) and attempts to resubmit them.
void	processNow(TransactionOutboxEntry entry)	Processes an entry immediately in the current thread.
<T> T	schedule(Class<T> clazz)	The main entry point for submitting new transaction outbox tasks.
boolean	whitelist(String entryId)	Marks a blacklisted entry back to not blacklisted and resets the attempt count.
boolean	whitelist(String entryId, Object transactionContext)	Marks a blacklisted entry back to not blacklisted and resets the attempt count.
TransactionOutbox.ParameterizedScheduleBuilder	with()	Starts building a schedule request with parameterization.

Methods inherited from class java.lang.Object

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

Method Detail

builder

public static TransactionOutbox.TransactionOutboxBuilder builder()

Returns:

A builder for creating a new instance of TransactionOutbox.

schedule

public <T> T schedule(Class<T> clazz)

The main entry point for submitting new transaction outbox tasks.

Returns a proxy of T which, when called, will instantly return and schedule a call of the real method to occur after the current transaction is committed (as such a transaction needs to be active and accessible from transactionManager)

Usage:

transactionOutbox.schedule(MyService.class)
   .runMyMethod("with", "some", "arguments");

This will write a record to the database using the supplied Persistor and Instantiator, using the current database transaction, which will get rolled back if the rest of the transaction is, and thus never processed. However, if the transaction is committed, the real method will be called immediately afterwards using the supplied submitter. Should that fail, the call will be reattempted whenever flush() is called, provided at least attemptFrequency has passed since the time the task was last attempted.

Type Parameters:

T - The type to proxy.

Parameters:

clazz - The class to proxy.

Returns:

The proxy of T.

with

public TransactionOutbox.ParameterizedScheduleBuilder with()

Starts building a schedule request with parameterization. See TransactionOutbox.ParameterizedScheduleBuilder.schedule(Class) for more information.

Returns:

Builder.

flush

public boolean flush()

Identifies any stale tasks queued using schedule(Class) (those which were queued more than attemptFrequency ago and have been tried less than blacklistAfterAttempts times) and attempts to resubmit them.

As long as submitter is non-blocking (e.g. uses a bounded queue with a RejectedExecutionHandler which throws such as ThreadPoolExecutor.AbortPolicy), this method will return quickly. However, if submitter uses a bounded queue with a blocking policy, this method could block for a long time, depending on how long the scheduled work takes and how large flushBatchSize is.

Calls TransactionManager.inTransactionReturns(TransactionalSupplier) to start a new transaction for the fetch.

Additionally, expires any records completed prior to the TransactionOutbox.TransactionOutboxBuilder.retentionThreshold(Duration).

Returns:

true if any work was flushed.

whitelist

public boolean whitelist(String entryId)

Marks a blacklisted entry back to not blacklisted and resets the attempt count. Requires an active transaction and a transaction manager that supports thread local context.

Parameters:

entryId - The entry id.

Returns:

True if the whitelisting request was successful. May return false if another thread whitelisted the entry first.

whitelist

public boolean whitelist(String entryId,
                         Object transactionContext)

Marks a blacklisted entry back to not blacklisted and resets the attempt count. Requires an active transaction and a transaction manager that supports supplied context.

Parameters:

entryId - The entry id.

transactionContext - The transaction context (TransactionManager implementation specific).

Returns:

True if the whitelisting request was successful. May return false if another thread whitelisted the entry first.

processNow

public void processNow(TransactionOutboxEntry entry)

Processes an entry immediately in the current thread. Intended for use in custom implementations of Submitter and should not generally otherwise be called.

Parameters:

entry - The entry.