Feature Archives

The feature packaging information is placed into a separate Java .jar. Standard Java jar facilities are used for constructing feature archives. Feature archives reference separately packaged plug-in archives (see next section) and non-plug-in files.

Features are identified using a structured identifier based on the provider internet domain name. For example, organization eclipse.org produces feature org.eclipse.jdt. The character set used for feature identifiers is as specified for plug-in identifiers (see Plug-in Manifest).

The recommended convention for naming the feature archives is
<id>_<version>.jar

Where <id> is the feature identifier and <version> is the full version identifier contained in the respective feature.xml. Note that this is a recommended convention that minimizes chance of collisions, but is not required by the Eclipse architecture. For example, the following are valid feature archive names

org.eclipse.jdt_2.0.0.jar
org.eclipse.pde_2.0.jar
my_feature.jar

Internally, each feature archive is packaged relative to its feature directory (but not including the directory path element). The archive has the following structure

feature.xml
feature<_locale>.properties (see "Translated Feature Information")
other feature files and subdirectories (TBD)
META-INF/
Java jar manifest and security files

Feature manifest

The feature manifest format is defined by the following dtd:

<?xml encoding="ISO-8859-1"?>

<!ELEMENT feature (install-handler?, description?, copyright?, license?, url?, includes*, requires?, plugin*, data*)>
<!ATTLIST feature
    id            CDATA #REQUIRED
    version       CDATA #REQUIRED
    label         CDATA #IMPLIED
    provider-name CDATA #IMPLIED
    image         CDATA #IMPLIED
    os            CDATA #IMPLIED
    arch          CDATA #IMPLIED
    ws            CDATA #IMPLIED
    nl            CDATA #IMPLIED
    colocation-affinity
                  CDATA #IMPLIED
    primary       (true | false) "false"
    application   CDATA #IMPLIED
>

<!ELEMENT install-handler EMPTY>
<!ATTLIST install-handler
library CDATA #IMPLIED
handler CDATA #IMPLIED
>

