Package dev.agenor.runtime.persistence

Class FilePersistenceService

java.lang.Object

dev.agenor.runtime.persistence.FilePersistenceService

All Implemented Interfaces:

PersistenceService

public class FilePersistenceService
extends Object
implements PersistenceService

File-based persistence service using JSON format. Stores agent states as JSON files with support for snapshots.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final record	FilePersistenceService.PersistenceStats	Statistics about persisted data

Constructor Summary

Constructors

Constructor	Description
FilePersistenceService()	Create a file persistence service with default directory
FilePersistenceService(Path dataDirectory)	Create a file persistence service with custom directory
FilePersistenceService(Path dataDirectory, boolean prettyPrint)	Create a file persistence service with custom settings

Method Summary

Modifier and Type	Method	Description
CompletableFuture<Integer>	cleanupSnapshots(String agentId, int keepCount)	Clean up old snapshots, keeping only the most recent N
CompletableFuture<String>	createSnapshot(String agentId, String snapshotId)	Creates a named snapshot of the current persisted state of an agent.
CompletableFuture<Void>	deleteState(String agentId)	Deletes the persisted state of an agent asynchronously.
CompletableFuture<Boolean>	existsState(String agentId)	Checks whether a persisted state exists for an agent.
FilePersistenceService.PersistenceStats	getStats()	Get statistics about persisted data
CompletableFuture<List<String>>	listSnapshots(String agentId)	Returns the list of snapshot identifiers available for an agent.
CompletableFuture<Optional<AgentState>>	loadState(String agentId)	Loads the persisted state of an agent asynchronously.
CompletableFuture<Optional<AgentState>>	restoreSnapshot(String agentId, String snapshotId)	Restores an agent's state from a previously created snapshot.
CompletableFuture<Void>	saveState(String agentId, AgentState state)	Saves (or overwrites) the state of an agent asynchronously.

Methods inherited from class java.lang.Object

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

Constructor Details

FilePersistenceService

public FilePersistenceService()

Create a file persistence service with default directory

FilePersistenceService

public FilePersistenceService(Path dataDirectory)

Create a file persistence service with custom directory

FilePersistenceService

public FilePersistenceService(Path dataDirectory,
 boolean prettyPrint)

Create a file persistence service with custom settings

Method Details

saveState

public CompletableFuture<Void> saveState(String agentId,
 AgentState state)

Description copied from interface: PersistenceService

Saves (or overwrites) the state of an agent asynchronously.

If a state for the given agentId already exists, it is replaced. Implementations should use the AgentState.version() field for optimistic concurrency control when the storage backend supports it.

Thread Safety: Concurrent saves for the same agentId must be serialized to prevent data corruption.

Specified by:

saveState in interface PersistenceService

Parameters:

agentId - the unique identifier of the agent, must not be null or blank

state - the state to persist, must not be null

Returns:

a CompletableFuture that completes when the save is committed, or completes exceptionally with PersistenceException on I/O or serialization failure

See Also:

• AgentState.version()

loadState

public CompletableFuture<Optional<AgentState>> loadState(String agentId)

Description copied from interface: PersistenceService

Loads the persisted state of an agent asynchronously.

Returns an empty Optional if no state has been saved for the given agentId. Never returns a null future or a future containing null.

Specified by:

loadState in interface PersistenceService

Parameters:

agentId - the unique identifier of the agent, must not be null or blank

Returns:

a CompletableFuture containing the saved state if present, or an empty Optional if not found; completes exceptionally with PersistenceException on failure

deleteState

public CompletableFuture<Void> deleteState(String agentId)

Description copied from interface: PersistenceService

Deletes the persisted state of an agent asynchronously.

Idempotency: If no state exists for the given agentId, the operation succeeds silently (no-op).

Snapshots: This method deletes only the current state. Snapshots created via PersistenceService.createSnapshot(java.lang.String, java.lang.String) are not automatically removed; use implementation-specific cleanup or PersistenceService.listSnapshots(java.lang.String) to manage them.

Specified by:

deleteState in interface PersistenceService

Parameters:

