platform-update-home/doc/optional_features.html
Parent Directory
| 
Revision Log
Revision 1.1 - (view) (download) (as text)
| 1 : | dejan | 1.1 | <html> |
| 2 : | |||
| 3 : | <head> | ||
| 4 : | <meta http-equiv="Content-Language" content="en-us"> | ||
| 5 : | <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> | ||
| 6 : | <meta name="GENERATOR" content="Microsoft FrontPage 4.0"> | ||
| 7 : | <meta name="ProgId" content="FrontPage.Editor.Document"> | ||
| 8 : | <title>Optional Included Features</title> | ||
| 9 : | </head> | ||
| 10 : | |||
| 11 : | <body> | ||
| 12 : | |||
| 13 : | <h1>Optional Included Features</h1> | ||
| 14 : | <p>Last Modified: September 03, 2002</p> | ||
| 15 : | <p><i>Note: The 2.0.1 Eclipse SDK release contains an early implementation of <b>optional | ||
| 16 : | included features</b>. This text describes this addition as it is implemented in | ||
| 17 : | 2.0.1 release. The behavior is subject to change based on further work and user | ||
| 18 : | feedback.</i></p> | ||
| 19 : | <p>The new attribute provides for specifying feature hierarchies where certain | ||
| 20 : | included (child) features are optional. There are several important consequences | ||
| 21 : | of declaring a feature optional. The purpose of this document is to describe | ||
| 22 : | these consequences and help you decide if optional features are suitable for | ||
| 23 : | your Eclipse-based product.</p> | ||
| 24 : | <h2>Declaration and Representation</h2> | ||
| 25 : | <p>A feature can be included in another feature as <b>optional</b> if an | ||
| 26 : | additional XML attribute is used in the <code>includes</code> element. By | ||
| 27 : | default, the attribute value is <code>false</code>. If set to <code>true</code>, | ||
| 28 : | the feature is treated as optional:</p> | ||
| 29 : | <blockquote> | ||
| 30 : | <pre><includes id="com.example.xyz" version="1.2.4" <b>optional="true"</b>/></pre> | ||
| 31 : | </blockquote> | ||
| 32 : | <p>Optional features are treated somewhat differently than their non-optional | ||
| 33 : | counterparts by the Eclipse Update:</p> | ||
| 34 : | <ul> | ||
| 35 : | <li>It is not an error for an optional feature to be missing from the update | ||
| 36 : | server</li> | ||
| 37 : | <li>An optional feature does not have to be installed with its parent if so | ||
| 38 : | chosen by the user</li> | ||
| 39 : | <li>Consequently, it is not an error for an optional feature to be missing | ||
| 40 : | from the platform configuration</li> | ||
| 41 : | <li>Since optional features are typically designated as such because their | ||
| 42 : | functionality is non-essential for the parent, it is possible to disable an | ||
| 43 : | optional feature independently of its parent.</li> | ||
| 44 : | </ul> | ||
| 45 : | <p>Regardless of the differences, one of the most important properties is that <b>optional | ||
| 46 : | features still must come from the same update site as the parent</b>. It is not | ||
| 47 : | possible to install or update optional features independently of their parents. | ||
| 48 : | In this regard, optional features cannot be treated as root (top-level). If a | ||
| 49 : | full freedom and flexibility is desired, optional features are not the answer. | ||
| 50 : | They are the most suitable for relatively self-contained units of functionality | ||
| 51 : | that users are given control over whether they need them or not (both by | ||
| 52 : | choosing not to install them and by disabling them later).</p> | ||
| 53 : | <p>It is also important to note that optional features should be 'all-inclusive' | ||
| 54 : | if the root feature represents a commercial product. If a root feature is | ||
| 55 : | available for purchase, whether certain optional features have been selected for | ||
| 56 : | installation or not should not affect the price. Feature collections that | ||
| 57 : | represent variations of the same base product in different price brackets (e.g. | ||
| 58 : | standard, professional, gold etc.) should be set up as different feature | ||
| 59 : | structures (using distinct names and identifiers).</p> | ||
| 60 : | <h2>Installation using native installers</h2> | ||
| 61 : | <p>When structuring a product whose initial installation and setup is performed | ||
| 62 : | using a native (OS) installer, users should be given a choice to install parts | ||
| 63 : | of the product that map to optional features. Optional features that are not | ||
| 64 : | selected should not be installed (both the features themselves and the | ||
| 65 : | referenced plug-ins). When checking the configuration of the newly installed | ||
| 66 : | product using the Update Manager, these features will be shown as 'not | ||
| 67 : | installed' (distinguished with a 'not installed' label suffix and a hollowed-out | ||
| 68 : | feature icon). Missing optional features are hidden by default and may be seen | ||
| 69 : | together with disabled features when disabled feature toggle is selected.</p> | ||
| 70 : | <h2>Installation using Eclipse Update Manager</h2> | ||
| 71 : | <p>When installing a feature that includes optional features, an additional page | ||
| 72 : | will appear in the install wizard, allowing users to choose optional features | ||
| 73 : | they want installed (by default, all optional features are checked; users can | ||
| 74 : | uncheck some or all). If a feature does not contain optional features somewhere | ||
| 75 : | in the hierarchy, the page will not appear. As in the case of native installers, | ||
| 76 : | features that were not checked will not be installed and the configuration view | ||
| 77 : | will show them as "not installed" and with a hollowed-out icon. </p> | ||
| 78 : | <h2>Adding optional features after the initial installation</h2> | ||
| 79 : | <p>Once a root (top-level) feature has been installed with some of the optional | ||
| 80 : | features unchecked, these optional features can be subsequently added to the | ||
| 81 : | configuration. If a native installer has been used in the initial installation, | ||
| 82 : | it should have a way of installing optional parts of the product (most native | ||
| 83 : | installers do). Eclipse Update will recognize the change and hook the feature | ||
| 84 : | into the hierarchy on the subsequent startup.</p> | ||
| 85 : | <p>If the root feature has been installed using Update Manager, and the | ||
| 86 : | installation was not full (some optional features were unchecked), they can be | ||
| 87 : | added at a later date by repeating the installation process. Update will compute | ||
| 88 : | the delta between the feature on the remote server and the feature in the | ||
| 89 : | platform and offer checkboxes for the remaining optional features (those already | ||
| 90 : | installed will have grayed-out boxes that cannot be unchecked).</p> | ||
| 91 : | <p>If all the optional features were installed initially, the 'Install' button | ||
| 92 : | will not be shown when the root feature is selected in the Update Manager.</p> | ||
| 93 : | <h2>Enabling and disabling optional features</h2> | ||
| 94 : | <p>Non-optional features that are part of a feature hierarchy cannot be | ||
| 95 : | individually enabled or disabled. Only the root feature can, and that act is | ||
| 96 : | recursive (all the included features are enabled or disabled in the process). In | ||
| 97 : | contrast, optional features are considered self-contained (otherwise they would | ||
| 98 : | have to be installed right away) and therefore can be enabled or disabled | ||
| 99 : | independently of the root feature. </p> | ||
| 100 : | <p>This independence is not absolute, however. If the parent feature is enabled, | ||
| 101 : | its optional child can be enabled or disabled. However, an optional child cannot | ||
| 102 : | be enabled if its parent is disabled. A consequence of this rule is that newly | ||
| 103 : | installed optional children may end up disabled if no enabled parent is detected | ||
| 104 : | in the platform. This property affects optional features are treated in | ||
| 105 : | conjunction with the new updates.</p> | ||
| 106 : | <h2>Updates and optional features</h2> | ||
| 107 : | <p>When a feature with a hierarchy that includes optional features is updated to | ||
| 108 : | a newer version, the following rules apply:</p> | ||
| 109 : | <ol> | ||
| 110 : | <li>If a feature is updated using one-click update (by selecting | ||
| 111 : | Help->Software Updates->New Updates), only optional features that are | ||
| 112 : | present will be updated. For example, if a parent Foo 1.0.0 has an optional | ||
| 113 : | child Bar 1.0.0 that has not been installed, the update to version 1.0.1 | ||
| 114 : | will result in a parent Foo 1.0.1 with an optional child Bar 1.0.1 (that is | ||
| 115 : | also not installed).</li> | ||
| 116 : | <li>If a feature is updated by selecting a newer feature in the Update Manager | ||
| 117 : | and pressing the 'Update' button, the user will be allowed to install the | ||
| 118 : | missing optional features in the process. These features are unchecked by | ||
| 119 : | default, and the default action of the wizard will be identical to the | ||
| 120 : | scenario 1. The only difference is that the user would have the option to | ||
| 121 : | install Bar 1.0.1 while updating.</li> | ||
| 122 : | <li>If a feature is updated to a new version and some of its installed | ||
| 123 : | optional children are currently disabled, they will be updated to the new | ||
| 124 : | version and their state will be preserved. For example, if a parent Foo | ||
| 125 : | 1.0.0 has an optional child Bar 1.0.0 that is installed but disabled, the | ||
| 126 : | update to a version 1.0.1 will result in a parent Foo 1.0.0 with an optional | ||
| 127 : | child Bar 1.0.1 that is disabled. In effect, the entire feature hierarchy | ||
| 128 : | will be 'silently' upgraded even though the user would not notice it because | ||
| 129 : | all the disabled optional features would remain disabled.</li> | ||
| 130 : | </ol> | ||
| 131 : | <h2>Adding optional features using native installer after an update</h2> | ||
| 132 : | <p>A combination of native installers, Eclipse update mechanism and optional | ||
| 133 : | features can create an awkward situation for a user. Consider the following | ||
| 134 : | scenario:</p> | ||
| 135 : | <ul> | ||
| 136 : | <li>A user installs a product A 1.0.0 that has an optional feature B 1.0.0 | ||
| 137 : | that he chooses not to install at that time</li> | ||
| 138 : | <li>After a while, the user searches for new updates and since A 1.0.1 is | ||
| 139 : | available, it upgrades the product. Since feature B has not been installed | ||
| 140 : | originally, it is also not upgraded.</li> | ||
| 141 : | <li>The configuration now shows that an optional feature <b>B 1.0.1</b> is not | ||
| 142 : | installed.</li> | ||
| 143 : | <li>The user decides to start using the optional feature B. Using the original | ||
| 144 : | installation medium (e.g. CD-ROM), she installs feature B using the native | ||
| 145 : | installer. However, the version on the CD is now back-level (1.0.0) and | ||
| 146 : | since its parent (A 1.0.0) is disabled, the newly installed feature is | ||
| 147 : | disabled too. A check of the current configuration shows that feature <b>B | ||
| 148 : | 1.0.1</b> is still not installed, which is true, because the user installed <b>B | ||
| 149 : | 1.0.0</b>!</li> | ||
| 150 : | </ul> | ||
| 151 : | <p>This potentially confusing situation is easily fixed by re-running the search | ||
| 152 : | for updates. The Eclipse Update behavior is here somewhat similar to OS fix packs. | ||
| 153 : | One of the requirement for the OS fix packs is that they need to be reapplied if | ||
| 154 : | a new product is installed, because OS fix packs typically only upgrade | ||
| 155 : | components that have been installed, and if a new product has been installed | ||
| 156 : | after that, no guarantee can be given that it did not bring back-level | ||
| 157 : | components. </p> | ||
| 158 : | <p>Eclipse update search algorithm has been modified to account for this case. | ||
| 159 : | In the scenario above, a repeated search for updates would detect that:</p> | ||
| 160 : | <ol> | ||
| 161 : | <li>The feature in the current configuration has some missing optional | ||
| 162 : | children.</li> | ||
| 163 : | <li>Previous versions of these children can be found in the current | ||
| 164 : | configurations (disabled, of course).</li> | ||
| 165 : | </ol> | ||
| 166 : | <p>This set of conditions would imply a back-level optional feature addition. It | ||
| 167 : | will cause update search to return <b>A 1.0.1</b> again as a new update, but | ||
| 168 : | really only install <b>B 1.0.1</b> when accepted because that is the only thing | ||
| 169 : | missing in the configuration.</p> | ||
| 170 : | <p>Of course, an alternative solution to the problem above would be to use | ||
| 171 : | Update Manager to connect to the update site, browse its contents, select A | ||
| 172 : | 1.0.1 and choose the missing optional feature from the wizard page. The | ||
| 173 : | assumption here is that missing optional features are covered by the same | ||
| 174 : | general license as the top-level (root or product) feature, and that it is OK to | ||
| 175 : | install features from an update site (as opposed to the purchased medium like a | ||
| 176 : | CD-ROM). Note that major releases of optional features for Eclipse-based commercial | ||
| 177 : | products will in most cases not be available from update sites (only service | ||
| 178 : | and/or minor version increments).</p> | ||
| 179 : | |||
| 180 : | </body> | ||
| 181 : | |||
| 182 : | </html> |
| help@eclipse.org | ViewVC Help |
| Powered by ViewVC 1.0.3 |