Package io.cloudstub.core.spi

Interface StateStore

All Known Implementing Classes:
AppendLogStateStore, InMemoryStateStore, JsonFileStateStore
public interface StateStore
Shared key-value backend owned and lifecycle-managed by the core engine.

Modules read from and write to the store so that one AWS SDK call can affect the response to a later call. The store has no AWS knowledge — modules are responsible for translating between the AWS API protocol and store operations.

Keys follow a path-like hierarchy: {serviceId}/{resource-type}/{name}[/{subresource}/{id}] For example:

  • sqs/queues/my-queue/messages/abc-123
  • s3/buckets/my-bucket/objects/my-key
  • secrets/my-secret

The store does not enforce key prefixing — scoping by service ID is a module-authoring convention.

The admin REST API, CLI, and management console read from the store via get(java.lang.String) and list(java.lang.String). They never write directly — all writes flow through module code triggered by AWS SDK calls.

Implementations must be thread-safe. The AWS SDK may fire concurrent requests and multiple modules share the same store instance.

Values must be JSON-serialisable. A value is read back as its original concrete type, including after a restart of a persistent store, so the type a module puts is the type it can cast the result of get to.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    clear(String prefix)
    Delete all entries whose key begins with prefix.
    void
    clearAll()
    Delete all entries in the store across all services.
    void
    delete(String key)
    Delete a single entry.
    Object
    get(String key)
    Retrieve the value stored under key, or null if the key does not exist.
    List<String>
    list(String prefix)
    List all keys whose path begins with prefix.
    void
    put(String key, Object value)
    Store a value under key.

  • Method Details

    • put

      void put(String key, Object value)
      Store a value under key. Overwrites any existing entry at the same key.
      Parameters:
      key - path-style key, e.g. "sqs/queues/my-queue/messages/abc-123"
      value - the value to store; must be JSON-serialisable
      Throws:
      NullPointerException - if key or value is null
      CloudStubStateException - if a persistent store fails to write to disk

    • get

      Object get(String key)
      Retrieve the value stored under key, or null if the key does not exist.
      Parameters:
      key - path-style key
      Returns:
      the stored value, or null

    • list

      List<String> list(String prefix)
      List all keys whose path begins with prefix. Passing "sqs/" lists every key the SQS module has written.
      Parameters:
      prefix - key prefix to match
      Returns:
      sorted list of matching keys; empty if none match

    • delete

      void delete(String key)
      Delete a single entry. No-op if the key does not exist.
      Parameters:
      key - the key to delete

    • clear

      void clear(String prefix)
      Delete all entries whose key begins with prefix. Passing "sqs/" clears all SQS state.
      Parameters:
      prefix - the key prefix to clear

    • clearAll

      void clearAll()
      Delete all entries in the store across all services. Called by the global reset endpoint.