langgraph/spec/JavaCheckpoint.md

Java Checkpoint Interfaces

This document defines the Java interfaces for the checkpoint layer of LangGraph, aligned with the Python implementation.

BaseCheckpointSaver Interface

The BaseCheckpointSaver interface provides methods for creating, loading, and managing checkpoints.

package com.langgraph.checkpoint.base;

import java.util.List;
import java.util.Map;
import java.util.Optional;

/**
 * Interface for saving and loading checkpoints.
 */
public interface BaseCheckpointSaver {
    /**
     * Create a new checkpoint.
     *
     * @param threadId The ID of the thread to checkpoint
     * @param channelValues The values of the channels to checkpoint
     * @return The ID of the new checkpoint
     */
    String checkpoint(String threadId, Map<String, Object> channelValues);

    /**
     * Get values from a checkpoint.
     *
     * @param checkpointId The ID of the checkpoint to load
     * @return The channel values from the checkpoint, or empty if not found
     */
    Optional<Map<String, Object>> getValues(String checkpointId);

    /**
     * List all checkpoints for a thread.
     *
     * @param threadId The ID of the thread
     * @return List of checkpoint IDs
     */
    List<String> list(String threadId);

    /**
     * Get the latest checkpoint for a thread.
     *
     * @param threadId The ID of the thread
     * @return The ID of the latest checkpoint, or empty if none exists
     */
    Optional<String> latest(String threadId);

    /**
     * Delete a checkpoint.
     *
     * @param checkpointId The ID of the checkpoint to delete
     */
    void delete(String checkpointId);

    /**
     * Clear all checkpoints for a thread.
     *
     * @param threadId The ID of the thread
     */
    void clear(String threadId);
}

ID Utility

A utility class for generating deterministic IDs, similar to the Python implementation.

package com.langgraph.checkpoint.base;

import java.nio.charset.StandardCharsets;
import java.util.UUID;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.Base64;

/**
 * Utility class for generating IDs.
 */
public final class ID {
    private ID() {} // Prevent instantiation

    /**
     * Generate a deterministic UUID based on a namespace and name.
     *
     * @param namespace The namespace for the ID
     * @param name The name within the namespace
     * @return A UUID
     */
    public static UUID uuid(String namespace, String name) {
        try {
            MessageDigest md = MessageDigest.getInstance("SHA-1");
            md.update(namespace.getBytes(StandardCharsets.UTF_8));
            md.update(name.getBytes(StandardCharsets.UTF_8));
            byte[] digest = md.digest();

            // Set the version (4) and variant (RFC4122) bits
            digest[6] = (byte) ((digest[6] & 0x0F) | 0x40);
            digest[8] = (byte) ((digest[8] & 0x3F) | 0x80);

            long msb = 0;
            long lsb = 0;

            for (int i = 0; i < 8; i++) {
                msb = (msb << 8) | (digest[i] & 0xff);
            }

            for (int i = 8; i < 16; i++) {
                lsb = (lsb << 8) | (digest[i] & 0xff);
            }

            return new UUID(msb, lsb);
        } catch (NoSuchAlgorithmException e) {
            throw new RuntimeException("SHA-1 algorithm not available", e);
        }
    }

    /**
     * Generate a checkpoint ID.
     *
     * @param threadId The thread ID
     * @return A checkpoint ID
     */
    public static String checkpointId(String threadId) {
        return uuid("checkpoint", threadId + "/" + System.currentTimeMillis()).toString();
    }

    /**
     * Generate a URL-safe base64 encoded ID.
     *
     * @param namespace The namespace for the ID
     * @param name The name within the namespace
     * @return A URL-safe base64-encoded ID
     */
    public static String urlSafeId(String namespace, String name) {
        try {
            MessageDigest md = MessageDigest.getInstance("SHA-256");
            md.update(namespace.getBytes(StandardCharsets.UTF_8));
            md.update(name.getBytes(StandardCharsets.UTF_8));
            byte[] digest = md.digest();

            return Base64.getUrlEncoder().withoutPadding().encodeToString(digest);
        } catch (NoSuchAlgorithmException e) {
            throw new RuntimeException("SHA-256 algorithm not available", e);
        }
    }
}