[[BackLinksMenu]]

[[TicketQuery(summary=PLUGIN_SUPPORT_LIB_CONFIGURING_R1, format=table, col=summary|owner|status|type|component|priority|effort|importance, rows=description|analysis_owners|analysis_reviewers|analysis_score|design_owners|design_reviewers|design_score|implementation_owners|implementation_reviewers|implementation_score|test_owners|test_reviewers|test_score|)]]

= 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 {{{ListEntry}}}s 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)

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

== Related ==
 * [wiki:GROUP_PLUGINS_R0] (encompasses PLUGIN_SUPPORT_LIB_CONFIGURING_R0)
 * [wiki:APP_PLUGIN_MANAGER_CONFIGURE_R0]

== How to demo ==
 * Open Sophie.
 * Maximize the main window.
 * Open the bug report form (in Help menu) and enter a valid e-mail address.
 * Close the form.
 * Restart Sophie.
 * Show that the main window is maximized.
 * Open the bug report and show the saved e-mail address.

= Design =
 * Package {{{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 - File
  * default value (if the key is not present in the file) - T
  * schema (for the persistence) - String, for example "imm:int|storage|decimal"

 * 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 of {{{ConfigEntry}}}s that stores all key-value pairs in that file.
  * get......... returns the default value........

 * Class {{{ConfigurationPersister}}} that loads/saves configuration files.
  * ..........
  * Register the persister as an extension.

 * Singleton class {{{ConfigurationManager}}}.
  * {{{T get(ConfigKey<T> key)}}}
   * Given the file name in the key, finds the corresponding Configuration and then returns the value for that key.
  * {{{set(ConfigKey<T> key, T value)}}}
   * Given the file name in the key, finds the corresponding Configuration.
   * Sets the new value for that key.
   * Saves the configuration using the persister.
  * Map<String, Configuration>, which maps Configuration objects to configuration file names.

= Implementation =
^(Describe and link the implementation results here (from the wiki or the repository).)^

= Testing =
^(Place the testing results here.)^

= Comments =
^(Write comments for this or later revisions here.)