Class EffectStore

java.lang.Object

com.kingsrook.qqq.backend.core.jobs.effects.EffectStore

public class EffectStore
extends Object

The jobs_effect outbox: write effects with a chunk's progress, claim due effects (FOR UPDATE SKIP LOCKED where supported, else conditional updates), record outcomes (fenced), and reap leases of dispatchers that died.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final record	EffectStore.EffectCounts	Counts of a job's effects.

Constructor Summary

Constructors

Constructor	Description
EffectStore(DurableJobsMetaData settings)	Constructor

Method Summary

Modifier and Type	Method	Description
List<EffectLease>	claimDue(String podId, int batch)	Claim up to batch effects that are due: PENDING (deliver) and UNKNOWN not yet sent to review (reconcile).
EffectStore.EffectCounts	countsForJob(Integer jobId)	A job's effects, summarized for its finalizer.
QRecord	get(Integer effectId)	Read an effect (as the system user).
int	insertEffects(List<QRecord> effects, QBackendTransaction transaction)	Write outbox rows (in the chunk's transaction when given).
EffectStatus	markNotDelivered(EffectLease lease, String message, boolean retry)	Definitely not delivered: retry later with backoff, or FAILED when the attempts are used up (or retry is false).
boolean	markNotFound(EffectLease lease)	A reconcile lookup found the effect was definitely not delivered: due again (safe to send).
boolean	markSent(EffectLease lease, String providerRef)	Delivered.
EffectStatus	markUnknown(EffectLease lease, JobEffectType type, String message)	The outcome is unknown (it may have been delivered).
Instant	now()	The database clock.
List<QRecord>	query(QQueryFilter filter)	Query the outbox (as the system user).
Set<Integer>	reapExpired()	Leases held past their expiry (the dispatcher died mid-delivery): the outcome is unknown.
boolean	resolve(Integer effectId, EffectStatus to, String note)	Review: an operator resolves an effect (not while a dispatcher holds it).

Methods inherited from class java.lang.Object

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

Constructor Details

EffectStore

public EffectStore(DurableJobsMetaData settings)

Constructor

Method Details

now

public Instant now()
            throws QException

The database clock.

Throws:

QException

insertEffects

public int insertEffects(List<QRecord> effects,
 QBackendTransaction transaction)
                  throws QException

Write outbox rows (in the chunk's transaction when given). Keys already in the outbox are skipped, so a rerun chunk never doubles its effects.

Throws:

QException

claimDue

public List<EffectLease> claimDue(String podId,
 int batch)
                           throws QException

Claim up to batch effects that are due: PENDING (deliver) and UNKNOWN not yet sent to review (reconcile).

Throws:

QException

get

public QRecord get(Integer effectId)
            throws QException

Read an effect (as the system user).

Throws:

QException

query

public List<QRecord> query(QQueryFilter filter)
                    throws QException

Query the outbox (as the system user).

Throws:

QException

markSent

public boolean markSent(EffectLease lease,
 String providerRef)
                 throws QException

Delivered. Fenced: false when the lease was lost (another holder decides).

Throws:

QException

markNotDelivered

public EffectStatus markNotDelivered(EffectLease lease,
 String message,
 boolean retry)
                              throws QException

Definitely not delivered: retry later with backoff, or FAILED when the attempts are used up (or retry is false).

Throws:

QException

markUnknown

public EffectStatus markUnknown(EffectLease lease,
 JobEffectType type,
 String message)
                         throws QException

The outcome is unknown (it may have been delivered). An idempotent effect is simply due again (same key); a non-idempotent one becomes UNKNOWN, to be reconciled - or, after the reconcile attempts, queued for review.

Throws:

QException

markNotFound

public boolean markNotFound(EffectLease lease)
                     throws QException

A reconcile lookup found the effect was definitely not delivered: due again (safe to send). Counts as a delivery attempt already made.

Throws:

QException

reapExpired

public Set<Integer> reapExpired()
                         throws QException

Leases held past their expiry (the dispatcher died mid-delivery): the outcome is unknown. Idempotent effects go back to PENDING (resent with the same key); others to UNKNOWN (reconcile, never a blind resend). Returns the job ids touched.

Throws:

QException

resolve

public boolean resolve(Integer effectId,
 EffectStatus to,
 String note)
                throws QException

Review: an operator resolves an effect (not while a dispatcher holds it). to is SENT (it was delivered), PENDING (send it now) or FAILED (skip it).

Throws:

QException

countsForJob

public EffectStore.EffectCounts countsForJob(Integer jobId)
                                      throws QException

A job's effects, summarized for its finalizer.

Throws:

QException