Design Note: Extended Handling of Nested Features (revised)

Change History:

* 9/10: initial content
 

Introduction

This document is based on an earlier document of the identical title that outlined possible options to handle requested design changes and enhancements of the Eclipse Update component. Since some of the requests have been addressed in 2.0.1 release, this document outlines only the changes that will be attempted in the fall of 2002. The changes will eventually end up in Eclipse 2.1 release, but may be available earlier in a service (fix pack) release based on 2.0.1 stream.

The Problem

The original (2.0.0) Eclipse Update design provides for feature nesting using the 'includes' element. Nesting is referential i.e. features are defined outside of the parent feature. The referencing is 'rigid' in that an exact version of the included feature has to be specified. Any other version will break the reference. In addition, child features are restricted in a number of ways:

• They cannot be enabled or disabled independent of the parent (this restriction has been somewhat relaxed by the introduction of optional features in 2.0.1 release)
• They cannot be updated independent of the parent
• Only the root feature (the feature not included in other features) can be subject to update searches

This design is sufficient to support traditional products that all originate from one team. The team can be large and the product (root feature) can have elaborate feature hierarchy, but all the peaces come from the same place and must have exact versions to ensure they all work together as tested.

However, there is a number of scenarios where this structure is too limiting. When larger products are composed of smaller ones (making product suites), they typically span teams, even companies. More latitude is required in the way feature hierarchies are specified, as well as in the way updates are delivered. The following limitations need addressing:

1. Product managers are willing to give up full control over the exact versions of the included features (products) when they are provided by separate product teams. They want to allow users to individually update member products (children in the hierarchy) within the fix pack version space (the exact 'room' for upgrades should be defined upfront). If versions start to diverge too much, a new version of the root feature can bring this back to normal.
2. When it comes to updates, product managers want to be able to define whether child features go to the parent for their updates or can go to their own update sites.
3. At the opposite side of the spectrum, product managers may want to prevent a child in the hierarchy to be updated ever (that is, outside of the hierarchy). If a new version of a child feature is installed as a root feature, the Eclipse run time will pick the newer version, thus having the same effect as updating the child. In case of the classic product structure, a mechanism to prohibit this is needed.

The Proposed Solution

<!ELEMENT includes EMPTY>
<!ATTLIST includes
    id                    CDATA #REQUIRED
    version               CDATA #REQUIRED
    name                  CDATA #IMPLIED
    optional              (true | false) "false"
        match                 (perfect | equivalent | compatible | greaterOrEqual) "perfect"  
    update-allowed        (true | false) "true"
    search-location       (root | self | both) "root"
>

• match - specifies the rule that will be applied when resolving the feature reference. A perfect match (the default that matches the 2.0.1 behavior) requires that the feature has exactly the version specified by the version attribute. Other choices progressively relax the rule (equivalent allows only service part of the version to be more recent, compatible also allows minor part to be included in the consideration, while greaterOrEqual simply allows any version that is more recent or identical to the one specified).
• update-allowed - indicates whether the nested feature can be updated separately (true, default), or must always updated as part of its parent feature (false). Detailed usage semantics are described later.
• search-location - indicates whether the "New Updates" action should search the update location determined by the nesting root feature (root, is the default), or the location defined by the nested feature (self), or search both (both) in that order (root first, self if nothing is found).

 The update-allowed attribute is used as follows [21352]:

• scenario: using the update manager to navigate to an update site, an installed feature that is nested is available on the update site as a root feature (eg. Eclipse JDT feature on eclipse.org, user has the Eclipse Platform (or Eclipse SDK) feature installed which includes JDT)
• the nested feature can be separately updated only if allowed by its nesting parent. This is indicated by update-allowed="true" being set on the <includes> element for the feature
• Setting update-allowed="true" only applies to the feature referenced on the <includes> element. Setting update-allowed="false" overrides all update-allowed attribute settings down the included nested tree (ie. if the feature packager indicates update is not allowed separately for a given nested feature, then none of that feature nested children can be updated separately regardless of their setting. This handles the case where a third party feature is being included and the packager wishes to control all updates).
• the new method feature.isUpdateAllowed() method does not simply return the value from the <includes> tag. It uses the above rules to compute the effective setting (based on the settings of nesting parents going up all parent chains that include the feature on the local site)
• Note: we may want to consider tweeking the Eclipse Platform/ SDK feature to specify update-allowed="true" for our subfeatures (JDT, PDE, etc). Product teams can override this when they package the platform, and Eclipse SDK users have the ability to update the nested features separately.
• since features can be multiply included, the check to see if an update is allowed needs to consider all features on the site.
• also, multiple copies of a feature can be installed (different install sites (directories) within the local site), the check needs to be all features across all local sites. This restriction is acceptable for 2.0.1, but needs to be revisited for 2.1 as part of [20910].

• Scenario: one-click update with nested features (or the equivalent initiated from the Update Manager)
• Setting the match attribute to anything other than perfect is a pre-requisite to allow updates to the child. Update Manager must be able to resolve feature references after children in the feature hierarchy are updated, and it can only do that if there is some version latitude. If the match attribute is set to perfect or not defined, search-location attribute is ignored and the scenario defaults to the 2.0.0/2.0.1 usage.
• When match is not set to perfect, Update will make the assumption that the child feature is individually updateable. In that case, it will check the search-location attribute to determine where to look for updates. The actual version window for updating the child may be narrower than the match attribute, however. The current search implementation only allows equivalent or compatible searches (user-configurable via Preferences). [In this light, greaterOrEqual may be useless as a choice if we can only updates up to the more recent minor versions i.e. do not allow updates to newer major releases] 
• when multiple hits from the same include "branch" are found (e.g.. when grandparent - parent - child features are all treated as roots and all result in hits) the results need to be treated in some consistent/ unambiguous way (e.g.. allowing only one of the related hits to be selected at one time). It is important to allow users to make an informed decision by disclosing versions of features that will be delivered automatically if a parent is selected. By default, the feature highest in the hierarchy is checked in the result list.
• the search-location attribute controls which update URLs are searched when looking for updates. By default, the update location is that of the root feature. If search-location="self" is specified, the update location specified by the included feature is used instead. If search-location="both" is specified, both the default and the update location specified by the included feature are used [need to define if we give up on self if we get some hits on root or we add up hits from root and self and pick the best of the bunch].