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
boolean	checkConnection(Transaction tx)	Checks the connection status of a transaction.
void	clear(Transaction tx)	Clears the database.
void	delete(Transaction tx, TransactionOutboxEntry entry)	Deletes a TransactionOutboxEntry.
int	deleteProcessedAndExpired(Transaction tx, int batchSize, Instant now)	Deletes records which have processed and passed their expiry time, in specified batch sizes.
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.
Optional<TransactionOutboxEntry>	nextInTopic(Transaction tx, String topic)	Fetches and locks the next available piece of work on the specified topic.
void	save(Transaction tx, TransactionOutboxEntry entry)	Saves a new TransactionOutboxEntry.
List<String>	selectActiveTopics(Transaction tx)	Selects the list of topics with work awaiting processing.
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 Details

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:

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:

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:

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.

selectActiveTopics

List<String> selectActiveTopics(Transaction tx)
                         throws Exception

Selects the list of topics with work awaiting processing.

Parameters:

tx - The current Transaction.

Returns:

The topics.

Throws:

Exception - Any exception.

nextInTopic

Optional<TransactionOutboxEntry> nextInTopic(Transaction tx,
 String topic)
                                      throws Exception

Fetches and locks the next available piece of work on the specified topic.

Parameters:

tx - The current Transaction.

topic - The topic.

Returns:

The next available piece of work on the selected topic.

Throws:

Exception - ANy exception.

deleteProcessedAndExpired

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

Deletes records which have processed and passed their expiry time, in specified batch sizes.

Parameters:

tx - The current Transaction.

batchSize - The number of records to select.

now - The time to use when selecting records.

Returns:

The number of records deleted.

Throws:

Exception - Any exception.

checkConnection

boolean checkConnection(Transaction tx)
                 throws Exception

Checks the connection status of a transaction.

Parameters:

tx - The current Transaction.

Returns:

true if connected and working.

Throws:

Exception

clear

void clear(Transaction tx)
    throws Exception

Clears the database. For testing only.

Parameters:

tx - The current Transaction.

Throws:

Exception