GPII-1230: MM Taking running applications into account and other improvements

documentation/CanopyMatchMaker.md

@@ -25,13 +25,16 @@ To ensure that several conflicting solutions (e.g. two screenreaders) are not la
 
 The apptology is described in more details here: [Apptology.md](Apptology.md).
 
+## Dispositions
+As described below, the matchmaker will assign a disposition to each solution based on priority and canopy matching. There are three dispositions available: "accept", "reject" and "deactivate". "accept" means that the solution will be accepted (and started, if relevant for that solution). "reject" means we do not do anything to the solution. "deactivate" means that we ensure that the solution is not running (i.e. running stop if required). The latter case is relevant for solutions that are conflicting with other solutions that the user might need.
+
 ## Disposing from prioriy:
 Explicit priorities are declared in the NP sets metadata section and will always be a floating point value of 1024 or more. Implicit priorities are deduced from application specific settings. When a user has application specific settings for a solution a priority of 512 is set for that solution.
 
 Goes through all solutions from high priority to low. If a solution already has a disposition, it is ignored. Else it will be selected (accepted). Any solution with the same type, but a lower priority (or no priority) will be rejected. If there are two or more solutions of the same priority _and_ the same type (even partly), these will be considered a "tie". All lower-priority solutions of this type will still be rejected. The tied solutions will have their current disposition and priority removed and left to be disposed by some other disposal algorithm.
 
 ## Disposing from Canopy
-The Canopy matching strategy is used for deciding how to dispose solutions in case no priorities are available or there is a priority-tie between two applications of the same type. 
+The Canopy matching strategy is used for deciding how to dispose solutions in case no priorities are available or there is a priority-tie between two applications of the same type.
 
 * The canopy approach is based on a vectorial "fitness measure" of a solution plus a lexicographical ordering
 * It is similar to the strategy used in resolving CSS rules.
@@ -45,7 +48,7 @@ The Canopy matching strategy is used for deciding how to dispose solutions in ca
 * Compute capabilities of solution
 * Compute vector of prefix depths for each leaf el path from NP set
 * Sort vector in descending order of fitness ("fitness vector")
-* Rank solutions by fitness using lexicographic ordering 
+* Rank solutions by fitness using lexicographic ordering
 
 *The canopy matching*
 * Compute fitness vectors for each solution and sort in rank order

documentation/MatchMakerFramework.md

@@ -148,7 +148,7 @@ The input for these POST requests will be in the following format. Note that it
 
 ### Return payload
 
-The return payload from at call to `/match` should be in the following format:
+The return payload from at call to `/match` should be in the following format. The "active" key expresses whether the application should be set to running. A `true` value means that it should be running, `undefined` means we leave it in its current run state and `false` mean we should actively ensure that it is not running.
 
 ```
 {

documentation/SolutionsRegistryFormat.md

@@ -14,7 +14,7 @@ Each entry in the solution registry should have a unique ID (`Solution.id` in th
     "start": [ .. ],
     "stop": [ .. ],
     "isInstalled": [ .. ],
-    
+
     // Not yet supported. Post-Cloud4All features.
     "install": [ ... ],
     "uninstall": [ ... ],
@@ -116,7 +116,7 @@ These four lifecycle blocks have different meanings to the system but has the sa
 * `start`: Launch/start the solution
 * `stop`: Stop/kill the solution
 
-Each of these lifecycle blocks allow the same content - which is an array with entries that are either references to settingsHandlers blocks or customized lifecycle blocks. To reference a settingsHandler block, the keywork `settings.<blockname>` is used, where `<blockname>` should be replaced with the name of a settingsHandler block. In the case of `configure` and `start`, a consequence of referencing a settingsHandler is that the settings given in the settingsHandler and users preferences set will be applied to that solution (and their original values will be saved to the system - if user just logged in). In the case of `restore` and `stop`, the settings that has previously been written using the settingshandler(s) in question will be restored. Alternative to referencings setting and restoring settings, arbitrary lifecycle actions are allowed - the syntax for this is an object that contains at least a `type` key for the function to call. None of these blocks are mandatory. 
+Each of these lifecycle blocks allow the same content - which is an array with entries that are either references to settingsHandlers blocks or customized lifecycle blocks. To reference a settingsHandler block, the keywork `settings.<blockname>` is used, where `<blockname>` should be replaced with the name of a settingsHandler block. In the case of `configure` and `start`, a consequence of referencing a settingsHandler is that the settings given in the settingsHandler and users preferences set will be applied to that solution (and their original values will be saved to the system - if user just logged in). In the case of `restore` and `stop`, the settings that has previously been written using the settingshandler(s) in question will be restored. Alternative to referencings setting and restoring settings, arbitrary lifecycle actions are allowed - the syntax for this is an object that contains at least a `type` key for the function to call. None of these blocks are mandatory.
 
 **Example blocks**:
 ```
@@ -144,7 +144,7 @@ Each of these lifecycle blocks allow the same content - which is an array with e
 
 The `update` block works very similarly to the configure, restore, start and stop blocks. It describes what should happen when the configuration needs to be updated (e.g. due to context changes, PCP adjustments, etc).
 
-The format of the `update` block allows for the same entries as the configure, restore, start and stop blocks - that is: arbitrary lifecycle action blocks and `settings.<blockname>`. Unlike for the other lifecycle blocks, the `update` block furthermore allows references to the `start`, `stop` and `configure` blocks. This is one by putting a string with the name of that block. When the system encounters one of these references, the entries of that block will be run.
+The format of the `update` block allows for the same entries as the configure, restore, start and stop blocks - that is: arbitrary lifecycle action blocks and `settings.<blockname>`. Unlike for the other lifecycle blocks, the `update` block furthermore allows references to the `start`, `stop` and `configure` blocks. This is done by putting a string with the name of that block. When the system encounters one of these references, the entries of that block will be run.
 
 **Example block**:
 ```
@@ -204,7 +204,7 @@ This is run before configuration to ensure that the application is actually read
 
 **Example Entry**:
 ```
-"isConfigurable": [{ 
+"isConfigurable": [{
     "type": "gpii.reporter.fileExists",
     "path": "${{environment}.XDG_DATA_HOME}/orca/user-settings.conf""
 }]