<!ELEMENT description (#PCDATA)>
<!ATTLIST description
url CDATA #IMPLIED
>

<!ELEMENT copyright (#PCDATA)>
<!ATTLIST copyright
url CDATA #IMPLIED
>

<!ELEMENT license (#PCDATA)>
<!ATTLIST license
url CDATA #IMPLIED
>

<!ELEMENT url (update?, discovery*)>

<!ELEMENT update EMPTY>
<!ATTLIST update
url CDATA #REQUIRED
label CDATA #IMPLIED
>

<!ELEMENT discovery EMPTY>
<!ATTLIST discovery
url CDATA #REQUIRED
label CDATA #IMPLIED
>

<!ELEMENT includes EMPTY>
<!ATTLIST includes
id CDATA #REQUIRED
version CDATA #REQUIRED
>

<!ELEMENT requires (import+)>

<!ELEMENT import EMPTY>
<!ATTLIST import
    plugin        CDATA #REQUIRED
    version       CDATA #IMPLIED
    match         (perfect | equivalent | compatible | greaterOrEqual) "compatible"
>

<!ELEMENT plugin EMPTY>
<!ATTLIST plugin
    id            CDATA #REQUIRED
    version       CDATA #REQUIRED
    fragment      (true | false) "false"
    os            CDATA #IMPLIED
    arch          CDATA #IMPLIED
    ws            CDATA #IMPLIED
    nl            CDATA #IMPLIED
    download-size CDATA #IMPLIED
    install-size CDATA #IMPLIED
>

<!ELEMENT data EMPTY>
<!ATTLIST data
    id            CDATA #REQUIRED
    os            CDATA #IMPLIED
    arch          CDATA #IMPLIED
    ws            CDATA #IMPLIED
    nl            CDATA #IMPLIED
    download-size CDATA #IMPLIED
    install-size CDATA #IMPLIED
>

The element and attribute definitions are as follows:

<feature> - defines the feature

id - required feature identifier (eg. com.xyz.myfeature)
version - required component version (eg. 1.0.3)
label - optional displayable label (name). Intended to be translated.
provider-name - optional display label identifying the organization providing this component. Intended to be translated.
image - optional image to use when displaying information about the feature. Specified relative to the feature.xml.
os - optional operating system specification. A comma-separated list of os designators defined by Eclipse (see Javadoc for org.eclipse.core.boot.BootLoader). Indicates this feature should only be installed on one of the specified os systems. If this attribute is not specified, the feature can be installed on all systems (portable implementation). This information is used as a hint by the installation and update support (user can force installation of feature regardless of this setting).
arch - optional machine architecture specification. A comma-separated list of architecture designators defined by Eclipse (see Javadoc for org.eclipse.core.boot.BootLoader). Indicates this feature should only be installed on one of the specified systems. If this attribute is not specified, the feature can be installed on all systems (portable implementation). This information is used as a hint by the installation and update support (user can force installation of feature regardless of this setting).
ws - optional windowing system specification. A comma-separated list of ws designators defined by Eclipse (see Javadoc for org.eclipse.core.boot.BootLoader). Indicates this feature should only be installed on one of the specified ws systems. If this attribute is not specified, the feature can be installed on all systems (portable implementation). This information is used as a hint by the installation and update support (user can force installation of feature regardless of this setting).
nl - optional locale specification. A comma-separated list of locale designators defined by Java. Indicates this feature should only be installed on a system running with a compatible locale (using Java locale-matching rules). If this attribute is not specified, the feature can be installed on all systems (language-neutral implementation). This information is used as a hint by the installation and update support (user can force installation of feature regardless of this setting).
colocation-affinity - optional reference to another feature identifier used to select the default installation location for this feature. When this feature is being installed as a new feature (no other versions of it are installed), an attempt is made to install this feature in the same installation location as the referenced feature.
primary - optional indication specifying whether this feature can be used as a primary feature. Default if false (not a primary feature).
application - optional identifier of the Eclipse application that is to be used during startup when the declaring feature is the primary feature. The application identifier must represent a valid application registered in the org.eclipse.core.runtime.applications extension point. Default is org.eclipse.ui.workbench.

<install-handler>

library - optional .jar library containing the install handler classes. If specified, the referenced .jar must be contained in the feature archive. It is specified as a path within the feature archive, relative to the feature.xml entry. If not specified, the feature archive itself is used to load the install handler classes. This attribute is only interpreted if class attribute is also specified
handler - optional identifier of the install handler. The value is interpreted depending on the value of the library attribute. If library is specified, the value is interpreted as a fully qualified name of a class contained in the specified library. If library is not specified, the value is is interpreted as an extension identifier of an extension registered in the org.eclipse.update.installHandlers extension point. In either case, the resulting class must implement the IInstallHandler interface. The class is dynamically loaded and called at specific points during feature processing. The handler has visibility to the API classes from the update plug-in, and Eclipse plug-ins required by the update plugin.

<description> - brief component description as simple text. Intended to be translated.

url - optional URL for the full description as HTML. The URL can be specified as absolute of relative. If relative, it is assumed to be relative to (and packaged in) the feature archive. Note, that for NL handling the URL value should be separated to allow alternate URLs to be specified for each national language.

<copyright> - feature copyright as simple text. Intended to be translated.

url - optional URL for the full description as HTML. The URL can be specified as absolute of relative. If relative, it is assumed to be relative to (and packaged in) the feature archive. Note, that for NL handling the URL value should be separated to allow alternate URLs to be specified for each national language.

<license> - feature "click-through" license as simple text. Intended to be translated. It is displayed in a standard dialog with [Accept] [Reject] actions during the download/ installation process. Note, that click-through license must be specified for any feature that will be selected for installation or update using the Eclipse update manager. When using nested features, only the nesting parent (ie. the feature selected for installation or update) must have click-through license text defined. The license text is required even if the optional url attribute is specified.

url - optional URL for the full description as HTML. The URL can be specified as absolute of relative. If relative, it is assumed to be relative to (and packaged in) the feature archive. Note, that for NL handling the URL value should be separated to allow alternate URLs to be specified for each national language. Note, that the "content" of this URL is not what is presented as the click-through license during installation processing. The click-through license is the actual value of the <license> element (eg. <license>click through text</license>)

<url> - optional URL specifying site(s) contain feature updates, or new features

<update> - URL to go to for updates to this feature

url - actual URL
label - displayable label (name) for the referenced site

<discovery> - URL to go to for new features. In general, a provider can use this element to reference its own site(s), or site(s) of partners that offer complementary features. Eclipse uses this element simply as a way to distribute new site URLs to the clients

url - actual URL
label - displayable label (name) for the referenced site

<includes> - optional reference to a nested feature that is considered to be part of this feature. Nested features must be located on the same update site as this feature

<id> - required nested feature identifier
<version> - required nested feature version

<requires> - optional feature dependency information. Is expressed in terms of plug-in dependencies. If specified, is enforced by the installation and update support at the time of installation

<import> - dependency entry. Specification and processing is a subset of the <import> specification in plugin.xml

plugin - identifier of dependent plug-in
version - optional plug-in version specification
match - optional matching rule. Valid values and processing are as follows:

if version attribute is not specifies, the match attribute (if specified) is ignored.
perfect - dependent plug-in version must match exactly the specified version.
equivalent - dependent plug-in version must be at least at the version specified, or at a higher service level (major and minor version levels must equal the specified version).
compatible - dependent plug-in version must be at least at the version specified, or at a higher service level or minor level (major version level must equal the specified version).
greaterOrEqual - dependent plug-in version must be at least at the version specified, or at a higher service, minor or major level.

<plugin> - identifies referenced plug-in

id - required plug-in identifier (from plugin.xml)
version - required plug-in version (from plugin.xml)
fragment - optional specification indicating if this entry is a plug-in fragment. Default is "false"
os - optional operating system specification. A comma-separated list of os designators defined by Eclipse (see Javadoc for org.eclipse.core.boot.BootLoader). Indicates this entry should only be installed on one of the specified os systems. If this attribute is not specified, the entry can be installed on all systems (portable implementation). This information is used as a hint by the installation and update support (user can force installation of entry regardless of this setting).
arch - optional machine architecture specification. A comma-separated list of architecture designators defined by Eclipse (see Javadoc for org.eclipse.core.boot.BootLoader). Indicates this feature should only be installed on one of the specified systems. If this attribute is not specified, the feature can be installed on all systems (portable implementation). This information is used as a hint by the installation and update support (user can force installation of feature regardless of this setting).
ws - optional windowing system specification. A comma-separated list of ws designators defined by Eclipse (see Javadoc for org.eclipse.core.boot.BootLoader). Indicates this entry should only be installed on one of the specified ws systems. If this attribute is not specified, the entry can be installed on all systems (portable implementation). This information is used as a hint by the installation and update support (user can force installation of entry regardless of this setting).
nl - optional locale specification. A comma-separated list of locale designators defined by Java. Indicates this entry should only be installed on a system running with a compatible locale (using Java locale-matching rules). If this attribute is not specified, the entry can be installed on all systems (language-neutral implementation). This information is used as a hint by the installation and update support (user can force installation of entry regardless of this setting).
download-size - optional hint supplied by the feature packager, indicating the download size in KBytes of the referenced plug-in archive. If not specified, the download size is not known (Implementation Note: the implementation needs to distinguish between "not known" and 0 size)
install-size - optional hint supplied by the feature packager, indicating the install size in KBytes of the referenced plug-in archive. If not specified, the install size is not known (Implementation Note: the implementation needs to distinguish between "not known" and 0 size)

<data> - identifies non-plugin data that is part of the feature

id - required data identifier in the form of a relative path.
os - optional operating system specification. A comma-separated list of os designators defined by Eclipse (see Javadoc for org.eclipse.core.boot.BootLoader). Indicates this entry should only be installed on one of the specified os systems. If this attribute is not specified, the entry can be installed on all systems (portable implementation). This information is used as a hint by the installation and update support (user can force installation of entry regardless of this setting).
arch - optional machine architecture specification. A comma-separated list of architecture designators defined by Eclipse (see Javadoc for org.eclipse.core.boot.BootLoader). Indicates this feature should only be installed on one of the specified systems. If this attribute is not specified, the feature can be installed on all systems (portable implementation). This information is used as a hint by the installation and update support (user can force installation of feature regardless of this setting).
ws - optional windowing system specification. A comma-separated list of ws designators defined by Eclipse (see Javadoc for org.eclipse.core.boot.BootLoader). Indicates this entry should only be installed on one of the specified ws systems. If this attribute is not specified, the entry can be installed on all systems (portable implementation). This information is used as a hint by the installation and update support (user can force installation of entry regardless of this setting).
nl - optional locale specification. A comma-separated list of locale designators defined by Java. Indicates this entry should only be installed on a system running with a compatible locale (using Java locale-matching rules). If this attribute is not specified, the entry can be installed on all systems (language-neutral implementation). This information is used as a hint by the installation and update support (user can force installation of entry regardless of this setting).
download-size - optional hint supplied by the feature packager, indicating the download size in KBytes of the referenced data archive. If not specified, the download size is not known (Implementation Note: the implementation needs to distinguish between "not known" and 0 size)
install-size - optional hint supplied by the feature packager, indicating the install size in KBytes of the referenced data archive. If not specified, the install size is not known (Implementation Note: the implementation needs to distinguish between "not known" and 0 size)

When interacting with the update site, the feature implementation maps the <plugin> and <data> elements into path identifiers used by the site to determine the actual files to download and install. The default feature implementation supplied by Eclipse constructs the path identifiers as follows:

<plugin> element results in a path entry in the form "plugins/<pluginId>_<pluginVersion>.jar" (for example, "plugins/org.eclipse.core.boot_2.0.0.jar")
<data> element results in a path entry in the form "features/<featureId>_<featureVersion>/<dataId>" (for example, "features/com.xyz.tools_1.0.3/examples.zip")

Note, that in general the feature.xml manifest documents should specify UTF-8 encoding. For example

<?xml version="1.0" encoding="UTF-8"?>

Translatable text contained in the feature.xml can be separated into feature<_locale>.properties files using Java property bundle conventions. Note that the translated strings are used at installation time (ie. do not employ the plug-in fragment runtime mechanism).