Package dev.galasa.framework.spi

Class FrameworkPropertyFile

java.lang.Object
dev.galasa.framework.spi.FrameworkPropertyFile
All Implemented Interfaces:
org.apache.commons.io.monitor.FileAlterationListener
public class FrameworkPropertyFile extends Object implements org.apache.commons.io.monitor.FileAlterationListener

Used by Galasa as an out of the box key value store. It is reccommended to use etcd3 for a performant system.

When provded with a URI to a K-V properties file, the FPF class can provide functionality similar to etcd3, including sets, gets, deletes, atomic sets and the watchng of values inside the properties.

Author:
James Davies

  • Constructor Summary

    Constructors
    Constructor
    Description
    FrameworkPropertyFile(URI file)
    This constructor loads the properties store in the file into memory.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    delete(String key)
    This method deletes a k-v pair from the property store.
    void
    delete(Set<String> keys)
    This method does the same as the regular delete for a single k-v pair, but for a set of key values.
    void
    deletePrefix(String prefix)
    This method deletes the set of key values with a certain prefix.
    void
    destroy()
    This method cleans up the properties in memory, the observers and monitors.
    String
    get(String key)
    This method retrieves the most up to date value from a specified key.
    List<String>
    getNamespaces()
    This method retrieves a List of namespaces which have properties set in the properties file.
    Map<String,String>
    getPrefix(String keyPrefix)
    This method retrieves a Map of values from the properties file that have a common prefix to the key.
    void
    load()
    This method is used for loading the properties from the java properties file in a memory loaded properties
    void
    onDirectoryChange(File file)
    This method is not used
    void
    onDirectoryCreate(File file)
    This method is not used
    void
    onDirectoryDelete(File file)
    This method is not used
    void
    onFileChange(File file)
    This method invoked when the montior thread detects a change to the file being observed
    void
    onFileCreate(File file)
    This method is not used
    void
    onFileDelete(File file)
    This method is not used
    void
    onStart(org.apache.commons.io.monitor.FileAlterationObserver observer)
    This method is not used
    void
    onStop(org.apache.commons.io.monitor.FileAlterationObserver observer)
    This method is not used
    void
    performActions(IDssAction... actions)
     
    void
    set(String key, String value)
    This method is used to set a single k-v pair into the properties file.
    void
    set(Map<String,String> values)
    This method is used for setting multiple k-v pairs into the file.
    boolean
    setAtomic(String key, String oldValue, String newValue)
    This memthod can perform a atomic set.
    boolean
    setAtomic(String key, String oldValue, String newValue, Map<String,String> otherValues)
    This methods also performs and atomic set, but with the additional feature of setting a map of other k-v pairs if the old value is found to be the current value
    void
    shutdown()
     
    void
    unwatch(UUID watchId)
    This method is used to stop any watcher service with a given UUID.
    UUID
    watch(IFrameworkPropertyFileWatcher watcher, String key)
    This method provides a watching service for a key value pair inside properties.
    UUID
    watchPrefix(IFrameworkPropertyFileWatcher watcher, String keyPrefix)
    This method provides a single watch service to watch multiple k-v pairs with a common prefix in there key.
    void
    write(FileChannel fileChannel, Properties newProperties)
    This method is used for the writing of the current properties in memory to be stored in the java properties file defined by the URI.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • FrameworkPropertyFile

      public FrameworkPropertyFile(URI file) throws FrameworkPropertyFileException

      This constructor loads the properties store in the file into memory. For the watchers to get updates from the file in question and not other files in the directory, the observer is intialised with a file filter.

      Parameters:
      file - - URI of the java properties file
      Throws:
      FrameworkPropertyFileException

  • Method Details

    • get

      public String get(String key)

      This method retrieves the most up to date value from a specified key.

      Parameters:
      key -
      Returns:
      - corresponding value from the key, null if non-exsisting

    • getPrefix

      public Map<String,String> getPrefix(String keyPrefix)

      This method retrieves a Map of values from the properties file that have a common prefix to the key.

      Parameters:
      keyPrefix - - a common key prefix to a number of keys in the property store.
      Returns:
      A map of any size or null. The key is a string which starts with the specified prefix.

    • getNamespaces

      public List<String> getNamespaces()

      This method retrieves a List of namespaces which have properties set in the properties file.

      Returns:
      - List of namespaces

    • delete

      public void delete(String key) throws FrameworkPropertyFileException

      This method deletes a k-v pair from the property store. As the properties file is changed, the fileModified method is invoked to update any watchers.

      Parameters:
      key - - the string key to be removoed from the loaded and file properties.
      Throws:
      FrameworkPropertyFileException

    • delete

      public void delete(Set<String> keys) throws FrameworkPropertyFileException
      This method does the same as the regular delete for a single k-v pair, but for a set of key values. Again the fileModified is invoked.
      Parameters:
      keys - - a set of string keys to remove from properties
      Throws:
      FrameworkPropertyFileException

    • deletePrefix

      public void deletePrefix(String prefix) throws FrameworkPropertyFileException
      This method deletes the set of key values with a certain prefix.
      Parameters:
      prefix - - a prefix of keys to remove from properties
      Throws:
      FrameworkPropertyFileException

    • performActions

      public void performActions(IDssAction... actions) throws DynamicStatusStoreException, DynamicStatusStoreMatchException
      Throws:
      DynamicStatusStoreException
      DynamicStatusStoreMatchException

    • write

      public void write(FileChannel fileChannel, Properties newProperties) throws IOException

      This method is used for the writing of the current properties in memory to be stored in the java properties file defined by the URI.

      Parameters:
      fileChannel - - a write file channel that has an exclusive lock.
      newProperties - - the most up to date properties in memory
      Throws:
      IOException

    • set

      public void set(String key, String value) throws FrameworkPropertyFileException

      This method is used to set a single k-v pair into the properties file. fileModified is invoked as to update watchers to any changed values that are being watched.

      Parameters:
      key - - String key
      value - - String value
      Throws:
      FrameworkPropertyFileException

    • set

      public void set(Map<String,String> values) throws FrameworkPropertyFileException, IOException

      This method is used for setting multiple k-v pairs into the file. This method is sycnronized on the class to ensure all values are set before any other work is completed

      Parameters:
      values - - a String String map of k-v pairs.
      Throws:
      FrameworkPropertyFileException
      IOException

    • watch

      public UUID watch(IFrameworkPropertyFileWatcher watcher, String key) throws FrameworkPropertyFileException

      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:
      FrameworkPropertyFileException

    • unwatch

      public void unwatch(UUID watchId) throws FrameworkPropertyFileException

      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:
      FrameworkPropertyFileException

    • watchPrefix

      public UUID watchPrefix(IFrameworkPropertyFileWatcher watcher, String keyPrefix) throws FrameworkPropertyFileException

      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:
      FrameworkPropertyFileException

    • setAtomic

      public boolean setAtomic(String key, String oldValue, String newValue) throws FrameworkPropertyFileException

      This memthod can perform a atomic set. This provides a set functionality in the case where a key is currrenly set to a specific value. If the value is not as expected, then no set is performed. fileModified is invoked to update any possible watches.

      This method is sycnronized on the class to ensure all values are set before any other work is completed

      The method will also fail if the oldvalue is null, which indicates that there is no key of that string.

      Parameters:
      key - the key that is to be changed.
      oldValue - the expected current value.
      newValue - the value to change to if the expected value is true.
      Returns:
      returns a boolean which informs if the set took place.
      Throws:
      FrameworkPropertyFileException

    • setAtomic

      public boolean setAtomic(String key, String oldValue, String newValue, Map<String,String> otherValues) throws FrameworkPropertyFileException

      This methods also performs and atomic set, but with the additional feature of setting a map of other k-v pairs if the old value is found to be the current value

      This method is sycnronized on the class to ensure all values are set before any other work is completed

      The method will also fail if the oldvalue is null, which indicates that there is no key of that string.

      Parameters:
      key - - String key
      oldValue - - String expected value
      newValue - - String value to change to if key has oldvalue
      otherValues - - Map of k-v pairs to set if key has oldvalue
      Returns:
      - boolean for if the atomic set was done
      Throws:
      FrameworkPropertyFileException

    • destroy

      public void destroy() throws FrameworkPropertyFileException

      This method cleans up the properties in memory, the observers and monitors.

      Throws:
      FrameworkPropertyFileException

    • load

      public void load() throws FrameworkPropertyFileException

      This method is used for loading the properties from the java properties file in a memory loaded properties

      *

      This method is sycnronized on the class to ensure all values are set before any other work is completed

      Throws:
      FrameworkPropertyFileException

    • onStart

      public void onStart(org.apache.commons.io.monitor.FileAlterationObserver observer)

      This method is not used

      Specified by:
      onStart in interface org.apache.commons.io.monitor.FileAlterationListener

    • onStop

      public void onStop(org.apache.commons.io.monitor.FileAlterationObserver observer)

      This method is not used

      Specified by:
      onStop in interface org.apache.commons.io.monitor.FileAlterationListener

    • onFileChange

      public void onFileChange(File file)

      This method invoked when the montior thread detects a change to the file being observed

      As this is an implemented method, it cannot throw a exception so the exception is logged

      Specified by:
      onFileChange in interface org.apache.commons.io.monitor.FileAlterationListener

    • onFileCreate

      public void onFileCreate(File file)

      This method is not used

      Specified by:
      onFileCreate in interface org.apache.commons.io.monitor.FileAlterationListener

    • onFileDelete

      public void onFileDelete(File file)

      This method is not used

      Specified by:
      onFileDelete in interface org.apache.commons.io.monitor.FileAlterationListener

    • onDirectoryCreate

      public void onDirectoryCreate(File file)

      This method is not used

      Specified by:
      onDirectoryCreate in interface org.apache.commons.io.monitor.FileAlterationListener

    • onDirectoryChange

      public void onDirectoryChange(File file)

      This method is not used

      Specified by:
      onDirectoryChange in interface org.apache.commons.io.monitor.FileAlterationListener

    • onDirectoryDelete

      public void onDirectoryDelete(File file)

      This method is not used

      Specified by:
      onDirectoryDelete in interface org.apache.commons.io.monitor.FileAlterationListener

    • shutdown

      public void shutdown() throws FrameworkPropertyFileException
      Throws:
      FrameworkPropertyFileException