Package org.mockserver.state

Interface KeyValueStore<V>

Type Parameters:
V - the value type
All Known Implementing Classes:
InfinispanKeyValueStore, InMemoryExpectationKeyValueStore, InMemoryKeyValueStore
public interface KeyValueStore<V>
Versioned key-value store abstraction for shared MockServer state.

The in-memory implementation wraps the existing concurrent data structures (e.g. CircularPriorityQueue for expectations, ConcurrentHashMap for scenario state). A clustered implementation can back this with a distributed cache while preserving identical semantics.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static final class 
    KeyValueStore.Entry<V>
    A key-value entry with version metadata.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addInvalidationListener(InvalidationListener listener)
    Adds an invalidation listener that is notified on mutations.
    void
    clear()
    Removes all entries.
    boolean
    compareAndRemove(String key, long expectedVersion)
    Atomically removes the entry only if the current version matches expectedVersion.
    boolean
    compareAndSet(String key, long expectedVersion, V value)
    Atomically replaces the value only if the current version matches expectedVersion.
    Stream<KeyValueStore.Entry<V>>
    entries()
    Returns a stream of all entries.
    Optional<Versioned<V>>
    get(String key)
    Retrieves the versioned value for the given key.
    long
    put(String key, V value)
    Unconditionally puts a value, creating or replacing any existing entry.
    Optional<Versioned<V>>
    putIfAbsent(String key, V value)
    Atomically inserts the value only if no entry for the key exists yet.
    boolean
    remove(String key)
    Unconditionally removes the entry for the given key.
    int
    size()
    Returns the number of entries.

  • Method Details

    • get

      Optional<Versioned<V>> get(String key)
      Retrieves the versioned value for the given key.
      Parameters:
      key - the key
      Returns:
      the versioned value, or empty if not present

    • put

      long put(String key, V value)
      Unconditionally puts a value, creating or replacing any existing entry. Returns the new version.

      Semantics are last-writer-wins: concurrent put calls for the same key race and the final value is whichever write lands last (mirroring ConcurrentHashMap). Callers that need to detect/avoid lost updates must use compareAndSet(java.lang.String, long, V) with the version from a prior get(java.lang.String).

      Parameters:
      key - the key
      value - the value
      Returns:
      the version assigned to this write

    • putIfAbsent

      Optional<Versioned<V>> putIfAbsent(String key, V value)
      Atomically inserts the value only if no entry for the key exists yet. If the key is already present, the store is not modified and the existing versioned value is returned. If insertion succeeds, an empty Optional is returned.

      This is the create-only counterpart of put(java.lang.String, V): it never overwrites an existing entry. Callers that need last-writer-wins semantics should use put(java.lang.String, V); callers that need to detect and defer to a concurrent creator should use this method.

      Parameters:
      key - the key
      value - the value to insert
      Returns:
      empty if the entry was created by this call; otherwise the existing versioned value that was already present

    • compareAndSet

      boolean compareAndSet(String key, long expectedVersion, V value)
      Atomically replaces the value only if the current version matches expectedVersion. Returns true on success.
      Parameters:
      key - the key
      expectedVersion - the version the caller last read
      value - the new value
      Returns:
      true if the swap succeeded

    • compareAndRemove

      boolean compareAndRemove(String key, long expectedVersion)
      Atomically removes the entry only if the current version matches expectedVersion. Returns true on success.
      Parameters:
      key - the key
      expectedVersion - the version the caller last read
      Returns:
      true if the removal succeeded

    • remove

      boolean remove(String key)
      Unconditionally removes the entry for the given key.
      Parameters:
      key - the key
      Returns:
      true if the key was present

    • entries

      Stream<KeyValueStore.Entry<V>> entries()
      Returns a stream of all entries. The iteration order is implementation-defined (unordered for a generic KV; sorted for the expectation store).
      Returns:
      stream of key-versioned-value triples

    • size

      int size()
      Returns the number of entries.

    • clear

      void clear()
      Removes all entries.

    • addInvalidationListener

      void addInvalidationListener(InvalidationListener listener)
      Adds an invalidation listener that is notified on mutations.
      Parameters:
      listener - the listener