Package at.aimon.session.web.spi

Interface ConversationLock

All Known Implementing Classes:

InMemoryConversationLock

public interface ConversationLock

Per-conversation distributed lock SPI.

Holder identity (typically "{nodeId}/{thread}/{turnSeq}", see design §7.3) is opaque to the lock; the lock uses it for diagnostics and reentrancy decisions. A ConversationLock.LockHandle carries a monotonically-increasing fencingToken so the manager can detect stale handles when extending or releasing.

Failure semantics (design §10.1):

• Lock held by another holder → empty Optional from tryAcquire(at.aimon.core.agent.conversation.ConversationId, java.lang.String, java.time.Duration).
• Backend communication failure → ConversationLockException.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static final class	ConversationLock.LockHandle	Immutable handle returned by a successful tryAcquire(at.aimon.core.agent.conversation.ConversationId, java.lang.String, java.time.Duration).

Method Summary

Modifier and Type	Method	Description
boolean	extend(ConversationLock.LockHandle handle, Duration lease)	Extends the lease of an already-held lock.
void	release(ConversationLock.LockHandle handle)	Releases the lock.
Optional<ConversationLock.LockHandle>	tryAcquire(at.aimon.core.agent.conversation.ConversationId id, String holderId, Duration lease)	Attempts to acquire the lock for id on behalf of holderId.

Method Details

tryAcquire

Optional<ConversationLock.LockHandle> tryAcquire(at.aimon.core.agent.conversation.ConversationId id,
 String holderId,
 Duration lease)

Attempts to acquire the lock for id on behalf of holderId.

Parameters:

id - the conversation to lock (must not be null)

holderId - the requesting holder identity (must not be null)

lease - requested lease duration (must not be null)

Returns:

a ConversationLock.LockHandle on success, empty if another holder owns it

Throws:

ConversationLockException - on backend communication failure

extend

boolean extend(ConversationLock.LockHandle handle,
 Duration lease)

Extends the lease of an already-held lock.

Parameters:

handle - the lock handle returned from a prior tryAcquire(at.aimon.core.agent.conversation.ConversationId, java.lang.String, java.time.Duration) (must not be null)

lease - new lease duration (must not be null)

Returns:

true when the lease was extended, false when the fencing token no longer matches (lease already expired or released)

Throws:

ConversationLockException - on backend communication failure

release

void release(ConversationLock.LockHandle handle)

Releases the lock. Token mismatches are silently ignored — the manager treats release as best-effort and the lease will eventually expire.

Parameters:

handle - the lock handle (must not be null)