io.flamingock.internal.core.external.store.lock

Interface LockService

All Known Subinterfaces:

CommunityLockService

public interface LockService

Operations against the persistent lock store.

This interface intentionally exposes only the post-acquisition operations needed by the runtime: extending an already-held lock, reading current lock state, and releasing. Acquisition is not part of this interface. Each implementation owns its own acquisition path:

• Community implementations acquire a lock via CommunityLockService.upsert(...), called from inside CommunityLock.acquire().
• The cloud implementation receives the lock as part of the execution-plan response and never calls a dedicated acquisition method on this interface.

Method Summary

Modifier and Type	Method and Description
LockAcquisition	extendLock(LockKey key, io.flamingock.internal.util.id.RunnerId owner, long leaseMillis) Refreshes (extends) a lock that the caller already owns.
LockAcquisition	getLockInfo(LockKey lockKey) Reads the current state of a lock.
void	releaseLock(LockKey lockKey, io.flamingock.internal.util.id.RunnerId owner) Releases (deletes) the lock identified by lockKey when the caller is the owner.

Method Detail

extendLock

LockAcquisition extendLock(LockKey key,
                           io.flamingock.internal.util.id.RunnerId owner,
                           long leaseMillis)
                    throws LockServiceException

Refreshes (extends) a lock that the caller already owns.

Asserts that (existingLock.key == newLock.key && existingLock.owner == newLock.owner) and rotates internal lock state (e.g. on cloud, the acquisitionId). This method does not grant ownership: a missing lock or a lock held by a different owner causes LockServiceException. If the lock has already expired but is still recorded against the same owner, extending succeeds (no other process has taken it yet).

Parameters:

key - lock key (typically the service id in cloud)

owner - caller's runner id; must equal the existing lock's owner

leaseMillis - requested lease duration in milliseconds. Honored by community implementations; ignored on cloud (the server keeps the duration set at acquire time and echoes it back).

Returns:

a LockAcquisition describing the lock after extension

Throws:

LockServiceException - if no lock exists for key, the lock belongs to a different owner, or the underlying store rejects the update

getLockInfo

LockAcquisition getLockInfo(LockKey lockKey)

Reads the current state of a lock.

Pure read. This method has no side effects: it never creates, extends, takes over, or releases a lock. It exists for diagnostic / error-recovery paths that need to inspect who currently holds a contended lock.

Note: not every backend can support this operation. The cloud implementation throws UnsupportedOperationException because the lock REST API exposes no read-only endpoint.

Parameters:

lockKey - lock key

Returns:

current lock state, or null if no lock is recorded for lockKey

releaseLock

void releaseLock(LockKey lockKey,
                 io.flamingock.internal.util.id.RunnerId owner)

Releases (deletes) the lock identified by lockKey when the caller is the owner.

Best-effort: implementations should not throw on contention or transient errors, because release is typically called from cleanup paths where rethrowing would mask the original failure. A lock not owned by owner is left untouched.

Parameters:

lockKey - lock key

owner - caller's runner id