[Use Cases] Add use cases for mounting

doc/news/_preparation_next_release.md

@@ -404,7 +404,7 @@ This section keeps you up-to-date with the multi-language support provided by El
 - <<TODO>>
 - <<TODO>>
 - <<TODO>>
-- <<TODO>>
+- Add use cases for mounting _(Florian Lindner @flo91)_
 - <<TODO>>
 - <<TODO>>
 - <<TODO>>

doc/usecases/mount/README.md

@@ -0,0 +1,25 @@
+# Use cases for mounting
+
+This folder contains the use cases for mounting, which means accessing configuration data sources (e.g. files, databases)
+through Elektra.
+
+The goal is to have a common key-value based view of configuration data that is stored in different data sources.
+
+## Basic use cases
+
+- [Mount a data source](./UC_mount.md)
+- [Unmount a data source](./UC_unmount.md)
+- [List all mountpoints](./UC_list_mountpoints.md)
+- [List all configuration keys and values from all currently mounted data sources](./UC_list_values.md)
+
+## CRUD (Create, Read, Update, Delete) use cases
+
+- [Read a configuration value from a file](./UC_read_file.md)
+- [Edit a configuration value stored in a file](./UC_edit_file.md)
+- [Write new configuration data to a file](./UC_write_file.md)
+- [Delete configuration data from a file](./UC_delete_from_file.md)
+
+- [Read a configuration value from a relational database](./UC_read_rdb.md)
+- [Edit a configuration value stored in a relational database](./UC_edit_rdb.md)
+- [Write new configuration data to a relational database](./UC_write_rdb.md)
+- [Delete configuration data from a relational database](./UC_delete_from_rdb.md)

doc/usecases/mount/UC_delete_from_file.md

@@ -0,0 +1,52 @@
+# Use Case: Delete configuration data from a file
+
+## Summary
+
+- **Scope:** Mounting
+- **Level:** Sea
+- **Actors:** Administrators
+- **Brief:** The administrators can use Elektra to delete a key and its associated value if it is stored in a file that has a supported format.
+- **Status:** Implemented
+
+## Scenarios
+
+- **Precondition:**
+
+  - The administrators have a working installation of Elektra and a tool to access the KDB (key database) on their system.
+  - The configuration file is mounted into the KDB. (see [Use Case: Mount a data source](./UC_mount.md))
+
+- **Main success scenario:**
+
+  - The administrators query a value from the mounted file by giving the unique keyname. (see [Use Case: Read a configuration value from a file](./UC_read_file.md))
+  - Elektra returns the current value of the given key to the administrators.
+  - The administrators command Elektra to remove the key and its associated value by giving the unique keyname.
+  - Elektra removes the entry for the given key from the mounted configuration file.
+  - The administrators query the same keyname as in the first step.
+  - Elektra now gives a message to the administrators that tells them that the requested key does not exist.
+  - The administrators open the configuration file in a text editor to check if the entry was correctly deleted from the file. (applies only to text-based file formats)
+
+- **Alternative scenario:**
+
+  - The requested key is not found in the configuration file.
+    - Elektra reports the error to the administrators.
+
+- **Error scenario:**
+
+  - The opening of the configuration file failed. (e.g. broken storage, faulty filesystem, network error).
+    - Elektra reports the error to the administrators.
+  - Writing to the configuration file failed. (e.g. because of missing permissions)
+    - Elektra reports the error to the administrators.
+
+- **Postconditions:**
+
+  - If the administrators use Elektra to read the value of the removed key, an error message must be returned.
+  - The change must be written to the mounted configuration file. (can be verified by opening the file with a text editor)
+
+- **Non-functional Constraints:**
+
+  - Deleting a key stored in the mounted file through Elektra should not take more than twice the time that is required to
+    edit the file with a text editor and do the same change.
+    - Only the loading and saving of the file is counted, not the time the administrators need to edit the file.
+    - For a benchmark, the editing of the file should be scripted.
+    - For access times less than one second, the access through Elektra should not add more than one second.
+    - This constraint is only applicable for text-based file formats, not for binary files.

