Ticket	Summary	Owner	Status	Type	Component	Priority	Effort	Importance
#118	PLUGIN_SUPPORT_LIB_CONFIGURING_R1	mitex	closed	planned_task	PLUGIN_ARCHITECTURE	3	1	0
Reported by Astea, 4 years ago.
Description	wiki page: PLUGIN_SUPPORT_LIB_CONFIGURING_R1 - effort: 1d
Analysis_owners	mitex
Analysis_reviewers	dido
Analysis_score	3.5
Design_owners	mitex
Design_reviewers	meddle
Design_score	3.5
Imp._owners	mitex
Imp._reviewers	meddle
Imp._score	3
Test_score	0

Analysis

Overview

The goal of this task is to provide ability to load and save configuration settings that are not defined by skins. For example, bug reporting requires user's e-mail address to be persisted.

Task requirements

• Configuration settings are stored as pairs (key, value).
• Loading and saving configuration settings should be easy and made in uniform way:
  • get : key -> value - reads the value from configuration file.
  • set : key, value - updates the value so any part of Sophie that depends on it is updated.

• Convention for configuration files:
  • Configuration files can be stored in distrib/conf/ directory of the corresponding plugin.
  • Their names should be unique for the application.
    • Use the name of the corresponding Sophie module, for example:
      • distrib/conf/org.sophie2.main.layout.mydoggy.conf
      • distrib/conf/org.sophie2.main.layout.mydoggy/some_name
  • Configuration files are saved in XML format.
  • Keys should be unique in a given configuration file, but there's no need to be globally unique, since the file names are unique.

• Make at least one of the following settings to be persisted in configuration files:
  • User's e-mail address in the bug report form.
  • Main window's size, location and state (maximized/normal).
  • Current skin - default or alternative.

Task result

• Source code.

Implementation idea

• This functionality has much in common with skins, but cannot be implemented as skins. So create a new module.

• Create a singleton class ConfigurationManager (or something else) that has the described get and set methods.

• Create a class Configuration that represents a single configuration file.
  • Use list of ListEntrys that stores all key-value pairs in that file.

• Create a generic class ConfigKey that encapsulates all of the information about a key:
  • key name
  • configuration file
  • default value (if the key is not present in the file)
  • schema (for the persistence)

• ConfigKeys should be defined as constants in the code, for example:
  • public static final ConfigKey USER_EMAIL = ...;
  • email = ConfigurationManager.get().get(USER_EMAIL);

Related

• GROUP_PLUGINS_R0 (encompasses PLUGIN_SUPPORT_LIB_CONFIGURING_R0)
• APP_PLUGIN_MANAGER_CONFIGURE_R0

How to demo

• Open Sophie.
• Open the bug report form (in Help menu) and enter a valid e-mail address.
• Close the form.
• Restart Sophie.
• Open the bug report and show the saved e-mail address.

Design

• New module org.sophie2.base.config.

• Immutable generic class ConfigKey<T> that encapsulates all of the information about a key:
  • name (of the key) - String
  • configuration file - String - relative path. For example, if the file is "distrib/conf/a/b.conf", this should be "a/b.conf".
  • default value (if the key is not present in the file) - T
  • schema (for the persistence) - String, for example "imm:int|storage|decimal"

• Class BaseConfigModule.
  • Extension point of type ConfigKey<?>.

• Class ConfigEntry that extends ListEntry
  • This class represents a key-value pair in a configuration file.
  • Override getKey to return a ConfigKey.

• Class Configuration - represents a single configuration file.
  • configuration file - File
  • list property of ConfigEntrys that stores all key-value pairs in that file.
  • T getValue(ConfigKey<T> key) - searches the list for a given entry and returns the corresponding value or the default value for the key.
  • void setValue(ConfigKey<T> key, T value) - sets the value in the list.

• Package org.sophie2.base.config.persistence
• Class ConfigurationStoragePersister that loads/saves configuration files from/to Storage.
  • Use the following structure for the storage, where "value" is the storage for the value of the configuration key, created with the according persister:
    • entry
      • key - attribute
      • value - text content of entry
    • entry
      • key - attribute
      • value - text content of entry
  • Schema: "configuration|storage|conf"
  • When reading, iterate over all registered extensions - config keys - for the given configuration file.
• Class ConfigurationFilePersister that loads/saves Storage from/to *.conf files.
  • Use the same structure as the storage for the XML file.
    • Name the root tag "configuration".
  • Schema: "storage|xml|conf"
• Register the persisters as extensions.

• Singleton class ConfigurationManager.
  • list of entries (String, Configuration), which maps Configuration objects to configuration file names.
  • T getValue(ConfigKey<T> key)
    • Given the file name in the key, finds the corresponding Configuration and then returns the result of Configuration.getValue.
  • setValue(ConfigKey<T> key, T value)
    • Given the file name in the key, finds the corresponding Configuration and sets the new value for that key.
  • When a Configuration for a given file is constructed, all entries are read from that file and stored in the list.
  • Method saveAll that saves all configurations using the persisters.
    • This method should be invoking when stopping the base.config module.

• In BugReportLogic
  • Remove the file "distrib/email" and create a new one "distrib/conf/org.sophie2.main.func.help.conf".
  • Create a ConfigKey userEmail and add it as an extension for the help module.
  • Remove the method readEmail and use getValue in ConfigurationManager.
  • In SAVE_EMAIL use setValue in ConfigurationManager.

• [3228], [3238], [3284]

Implementation

• [3228], [3238], [3284], [3427] (most of the work is here), [3428], [3430]

Merged to the trunk in [3539].

Testing

^{(Place the testing results here.)}

Comments

^{(Write comments for this or later revisions here.)}