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).

Author:

Michael Baylis

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