doc/usecases/mount/UC_delete_from_rdb.md

@@ -0,0 +1,49 @@
+# Use Case: Delete configuration data from a relational database
+
+## Summary
+
+- **Scope:** Mounting
+- **Level:** Sea
+- **Actors:** Administrators
+- **Brief:** The administrators can use Elektra to delete a key and its associated value stored in a supported relational database.
+- **Status:** Draft
+
+## Scenarios
+
+- **Precondition:**
+
+  - The administrators have a working installation of Elektra and a tool to access the KDB (key database) on their system.
+  - The database is mounted into the KDB. (see [Use Case: Mount a data source](./UC_mount.md))
+
+- **Main success scenario:**
+
+  - The administrators query a value from the mounted database by giving the unique keyname. (see [Use Case: Read a configuration value from a file](./UC_read_rdb.md))
+  - Elektra returns the current value of the given key to the administrators.
+  - The administrators command Elektra to remove the key and its associated value by giving the unique keyname.
+  - Elektra removes the affected tuple from the database.
+  - The administrators query the same key as in the first step from Elektra.
+  - Elektra gives an error message to the administrators which tells them that the requested key does not exist.
+  - The administrators query the database directly to verify that the requested key and value were deleted.
+
+- **Alternative scenario:**
+
+  - The requested key is not found in the database.
+    - Elektra reports the error to the administrators.
+
+- **Error scenario:**
+
+  - The connection to the database failed. (e.g. network error)
+    - Elektra reports the error to the administrators.
+  - Writing to the database table(s) failed. (e.g. because of missing permissions or full storage)
+    - Elektra reports the error to the administrators.
+
+- **Postconditions:**
+
+  - If the administrators use Elektra to read the value of the removed key, an error message must be returned.
+  - The change must be written to the mounted database. (can be verified by querying the database directly, e.g. by using SQL)
+
+- **Non-functional Constraints:**
+
+  - Deleting a key stored in the mounted database through Elektra should not take more than twice the time that is required to delete the tuple directly in the database without using Elektra. (e.g. by using SQL)
+    - For access times less than one second, the access through Elektra should not add more than one second.
+    - If the datasource is accessed through an intermediate data access layer (e.g. ODBC), than the same data access layer is also used for retrieving the time for the access without Elektra.

doc/usecases/mount/UC_edit_file.md

@@ -0,0 +1,52 @@
+# Use Case: Edit a configuration value stored in a file
+
+## Summary
+
+- **Scope:** Mounting
+- **Level:** Sea
+- **Actors:** Administrators
+- **Brief:** The administrators can use Elektra to change key-value based configuration data stored in a file that has a supported format.
+- **Status:** Implemented
+
+## Scenarios
+
+- **Precondition:**
+
+  - The administrators have a working installation of Elektra and a tool to access the KDB (key database) on their system.
+  - The configuration file is mounted into the KDB. (see [Use Case: Mount a data source](./UC_mount.md))
+
+- **Main success scenario:**
+
+  - The administrators query a value from the mounted file by giving the unique keyname. (see [Use Case: Read a configuration value from a file](./UC_read_file.md))
+  - Elektra returns the current (old) value of the given key to the administrators.
+  - The administrators query Elektra to change the value of the given key, by giving the unique keyname and the new value.
+  - Elektra updates the value in the mounted configuration file.
+  - The administrators query the same key as in the first step.
+  - Elektra returns the new value of the given key to the administrators.
+  - The administrators open the affected file to check that the requested changes were written correctly and to the correct file. (applies only to text-based file formats)
+
+- **Alternative scenario:**
+
+  - The requested key is not found in the configuration file.
+    - Elektra reports the error to the administrators.
+
+- **Error scenario:**
+
+  - The opening of the configuration file failed. (e.g. broken storage, faulty filesystem, network error).
+    - Elektra reports the error to the administrators.
+  - Writing to the configuration file failed. (e.g. because of missing permissions)
+    - Elektra reports the error to the administrators.
+
+- **Postconditions:**
+
+  - If the administrators use Elektra to read the value of the edited key, the new value must be returned.
+  - The change must be written to the mounted configuration file. (can be verified by opening the file with a text editor)
+
+- **Non-functional Constraints:**
+
+  - Changing the value of a key stored in the mounted file through Elektra should not take more than twice the time that is required to
+    edit the file with a text editor and do the same change.
+    - Only the loading and saving of the file is counted, not the time the administrators need to edit the file.
+    - For a benchmark, the editing of the file should be scripted.
+    - For access times less than one second, the access through Elektra should not add more than one second.
+    - This constraint is only applicable for text-based file formats, not for binary files.

