platform-update-home/doc/working/feature_extensions_2.html
Parent Directory
| 
Revision Log
Revision 1.1 - (view) (download) (as text)
| 1 : | dejan | 1.1 | <!doctype html public "-//w3c//dtd html 4.0 transitional//en"> |
| 2 : | <html> | ||
| 3 : | <head> | ||
| 4 : | <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> | ||
| 5 : | <meta name="GENERATOR" content="Microsoft FrontPage 4.0"> | ||
| 6 : | </head> | ||
| 7 : | <body> | ||
| 8 : | |||
| 9 : | <h2> | ||
| 10 : | Design Note: Extended Handling of Nested Features (revised)</h2> | ||
| 11 : | <font size=-1>Last Updated: <!--webbot bot="Timestamp" startspan S-Type="EDITED" | ||
| 12 : | S-Format="%m/%d/%Y" -->09/09/2002<!--webbot bot="Timestamp" I-CheckSum="12642" | ||
| 13 : | endspan --> | ||
| 14 : | </font> | ||
| 15 : | <p><font size=-1>Change History:</font> | ||
| 16 : | <p><font size=-1>* 9/10: initial content</font> | ||
| 17 : | <br> | ||
| 18 : | <h3>Introduction</h3> | ||
| 19 : | <p>This document is based on an earlier document of the identical title that | ||
| 20 : | outlined possible options to handle requested design changes and enhancements of | ||
| 21 : | the Eclipse Update component. Since some of the requests have been addressed in | ||
| 22 : | 2.0.1 release, this document outlines only the changes that will be attempted in | ||
| 23 : | the fall of 2002. The changes will eventually end up in Eclipse 2.1 release, but | ||
| 24 : | may be available earlier in a service (fix pack) release based on 2.0.1 stream.</p> | ||
| 25 : | <h3>The Problem</h3> | ||
| 26 : | <p>The original (2.0.0) Eclipse Update design provides for feature nesting using | ||
| 27 : | the 'includes' element. Nesting is referential i.e. features are defined outside | ||
| 28 : | of the parent feature. The referencing is 'rigid' in that an exact version of | ||
| 29 : | the included feature has to be specified. Any other version will break the | ||
| 30 : | reference. In addition, child features are restricted in a number of ways:</p> | ||
| 31 : | <ul> | ||
| 32 : | <li>They cannot be enabled or disabled independent of the parent (this | ||
| 33 : | restriction has been somewhat relaxed by the introduction of optional | ||
| 34 : | features in 2.0.1 release)</li> | ||
| 35 : | <li>They cannot be updated independent of the parent</li> | ||
| 36 : | <li>Only the root feature (the feature not included in other features) can be | ||
| 37 : | subject to update searches</li> | ||
| 38 : | </ul> | ||
| 39 : | <p>This design is sufficient to support traditional products that all originate | ||
| 40 : | from one team. The team can be large and the product (root feature) can have | ||
| 41 : | elaborate feature hierarchy, but all the peaces come from the same place and | ||
| 42 : | must have exact versions to ensure they all work together as tested.</p> | ||
| 43 : | <p>However, there is a number of scenarios where this structure is too limiting. | ||
| 44 : | When larger products are composed of smaller ones (making product suites), they | ||
| 45 : | typically span teams, even companies. More latitude is required in the way | ||
| 46 : | feature hierarchies are specified, as well as in the way updates are delivered. | ||
| 47 : | The following limitations need addressing:</p> | ||
| 48 : | <ol> | ||
| 49 : | <li>Product managers are willing to give up full control over the exact | ||
| 50 : | versions of the included features (products) when they are provided by | ||
| 51 : | separate product teams. They want to allow users to individually update | ||
| 52 : | member products (children in the hierarchy) within the fix pack version | ||
| 53 : | space (the exact 'room' for upgrades should be defined upfront). If versions | ||
| 54 : | start to diverge too much, a new version of the root feature can bring this | ||
| 55 : | back to normal.</li> | ||
| 56 : | <li>When it comes to updates, product managers want to be able to define | ||
| 57 : | whether child features go to the parent for their updates or can go to their | ||
| 58 : | own update sites.</li> | ||
| 59 : | <li>At the opposite side of the spectrum, product managers may want to prevent | ||
| 60 : | a child in the hierarchy to be updated ever (that is, outside of the | ||
| 61 : | hierarchy). If a new version of a child feature is installed as a root | ||
| 62 : | feature, the Eclipse run time will pick the newer version, thus having the | ||
| 63 : | same effect as updating the child. In case of the classic product structure, | ||
| 64 : | a mechanism to prohibit this is needed.</li> | ||
| 65 : | </ol> | ||
| 66 : | |||
| 67 : | <h3> | ||
| 68 : | The Proposed Solution</h3> | ||
| 69 : | |||
| 70 : | We will extend the <includes> element to support | ||
| 71 : | several additional attributes that capture the semantics described above. In particular, the <tt><includes></tt> element | ||
| 72 : | would be extended as follows (elements that are new compared to the 2.0.1 | ||
| 73 : | release are shown in <font color="#800000">dark red</font>):<p><tt><!ELEMENT includes EMPTY></tt> | ||
| 74 : | <br><tt><!ATTLIST includes</tt> | ||
| 75 : | <br><tt> <font color="#000000"> id | ||
| 76 : | CDATA #REQUIRED</font></tt> | ||
| 77 : | <br><tt><font color="#000000"> version | ||
| 78 : | CDATA #REQUIRED</font></tt> | ||
| 79 : | <br><tt><font color="#000000"> name | ||
| 80 : | CDATA #IMPLIED</font></tt> | ||
| 81 : | <br><font color="#000000"><tt> optional | ||
| 82 : | (true | false) "false"</tt> | ||
| 83 : | </font> | ||
| 84 : | <br> <font color="#800000"><samp>match | ||
| 85 : | (perfect | equivalent | compatible | greaterOrEqual) "perfect" </samp><br> | ||
| 86 : | <tt> update-allowed | ||
| 87 : | (true | false) "true"</tt> | ||
| 88 : | <br><tt> search-location | ||
| 89 : | (root | self | both) "root"</tt> | ||
| 90 : | <br><tt>></tt> | ||
| 91 : | </font> | ||
| 92 : | <ul> | ||
| 93 : | |||
| 94 : | <li> | ||
| 95 : | <samp><font color="#800000">match</font></samp> - specifies the rule that will | ||
| 96 : | be applied when resolving the feature reference. A <samp>perfect</samp> match | ||
| 97 : | (the default that matches the 2.0.1 behavior) requires that the feature has | ||
| 98 : | exactly the version specified by the version attribute. Other choices | ||
| 99 : | progressively relax the rule (<samp>equivalent</samp> allows only service part | ||
| 100 : | of the version to be more recent, <samp>compatible</samp> also allows minor part | ||
| 101 : | to be included in the consideration, while <samp>greaterOrEqual</samp> simply | ||
| 102 : | allows any version that is more recent or identical to the one specified).</li> | ||
| 103 : | |||
| 104 : | <li> | ||
| 105 : | <tt><font color="#800000">update-allowed</font></tt> - indicates whether the nested feature can be updated | ||
| 106 : | separately (<tt>true</tt>, default), or must always updated as part of | ||
| 107 : | its parent feature (<tt>false</tt>). Detailed usage semantics are described | ||
| 108 : | later.</li> | ||
| 109 : | |||
| 110 : | <li> | ||
| 111 : | <tt><font color="#800000">search-location</font></tt> - indicates whether the "New Updates" action should | ||
| 112 : | search the update location determined by the nesting root feature (<tt>root</tt>, | ||
| 113 : | is the default), or the location defined by the nested feature (<tt>self</tt>), | ||
| 114 : | or search both (<tt>both</tt>) in that order (root first, self if nothing is | ||
| 115 : | found).</li> | ||
| 116 : | </ul> | ||
| 117 : | <p> The <tt>update-allowed</tt> attribute is used as follows [<a href="http://dev.eclipse.org/bugs/show_bug.cgi?id=21352">21352</a>]:</p> | ||
| 118 : | <ul> | ||
| 119 : | <li> | ||
| 120 : | scenario: using the update manager to navigate to an update site, an installed | ||
| 121 : | feature that is nested is available on the update site as a root feature | ||
| 122 : | (eg. Eclipse JDT feature on eclipse.org, user has the Eclipse Platform | ||
| 123 : | (or Eclipse SDK) feature installed which includes JDT)</li> | ||
| 124 : | |||
| 125 : | <li> | ||
| 126 : | the nested feature can be separately updated only if allowed by its nesting | ||
| 127 : | parent. This is indicated by <tt>update-allowed="true"</tt> being set on | ||
| 128 : | the <includes> element for the feature</li> | ||
| 129 : | |||
| 130 : | <li> | ||
| 131 : | Setting<tt> update-allowed="true"</tt> only applies to the feature referenced | ||
| 132 : | on the <tt><includes></tt> element. Setting <tt>update-allowed="false"</tt> | ||
| 133 : | overrides all <tt>update-allowed</tt> attribute settings down the included | ||
| 134 : | nested tree (ie. if the feature packager indicates update is not allowed | ||
| 135 : | separately for a given nested feature, then none of that feature nested | ||
| 136 : | children can be updated separately regardless of their setting. This handles | ||
| 137 : | the case where a third party feature is being included and the packager | ||
| 138 : | wishes to control all updates).</li> | ||
| 139 : | |||
| 140 : | <li> | ||
| 141 : | the new method feature.isUpdateAllowed() method does not simply return | ||
| 142 : | the value from the <tt><includes></tt> tag. It uses the above rules | ||
| 143 : | to compute the effective setting (based on the settings of nesting parents | ||
| 144 : | going up all parent chains that include the feature on the local site)</li> | ||
| 145 : | |||
| 146 : | <li> | ||
| 147 : | Note: we may want to consider tweeking the Eclipse Platform/ SDK feature | ||
| 148 : | to specify <tt>update-allowed="true"</tt> for our subfeatures (JDT, PDE, | ||
| 149 : | etc). Product teams can override this when they package the platform, and | ||
| 150 : | Eclipse SDK users have the ability to update the nested features separately.</li> | ||
| 151 : | |||
| 152 : | <li> | ||
| 153 : | since features can be multiply included, the check to see if an update | ||
| 154 : | is allowed needs to consider all features on the site.</li> | ||
| 155 : | |||
| 156 : | <li> | ||
| 157 : | also, multiple copies of a feature can be installed (different install | ||
| 158 : | sites (directories) within the local site), the check needs to be all features | ||
| 159 : | across all local sites. This restriction is acceptable for 2.0.1, but needs | ||
| 160 : | to be revisited for 2.1 as part of [<a href="http://dev.eclipse.org/bugs/show_bug.cgi?id=20910">20910</a>].</li> | ||
| 161 : | </ul> | ||
| 162 : | The <tt>match</tt> attribute and the <tt>search-location</tt> | ||
| 163 : | attribute are used as follows [<a href="http://dev.eclipse.org/bugs/show_bug.cgi?id=21351">21351</a>]: | ||
| 164 : | <ul> | ||
| 165 : | <li> | ||
| 166 : | Scenario: one-click update with nested features (or the equivalent initiated | ||
| 167 : | from the Update Manager)</li> | ||
| 168 : | |||
| 169 : | <li> | ||
| 170 : | Setting the match attribute to anything other than <samp>perfect</samp> is a | ||
| 171 : | pre-requisite to allow updates to the child. Update Manager must be able to | ||
| 172 : | resolve feature references after children in the feature hierarchy are updated, | ||
| 173 : | and it can only do that if there is some version latitude. If the match | ||
| 174 : | attribute is set to <samp>perfect</samp> or not defined, <samp>search-location</samp> | ||
| 175 : | attribute is ignored and the scenario defaults to the 2.0.0/2.0.1 usage.</li> | ||
| 176 : | |||
| 177 : | <li> | ||
| 178 : | When <samp>match</samp> is not set to <samp>perfect</samp>, Update will make the | ||
| 179 : | assumption that the child feature is individually updateable. In that case, it | ||
| 180 : | will check the <samp>search-location</samp> attribute to determine where to look | ||
| 181 : | for updates. The actual version window for updating the child may be narrower | ||
| 182 : | than the <samp>match</samp> attribute, however. The current search | ||
| 183 : | implementation only allows <samp>equivalent</samp> or <samp>compatible</samp> | ||
| 184 : | searches (user-configurable via Preferences). [In this light, <samp>greaterOrEqual</samp> | ||
| 185 : | may be useless as a choice if we can only updates up to the more recent minor | ||
| 186 : | versions i.e. do not allow updates to newer major releases] </li> | ||
| 187 : | |||
| 188 : | <li> | ||
| 189 : | when multiple hits from the same include "branch" are found (e.g.. when grandparent | ||
| 190 : | - parent - child features are all treated as roots and all result in hits) | ||
| 191 : | the results need to be treated in some consistent/ unambiguous way (e.g.. | ||
| 192 : | allowing only one of the related hits to be selected at one time). It is | ||
| 193 : | important to allow users to make an informed decision by disclosing versions of | ||
| 194 : | features that will be delivered automatically if a parent is selected. By | ||
| 195 : | default, the feature highest in the hierarchy is checked in the result list.</li> | ||
| 196 : | |||
| 197 : | <li> | ||
| 198 : | the <tt>search-location</tt> attribute controls which update URLs are searched | ||
| 199 : | when looking for updates. By default, the update location is that of the | ||
| 200 : | root feature. If <tt>search-location="self"</tt> is specified, the update | ||
| 201 : | location specified by the included feature is used instead. If <tt>search-location="both"</tt> | ||
| 202 : | is specified, both the default and the update location specified by the | ||
| 203 : | included feature are used [need to define if we give up on <samp>self</samp> if | ||
| 204 : | we get some hits on <samp>root</samp> or we add up hits from <samp>root</samp> | ||
| 205 : | and <samp>self</samp> and pick the best of the bunch].</li> | ||
| 206 : | </ul> | ||
| 207 : | Eclipse 2.0 clients that have not updated to the 2.0.1 support would ignore | ||
| 208 : | the additional attributes and enforce the stricter 2.0 <includes> semantics. | ||
| 209 : | This avoids having to support an additional concrete feature type implementation | ||
| 210 : | in 2.0.1. | ||
| 211 : | <br> | ||
| 212 : | </body> | ||
| 213 : | </html> |
| help@eclipse.org | ViewVC Help |
| Powered by ViewVC 1.0.3 |