Package com.tnsai.state

Class FileCheckpointer

java.lang.Object

com.tnsai.state.FileCheckpointer

All Implemented Interfaces:

Checkpointer

public class FileCheckpointer
extends Object
implements Checkpointer

File-based Checkpointer with JSON serialization.

Features:

• JSON serialization with Jackson
• Atomic writes (write to temp then rename)
• File rotation (configurable max checkpoints per thread)
• Optional GZIP compression
• Thread-safe with ReadWriteLock

Directory Structure:

 baseDir/
   thread-{threadId}/
     checkpoint-{timestamp}-{checkpointId}.json[.gz]
     writes-{checkpointId}.json[.gz]
 

Example usage:

 // Basic usage
 FileCheckpointer checkpointer = new FileCheckpointer(Path.of("./checkpoints"));

 // With compression and rotation
 FileCheckpointer checkpointer = FileCheckpointer.builder()
     .baseDir(Path.of("./checkpoints"))
     .enableCompression(true)
     .maxCheckpointsPerThread(100)
     .prettyPrint(true)
     .build();

 // Save checkpoint
 checkpointer.put("thread-1", "cp-001",
     Map.of("messages", List.of("hello")),
     Map.of("step", 1));

 // Retrieve latest
 CheckpointTuple latest = checkpointer.getTuple("thread-1", null);
 

See Also:

• Checkpointer
• InMemoryCheckpointer

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	FileCheckpointer.Builder	Builder for FileCheckpointer.

Nested classes/interfaces inherited from interface com.tnsai.state.Checkpointer

Checkpointer.CheckpointTuple, Checkpointer.Write

Constructor Summary

Constructors

Constructor	Description
FileCheckpointer(Path baseDir)	Creates a FileCheckpointer with default settings.
FileCheckpointer(Path baseDir, boolean enableCompression, int maxCheckpointsPerThread, boolean prettyPrint)	Creates a FileCheckpointer with custom settings.

Method Summary

Modifier and Type	Method	Description
static FileCheckpointer.Builder	builder()	Returns a builder for FileCheckpointer.
void	clear()	Clear all checkpoints.
void	delete(String threadId)	Delete checkpoints for a thread.
int	getCheckpointCount()	Get the total number of checkpoint files.
long	getTotalSize()	Get the total size of all checkpoint files in bytes.
Checkpointer.CheckpointTuple	getTuple(String threadId, String checkpointId)	Fetch a checkpoint.
List<Checkpointer.CheckpointTuple>	list(String threadId)	List checkpoints for a thread.
void	put(String threadId, String checkpointId, Map<String,Object> state, Map<String,Object> metadata)	Store a checkpoint.
void	putWrites(String checkpointId, List<Checkpointer.Write> writes)	Store intermediate writes.

Methods inherited from class java.lang.Object

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

Constructor Details

FileCheckpointer

public FileCheckpointer(Path baseDir)

Creates a FileCheckpointer with default settings.

Parameters:

baseDir - base directory for checkpoint storage

FileCheckpointer

public FileCheckpointer(Path baseDir,
 boolean enableCompression,
 int maxCheckpointsPerThread,
 boolean prettyPrint)

Creates a FileCheckpointer with custom settings.

Parameters:

baseDir - base directory for checkpoint storage

enableCompression - whether to GZIP compress files

maxCheckpointsPerThread - max checkpoints to keep per thread (0 = unlimited)

prettyPrint - whether to pretty-print JSON

Method Details

builder

public static FileCheckpointer.Builder builder()

Returns a builder for FileCheckpointer.

Returns:

new builder instance

put

public void put(String threadId,
 String checkpointId,
 Map<String,Object> state,
 Map<String,Object> metadata)

Description copied from interface: Checkpointer

Store a checkpoint.

Specified by:

put in interface Checkpointer

Parameters:

threadId - Thread identifier

checkpointId - Checkpoint identifier

state - State data

metadata - Checkpoint metadata

putWrites

public void putWrites(String checkpointId,
 List<Checkpointer.Write> writes)

Description copied from interface: Checkpointer

Store intermediate writes.

Specified by:

putWrites in interface Checkpointer

Parameters:

checkpointId - Checkpoint identifier

writes - List of writes

getTuple

public Checkpointer.CheckpointTuple getTuple(String threadId,
 String checkpointId)

Description copied from interface: Checkpointer

Fetch a checkpoint.

Specified by:

getTuple in interface Checkpointer

Parameters:

threadId - Thread identifier

checkpointId - Checkpoint identifier (null for latest)

Returns:

Checkpoint tuple

list

public List<Checkpointer.CheckpointTuple> list(String threadId)

Description copied from interface: Checkpointer

List checkpoints for a thread.

Specified by:

list in interface Checkpointer

Parameters:

threadId - Thread identifier

Returns:

List of checkpoints

delete

public void delete(String threadId)

Description copied from interface: Checkpointer

Delete checkpoints for a thread.

Specified by:

delete in interface Checkpointer

Parameters:

threadId - Thread identifier

getCheckpointCount

public int getCheckpointCount()

Get the total number of checkpoint files.

Returns:

total checkpoint count

getTotalSize

public long getTotalSize()

Get the total size of all checkpoint files in bytes.

Returns:

total size in bytes

clear

public void clear()

Clear all checkpoints.