Last Modified: September 03, 2002
Note: The 2.0.1 Eclipse SDK release contains an early implementation of optional included features. This text describes this addition as it is implemented in 2.0.1 release. The behavior is subject to change based on further work and user feedback.
The new attribute provides for specifying feature hierarchies where certain included (child) features are optional. There are several important consequences of declaring a feature optional. The purpose of this document is to describe these consequences and help you decide if optional features are suitable for your Eclipse-based product.
A feature can be included in another feature as optional if an
additional XML attribute is used in the includes element. By
default, the attribute value is false. If set to true,
the feature is treated as optional:
<includes id="com.example.xyz" version="1.2.4" optional="true"/>
Optional features are treated somewhat differently than their non-optional counterparts by the Eclipse Update:
Regardless of the differences, one of the most important properties is that optional features still must come from the same update site as the parent. It is not possible to install or update optional features independently of their parents. In this regard, optional features cannot be treated as root (top-level). If a full freedom and flexibility is desired, optional features are not the answer. They are the most suitable for relatively self-contained units of functionality that users are given control over whether they need them or not (both by choosing not to install them and by disabling them later).
It is also important to note that optional features should be 'all-inclusive' if the root feature represents a commercial product. If a root feature is available for purchase, whether certain optional features have been selected for installation or not should not affect the price. Feature collections that represent variations of the same base product in different price brackets (e.g. standard, professional, gold etc.) should be set up as different feature structures (using distinct names and identifiers).
When structuring a product whose initial installation and setup is performed using a native (OS) installer, users should be given a choice to install parts of the product that map to optional features. Optional features that are not selected should not be installed (both the features themselves and the referenced plug-ins). When checking the configuration of the newly installed product using the Update Manager, these features will be shown as 'not installed' (distinguished with a 'not installed' label suffix and a hollowed-out feature icon). Missing optional features are hidden by default and may be seen together with disabled features when disabled feature toggle is selected.
When installing a feature that includes optional features, an additional page will appear in the install wizard, allowing users to choose optional features they want installed (by default, all optional features are checked; users can uncheck some or all). If a feature does not contain optional features somewhere in the hierarchy, the page will not appear. As in the case of native installers, features that were not checked will not be installed and the configuration view will show them as "not installed" and with a hollowed-out icon.
Once a root (top-level) feature has been installed with some of the optional features unchecked, these optional features can be subsequently added to the configuration. If a native installer has been used in the initial installation, it should have a way of installing optional parts of the product (most native installers do). Eclipse Update will recognize the change and hook the feature into the hierarchy on the subsequent startup.
If the root feature has been installed using Update Manager, and the installation was not full (some optional features were unchecked), they can be added at a later date by repeating the installation process. Update will compute the delta between the feature on the remote server and the feature in the platform and offer checkboxes for the remaining optional features (those already installed will have grayed-out boxes that cannot be unchecked).
If all the optional features were installed initially, the 'Install' button will not be shown when the root feature is selected in the Update Manager.
Non-optional features that are part of a feature hierarchy cannot be individually enabled or disabled. Only the root feature can, and that act is recursive (all the included features are enabled or disabled in the process). In contrast, optional features are considered self-contained (otherwise they would have to be installed right away) and therefore can be enabled or disabled independently of the root feature.
This independence is not absolute, however. If the parent feature is enabled, its optional child can be enabled or disabled. However, an optional child cannot be enabled if its parent is disabled. A consequence of this rule is that newly installed optional children may end up disabled if no enabled parent is detected in the platform. This property affects optional features are treated in conjunction with the new updates.
When a feature with a hierarchy that includes optional features is updated to a newer version, the following rules apply:
A combination of native installers, Eclipse update mechanism and optional features can create an awkward situation for a user. Consider the following scenario:
This potentially confusing situation is easily fixed by re-running the search for updates. The Eclipse Update behavior is here somewhat similar to OS fix packs. One of the requirement for the OS fix packs is that they need to be reapplied if a new product is installed, because OS fix packs typically only upgrade components that have been installed, and if a new product has been installed after that, no guarantee can be given that it did not bring back-level components.
Eclipse update search algorithm has been modified to account for this case. In the scenario above, a repeated search for updates would detect that:
This set of conditions would imply a back-level optional feature addition. It will cause update search to return A 1.0.1 again as a new update, but really only install B 1.0.1 when accepted because that is the only thing missing in the configuration.
Of course, an alternative solution to the problem above would be to use Update Manager to connect to the update site, browse its contents, select A 1.0.1 and choose the missing optional feature from the wizard page. The assumption here is that missing optional features are covered by the same general license as the top-level (root or product) feature, and that it is OK to install features from an update site (as opposed to the purchased medium like a CD-ROM). Note that major releases of optional features for Eclipse-based commercial products will in most cases not be available from update sites (only service and/or minor version increments).