-
Notifications
You must be signed in to change notification settings - Fork 123
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[Use Cases] Add use cases for mounting #4773
base: master
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,25 @@ | ||
# Use cases for mounting | ||
|
||
This folder contains the use cases for mounting, which means accessing configuration data sources through Elektra. | ||
The use cases here cover configuration files and databases. | ||
|
||
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) |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 relational database](./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. |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 relational database](./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 creates a new tuple with the given key and value and writes it to the database. | ||
|
||
- **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. |
Original file line number | Diff line number | Diff line change | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
@@ -0,0 +1,43 @@ | ||||||||||||||||||||
# Use Case: List all mountpoints | ||||||||||||||||||||
|
||||||||||||||||||||
## Summary | ||||||||||||||||||||
|
||||||||||||||||||||
- **Scope:** Mounting | ||||||||||||||||||||
- **Level:** Kite | ||||||||||||||||||||
- **Actors:** Administrators | ||||||||||||||||||||
- **Brief:** The administrators can query the current mountpoints. | ||||||||||||||||||||
- **Status:** Draft (currently only file-based data sources can be listed) | ||||||||||||||||||||
|
||||||||||||||||||||
## 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. | ||||||||||||||||||||
Comment on lines
+19
to
+26
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The other use cases already cover mounting/umounting:
Suggested change
|
||||||||||||||||||||
|
||||||||||||||||||||
- **Alternative scenario:** | ||||||||||||||||||||
|
||||||||||||||||||||
- none new | ||||||||||||||||||||
- The scenarios of the used use cases (mounting and unmounting) apply. | ||||||||||||||||||||
|
||||||||||||||||||||
- **Error scenario:** | ||||||||||||||||||||
|
||||||||||||||||||||
|
||||||||||||||||||||
- **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 |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,40 @@ | ||
# Use Case: List all configuration keys and values from all currently mounted data sources | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I don't know which functionality this is? Is this |
||
|
||
## 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. |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 desired mountpoint already exists with a different configuration. | ||
- Elektra reports the error to the administrators, unless `--strategy` is used, then keys are merged as requested. | ||
- The given data source is not supported by Elektra. (e.g. wrong file format, syntax errors) | ||
- Elektra reports the error to the administrators. | ||
Comment on lines
+27
to
+28
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Why isn't this an error scenario? |
||
|
||
- **Error scenario:** | ||
|
||
- The opening of the data source failed. | ||
- Elektra reports the error to the administrators. | ||
Comment on lines
+32
to
+33
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Please describe what "opening of the data source failed" means. I don't think this is done during mounting except for the |
||
|
||
- **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:** | ||
|
||
- Mounting should be reasonable fast for interactive use. | ||
- Delays caused by slow storages or network connections are not a part of that constraint, because Elektra is not responsible for that areas. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would simplify this and only have a get and set use case. (Delete is part of set).
I think it is enough that you only write the rdb use cases.
I don't think they should be part of
mount
, but rather another folder ("rdb").