| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| <html> |
| <head> |
| <title>Untitled Document</title> |
| <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
| </head> |
| |
| <body> |
| <h1>Registry Resolver – Pseudo Code and Notes</h1> |
| <p><em>Last updated April 15, 2003</em></p> |
| <pre>if (registry is already resolved) |
| stop now – nothing to do |
| |
| foreach (plugin in the registry) do { |
| if (the plugin is missing any of the required fields) |
| generate an error and disable this plugin |
| make an IndexEntry for this plugin id (if one doesn’t exist) |
| put this plugin in the version list of this IndexEntry in order from largest down |
| } end foreach |
| |
| foreach (fragment in the registry) do { |
| if (the fragment is missing any of the required fields) |
| generate an error and ignore this fragment |
| make sure all prerequisites for this fragment exist (bug 10799) |
| find the plugin for fragment.getPluginId() + fragment.getPluginVersion() using |
| the matching rules described in class PluginVersionIdentifier (bug 5668) |
| if (the plugin is not found) |
| generate an error and ignore this fragment |
| add this fragment to the plugin’s list of fragments (plugin.fragments) |
| } end foreach |
| |
| foreach (plugin in the registry) do { |
| foreach (fragment in this plugin’s fragment list) do { |
| if (this is the most recent version of this fragment in this list) |
| add the components of this fragment to this plugin |
| if (this fragment adds a library to the plugin) |
| make sure we don’t have duplicate library entries in the plugin (bug 23522) |
| } end foreach |
| remove any fragments not contributing to the plugin (i.e. older versions of a fragment) (bug 10719 and 10720) |
| } end foreach |
| |
| identify all the root plugin ids |
| foreach (root plugin id) do { |
| identify the latest version of the root and use it only |
| build the ConstraintsEntry -> Constraints structure under this IndexEntry |
| recursively build these structures for each prerequisite |
| } end foreach</pre> |
| <p>NOTE: When the above foreach is done, each plugin id will have an associated |
| IndexEntry -> ConstraintsEntry -> Constraints structure. For a given plugin |
| id, the associated IndexEntry, etc. will identify all plugins which require |
| this one as a prerequisite and all conditions which much be satisfied. |
| The building of these structures must also remove any prerequisite loops and |
| remove any conflicts. This may require disabling some plugins and removing portions |
| of the ConstraintsEntry -> Constraints structure under a particular IndexEntry.</p> |
| <pre>foreach (IndexEntry) do { |
| foreach (ConstraintsEntry) do { |
| find the plugin descriptor that is a best match for this group of Constraints |
| } end foreach (ConstraintsEntry) |
| } end foreach (IndexEntry) |
| |
| |
| disable all plugin descriptors |
| |
| |
| foreach (IndexEntry) do { |
| foreach (ConstraintsEntry) do { |
| enable the plugin found to be the best match in the previous loop |
| find the PluginPrerequisite that this plugin descriptor satisfies |
| tell the PluginPrerequisite which version we resolved to |
| } end foreach (ConstraintsEntry) |
| } end foreach (IndexEntry) |
| |
| optional – remove all disabled plugins from the registry |
| optional |
| foreach (enabled plugin in the registry) do { |
| foreach (extension in this plugin) do { |
| find the associated extension point |
| if (extension point not found){ |
| generate an error |
| NOTE: Should the plugin be disabled? |
| } endif |
| add this extension to the list of extensions for the found extension point |
| } end foreach (extension) |
| } end foreach (enabled plugin) |
| end optional |
| </pre> |
| <h3>Some Notes:</h3> |
| <p>A plugin with no extensions or extension points is termed a ‘library’ |
| plugin.</p> |
| <p>Version Numbers are matched as follows: |
| <li>if no version number is specified, pick the latest version that satisfies any other related constraints</li> |
| <li>if only a version number is specified, ensure a ‘compatible’ match</li> |
| <li>for exact matching rules, check out class PluginVersionIdentifier</li> |
| <li>multiple versions of a particular plugin id are allowed only if there are |
| no extensions or extension points in any of the versions</li> |
| <li>we always try to use at most 1 version of a plugin even if all plugins are |
| ‘library’ plugins.</li> |
| <p>Example (all plugins are library plugins):</p> |
| <li>pluginA version 1.2.0 requires pluginB and pluginC version 1.0.0</li> |
| <li>pluginB version 1.0.0 has no requirements</li> |
| <li>pluginB version 2.1.0 requires pluginC</li> |
| <li>pluginC version 1.0.0 has no requirements</li> |
| <li>pluginC version 1.1.0 has no requirements</li> |
| <li>pluginC version 2.0.5 has no requirements</li> |
| <p>Resolving will give us the following plugins:</p> |
| <li>pluginA version 1.2.0 requires pluginB and pluginC version 1.0.0</li> |
| <li>pluginB version 2.1.0 requires pluginC</li> |
| <li>pluginC version 1.1.0 has no requirements</li> |
| <p>Ideally, pluginB could have used pluginC version 2.0.5.</p> |
| <h3>Internal RegistryResolver structures:</h3> |
| <h4>IndexEntry:</h4> |
| <li>one index entry for each plugin id</li> |
| <li>each index entry has a pointer to each of the plugin descriptors that have this id</li> |
| <li>the pointers of plugin descriptors are in version order from the largest version to the smallest</li> |
| <li>each index entry also has a list of ConstraintsEntry’s (each ConstraintsEntry |
| represents a group of constraints that can all be satisfied without conflict)</li> |
| <li>there is no ordering of ConstraintsEntry’s (just the order in which they are built)</li> |
| <h4>ConstraintsEntry:</h4> |
| <li>represents a group of constraints on a particular plugin id that can all be |
| satisfied without conflict</li> |
| <li>these constraints are kept in a list</li> |
| <li>a new ConstraintsEntry is not created if multiple versions of this plugin |
| are required and extensions or extension points exist</li> |
| <li>when an IndexEntry is created, the first (empty) ConstraintsEntry is also |
| created (therefore, the first invocation must use this first ConstrainsEntry |
| while other invocations may need to create a new one, if concurrent versions |
| of this plugin are allowed)</li> |
| <li>the ConstraintsEntry points back to it’s parent IndexEntry</li> |
| <h4>Constraint:</h4> |
| <li>represents a particular prerequisite in a plugin</li> |
| <li>a Constraint hangs off a ConstraintsEntry and a ConstraintsEntry hangs off |
| an IndexEntry. The ‘parent’ plugin descriptor in the Constraint |
| is one of the same plugin descriptors that can be found in the version list |
| for this IndexEntry</li> |
| <li>each Constraint exists in only one ConstraintsEntry but a ConstraintsEntry |
| can have multiple Constraints</li> |
| <li>the Constraint points back to its parent ConstraintsEntry</li> |
| <h4>Cookie:</h4> |
| <li>used primarily as a tool to communicate any errors back to the calling methods |
| (and thus terminate processing of a particular area of the tree)</li> |
| <li>keeps a list of all Constraints that have been successfully evaluated to the |
| current point of execution. This list of constraints is also our was of ensure |
| we don’t have any circular dependencies. If we have already have a constraint |
| in this list with the same PluginPrerequisite as the one we are currently trying |
| to resolve, we know we have a circular dependency.</li> |
| <h4>Orphaned Subtrees:</h4> |
| <p>If a conflict arises such that a particular subtree becomes orphaned, the root |
| of this subtree will be considered a root node and the remainder of the subtree |
| (if it resolves correctly) will remain intact. Consider the following example |
| (pluginResolveTest_15):</p> |
| <p>PluginA 1.2.0 requires PluginB 2.1.0 and PluginC 1.0.0<br> |
| PluginB 1.0.0 has no requirements but does have an extension and extension point<br> |
| PluginB 2.1.0 requires PluginC 2.0.5 (exact match)<br> |
| PluginC 1.0.0 has no requirements<br> |
| PluginC 1.1.0 has no requirements but have an extension and extension point<br> |
| PluginC 2.0.5 has no requirements</p> |
| <p>In this case, a conflict (non-resolvable because of extensions and extension |
| points) exists in PluginA and it is disabled. This causes PluginB to be orphaned |
| and it is then considered a root. Resolution of the above example will return |
| a registry containing PluginB 2.1.0 and PluginC 2.0.5. While this may seem counter-intuitive, |
| consider the case where PluginA was a PDE plugin and PluginB was the JDT plugin. |
| JDT can live without PDE and the subtree really should survive the conflict |
| in PDE’s plugin.</p> |
| <h4>Soft Prerequisites (Optional clause):</h4> |
| <p>We now have the notion of prerequisites which are optional, called soft prerequisites. |
| These prerequisites must have the clause ‘optional=”true”’. |
| Consider the following xml statement:</p> |
| <pre><requires> |
| <import plugin="tests.c" version="2.1.0" optional=”true”/> |
| </requires></pre> |
| <p>This prerequisite will be ignored if any of the following conditions apply:</p> |
| <li>the plugin ‘tests.c’ does not exist at all</li> |
| <li>the plugin ‘tests.c’ does exist but there are no versions compatible |
| with version number 2.1.0</li> |
| <li>the plugin ‘tests.c’ exists and there is a version compatible |
| with 2.1.0 but the addition of this plugin will cause a conflict. A conflict |
| arises if a particular root plugin requires more than one version of ‘tests.c’, |
| the versions are not compatible with each other, and at least one of the versions |
| contains a minimum of one extension or extension point</li> |
| <p>If an optional prerequisite is ignored for any of the reasons listed above |
| no error message is generated (but an informational message may be output to |
| indicate that this prerequisite is being ignored). Ignoring an optional prerequisite |
| does not cause any plugins to be disabled. This causes potential error conditions |
| to be more complex. Each time we have a situation where we have a conflict, |
| we must first check to see if this is an optional prerequisite. The same is |
| true of situations where we expect to find an associated IndexEntry (or other |
| structure).</p> |
| <p>If a prerequisite is ignored, the Constraint structure associated with this |
| particular parent/prerequisite pair is not added into the IndexEntry, ConstraintsEntry, |
| Constraint structure. None of the existing structures or pointers to them are |
| altered or removed. We cannot tell, without re-examining every relationship |
| associated with this particular root plugin, which portions were used for other |
| relationships (and not just the relationship leading to this ignored prerequisite).</p> |
| <h4>Question on ‘lastResolved’ field:</h4> |
| <p>The ConstraintsEntry structure contains a field called ‘lastResolved’ |
| which is set but does not seem to be used. At the same time, there are numerous |
| places where we examine all of the Constraints off a ConstraintsEntry structure |
| to determine which plugin (if any) is the best one to resolve these Constraints |
| compatibly. Can we use ‘lastResolved’ to try and minimize these? |
| Each time we look for a best match plugin, we cycle through all versions of |
| this plugin and all Constraints off this ConstraintsEntry.</p> |
| <p></p> |
| </body> |
| </html> |
