platform-update-home/doc/eclipse_update_packaging.html
Parent Directory
| 
Revision Log
Revision 1.13 -
(download)
(as text)
(annotate)
Mon Jan 13 19:01:27 2003 UTC (6 years, 10 months ago) by celek
Branch: MAIN
Changes since 1.12: +1151 -1138 lines
Mon Jan 13 19:01:27 2003 UTC (6 years, 10 months ago) by celek
Branch: MAIN
Changes since 1.12: +1151 -1138 lines
*** empty log message ***
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<meta name="Author" content="Lab User">
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
<title>Eclipse Platform: Installation and Update</title>
</head>
<body>
<h1> Eclipse Platform<br>
Update Packaging Conventions</h1>
<font size="-1">Revision Date: 01/02/2003 9:33AM - Version: 2.0.16</font><br>
<a href="../../../../../hglegal.htm"><img src="ngibmcpy.gif"
border="0" height="12" width="195">
</a>
<p><b>Change History:</b> </p>
<ul>
<li><small>2.0.16</small> <small><br>
</small>
<ul>
<li><small>added <site><feature> os,arch,nl,ws support
"*"</small></li>
</ul>
</li>
<li><small>2.0.15</small>
<ul>
<li><small>added <site><feature> os,arch,nl,ws,patch
tag</small></li>
</ul>
</li>
<li><small>2.0.14<br>
</small>
<ul>
<li><small>added <site><feature> label tag</small><br>
</li>
</ul>
</li>
<li><font size="-1">2.0.13</font> <small><br>
</small>
<ul>
<li><small>added <includes name,optional,match,search_location</small>
></li>
<li><small>added <import feature,patch></small></li>
</ul>
</li>
</ul>
<ul>
<li><font size="-1">2.0.12</font></li>
<ul>
<li> <font size="-1">added reference to the <a
href="http://www.eclipse.org/legal/updatemanager.html"> Eclipse.org Update
Manager Agreement</a> </font></li>
</ul>
<li> <font size="-1">2.0.11</font></li>
<ul>
<li> <font size="-1"><feature> <license> is required</font></li>
</ul>
<li> <font size="-1">2.0.10</font></li>
<ul>
<li> <font size="-1"><feature colocation-affinity=""></font></li>
</ul>
<li> <font size="-1">2.0.9</font></li>
<ul>
<li> <font size="-1"><site> <feature> changes - additional
markup to optionally expose feature identification information to speed
up searches</font></li>
<li> <font size="-1">removed obsolete text</font></li>
<li> <font size="-1">web-triggered update not in 2.0</font></li>
<li> <font size="-1">no assist in 2.0 for license/ "key file" handling
(individual application/ plugin responsibility)</font></li>
</ul>
<li> <font size="-1">2.0.8</font></li>
<ul>
<li> <font size="-1"><feature> <includes></font></li>
</ul>
<li> <font size="-1">2.0.7</font></li>
<ul>
<li> <font size="-1">support explicit xml markup for primary features</font></li>
</ul>
<li> <font size="-1">2.0.6</font></li>
<ul>
<li> <font size="-1">install handler markup changes</font></li>
</ul>
<li> <font size="-1">2.0.5</font></li>
<ul>
<li> <font size="-1">updates to security section</font></li>
</ul>
<li> <font size="-1">2.0.4</font></li>
<ul>
<li> <font size="-1">general text cleanup</font></li>
<li> <font size="-1"><feature><group> support removed
(will not be in Eclipse 2.0)</font></li>
<li> <font size="-1">arch= support added to <feature> and <feature><plugin></font></li>
<li> <font size="-1">os=/ arch=/ ws=/ nl= added to <fetaure><data></font></li>
<li> <font size="-1"><site url=""> new semantics</font></li>
<li> <font size="-1">corrected errors in native installer link support</font></li>
<li> <font size="-1">defined callback query strings for browser-triggered
processing</font></li>
</ul>
</ul>
<h3> <font size="+2">Table of Contents</font></h3>
<a href="#Introduction">Introduction</a> <br>
<a href="#Changes_from_R1.0">Changes
from 1.0</a> <br>
<a href="#Concepts">Concepts</a>
<br>
<a href="#Framework">Framework</a>
<br>
<a href="#Packaging_Conventions">Packaging Conventions</a> <br>
<a href="#Feature_Archive">Feature
Archive</a> <br>
<a href="#Plug-In_Archive">Plug-In
Archive</a> <br>
<a href="#Packaging_NL">Packaging
NL</a> <br>
<a
href="#Translated_Feature_Information"> Translated Feature Information</a>
<br>
<a
href="#Translated_Plug-In_Information"> Translated Plug-In Information</a>
<br>
<a
href="#Packaging_Target-Specific_Support"> Packaging Target-Specific Support</a>
<br>
<a
href="#Packaging_Attribution_Information"> Packaging Attribution Information</a>
<br>
<a
href="#Packaging_Attribution_Information"> Packaging Non-Plug-In Files</a>
<br>
<a
href="#Packaging_Attribution_Information"> Custom Install Handling</a>
<br>
<a
href="#Security_Considerations">Security Considerations</a> <br>
<a href="#Update_Server">Update Server</a> <br>
<a href="#Site_Map">Site Map</a>
<br>
<a href="#Default_Site_Layout">Default
Site Layout</a> <br>
<a href="#Controlling_Access">Controlling
Access</a> <br>
<a href="#Eclipse_Install">Eclipse Install</a> <br>
<a
href="#Default_Install_Layout">Default Install Layout</a> <br>
<a href="#Unmanaged_Plugins">"Unmanaged"
Plug-Ins</a> <br>
<a
href="#Using_Native_Platform_Installers"> Using Native Platform Installers</a>
<h2> <a name="Introduction"></a> Introduction</h2>
This document outlines the support for managing the delivery of function
within the Eclipse platform. Also refer to the "<a
href="http://www.eclipse.org/legal/updatemanager.html"> Eclipse.org Update
Manager Agreement</a> " for additional legal information governing the
use of the Eclipse update manager function.
<h3> <a name="Changes_from_R1.0"></a> Changes from R1.0</h3>
This section describes the major design changes from the R1.0 Installation
and Update support and supplies rationale for each design change.
<ul>
<li> <b>extendable framework</b></li>
<br>
In R2.0 Eclipse defines an extendable framework for installation and
update, allowing the support for alternate packaging and site management
schemes. R2.0 supplies a default concrete implementation of this framework.
<li> <b> feature support</b></li>
<br>
In R2.0 the concept of a <i>component</i> and <i>configuration</i> is
merged into <i>feature</i>. Features define the packaging structure for
a group of related plug-ins, plug-in fragments, and optionally non-plug-in
files. Features are treated purely as an installation and packaging construct.
They do not play a role during Eclipse plug-in execution. Features do not
nest. They are simply an inclusive "manifest" of the plug-ins, fragments
and other files that make up that feature. If features are logically made
up of plug-ins from "sub-features", the top-level feature "manifest" must
be fully resolved at packaging time. <li> <b>default feature archive format</b></li>
<br>
R1.0 components were packaged as a single Java .jar containing the component
manifest as well as the actual plug-in files. The problem with this approach
is lack of granularity at download time. In R2.0, the feature archive consists
of multiple separate .jars - one .jar per plug-in and fragment, plus one
.jar for the actual feature information. The Installation and Update support
selectively downloads only those jars required for the installation. <li>
<b>site map</b></li>
<br>
Default Eclipse update server must contain a <i>site map</i> file (site.xml).
This is an evolution of the R1.0 install.index support. The rationale
for using a structured site defined by the map rather than a "free form"
web site, is the ability to present a consistent installation experience
for the user. Also, this provides the necessary structure for discovery
of available updates. Additional support for "free form" browsing may be
considered in future work. <li> <b>using native install/ uninstall</b></li>
<br>
The primary mechanism for installing and updating Eclipse features is
the built-in installation and update support. Some products may instead
choose to use native installer technology (eg. MSI, RPM, etc) to deliver
Eclipse features. However, native installers do not implement the required
support for understanding the Eclipse installation structure. In particular,
the native uninstallers will, by default, remove plug-in files that were
installed using the native installer without regard to these plug-ins being
needed by other features. As a result, features installed using native installers
must be written into private product-specific installation location and not
the shared Eclipse installation location. The shared Eclipse is made aware
of the produce-specific location via an installed "link file". <li>
<b>custom install handling</b></li>
<br>
In many cases the standard installation handling supplied by Eclipse
is not be sufficient to handle various custom requirements. To accommodate
this, R2.0 Eclipse supports custom install handlers packaged as part of
the feature and executed during the feature installation. <li> <b>path naming
conventions</b></li>
<br>
R1.0 mandated the use of the various identifiers and versions inside
the packaged archives (eg. directory path names for plug-ins). This approach
has proven to be ackward and error prone. In 2.0, the packaging requirements
no longer mandate that path names of packaged files precisely reflect the
contained identifiers and versions. The properly identified install subdirectories
are created by the Eclipse support during the installation and update process
based on the archive content (rather than explicit jar path structure
set up at packaging time)
</ul>
<h3> <a name="Concepts"></a> Concepts</h3>
<b>Plug-in</b> <br>
Eclipse developers build plug-ins. Plug-ins are the base units of execution
recognized by the Eclipse runtime environment. In general, plug-ins are
not exposed to users that select function during installation or update.
The reason is that plug-in boundaries are established by developers for development
reasons (like function reuse) and present the wrong level of granularity
in terms of what the user sees as the unit of function.
<p>While plug-ins are being developed (ie. are frequently being changed),
their internal file structure will reflect what is convenient to the developer.
This will generally depend on the particular development tool being used.
Typically, however, the developer will likely setup the plug-in to execute
from a directory tree containing exposed .class files, rather than executing
from a .jar (requires an extra step to create the .jar and we all know
developers hate extra steps). Also, at this stage the developer does not
pay particular attention to plug-in versioning information, because the
plug-in is continually changing. </p>
<p>However, when the plug-in is ready to be packaged, it needs to be converted
to a form suitable for packaging and installation. Typically it means
creation of the runtime .jar(s) and removing any development-time files
(source, exposed .class files, etc). It also means updating the plugin.xml
manifest with the formal plug-in version and reflecting the version in the
plug-in directory name (see "Concurrent Plug-In Version Support" for details).
</p>
<p><b>Plug-in Fragment</b> <br>
Plug-in Fragments (or simply Fragments) allow independent packaging
of certain aspects of the base plug-in. This includes (but may not be limited
to) translated resources for the plug-in, OS-specific or windowing-system-specific
code. At runtime, fragments are logically merged into the base plug-in.
From a packaging point of view, the install and update support does not really
differentiate between plug-ins and their related fragments. </p>
<p><b>Feature</b> <br>
A feature is an installation packaging mechanism used to define a group
of versioned plug-ins and/or plug-in fragments plus non-plug-in files that
is used to deliver some user function. A feature can also include other
features. Features are exposed to users as part of the packaging and installation
process, because they represent a unit of function selection. Features also
represent a unit of installation. Features carry a version identifier.</p>
<p>Features are packaged as a feature archive, referencing the required plug-ins,
plug-in fragments and optional non-plug-in files. The feature archives are
placed on an update server for download and installation by the Eclipse
update manager, or they can be used as the input into a formal packaging
process using one of the "traditional" installer technologies. The format
of the feature archive is described later. </p>
<h3> <a name="Framework"></a> Framework</h3>
The 2.0 installation and update support is provided as a framework
that allows custom implementations to be supplied for its key elements.
In particular, the following can be supplied:
<ul>
<li> concrete implementations of feature (IFeature interface) that
can be used to support alternate packaging schemes. New concrete feature
types are registere via the "org.eclipse.update.featureTypes" extension
point.</li>
<li> concrete implementations of site (ISite interface) that can be
used to support alternate site layout, or site behavior. New concrete site
types are registered via the "org.eclipse.update.siteTypes" extension
point.</li>
<li> each feature can specify a custom install handler as part of
its feature manifest. Install handlers (IInstallHandler interface) are
dynamically invoked as part of the installation process to handle non-plugin
data, plus perform other custom processing allowed by the framework.</li>
</ul>
Eclipse provides default implementations of feature and site. These
are described in the rest of this document. <br>
<table border="1" cols="1" width="100%">
<tbody>
<tr>
<td><b>Note: <i>The reminder of this document describes the default
concrete implementation of the framework delivered with Eclipse. It specifies
the structure of the default feature implementation, as well as the default
site implementation, plus the corresponding xml files (feature.xml and
site.xml). Providers of alternate concrete implementations can extend
parts or all of the default Eclipse implementation. This includes providing
a mechanism for dynamic computation of the site map (site.xml)</i></b></td>
</tr>
</tbody>
</table>
<h2> <a name="Packaging_Conventions"></a> Packaging Conventions</h2>
Default feature packages consist of several related files:
<ul>
<li> exactly one jar containing the feature manifest and related files.
This one is refered to as the "<b>feature archive</b>"</li>
<li> zero or more jars containing the feature plug-ins. These are
refered to as the "<b>plug-in archives</b>"</li>
<li> zero or more non-plug-in files associated with the feature. They
are used by feature custom install handlers and contain data not interpreted
by Eclipse</li>
</ul>
<h3> <a name="Feature_Archive"></a> Feature Archive</h3>
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.
<p>Features are identified using a structured identifier based on the provider
internet domain name. For example, organization eclipse.org may produce
feature org.eclipse.javatooling. The character set used for feature identifiers
is as specified for plug-in identifiers (see reference information describing
the plug-in manifest). </p>
<p>The recommended convention for naming the feature archives is <br>
<tt><id>_<version>.jar</tt> </p>
<p>Where <tt><id></tt> is the feature identifier and <tt><version></tt>
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 </p>
<p><tt>org.eclipse.javatooling_1.0.3.jar</tt> <br>
<tt>org.eclipse.pde_2.0.jar</tt> <br>
<tt>my_feature.jar</tt> </p>
<p>Internally, each feature archive is packaged relative to its feature directory
(but not including the directory path element). The archive has the following
structure </p>
<p><tt>feature.xml</tt> <br>
<tt>feature<_locale>.properties (see "Translated Feature Information")</tt>
<br>
<tt>other feature files and subdirectories (TBD)</tt> <br>
<tt>META-INF/</tt> <br>
<tt> Java jar manifest and security files</tt> </p>
<p>The feature install.xml format is defined by the following dtd: </p>
<p><tt><?xml encoding="ISO-8859-1"?></tt> </p>
<p><tt><!ELEMENT feature (install-handler?, description?, copyright?,
license?, url?, includes*, requires?, plugin*, data*)></tt> <br>
<tt><!ATTLIST feature</tt> <br>
<tt> id
CDATA #REQUIRED</tt> <br>
<tt> version CDATA
#REQUIRED</tt> <br>
<tt> label
CDATA #IMPLIED</tt> <br>
<tt> provider-name CDATA #IMPLIED</tt> <br>
<tt> image
CDATA #IMPLIED</tt> <br>
<tt> os
CDATA #IMPLIED</tt> <br>
<tt> arch
CDATA #IMPLIED</tt> <br>
<tt> ws
CDATA #IMPLIED</tt> <br>
<tt> nl
CDATA #IMPLIED</tt> <br>
<tt> colocation-affinity</tt> <br>
<tt>
CDATA #IMPLIED</tt> <br>
<tt> primary (true
| false) "false"</tt> <br>
<tt> application CDATA #IMPLIED</tt> <br>
<tt>></tt> </p>
<p><tt><!ELEMENT install-handler EMPTY></tt> <br>
<tt><!ATTLIST install-handler</tt> <br>
<tt> library CDATA
#IMPLIED</tt> <br>
<tt> handler CDATA
#IMPLIED</tt> <br>
<tt>></tt> </p>
<p><tt><!ELEMENT description (#PCDATA)></tt> <br>
<tt><!ATTLIST description</tt> <br>
<tt> url
CDATA #IMPLIED</tt> <br>
<tt>></tt> </p>
<p><tt><!ELEMENT copyright (#PCDATA)></tt> <br>
<tt><!ATTLIST copyright</tt> <br>
<tt> url
CDATA #IMPLIED</tt> <br>
<tt>></tt> </p>
<p><tt><!ELEMENT license (#PCDATA)></tt> <br>
<tt><!ATTLIST license</tt> <br>
<tt> url
CDATA #IMPLIED</tt> <br>
<tt>></tt> </p>
<p><tt><!ELEMENT url (update?, discovery*)></tt> </p>
<p><tt><!ELEMENT update EMPTY></tt> <br>
<tt><!ATTLIST update</tt> <br>
<tt> url
CDATA #REQUIRED</tt> <br>
<tt> label
CDATA #IMPLIED</tt> <br>
<tt>></tt> </p>
<p><tt><!ELEMENT discovery EMPTY></tt> <br>
<tt><!ATTLIST discovery</tt> <br>
<tt> url
CDATA #REQUIRED</tt> <br>
<tt> label
CDATA #IMPLIED</tt> <br>
<tt>></tt> </p>
<p><tt><!ELEMENT includes EMPTY></tt> <br>
<tt><!ATTLIST includes</tt> <br>
<tt> id
CDATA #REQUIRED</tt> <br>
<tt> version
CDATA #REQUIRED</tt> <br>
<tt> name
CDATA #IMPLIED</tt> <br>
<tt> optional </tt><tt>
(true | false) "false"</tt><tt> <br>
</tt><tt> match
(perfect | equivalent | compatible | greaterOrEqual)
"compatible"</tt><tt> </tt><br>
<tt> search_location </tt><tt>(</tt><font
color="#000000"><tt> root | self | both) "root"</tt></font><br>
<tt>></tt> </p>
<p><tt><!ELEMENT requires (import+)></tt> </p>
<p><tt><!ELEMENT import EMPTY></tt> <br>
<tt><!ATTLIST import</tt> <br>
<tt> plugin
CDATA #IMPLIED</tt><br>
<tt> feature CDATA
#IMPLIED</tt><br>
<tt> version CDATA
#IMPLIED</tt> <br>
<tt> match
(perfect | equivalent | compatible | greaterOrEqual) "compatible"</tt> <br>
<tt> patch </tt><tt>
(true | false) "false"</tt><tt> </tt><tt><br>
></tt><br>
</p>
<p><tt><!ELEMENT plugin EMPTY></tt> <br>
<tt><!ATTLIST plugin</tt> <br>
<tt> id
CDATA #REQUIRED</tt> <br>
<tt> version CDATA
#REQUIRED</tt> <br>
<tt> fragment (true
| false) "false"</tt> <br>
<tt> os
CDATA #IMPLIED</tt> <br>
<tt> arch
CDATA #IMPLIED</tt> <br>
<tt> ws
CDATA #IMPLIED</tt> <br>
<tt> nl
CDATA #IMPLIED</tt> <br>
<tt> download-size CDATA #IMPLIED</tt> <br>
<tt> install-size CDATA #IMPLIED</tt> <br>
<tt>></tt> </p>
<p><tt><!ELEMENT data EMPTY></tt> <br>
<tt><!ATTLIST data</tt> <br>
<tt> id
CDATA #REQUIRED</tt> <br>
<tt> os
CDATA #IMPLIED</tt> <br>
<tt> arch
CDATA #IMPLIED</tt> <br>
<tt> ws
CDATA #IMPLIED</tt> <br>
<tt> nl
CDATA #IMPLIED</tt> <br>
<tt> download-size CDATA #IMPLIED</tt> <br>
<tt> install-size CDATA #IMPLIED</tt> <br>
<tt>></tt> </p>
<p>The element and attribute definitions are as follows: </p>
<ul>
<li> <feature> - defines the feature</li>
<ul>
<li> id - required feature identifier (eg. com.xyz.myfeature)</li>
<li> version - required component version (eg. 1.0.3)</li>
<li> label - optional displayable label (name). Intended to be translated.</li>
<li> provider-name - optional display label identifying the organization
providing this component. Intended to be translated.</li>
<li> image - optional image to use when displaying information about
the feature. Specified relative to the feature.xml.</li>
<li> os - optional operating system specification. A comma-separated
list of os designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt>
. 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).</li>
<li> arch - optional machine architecture specification. A comma-separated
list of architecture designators defined by Eclipse (see Javadoc for <tt>
org.eclipse.core.boot.BootLoader)</tt>. 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).</li>
<li> ws - optional windowing system specification. A comma-separated
list of ws designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt>
. 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).</li>
<li> 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).</li>
<li> 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.</li>
<li> primary - optional indication specifying whether this feature
can be used as a <a href="#Dominant_Feature">primary feature</a> . Default
if <i>false</i> (not a primary feature).</li>
<li> application - optional identifier of the Eclipse application
that is to be used during startup when the declaring feature is the <a
href="#Dominant_Feature"> primary feature</a> . The application identifier
must represent a valid application registered in the <tt>org.eclipse.core.runtime.applications</tt>
extension point. Default is <tt>org.eclipse.ui.workbench</tt>.</li>
</ul>
<li> <install-handler></li>
<ul>
<li> 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 <i>class</i> attribute is also specified</li>
<li> handler - optional identifier of the install handler. The value
is interpreted depending on the value of the <i>library</i> attribute. If
<i> library</i> is specified, the value is interpreted as a
fully qualified name of a class contained in the specified <i>library</i>.
If <i>library</i> is not specified, the value is is interpreted as
an extension identifier of an extension registered in the <i>org.eclipse.update.installHandlers</i>
extension point. In either case, the resulting class must implement the
<i> IInstallHandler</i> 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.</li>
</ul>
<li> <description> - brief component description as simple text.
Intended to be translated.</li>
<ul>
<li> 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.</li>
</ul>
<li> <copyright> - feature copyright as simple text. Intended
to be translated.</li>
<ul>
<li> 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.</li>
</ul>
<li> <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 <i>url</i> attribute is specified.</li>
<ul>
<li> 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 <b>not</b>
what is presented as the click-through license during installation processing.
The click-through license is the actual value of the <i><license></i>
element (eg. <tt><license>click through text</license></tt>)</li>
</ul>
<li> <url> - optional URL specifying site(s) contain feature
updates, or new features</li>
<ul>
<li> <update> - URL to go to for updates to this feature</li>
<ul>
<li> url - actual URL</li>
<li> label - displayable label (name) for the referenced site</li>
</ul>
<li> <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</li>
<ul>
<li> url - actual URL</li>
<li> label - displayable label (name) for the referenced site</li>
</ul>
</ul>
<li> <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</li>
<ul>
<li> id - required nested feature identifier</li>
<li> version - required nested feature version</li>
<li> name- optional displayable label (name). Intended to be translated.</li>
<li>optional - optional specification indicating if this included
feature can be optionally installed. Default is "false"<br>
</li>
<li>match - optional rule that will be applied when resolving
the feature reference. A <samp>perfect</samp> 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 (<samp>
equivalent</samp> allows only service part of the version to be more recent,
<samp>compatible</samp> also allows minor part to be included in the
consideration, while <samp>greaterOrEqual</samp> simply allows any version
that is more recent or identical to the one specified).</li>
<li>search_location - optional. Indicates whether the "New
Updates" action should search the update location determined by the nesting
root feature (<tt>root</tt>, is the default), or the location defined by
the nested feature (<tt>self</tt>), or search both (<tt>both</tt>) in that
order (root first, self if nothing is found).</li>
</ul>
<li> <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</li>
<ul>
<li> <import> - dependency entry. Specification and processing
is a subset of the <import> specification in plugin.xml</li>
<ul>
<li> plugin - identifier of dependent plug-in.</li>
<li> feature - identifier of dependent feature. If plugin and
feature are specified, plugin takes precedence upon feature. Feature or
plugin must be specified.</li>
<li> version - optional plug-in/feature version specification</li>
<li>patch - optional specification indicating if this feature
is a patch of the dependant feature. Default is "false". If patch is true,
version must be specified. If patch is true, only feature must be specified.
If patch is true, and match is specified, it must be 'perfect'.<br>
</li>
<li> match - optional matching rule. Valid values and processing are
as follows:</li>
<ul>
<li> if version attribute is not specified, the match attribute (if
specified) is ignored.</li>
<li>if version is specified, match defaults to compatible.<br>
</li>
<li>if patch is true, and match is not specified, match defaults
to perfect.<br>
</li>
<li> <b><i>perfect</i></b> - dependent plug-in version must match
exactly the specified version.</li>
<li> <b><i>equivalent</i></b> - 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).</li>
<li> <b><i>compatible</i></b> - 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).</li>
<li> <b><i>greaterOrEqual</i></b> - dependent plug-in version must
be at least at the version specified, or at a higher service, minor or major
level.</li>
</ul>
</ul>
</ul>
<li> <plugin> - identifies referenced plug-in</li>
<ul>
<li> id - required plug-in identifier (from plugin.xml)</li>
<li> version - required plug-in version (from plugin.xml)</li>
<li> fragment - optional specification indicating if this entry is
a plug-in fragment. Default is "false"</li>
<li> os - optional operating system specification. A comma-separated
list of os designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt>
. 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).</li>
<li> arch - optional machine architecture specification. A comma-separated
list of architecture designators defined by Eclipse (see Javadoc for <tt>
org.eclipse.core.boot.BootLoader)</tt>. 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).</li>
<li> ws - optional windowing system specification. A comma-separated
list of ws designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt>
. 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).</li>
<li> 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).</li>
<li> 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 (<b>Implementation Note:</b>
the implementation needs to distinguish between "not known" and 0 size)</li>
<li> 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 (<b>Implementation Note:</b>
the implementation needs to distinguish between "not known" and 0 size)</li>
</ul>
<li> <data> - identifies non-plugin and non-feature data that
is part of the feature. Generally, data are post-install processed using
feature Install handler. Feature files like feature.properties are not considered
data.</li>
<ul>
<li> id - required data identifier in the form of a relative path.</li>
<li> os - optional operating system specification. A comma-separated
list of os designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt>
. 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).</li>
<li> arch - optional machine architecture specification. A comma-separated
list of architecture designators defined by Eclipse (see Javadoc for <tt>
org.eclipse.core.boot.BootLoader)</tt>. 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).</li>
<li> ws - optional windowing system specification. A comma-separated
list of ws designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt>
. 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).</li>
<li> 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).</li>
<li> 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 (<b>Implementation Note:</b>
the implementation needs to distinguish between "not known" and 0 size)</li>
<li> 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 (<b>Implementation Note:</b>
the implementation needs to distinguish between "not known" and 0 size)</li>
</ul>
</ul>
<a name="Feature_Archive_Mapping_Id_To_Path"></a> When interacting
with the update site, the feature implementation maps the <tt><plugin></tt>
and <tt><data></tt> 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:
<ul>
<li> <tt><plugin></tt> element results in a path entry in the
form "<tt>plugins/<pluginId>_<pluginVersion>.jar</tt>" (for
example, "<tt>plugins/org.eclipse.core.boot_1.0.3.jar</tt>")</li>
<li> <tt><data></tt> element results in a path entry in the
form "<tt>features/<featureId>_<featureVersion>/<dataId></tt>
" (for example, "f<tt>eatures/com.xyz.tools_2.3.1/examples.zip</tt>")</li>
</ul>
Note, that in general the feature.xml manifest documents should
specify UTF-8 encoding. For example
<p><tt><?xml version="1.0" encoding="UTF-8"?></tt> </p>
<p>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). </p>
<h3> <a name="Plug-In_Archive"></a> Plug-In Archive</h3>
Plug-ins and plug-in fragments are individually packaged as separate
Java .jars. Standard Java jar facilities are used for constructing plug-in
archives. There is no distinction made between a plug-in archive containing
a plug-in and one containing a plug-in fragment.
<p>The recommended convention for naming the plug-in archives is <br>
<tt><id>_<version>.jar</tt> </p>
<p>Where <tt><id></tt> is the plug-in or fragment identifier and <tt>
<version></tt> is the full version identifier contained in the respective
plugin.xml or fragment.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 plug-in archive names </p>
<p><tt>org.eclipse.platform_1.0.3.jar</tt> <br>
<tt>org.eclipse.ui.nl_2.0.jar</tt> <br>
<tt>my_plugin.jar</tt> </p>
<p>Internally, each plug-in archive packages all the relevant plug-in or
fragment files relative to its plug-in or fragment directory (but not including
the directory path element). The archive has the following structure </p>
<p><tt>plugin.xml *OR* fragment.xml</tt> <br>
<tt>other plug-in or feature files and subdirectories</tt> <br>
<tt>META-INF/</tt> <br>
<tt> Java jar manifest and security files</tt> </p>
<h3> <a name="Packaging_NL"></a> Packaging NL</h3>
In Eclipse, translated plug-in information is packaged either together
with the base plug-in, or as a plug-in fragment. At runtime, Eclipse locates
the translations for the required locale. The use of fragments allows translations
to be added to the runtime without the need to repackage the base plug-ins.
<p>This mechanism cannot be used for translating the actual packaging information
that is part of the installation xml files. Consequently the standard
Java translation conventions are used for the packaging information, and
all necessary translations must be available at the time the feature is
packaged. </p>
<h4> <a name="Translated_Feature_Information"></a> Translated Feature Information</h4>
<b>Note:</b> This section describes the conventions used for translating
the information contained within the feature manifest. It allows for the
update client to select the correctly localized strings from the update
server. This section specifically does not describe localization of individual
plug-ins.
<p>Several of the attributes within the feature manifest are strings intended
for display through user interfaces. To facilitate translation, these
attribute values use the convention defined for translatable attributes
of plugin.xml. Strings beginning with % up to the first space are treated
as resource identifier keys (without the %) and looked up in a properties
file. For example </p>
<p><tt>label="%cfg Tool Feature for Linux"</tt> </p>
<p>results in a resource lookup in the correct property file with key "cfg".
If no property files are supplied, or the key is not found the default
string value (following the %key) is used. </p>
<p>The property files are named as feature_<locale>.properties using
the Java resource bundle naming conventions. Within the feature archive
.jar they are placed in the same directory as their corresponding feature.xml
file. </p>
<p><b>Implementation Note</b>: When accessing the resource bundles the Eclipse
installation and update code should create a class loader for accessing
the translated string. This way, the standard locale lookup algorithm implemented
by Java is automatically used. </p>
<p><tt>ResourceBundle b;</tt> <br>
<tt>ClassLoader l;</tt> <br>
<tt>l = new URLClassLoader(new URL[] {<targetDirectoryURL>}, null);</tt>
<br>
<tt>b = ResourceBundle.getBundle("feature",Locale.getDefault(),l);</tt>
</p>
<p>The resulting resource bundle can be used in <tt>IPluginDescriptor.getResourceString(String,ResourceBundle)</tt>
to actually return the correct translated string for the manifest attribute.
</p>
<h4> <a name="Translated_Plug-In_Information"></a> Translated Plug-In Information</h4>
No change from 1.0. Translated plug-in information should be packaged
as plug-in fragments.
<h3> <a name="Packaging_Target-Specific_Support"></a> Packaging Target-Specific
Support</h3>
No change from 1.0. Target-specific plug-in support (os, ws) should
be packaged as plug-in fragments.
<h3> <a name="Packaging_Attribution_Information"></a> Packaging Attribution
Information</h3>
This topic is covered in separate documents available on the eclipse.org
development resources page of the Update component.
<h3> <a name="Packaging_Non_Plug_In_Files"></a> Packaging Non-Plug-In Files</h3>
Arbitrary non-plug-in files can be included as part of the feature
definition using the <tt><data></tt> elements. Non-plug-in files
typically also requires specification of a custom install handler. In
general, the Eclipse support only downloads the referenced non-plug-in
files and calls the custom install handler to perform any actual installation
steps.
<p>Eclipse does not specify the format of the non-plug-in files. </p>
<h3> <a name="Custom_Install_Handling"></a> Custom Install Handling</h3>
Custom install handlers are written as a Java class and are packaged
as part of the <a href="#Feature_Archive">feature archive</a> . The installer
must implement the <tt>IInstallHandler</tt> interface (in most cases will
extend the <tt>BaseInstallHandler</tt> abstract helper class which implements
<tt>IInstallHandler</tt>). When required, the install handler is dynamically
loaded by the installation and update code, and is called at specific points
during its processing. The install handler code has visibility to classes
from the installation and update support plug-in, and its prerequisite
plug-ins.
<p><b>Implementation Note:</b> the detailed list of visible prerequisite
plug-ins is still evolving. It is expected to include <tt>org.eclipse.core.boot
</tt> and <tt>org.eclipse.core.runtime</tt> in all cases, plus <tt>org.eclipse.ui</tt>
and <tt>org.eclipse.swt</tt> when running with full workbench (ie. not
"headless mode"). Also, it would be useful to always expose <tt>org.eclipse.core.ant</tt>
so that build scripts can be used as part of the install handler implementation.
</p>
<p>The IInstallHandler interface supports the following methods [<b>Implementation
Note:</b> the detailed definition of the IInstallHandler interface is
still evolving. The description below is not an API specification (simply
a functional description)]: </p>
<ul>
<li> install-initiated - the install handler is called after a feature
was selected for installation, but before any files were downloaded. It
is intended to implement any custom click-through or user registration
dialogs. The base implementation of this method supplied with the abstract
class <tt>BaseInstallHandler </tt>performs the default click-through
processing using the license text supplied as part of the feature manifest.
On return this method indicates success (installation continues) of failure
(installation is aborted).</li>
<li> install-downloaded - the install handler is called after all
the required feature files were downloaded (feature, plugins, data) but
before the actual installation is performed. The install handler is expected
to perform verification of the non-plug-in data files (eg. security),
or any other pre-install processing. On return this method indicates
success (installation continues) or failure (installation is aborted).</li>
<li> install-completion - the install handler is called after the
feature information and the plug-ins were installed. It is expected to
complete the installation of any non-plug-in data that was part of the feature.
On return this method indicates success (returns custom install log) or
failure (installation is aborted). On failure, the install handler is expected
to perform any required cleanup.</li>
<li> uninstall-initiated - the install handler is called when a feature
is selected for removal, but before any of the standard uninstall processing
has taken place. It is passed the custom install log created by the install
handler install-completion step.</li>
<li> uninstall-completion - the install handler is called on completion
of the standard uninstall steps. It is passed the custom install log created
by the install handler install-completion step.</li>
</ul>
Note, that as a general practice, install handlers should be provided
in their own jars (even though they could be just exposed in the feature
archive jar). The jar should be signed, and sealed.
<h3> <a name="Security_Considerations"></a> Security Considerations</h3>
The general approach is to use base Java jar signing for the feature
and plug-in archive .jars.
<p>Features are verified as follows: </p>
<ul>
<li> download and verify the feature archive (use base Java jar verification)</li>
<li> for each plug-in archive</li>
<ul>
<li> verify the archive jar content (use base Java jar verification)</li>
<li> verify plug-in id and version from <tt><plugin></tt> entry
in feature manifest matches downloaded plugin.xml</li>
</ul>
<li> for each non-plugin file</li>
<ul>
<li> call install handler to verify file</li>
</ul>
</ul>
In general, when processing signed jars, the user will be prompted
for each unrecognized certificate. The response choices will include aborting
the installation (originator is not trusted), continuing the installation
(originator is trusted for this installation).
<h2> <a name="Update_Server"></a> Update Server</h2>
The default Eclipse update server is any URL-accessible server. The
default implementation assumes a fixed-layout server. The content of the
server (in terms of available features and plug-ins) is described in a site
map file, <i>site.xml</i>. This file can be manually maintained, or can be
dynamically computed by the server.
<h3> <a name="Site_Map"></a> Site Map</h3>
The update server URL can be specified as a full URL to the site map
file, or a URL of a directory path containing the site map file (similar
to index.html processing). The site map site.xml format is defined by
the following dtd:
<p><tt><?xml encoding="ISO-8859-1"?></tt> </p>
<p><tt><!ELEMENT site (description?, feature*, archive*, category-def*)></tt>
<br>
<tt><!ATTLIST site</tt> <br>
<tt> type
CDATA #IMPLIED</tt> <br>
<tt> url
CDATA #IMPLIED</tt> <br>
<tt>></tt> </p>
<p><tt><!ELEMENT description (#PCDATA)></tt> <br>
<tt><!ATTLIST description</tt> <br>
<tt> url
CDATA #IMPLIED</tt> <br>
<tt>></tt> </p>
<p><tt><!ELEMENT feature (category*)></tt> <br>
<tt><!ATTLIST feature</tt> <br>
<tt> type
CDATA #IMPLIED</tt> <br>
<tt> id
CDATA #IMPLIED</tt> <br>
<tt> version CDATA
#IMPLIED</tt> <br>
<tt> url
CDATA #REQUIRED<br>
label CDATA
#IMPLIED<br>
</tt><tt> os
CDATA #IMPLIED</tt> <br>
<tt> arch
CDATA #IMPLIED</tt> <br>
<tt> ws
CDATA #IMPLIED</tt> <br>
<tt> nl
CDATA #IMPLIED</tt><br>
<tt> patch </tt><tt>
(true | false) "false"</tt><br>
<tt> ></tt> </p>
<p><tt><!ELEMENT archive EMPTY></tt> <br>
<tt><!ATTLIST archive</tt> <br>
<tt> path
CDATA #REQUIRED</tt> <br>
<tt> url
CDATA #REQUIRED</tt> <br>
<tt>></tt> </p>
<p><tt><!ELEMENT category EMPTY></tt> <br>
<tt><!ATTLIST category</tt> <br>
<tt> name
CDATA #REQUIRED</tt> <br>
<tt>></tt> </p>
<p><tt><!ELEMENT category-def (description?)></tt> <br>
<tt><!ATTLIST category-def</tt> <br>
<tt> name
CDATA #REQUIRED</tt> <br>
<tt> label
CDATA #REQUIRED</tt> <br>
<tt>></tt> </p>
<p>The element and attribute definitions are as follows: </p>
<ul>
<li> <site> - defines the site map</li>
<ul>
<li> type - optional site type specification. The value refers to a
type string registered via the <a href="#Framework">install framework</a>
extension point. If not specified, the type is assumed to be the default
Eclipse site type (as specified in this document).</li>
<li> url - optional URL defining the update site baseline URL (used
to determine individual <feature> and <archive> location).
Can be relative or absolute. If relative, is relative to site.xml. If not
specified, the default is the URL location of the site.xml file.</li>
</ul>
<li> <description> - brief description as simple text. Intended
to be translated.</li>
<ul>
<li> url - optional URL for the full description as HTML. The URL can
be specified as absolute of relative. If relative, If relative, is relative
to site.xml.</li>
<br>
Note, that for NL handling the URL value should be separated to allow
alternate URLs to be specified for each national language.
</ul>
<li> <feature> - identifies referenced feature archive</li>
<ul>
<li> type - optional feature type specification. The value refers to
a type string registered via the <a href="#Framework">install framework</a>
extension point. If not specified, the type is assumed to be the default
feature type for the site. If the site type is the default Eclipse site
type, the default feature type is the packaged feature type (as specified
in this document).</li>
<li> id - optional feature identifier. The information is used as
a performance optimization to speed up searches for features. Must match
the identifier specified in the feature.xml of the referenced archive (the
url attribute). If specified, the version attribute must also be specified.</li>
<li> version - optional feature version. The information is used as
a performance optimization to speed up searches for features. Must match
the version specified in the feature.xml of the referenced archive (the
url attribute). If specified, the id attribute must also be specified.</li>
<li> url - required URL reference to the feature archive. Can be relative
or absolute. If relative, it is relative to the location of the site.xml
file. <b>Note</b>: the default site implementation allows features
to be accessed without being explicitly declared using a <feature> entry.
By default, an undeclared features reference is interpreted as "features/<id>_<version>.jar"</li>
<li>label - optional feature label. The value is used for optimization
when browsing the site from the update manager. Intended to be translated.<br>
</li>
<li> os - optional operating system specification. A comma-separated
list of os designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt>
. Indicates this feature should only be installed on one of the specified
os systems. If this attribute is "*", 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).</li>
<li> arch - optional machine architecture specification. A comma-separated
list of architecture designators defined by Eclipse (see Javadoc for <tt>
org.eclipse.core.boot.BootLoader)</tt>. Indicates this feature should only
be installed on one of the specified systems. If this attribute is
"*", 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).</li>
<li> ws - optional windowing system specification. A comma-separated
list of ws designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt>
. Indicates this feature should only be installed on one of the specified
ws systems. If this attribute is "*", 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).</li>
<li> 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 "*", 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).</li>
<li>patch - optional specification indicating if this feature is a
patch. Default is "false". </li>
</ul>
<li> <archive> - identifies referenced "storage" archive (the
actual files referenced via the <tt><plugin></tt> or <tt><data></tt>
elements in the feature manifest). The site simply manages archives as
a path-to-URL map. The default Eclipse site implementation does not require
the <archive> section to be included in the site map (site.xml). Any
archive reference not explicitly defined as part of an <archive> section
is assumed to be mapped to a url in the form "<archivePath>" relative
to the location of the site.xml file.</li>
<ul>
<li> path - required archive path identifier. This is a string that
is determined by the <a href="#Feature_Archive_Mapping_Id_To_Path">feature</a>
referencing this archive and is not otherwise interpreted by the site (other
than as a lookup token).</li>
<li> url - required URL reference to the archive. Can be relative
or absolute. If relative, it is relative to the location of the site.xml
file.</li>
</ul>
<li> <category-def> - an optional definition of a category that
can be used by installation and update support to hierarchicaly organize
features</li>
<ul>
<li> name - category name. Is specified as a path of name tokens separated
by /</li>
<li> label - displayable label. Intended to be translated.</li>
</ul>
<li> <category> - actual category specification for a feature
entry</li>
<ul>
name - category name
</ul>
</ul>
Note, that in general the feature.xml manifest documents should
specify UTF-8 encoding. For example
<p><tt><?xml version="1.0" encoding="UTF-8"?></tt> </p>
<p>Translatable text contained in the site.xml can be separated into site<_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). The property bundles are located relative to the site.xml
location. </p>
<h3> <a name="Default_Site_Layout"></a> Default Site Layout</h3>
<tt><site root>/</tt> <br>
<tt> site.xml</tt> <br>
<tt> features/</tt> <br>
<tt> feature archives
(eg. org.eclipse.javatools_1.0.1.jar)</tt> <br>
<tt> <featureId>_<featureVersion>/
(optional)</tt> <br>
<tt>
non-plug-in files for feature</tt> <br>
<tt> plugins/</tt> <br>
<tt> plug-in argives
(eg. org.eclipse.ui_1.0.3.jar)</tt>
<h3> <a name="Controlling_Access"></a> Controlling Access</h3>
The default Eclipse site implementation provides support for http access
with basic user authentication (userid and password).
<p>Custom access control mechanisms can be added to base Eclipse in one of
2 ways: </p>
<ul>
<li> by supplying server-side logic on the update server (eg. implementing
servlets that compute the site.xml map, and control access to individual
archives based on some user criteria)</li>
<li> by supplying a custom concrete implementation of the site object
(installed on the client machine, update server specified <tt><site
type=""></tt> ). The custom concrete site implementation, together with
any server-side logic support the required control mechanisms.</li>
</ul>
Eclipse provides an example demonstrating an implementation of an access
mechanism based on feature key files.
<h2> <a name="Eclipse_Install"></a> Eclipse Install</h2>
<h3> <a name="Default_Install_Layout"></a> Default Install Layout</h3>
<tt><install root>/</tt> <br>
<tt> install/</tt> <br>
<tt> features/</tt> <br>
<tt>
<featureId>_<version>/</tt> <br>
<tt>
feature.xml</tt> <br>
<tt>
other feature files</tt> <br>
<tt>
META-INF/</tt> <br>
<tt>
META-INF-ECLIPSE/</tt>
<p><tt> plugins/</tt> <br>
<tt> <pluginORfragmentId>_<version>/</tt>
<br>
<tt>
plugin.xml or fragment.xml</tt> <br>
<tt>
other plugin or fragment files</tt> <br>
<tt>
META_INF/</tt> </p>
<p><b>Implementation Note:</b> we will go back to the original design of
not splitting out fragments (ie. plugin and fragments go into the same install
location) </p>
<h3> <a name="Unmanaged_Plugins"></a> "Unmanaged" Plug-Ins</h3>
Eclipse supports a concept of "unmanaged" plug-ins. These are plug-ins
that were directly installed into the Eclipse file tree without being part
of a feature (eg. developer unzipping plug-in archive directly into the
Eclipse file tree).
<p>Eclipse runtime recognizes these plugins during startup and loads the
plug-in information into the runtime registry following the standard plug-in
binding rules. The update support also recognizes the presence of this new
plug-in, but since this plug-in is not part of any feature it cannot be updated
using the update support (hence "unmanaged"). Unmanaged plug-in that become
referenced by a feature as a result of some future installation or update
action become "managed" (can be updated as part of the feature). </p>
<p>Unmanaged plug-ins are not displayed as part of the installation and update
UI. </p>
<h3> <a name="Using_Native_Platform_Installers"></a> Using Native Platform
Installers</h3>
The Eclipse installation contains plugins that can be shared across
multiple features. When installing and uninstalling features using the Eclipse
installation and update support, these relationship are correctly maintained.
Only one copy of any version of a plug-in is used.
<p>However, when using native platform installers, performing native uninstall
creates problems because plug-ins would be removed without regard to any
sharing relationships. As a result, Eclipse <b>does not allow</b> plug-ins
to be installed using native installers into the shared installation tree.
Instead, native installers must establish their own installation root directory.
The subdirectory structure is the same as defined for base Eclipse. The
private root directory is logically linked into the shared Eclipse installation
via a link file installed by the native installer. The file path for the
link file is <tt><configRoot>/links/</tt>. The <tt><configRoot>
</tt> location is computed by Eclipse relative to the launch <a
href="#Multiple%20Launch%20Points"> configuration file</a> . By default,
this is the <tt>install/</tt> directory in the shared Eclipse installation
tree. </p>
<p>The name of the link file is not specified by Eclipse. The name is determined
by the native installer. To minimize the potential for naming collisions,
it is recommended that the file name contain the identifier and version
of the feature being installed by the native installer. For example, <tt><featureId>_<featureVersion>.properties</tt>
. The file content is in the form of a Java properties file, with the following
properties defined: </p>
<p><tt>path=[r|rw] install-path[,[r|rw] install-path]*</tt> </p>
<p>The property <tt>path</tt> is a comma-separated list of optionally annotated
install paths. The property value <tt>install-path</tt> is a full file
path to the installation directory root, specified in local OS format. The
optional annotation <tt>r</tt> or <tt>rw</tt> indicates whether Eclipse
update support should allow the specified location to be used for updates.
Default is to allow updates (w). </p>
<p>Eclipse does not manage the linked directories in any way. It simply detects
their existence by the presence of the link files, and includes the linked
plug-ins during the platform startup. The native installer is responsible
for uninstalling the link when the corresponding directory is removed. Eclipse
runtime ignores any links that cannot be resolved. <br>
</p>
<br>
<br>
<br>
<br>
<br>
</body>
</html>
| help@eclipse.org | ViewVC Help |
| Powered by ViewVC 1.0.3 |