software.amazon.kinesis.coordinator.migration

Interface TableMigrationStateMachine

All Known Implementing Classes:

TableMigrationStateMachineImpl

public interface TableMigrationStateMachine

Table State machine that provides: 1. 2-Phase upgrade from 3.4 or lower to 3.5 or higher with a single DDB table for all KCL entity types such as Lease, CoordinatorState and WorkerMetricStats 2. Backward compatible upgrade - 2 phase upgrade allows the migration to safely transition to a single table in Phase 2 when the Phase 1 code is forward compatible for non-lease entries in lease table. 3. Support roll-back and roll-forward - rollback from Phase 2 to Phase 1 will revert back to using multiple DDB tables. Rollforward from Phase 1 will continue table migration. 4. Table migration will complete in Phase 2 after a configured bake time.

During initialization, this state machine:

1. Calls coordinatorStateDAO.initializeDelegates() so reads work
2. Determines the current TableMigrationStatus and sets the TableMigrationStatusProvider
3. Calls coordinatorStateDAO.initialize() to enable writes

For 2→3 migration (where legacy tables never existed), this state machine short-circuits to COMPLETE immediately.

State transitions for 3.x→3.5 upgrade: INIT → DEPLOYED → PENDING → COMPLETE

• INIT: Written by leader when entering CLIENT_VERSION_3X (3.4→3.5 upgrade)
• DEPLOYED: Leader moves here after monitoring min support code across fleet + bake time
• PENDING: Any worker moves here when Phase 2 config is detected
• COMPLETE: Leader moves here after bake time in PENDING, after copying all entities to lease table

Method Summary

Modifier and Type	Method and Description
void	handleLeaderLockResult(boolean isLeader) Called after leader election to handle table migration state transitions that require leader ownership.
void	initialize() Initialize the table migration state machine.
void	shutdown() Idempotent shutdown of the table migration state machine.

Method Detail

initialize

void initialize()
         throws DependencyException,
                InvalidStateException

Initialize the table migration state machine. This is called during KCL startup before the client version migration state machine runs. It is idempotent — calling it multiple times after successful initialization is a no-op.

This method:

1. Calls coordinatorStateDAO.initializeDelegates() — legacy checks table existence
2. Determines TableMigrationStatus — for 2→3 (no legacy tables) → COMPLETE; for 3.x→3.5 reads from DDB
3. Sets the TableMigrationStatusProvider with the determined status
4. Calls coordinatorStateDAO.initialize() to enable write operations

If it fails, the Scheduler retries the entire initialization. On retry, if already initialized, this is a no-op.

Throws:

DependencyException - if DDB operations fail

InvalidStateException - if the state is inconsistent

handleLeaderLockResult

void handleLeaderLockResult(boolean isLeader)
                     throws DependencyException,
                            InvalidStateException

Called after leader election to handle table migration state transitions that require leader ownership. The leader drives transitions between states.

When the PENDING → COMPLETE transition completes (async copy done, status updated), this method throws InvalidStateException to signal the caller to release the current leader lock (held on the legacy table). The next isLeader check will use the updated TableMigrationStatusProvider (now COMPLETE) to acquire the lock from the lease table instead.

Parameters:

isLeader - whether the current worker holds the leader lock

Throws:

DependencyException - if DDB read/write fails — caller should treat as transient and retry on the next cycle (e.g., isLeader returns false for this cycle)

InvalidStateException - when the migration has just completed and the caller must release the current lock so the correct lock can be acquired

shutdown

void shutdown()

Idempotent shutdown of the table migration state machine. Cancels any in-flight async copy operation and shuts down the dedicated executor used for migration tasks.

After this method returns, no further DDB mutations will be performed by the state machine. This should be called during scheduler shutdown to ensure a leader shutting down mid-copy does not continue mutating DDB tables after the worker considers itself stopped.

Calling this method multiple times is safe and has no additional effect.