doc/usecases/mount/UC_edit_rdb.md

@@ -0,0 +1,49 @@
+# Use Case: Edit a configuration value stored in a relational database
+
+## Summary
+
+- **Scope:** Mounting
+- **Level:** Sea
+- **Actors:** Administrators
+- **Brief:** The administrators can use Elektra to change key-value based configuration data stored in a supported relational database.
+- **Status:** Draft
+
+## Scenarios
+
+- **Precondition:**
+
+  - The administrators have a working installation of Elektra and a tool to access the KDB (key database) on their system.
+  - The database is mounted into the KDB. (see [Use Case: Mount a data source](./UC_mount.md))
+
+- **Main success scenario:**
+
+  - The administrators query a value from the mounted database by giving the unique keyname. (see [Use Case: Read a configuration value from a file](./UC_read_rdb.md))
+  - Elektra reads the current (old) value from the mounted database and returns it to the administrators.
+  - The administrators use Elektra to change the value of the given key, by giving the unique keyname and the new value.
+  - Elektra updates the affected tuple in the database.
+  - The administrators query the same key as in the first step.
+  - Elektra returns the new value of the given key to the administrators.
+  - The administrators query the database directly to verify that the requested change was written.
+
+- **Alternative scenario:**
+
+  - The requested key is not found in the database.
+    - Elektra reports the error to the administrators.
+
+- **Error scenario:**
+
+  - The connection to the database failed. (e.g. network error)
+    - Elektra reports the error to the administrators.
+  - Writing to the database table(s) failed. (e.g. because of missing permissions or full storage)
+    - Elektra reports the error to the administrators.
+
+- **Postconditions:**
+
+  - If the administrators use Elektra to read the value of the edited key, the new value must be returned.
+  - The change must be written to the mounted database. (can be verified by querying the database directly, e.g. by using SQL)
+
+- **Non-functional Constraints:**
+
+  - Changing the value of a key stored in the mounted database through Elektra should not take more than twice the time that is required to change the value directly in the database without using Elektra. (e.g. by using SQL)
+    - For access times less than one second, the access through Elektra should not add more than one second.
+    - If the datasource is accessed through an intermediate data access layer (e.g. ODBC), than the same data access layer is also used for retrieving the time for the access without Elektra.

doc/usecases/mount/UC_list_mountpoints.md

@@ -0,0 +1,47 @@
+# Use Case: List all mountpoints
+
+## Summary
+
+- **Scope:** Mounting
+- **Level:** Kite
+- **Actors:** Administrators
+- **Brief:** The administrators can query the current mountpoints.
+- **Status:** Implemented (currently only file-based data sources can be mounted)
+
+## Scenarios
+
+- **Precondition:**
+
+  - The administrators have a working installation of Elektra and a tool to access the KDB (key database) on their systems.
+
+- **Main success scenario:**
+
+  - The administrators use Elektra to query a list with all current mountpoints.
+  - Elektra returns the list with the mountpoints and the data source identifiers. (e.g. filename and path, data source name)
+  - The administrators mount a new data source. (see [Use Case: Mount a data source](./UC_mount.md))
+  - The administrators use Elektra to query a list with all current mountpoints.
+  - The new mountpoint is now added to the list.
+  - The administrators unmount the previously mounted data source. (see [Use Case: Unmount a data source](./UC_unmount.md))
+  - The administrators use Elektra to query a list with all current mountpoints.
+  - The mountpoint for the unmounted data source is now not included in the list.
+
+- **Alternative scenario:**
+
+  - none new
+  - The scenarios of the used use cases (mounting and unmounting) apply.
+
+- **Error scenario:**
+
+  - An error occurred while mounting the data source. (see [Use Case: Mount a data source](./UC_mount.md))
+    - Elektra reports the error to the administrators.
+  - An error occurred while unmounting the data source. (see [Use Case: Unmount a data source](./UC_unmount.md))
+    - Elektra reports the error to the administrators.
+
+- **Postconditions:**
+
+  - The administrators get a (possibly empty) list of all data sources that are currently mounted into the KDB.
+  - No data in any of the mounted data sources has changed.
+
+- **Non-functional Constraints:**
+
+  - Listing the mountpoints should not take more than three seconds. (reference system has to be defined) for less than 100 mountpoints