agentId - the unique identifier of the agent, must not be null or blank

Returns:

a CompletableFuture that completes when the state is deleted, or completes exceptionally with PersistenceException on failure

existsState

public CompletableFuture<Boolean> existsState(String agentId)

Description copied from interface: PersistenceService

Checks whether a persisted state exists for an agent.

This is a lightweight probe that avoids deserializing the full state. Prefer this over PersistenceService.loadState(java.lang.String) when you only need to know if state exists, not its content.

Specified by:

existsState in interface PersistenceService

Parameters:

agentId - the unique identifier of the agent, must not be null or blank

Returns:

a CompletableFuture containing true if state exists, false otherwise; completes exceptionally with PersistenceException on failure

createSnapshot

public CompletableFuture<String> createSnapshot(String agentId,
 String snapshotId)

Description copied from interface: PersistenceService

Creates a named snapshot of the current persisted state of an agent.

A snapshot is an immutable copy of the state at the time of creation. It can be used to implement rollback, auditing, or checkpoint-based recovery. The current state (as saved via PersistenceService.saveState(java.lang.String, dev.agenor.core.persistence.AgentState)) must exist before a snapshot can be created.

If snapshotId is null or blank, implementations should auto-generate a unique identifier (e.g., timestamp-based).

Example:

 String snapshotId = persistenceService
     .createSnapshot("order-processor-1", null)  // auto-generated ID
     .join();
 log.info("Snapshot created: {}", snapshotId);
 

Specified by:

createSnapshot in interface PersistenceService

Parameters:

agentId - the unique identifier of the agent, must not be null or blank

snapshotId - an optional user-defined snapshot name; if null or blank, the implementation generates one

Returns:

a CompletableFuture containing the effective snapshot identifier; completes exceptionally with PersistenceException if the current state does not exist or the operation fails

See Also:

• PersistenceService.restoreSnapshot(String, String)
• PersistenceService.listSnapshots(String)

restoreSnapshot

public CompletableFuture<Optional<AgentState>> restoreSnapshot(String agentId,
 String snapshotId)

Description copied from interface: PersistenceService

Restores an agent's state from a previously created snapshot.

The restored state is returned but not automatically written back as the current state. Callers must explicitly call PersistenceService.saveState(java.lang.String, dev.agenor.core.persistence.AgentState) if they want the snapshot to become the active state.

Returns an empty Optional if no snapshot with the given snapshotId exists for the agent.

Example:

 persistenceService.restoreSnapshot("order-processor-1", snapshotId)
     .thenCompose(opt -> {
         if (opt.isPresent()) {
             agent.restoreState(opt.get());
             return persistenceService.saveState(agent.getAgentId(), opt.get());
         }
         return CompletableFuture.completedFuture(null);
     });
 

Specified by:

restoreSnapshot in interface PersistenceService

Parameters:

agentId - the unique identifier of the agent, must not be null or blank

snapshotId - the identifier of the snapshot to restore, must not be null or blank

Returns:

a CompletableFuture containing the snapshot state if found, or an empty Optional if the snapshot does not exist; completes exceptionally with PersistenceException on failure

See Also:

• PersistenceService.createSnapshot(String, String)

listSnapshots

public CompletableFuture<List<String>> listSnapshots(String agentId)

Description copied from interface: PersistenceService

Returns the list of snapshot identifiers available for an agent.

The order of the returned identifiers is implementation-dependent. Returns an empty list if no snapshots exist; never returns null.

Specified by:

listSnapshots in interface PersistenceService

Parameters:

agentId - the unique identifier of the agent, must not be null or blank

Returns:

a CompletableFuture containing the (possibly empty) list of snapshot identifiers; completes exceptionally with PersistenceException on failure

See Also:

• PersistenceService.createSnapshot(String, String)
• PersistenceService.restoreSnapshot(String, String)

cleanupSnapshots

public CompletableFuture<Integer> cleanupSnapshots(String agentId,
 int keepCount)

Clean up old snapshots, keeping only the most recent N

getStats

public FilePersistenceService.PersistenceStats getStats()

Get statistics about persisted data