Package com.gruelbox.transactionoutbox

Interface Persistor

All Known Implementing Classes:

DefaultPersistor, StubPersistor

public interface Persistor

Saves and loads TransactionOutboxEntrys. For most use cases, just use DefaultPersistor. It is parameterisable and designed for extension, so can be easily modified. Creating completely new implementations of Persistor should be reserved for cases where the underlying data store is of a completely different nature entirely.

Method Summary

Modifier and Type	Method	Description
void	delete(Transaction tx, TransactionOutboxEntry entry)	Deletes a TransactionOutboxEntry.
int	deleteProcessedAndExpired(Transaction tx, int batchSize, Instant now)
static DefaultPersistor	forDialect(Dialect dialect)	Uses the default relational persistor.
boolean	lock(Transaction tx, TransactionOutboxEntry entry)	Attempts to pessimistically lock an existing TransactionOutboxEntry.
void	migrate(TransactionManager transactionManager)	Upgrades any database schema used by the persistor to the latest version.
void	save(Transaction tx, TransactionOutboxEntry entry)	Saves a new TransactionOutboxEntry.
List<TransactionOutboxEntry>	selectBatch(Transaction tx, int batchSize, Instant now)	Selects up to a specified maximum number of non-blocked records which have passed their TransactionOutboxEntry.getNextAttemptTime().
boolean	unblock(Transaction tx, String entryId)	Clears the blocked flag and resets the attempt count to zero.
void	update(Transaction tx, TransactionOutboxEntry entry)	Modifies an existing TransactionOutboxEntry.

Method Detail

forDialect

static DefaultPersistor forDialect(Dialect dialect)

Uses the default relational persistor. Shortcut for: DefaultPersistor.builder().dialect(dialect).build();

Parameters:

dialect - The database dialect.

Returns:

The persistor.

migrate

void migrate(TransactionManager transactionManager)

Upgrades any database schema used by the persistor to the latest version. Called on creation of a TransactionOutbox.

Parameters:

transactionManager - The transactoin manager.

save

void save(Transaction tx,
          TransactionOutboxEntry entry)
   throws Exception

Saves a new TransactionOutboxEntry. Should throw AlreadyScheduledException if the record already exists based on the id or uniqueRequestId (the latter of which should not treat nulls as duplicates).

Parameters:

tx - The current Transaction.

entry - The entry to save. All properties on the object should be saved recursively.

Throws:

Exception - Any exception.

delete

void delete(Transaction tx,
            TransactionOutboxEntry entry)
     throws Exception

Deletes a TransactionOutboxEntry.

A record should only be deleted if both the id and version on the database match that on the object. If no such record is found, OptimisticLockException should be thrown.

Parameters:

tx - The current Transaction.

entry - The entry to be deleted.

Throws:

com.gruelbox.transactionoutbox.OptimisticLockException - If no such record is found.

Exception - Any other exception.

update

void update(Transaction tx,
            TransactionOutboxEntry entry)
     throws Exception

Modifies an existing TransactionOutboxEntry. Performs an optimistic lock check on any existing record via a compare-and-swap operation and throws OptimisticLockException if the lock is failed. TransactionOutboxEntry.setVersion(int) is called before returning containing the new version of the entry.

Parameters:

tx - The current Transaction.

entry - The entry to be updated.

Throws:

com.gruelbox.transactionoutbox.OptimisticLockException - If no record with same id and version is found.

Exception - Any other exception.

lock

boolean lock(Transaction tx,
             TransactionOutboxEntry entry)
      throws Exception

Attempts to pessimistically lock an existing TransactionOutboxEntry.

Parameters:

tx - The current Transaction.

entry - The entry to be locked

Returns:

true if the lock was successful.

Throws:

com.gruelbox.transactionoutbox.OptimisticLockException - If no record with same id and version is found.

Exception - Any other exception.

unblock

boolean unblock(Transaction tx,
                String entryId)
         throws Exception

Clears the blocked flag and resets the attempt count to zero.

Parameters:

tx - The current Transaction.

entryId - The entry id.

Returns:

true if the update was successful. This will be false if the record was no longer blocked or didn't exist anymore.

Throws:

Exception - Any other exception.

selectBatch

List<TransactionOutboxEntry> selectBatch(Transaction tx,
                                         int batchSize,
                                         Instant now)
                                  throws Exception

Selects up to a specified maximum number of non-blocked records which have passed their TransactionOutboxEntry.getNextAttemptTime(). Until a subsequent call to lock(Transaction, TransactionOutboxEntry), these records may be selected by another instance for processing.

Parameters:

tx - The current Transaction.

batchSize - The number of records to select.

now - The time to use when selecting records.

Returns:

The records.

Throws:

Exception - Any exception.

deleteProcessedAndExpired

int deleteProcessedAndExpired(Transaction tx,
                              int batchSize,
                              Instant now)
                       throws Exception

Throws:

Exception