Package dev.galasa.framework.spi

Interface IDynamicStatusStoreKeyAccess

All Known Subinterfaces:
IDynamicResource, IDynamicStatusStore, IDynamicStatusStoreService
public interface IDynamicStatusStoreKeyAccess

Used to gain access to properties in the Dynamic Status Store

The framework will be configured with a single Dynamic Status Store where all the dynamic properties for run and resources are kept.

etcd3 is the preferred dynamic status store for Galasa

An IDynamicStatusStoreKeyAccess can be obtained from IFramework.getDynamicStatusStoreService(String).

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    delete(@NotNull String key)
    Delete the key
    void
    delete(@NotNull Set<String> keys)
    Delete a set of keys from the server
    void
    deletePrefix(@NotNull String keyPrefix)
    Delete all keys with this prefix
    @Null String
    get(@NotNull String key)
    Retrieves a string property from the Dynamic Status Store
    @NotNull Map<String,String>
    getPrefix(@NotNull String keyPrefix)
    Retrieve all values with this key prefix
    void
    performActions(IDssAction... actions)
    Will perform multiple actions on the DSS in an atomic fashion.
    void
    put(@NotNull String key, @NotNull String value)
    Store a new key value pair in the server
    void
    put(@NotNull Map<String,String> keyValues)
    Store multiple key/value pairs in the server.
    boolean
    putSwap(@NotNull String key, String oldValue, @NotNull String newValue)
    Put a key/value pair in the server if the key is set to the oldValue.
    boolean
    putSwap(@NotNull String key, String oldValue, @NotNull String newValue, @NotNull Map<String,String> others)
    Put a key/value pair in the server if the key is set to the old value, along with a set of other key value pairs
    void
    unwatch(UUID watchId)
    This method is used to stop any watcher service with a given UUID.
    UUID
    watch(IDynamicStatusStoreWatcher watcher, String key)
    This method provides a watching service for a key value pair inside properties.
    UUID
    watchPrefix(IDynamicStatusStoreWatcher watcher, String keyPrefix)
    This method provides a single watch service to watch multiple k-v pairs with a common prefix in there key.

  • Method Details

    • put

      void put(@NotNull @NotNull String key, @NotNull @NotNull String value) throws DynamicStatusStoreException
      Store a new key value pair in the server
      Parameters:
      key - - the key to use
      value - - the value to use
      Throws:
      DynamicStatusStoreException

    • put

      void put(@NotNull @NotNull Map<String,String> keyValues) throws DynamicStatusStoreException
      Store multiple key/value pairs in the server.
      Parameters:
      keyValues - - map of key/value pairs
      Throws:
      DynamicStatusStoreException

    • putSwap

      boolean putSwap(@NotNull @NotNull String key, String oldValue, @NotNull @NotNull String newValue) throws DynamicStatusStoreException
      Put a key/value pair in the server if the key is set to the oldValue.
      Parameters:
      key - - the key to use
      oldValue - - the value to compare with and must be equal to before the put is actioned. Null means does not exist
      newValue - - The new value to set the key to
      Returns:
      true if the put was actioned, false if not.
      Throws:
      DynamicStatusStoreException

    • putSwap

      boolean putSwap(@NotNull @NotNull String key, String oldValue, @NotNull @NotNull String newValue, @NotNull @NotNull Map<String,String> others) throws DynamicStatusStoreException
      Put a key/value pair in the server if the key is set to the old value, along with a set of other key value pairs
      Parameters:
      key - - the key to use
      oldValue - - the value to compare with and must be equal to before the put is actioned. Null means does not exist
      newValue - - The new value to set the key to
      others - - other key/value pairs to put if the primary key is valid.
      Returns:
      true if the
      Throws:
      DynamicStatusStoreException

    • get

      @Null @Null String get(@NotNull @NotNull String key) throws DynamicStatusStoreException

      Retrieves a string property from the Dynamic Status Store

      Parameters:
      key - The name of the property.
      Returns:
      The value of the property, can be null if it does not exist
      Throws:
      DynamicStatusStoreException

    • getPrefix

      @NotNull @NotNull Map<String,String> getPrefix(@NotNull @NotNull String keyPrefix) throws DynamicStatusStoreException
      Retrieve all values with this key prefix
      Parameters:
      keyPrefix - - the prefix of all the keys to use.
      Returns:
      A map. The keys start with the specified prefix. The value is a string.
      Throws:
      DynamicStatusStoreException

    • delete

      void delete(@NotNull @NotNull String key) throws DynamicStatusStoreException
      Delete the key
      Parameters:
      key - - the key to use
      Throws:
      DynamicStatusStoreException

    • delete

      void delete(@NotNull @NotNull Set<String> keys) throws DynamicStatusStoreException
      Delete a set of keys from the server
      Parameters:
      keys - - all the keys that need to be deleted
      Throws:
      DynamicStatusStoreException

    • deletePrefix

      void deletePrefix(@NotNull @NotNull String keyPrefix) throws DynamicStatusStoreException
      Delete all keys with this prefix
      Parameters:
      keyPrefix - - the prefix of all the keys to use.
      Throws:
      DynamicStatusStoreException

    • performActions

      void performActions(IDssAction... actions) throws DynamicStatusStoreException, DynamicStatusStoreMatchException
      Will perform multiple actions on the DSS in an atomic fashion. If any of the actions fail, they all fail.
      Parameters:
      actions - a list of actions to perform on the DSS.
      Throws:
      DynamicStatusStoreException
      DynamicStatusStoreMatchException - - if preconditions fail

    • watch

      UUID watch(IDynamicStatusStoreWatcher watcher, String key) throws DynamicStatusStoreException

      This method provides a watching service for a key value pair inside properties. The value does not need to exsists to create a watcher. The watcher records the activity and event type on detection of chnageds (Modified, Deleted, Created).

      The watcher service uses two methods of detecting changes to the file. A polling service which montiors the file every 50ms for any changes. It also uses the checkAndNotify() methods provided from the observer set up on the class intialiastion, which is a manual check for file changes which notifies any watches.

      Parameters:
      watcher - - an interface for the watchers inplementation.
      key - - the string key to watch
      Returns:
      - returns a UUID which is used to identify a watcher service.
      Throws:
      DynamicStatusStoreException

    • watchPrefix

      UUID watchPrefix(IDynamicStatusStoreWatcher watcher, String keyPrefix) throws DynamicStatusStoreException

      This method provides a single watch service to watch multiple k-v pairs with a common prefix in there key.

      Parameters:
      watcher - - an interface for the watchers inplementation.
      keyPrefix - - the string prefix to a key set to watch
      Returns:
      - returns a UUID which is used to identify a watcher service.
      Throws:
      DynamicStatusStoreException

    • unwatch

      void unwatch(UUID watchId) throws DynamicStatusStoreException

      This method is used to stop any watcher service with a given UUID. It removes the given watcher from the watches list. If this is the final watcher in the list the method also shuts down the monitor

      Parameters:
      watchId - - the identifying UUID
      Throws:
      DynamicStatusStoreException