Package com.gruelbox.transactionoutbox

Interface TransactionOutbox

public interface TransactionOutbox

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

Nested Class Summary

Nested Classes

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

Method Summary

Modifier and Type	Method	Description
static TransactionOutbox.TransactionOutboxBuilder	builder()
default boolean	flush()	Flush in a single thread.
boolean	flush(Executor executor)	Identifies any stale tasks queued using schedule(Class) (those which were queued more than supplied TransactionOutbox.TransactionOutboxBuilder.attemptFrequency(Duration) ago and have been tried less than TransactionOutbox.TransactionOutboxBuilder.blockAfterAttempts(int) )} times) and attempts to resubmit them.
void	initialize()	Performs initial setup, making the instance usable.
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	unblock(String entryId)	Unblocks a blocked entry and resets the attempt count so that it will be retried again.
boolean	unblock(String entryId, Object transactionContext)	Clears a failed entry of its failed state and resets the attempt count so that it will be retried again.
TransactionOutbox.ParameterizedScheduleBuilder	with()	Starts building a schedule request with parameterization.

Method Details

builder

static TransactionOutbox.TransactionOutboxBuilder builder()

Returns:

A builder for creating a new instance of TransactionOutbox.

initialize

void initialize()

Performs initial setup, making the instance usable. If TransactionOutbox.TransactionOutboxBuilder.initializeImmediately(boolean) is true, which is the default, this method is called automatically when the instance is constructed.

schedule

<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 the transaction manager supplied to TransactionOutbox.TransactionOutboxBuilder.transactionManager(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 submitter supplied to TransactionOutbox.TransactionOutboxBuilder.submitter(Submitter). Should that fail, the call will be reattempted whenever flush() is called, provided at least supplied TransactionOutbox.TransactionOutboxBuilder.attemptFrequency(Duration) 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

TransactionOutbox.ParameterizedScheduleBuilder with()

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

Returns:

Builder.

flush

default boolean flush()

Flush in a single thread. Calls flush(Executor) with an Executor which runs all work in the current thread.

Returns:

true if any work was flushed.

See Also:

• flush(Executor)

flush

boolean flush(Executor executor)

Identifies any stale tasks queued using schedule(Class) (those which were queued more than supplied TransactionOutbox.TransactionOutboxBuilder.attemptFrequency(Duration) ago and have been tried less than TransactionOutbox.TransactionOutboxBuilder.blockAfterAttempts(int) )} times) and attempts to resubmit them.

As long as the TransactionOutbox.TransactionOutboxBuilder.submitter(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 the TransactionOutbox.TransactionOutboxBuilder.submitter(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 TransactionOutbox.TransactionOutboxBuilder.flushBatchSize(int) 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).

Parameters:

executor - to be used for parallelising work (note that the method overall is blocking and this is solely ued for fork-join semantics).

Returns:

true if any work was flushed.

unblock

boolean unblock(String entryId)

Unblocks a blocked entry and resets the attempt count so that it will be retried again. Requires an active transaction and a transaction manager that supports thread local context.

Parameters:

entryId - The entry id.

Returns:

True if the request to unblock the entry was successful. May return false if another thread unblocked the entry first.

unblock

boolean unblock(String entryId,
 Object transactionContext)

Clears a failed entry of its failed state and resets the attempt count so that it will be retried again. 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 request to unblock the entry was successful. May return false if another thread unblocked the entry first.

processNow

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.