doc/usecases/mount/UC_list_values.md

@@ -0,0 +1,40 @@
+# Use Case: List all configuration keys and values from all currently mounted data sources
+
+## Summary
+
+- **Scope:** Mounting
+- **Level:** Kite
+- **Actors:** Administrators
+- **Brief:** The administrators can use Elektra to get a list of all keynames and associated values from all currently mounted data sources.
+- **Status:** Implemented (currently only file-based data sources can be mounted)
+
+## Scenarios
+
+- **Precondition:**
+
+  - The administrators have a working installation of Elektra and a tool to access the KDB (key database) on their systems.
+
+- **Main success scenario:**
+
+  - The administrators query a list with all keys and values from the currently mounted data sources.
+  - Elektra returns the requested list.
+
+- **Alternative scenario:**
+
+  - none
+
+- **Error scenario:**
+
+  - The reading from at least one mounted data source failed.
+    - Elektra reports the error to the administrators.
+
+- **Postconditions:**
+
+  - The administrators can see a list with all keynames and values from all mounted data sources.
+  - Nothing is written to any of the data sources.
+
+- **Non-functional Constraints:**
+
+  - Creating the list should not take longer than twice the time to query all mounted data source without Elektra.
+    - This means for text-based files to print them to stdout and for databases to select all entries (`SELECT * from <table>`)
+    - For access times less than one second (sum of access times for all mounted data sources), the access through Elektra should not add more than one second.

doc/usecases/mount/UC_mount.md

@@ -0,0 +1,43 @@
+# Use Case: Mount a data source
+
+## Summary
+
+- **Scope:** Mounting
+- **Level:** Kite
+- **Actors:** Administrators
+- **Brief:** The administrators can include configuration data from different data sources into Elektra.
+- **Status:** Draft (currently only files are supported)
+
+## Scenarios
+
+- **Precondition:**
+
+  - The administrators have a working installation of Elektra and a tool to access the KDB (key database) on their system.
+
+- **Main success scenario:**
+
+  - The administrators specify a mountpoint in the KDB and an identifier for the data source they want to mount.
+    - For file-based data sources, the identifier is usually the path and filename.
+  - The data source is successfully mounted into the KDB.
+
+- **Alternative scenario:**
+
+  - The given data source is not found. (e.g. wrong filename)
+    - Elektra reports the error to the administrators.
+  - The given data source is not supported by Elektra. (e.g. wrong file format, syntax errors)
+    - Elektra reports the error to the administrators.
+
+- **Error scenario:**
+
+  - The opening of the data source failed.
+    - Elektra reports the error to the administrators.
+
+- **Postconditions:**
+
+  - The newly mounted data source is listed when querying the current mountpoints. (see [Use Case: List all mountpoints](./UC_list_mountpoints.md))
+  - The administrators can now work (CRUD) with the configuration data stored in the newly mounted data source using Elektras key-value-based interface. (see other mounting use cases)
+
+- **Non-functional Constraints:**
+
+  - The mounting of new data sources should not take longer than 5 seconds (reference system has to be defined).
+    - Delays caused by slow storages or network connections are not a part of that constraint, because Elektra is not responsible for that areas.