| <html> | |
| <head><title>Plug-in registry resolution</title></head> | |
| <body> | |
| <h1>Plug-in registry resolution</h1> | |
| <EM>Last update: April 23, 2003</EM> | |
| <p><cite>This document is intended as a home for gathering as much information | |
| about the expected semantics for the registry resolution algorithm as possible. | |
| The goal is to keep this knowledge separately from the implementation (which | |
| may tell a different story), in order to make easier for developers to enhance/fix | |
| it or to develop a new algorithm for registry resolution. Comments and improvements | |
| are welcome. </cite></p> | |
| <h3>Soft pre-requisites</h3> | |
| <p>Soft pre-requisites are pre-requisites whose "optional" clause is | |
| "true". </p> | |
| <p>Unsatisfied optional pre-requisites should be ignored (handled in the | |
| same way as if they didn't exist at all).</p> | |
| <p>An optional pre-requisite will be ignored if any of the following | |
| conditions apply:</p> | |
| <ul> | |
| <li>the required plug-in does not exist at all;</li> | |
| <li>the required plug-in does exist but there are no versions | |
| compatible with the required version;</li> | |
| <li>the required plug-in exists and there is a version compatible | |
| with the required version but the addition of this plug-in would cause | |
| a conflict. A conflict arises if more than one version | |
| of a given plug-in are required by other plug-ins, the versions are not compatible | |
| with each other, and at least one of the versions is not a library | |
| plug-in.</li> | |
| </ul> | |
| <p>If an optional pre-requisite 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 pre-requisite is being ignored). Ignoring an optional | |
| pre-requisite does not cause any plug-ins 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 | |
| pre-requisite.</p> | |
| <h3>Version matching</h3> | |
| <p> The following applies for both plug-in pre-requisites and fragments matching their associated plug-ins.</p> | |
| <p>Versions have the following form: major.minor.service.qualifier, where major, minor and service | |
| are integers and qualifier is a string.</p> | |
| <p>Version Numbers are matched as follows:</p><ul> | |
| <li>if no version number is specified, pick the latest version that | |
| satisfies any other related constraints (which is not necessarily | |
| the latest one available in the registry);</li> | |
| <li>perfect Version (a.b.c.q is a perfect match with d.e.f.r) if: | |
| <p>a = d and b = e and c = f and q = r</p> | |
| </li> | |
| <li>equivalent Version (a.b.c.q is an equivalent match with d.e.f.r) if: | |
| <p>a = d and b = e and ((c > f) or (c = f and q >= r))</p> | |
| </li> | |
| <li>compatible Version (a.b.c.q is compatible with d.e.f.r) if: | |
| <p>a = d and ((b > e) or (b = e and c > f) or (b = e and c = f and q >= r)) </p> | |
| </li> | |
| <li>greaterOrEqual Version (a.b.c.q is a higher version than d.e.f.r) if: | |
| <p>a > d or (a = d and b > e) or (a = d and b = e and c > f) or (a = d and b = e and c = f and q >= r)</p> | |
| </li> | |
| </ul> | |
| <p>Also:</p> | |
| <p>Two or more versions of the same plug-in can only be simultaneously | |
| enabled if they all are <cite>library plug-ins</cite> (they do not expose extension | |
| points nor contribute extensions).</p> | |
| <p>If a highest version of a plug-in is disabled for some reason, the new highest | |
| version (if available) should replace it (when possible) - all plug-ins (not | |
| fragments) that required the disabled version should refer to the new one. </p> | |
| <h3>Questions to be answered</h3> | |
| <ol> | |
| <li>What happens if a fragment contributes pre-requisites to a plug-in that | |
| has multiple versions, and these pre-requisites cannot be satisfied? Currently, | |
| the association of a fragment and a plug-in happens before the resolution | |
| itself starts. So if a plug-in a fragment contributes to is disabled, the | |
| fragment is lost (we don't try the next highest version). Should we? This | |
| would cause all versions compatible with the fragment to be successively disabled, | |
| if the fragment contributes unsatisfiable pre-requisites. Do we want that?</li> | |
| </ol> | |
| <h3>Current registry resolution algorithm (RegistryResolver#resolve)</h3> | |
| <p>The existing resolution algorithm works based on a directed graph whose nodes | |
| represent all versions of a given plug-in, and arc from "a" to "b" | |
| means plug-in "a" requires plug-in "b". The algorithm starting | |
| point is a set of root vertices (in-degree is 0) - plug-ins that are not required | |
| by any other plug-ins. The resolution is done through a depth-first traversal | |
| of the graph from the roots to their pre-requisites.</p> | |
| <ol> | |
| <li>Initial state: Registry initially contains all plug-ins and fragments | |
| discovered by the platform - no checking of pre-requisites has been done.</li> | |
| <li>Model objects that are missing mandatory fields are ignored (#required*)</li> | |
| <li>Create a map of plug-in descriptors where for each plug-in id there is a list | |
| of plug-in descriptors that have the same id, ordered by plug-in version, higher to lower (#add)</li> | |
| <li>For each fragment in the registry, add it to the list of fragments of the right plug-in descriptor | |
| (the highest version that fits the matching criteria) (#linkFragments).</li> | |
| <li>For each plug-in which has a fragment:<ul> | |
| <li>For each fragment in the plug-in's fragment list (the highest | |
| version only), add extensions, extension points, libraries and | |
| pre-requisites to the plug-in (#resolvePluginFragments).</li> | |
| </ul></li> | |
| <li>Create a set with the identifiers of all root plug-ins in the registry.</li> | |
| <li>If there are no roots, there is circularity - all plug-ins are disabled and | |
| the process is finished (registry is emptied if it was to be trimmed).</li> | |
| <li>For each plug-in identifier in the current set of roots:<ul> | |
| <li>Look for the right version(s) to enable, doing a depth-first | |
| traversal in its children (plug-ins that require it). This includes | |
| ensuring: <ul> | |
| <li>all mandatory pre-requisites are satisfied | |
| (considering versions and match clauses);</li> | |
| <li>there are no conflicts (no different versions are | |
| required simultaneously of plug-ins that provide | |
| extensions/extension points).</li> | |
| <li>if a root is disabled, its direct children are promoted | |
| to roots if they are not required by any other plug-ins.</li> | |
| </ul></li> | |
| </ul></li> | |
| <li>If the registry is to be trimmed, delete any plug-ins which | |
| are not enabled/do not have pre-requisites satisfied | |
| (#resolvePluginRegistry).</li> | |
| <li>If the registry is to be linked, link extensions to the targetted extension | |
| points (#resolvePluginRegistry).</li> | |
| </ol> | |
| <h3>Problems in the current registry resolution algorithm</h3> | |
| <ol> | |
| <li>all versions of a plug-in are disabled when the version in use causes a | |
| conflict - when a plug-in is disabled for causing a conflict, if there are | |
| different versions available, the highest one should be selected and the resolution | |
| should try to enable that one;</li> | |
| <li>order should not matter - for instance, when a conflict is detected, all | |
| plug-ins involved should be disabled not only the one that introduced the | |
| conflict (bug <a href="http://bugs.eclipse.org/bugs/show_bug.cgi?id=34752">34752</a>);</li> | |
| <li>fragments not associated with a plug-in or fragments not used because another | |
| version of the same fragment exists should be trimmed when the user requests | |
| it and currently are not (bug <a href="http://bugs.eclipse.org/bugs/show_bug.cgi?id=33911">33911</a>).</li> | |
| <li>the resulting plug-in descriptor should indicate which portions came from | |
| fragments (feature request <a href="http://bugs.eclipse.org/bugs/show_bug.cgi?id=23165">23165</a>).</li> | |
| </ol> | |
| </body> | |
| </html> |