Class TableStateProvider

java.lang.Object

com.kingsrook.qqq.backend.core.state.TableStateProvider

All Implemented Interfaces:

StateProviderInterface

public class TableStateProvider
extends Object
implements StateProviderInterface

Process and async job state shared through a QQQ table, so any node of a multi-node application can serve any process step, status poll or cancel (spec 2026-10-15-cluster-ha-design, section B). Works on any backend; the table is defined by defineTable and created by the application's migrations. Every operation runs as the system user with no transaction of its own, so state is visible to other nodes immediately, whatever the caller's transaction does. Values are serialized by StateSerialization (gzip, and AES-GCM with a key). Entries expire after ttlHours; every node sweeps expired rows every cleanIntervalMinutes. A value that cannot be serialized is kept in this node's memory instead (and logged once per class), so a process keeps working on a single node.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	FIELD_CREATE_DATE
static final String	FIELD_EXPIRES_AT
static final String	FIELD_MODIFY_DATE
static final String	FIELD_NODE_ID
static final String	FIELD_PAYLOAD
static final String	FIELD_STATE_KEY
static final String	FIELD_STATE_TYPE

Constructor Summary

Constructors

Constructor	Description
TableStateProvider(QInstance instance, StateProviderMetaData metaData)	Constructor.

Method Summary

Modifier and Type	Method	Description
void	clean(Instant startTime)	Delete entries that expired before now (the argument is ignored: expiry is per entry).
static QTableMetaData	defineTable(String tableName, String backendName)	The state table: stateKey (primary key), stateType, payload (text), nodeId, createDate, modifyDate, expiresAt; columns are snake_case.
<T extends Serializable> Optional<T>	get(Class<? extends T> type, AbstractStateKey key)	Read a value.
StateProviderMetaData	getMetaData()	The meta data.
boolean	isEncrypted()	Whether stored values are encrypted (a state encryption key is configured).
<T extends Serializable> void	put(AbstractStateKey key, T data)	Store a value.
void	remove(AbstractStateKey key)	Remove a value.
void	startSweeper()	Start the expired-entry sweeper (idempotent).
String	status()	Status text.
void	stopSweeper()	Stop the sweeper.
static String	storedKey(AbstractStateKey key)	The stored key for a state key.

Methods inherited from class java.lang.Object

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

Field Details

FIELD_STATE_KEY

public static final String FIELD_STATE_KEY

See Also:

• Constant Field Values

FIELD_STATE_TYPE

public static final String FIELD_STATE_TYPE

See Also:

• Constant Field Values

FIELD_PAYLOAD

public static final String FIELD_PAYLOAD

See Also:

• Constant Field Values

FIELD_NODE_ID

public static final String FIELD_NODE_ID

See Also:

• Constant Field Values

FIELD_CREATE_DATE

public static final String FIELD_CREATE_DATE

See Also:

• Constant Field Values

FIELD_MODIFY_DATE

public static final String FIELD_MODIFY_DATE

See Also:

• Constant Field Values

FIELD_EXPIRES_AT

public static final String FIELD_EXPIRES_AT

See Also:

• Constant Field Values

Constructor Details

TableStateProvider

public TableStateProvider(QInstance instance,
 StateProviderMetaData metaData)
                   throws QException

Constructor.

Throws:

QException

Method Details

defineTable

public static QTableMetaData defineTable(String tableName,
 String backendName)

The state table: stateKey (primary key), stateType, payload (text), nodeId, createDate, modifyDate, expiresAt; columns are snake_case. Only holders of the table's permissions see it (the payload is opaque - and encrypted with a key); the provider reads and writes it as the system user.

storedKey

public static String storedKey(AbstractStateKey key)

The stored key for a state key.

startSweeper

public void startSweeper()

Start the expired-entry sweeper (idempotent).

stopSweeper

public void stopSweeper()

Stop the sweeper.

put

public <T extends Serializable> void put(AbstractStateKey key,
 T data)

Store a value.

Specified by:

put in interface StateProviderInterface

get

public <T extends Serializable> Optional<T> get(Class<? extends T> type,
 AbstractStateKey key)

Read a value.

Specified by:

get in interface StateProviderInterface

remove

public void remove(AbstractStateKey key)

Remove a value.

Specified by:

remove in interface StateProviderInterface

status

public String status()

Status text.

Specified by:

status in interface StateProviderInterface

clean

public void clean(Instant startTime)

Delete entries that expired before now (the argument is ignored: expiry is per entry).

Specified by:

clean in interface StateProviderInterface

isEncrypted

public boolean isEncrypted()

Whether stored values are encrypted (a state encryption key is configured).

getMetaData

public StateProviderMetaData getMetaData()

The meta data.