platform-update-home/doc/optional_features.html

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.1 - (download) (as text) (annotate)
Tue Sep 3 22:35:30 2002 UTC (7 years, 2 months ago) by dejan
Branch: MAIN
CVS Tags: v20050526, R3_0, R3_1, v20040514, v20040219, HEAD 
*** empty log message ***

<html>

<head>
<meta http-equiv="Content-Language" content="en-us">
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<title>Optional Included Features</title>
</head>

<body>

<h1>Optional Included Features</h1>
<p>Last Modified: September 03, 2002</p>
<p><i>Note: The 2.0.1 Eclipse SDK release contains an early implementation of <b>optional
included features</b>. 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.</i></p>
<p>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.</p>
<h2>Declaration and Representation</h2>
<p>A feature can be included in another feature as <b>optional</b> if an
additional XML attribute is used in the <code>includes</code> element. By
default, the attribute value is <code>false</code>. If set to <code>true</code>,
the feature is treated as optional:</p>
<blockquote>
  <pre>&lt;includes id=&quot;com.example.xyz&quot; version=&quot;1.2.4&quot; <b>optional=&quot;true&quot;</b>/&gt;</pre>
</blockquote>
<p>Optional features are treated somewhat differently than their non-optional
counterparts by the Eclipse Update:</p>
<ul>
  <li>It is not an error for an optional feature to be missing from the update
    server</li>
  <li>An optional feature does not have to be installed with its parent if so
    chosen by the user</li>
  <li>Consequently, it is not an error for an optional feature to be missing
    from the platform configuration</li>
  <li>Since optional features are typically designated as such because their
    functionality is non-essential for the parent, it is possible to disable an
    optional feature independently of its parent.</li>
</ul>
<p>Regardless of the differences, one of the most important properties is that <b>optional
features still must come from the same update site as the parent</b>. 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).</p>
<p>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).</p>
<h2>Installation using native installers</h2>
<p>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.</p>
<h2>Installation using Eclipse Update Manager</h2>
<p>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 &quot;not installed&quot; and with a hollowed-out icon.&nbsp;</p>
<h2>Adding optional features after the initial installation</h2>
<p>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.</p>
<p>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).</p>
<p>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.</p>
<h2>Enabling and disabling optional features</h2>
<p>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.&nbsp;</p>
<p>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.</p>
<h2>Updates and optional features</h2>
<p>When a feature with a hierarchy that includes optional features is updated to
a newer version, the following rules apply:</p>
<ol>
  <li>If a feature is updated using one-click update (by selecting
    Help-&gt;Software Updates-&gt;New Updates), only optional features that are
    present will be updated. For example, if a parent Foo 1.0.0 has an optional
    child Bar 1.0.0 that has not been installed, the update to version 1.0.1
    will result in a parent Foo 1.0.1 with an optional child Bar 1.0.1 (that is
    also not installed).</li>
  <li>If a feature is updated by selecting a newer feature in the Update Manager
    and pressing the 'Update' button, the user will be allowed to install the
    missing optional features in the process. These features are unchecked by
    default, and the default action of the wizard will be identical to the
    scenario 1. The only difference is that the user would have the option to
    install Bar 1.0.1 while updating.</li>
  <li>If a feature is updated to a new version and some of its installed
    optional children are currently disabled, they will be updated to the new
    version and their state will be preserved. For example, if a parent Foo
    1.0.0 has an optional child Bar 1.0.0 that is installed but disabled, the
    update to a version 1.0.1 will result in a parent Foo 1.0.0 with an optional
    child Bar 1.0.1 that is disabled. In effect, the entire feature hierarchy
    will be 'silently' upgraded even though the user would not notice it because
    all the disabled optional features would remain disabled.</li>
</ol>
<h2>Adding optional features using native installer after an update</h2>
<p>A combination of native installers, Eclipse update mechanism and optional
features can create an awkward situation for a user. Consider the following
scenario:</p>
<ul>
  <li>A user installs a product A 1.0.0 that has an optional feature B 1.0.0
    that he chooses not to install at that time</li>
  <li>After a while, the user searches for new updates and since A 1.0.1 is
    available, it upgrades the product. Since feature B has not been installed
    originally, it is also not upgraded.</li>
  <li>The configuration now shows that an optional feature <b>B 1.0.1</b> is not
    installed.</li>
  <li>The user decides to start using the optional feature B. Using the original
    installation medium (e.g. CD-ROM), she installs feature B using the native
    installer. However, the version on the CD is now back-level (1.0.0) and
    since its parent (A 1.0.0) is disabled, the newly installed feature is
    disabled too. A check of the current configuration shows that feature <b>B
    1.0.1</b> is still not installed, which is true, because the user installed <b>B
    1.0.0</b>!</li>
</ul>
<p>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.&nbsp;</p>
<p>Eclipse update search algorithm has been modified to account for this case.
In the scenario above, a repeated search for updates would detect that:</p>
<ol>
  <li>The feature in the current configuration has some missing optional
    children.</li>
  <li>Previous versions of these children can be found in the current
    configurations (disabled, of course).</li>
</ol>
<p>This set of conditions would imply a back-level optional feature addition. It
will cause update search to return <b>A 1.0.1</b> again as a new update, but
really only install <b>B 1.0.1</b> when accepted because that is the only thing
missing in the configuration.</p>
<p>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).</p>

</body>

</html>