platform-update-home/doc/eclipse_update_packaging.html
Parent Directory
| 
Revision Log
Revision 1.10 -
(download)
(as text)
(annotate)
Mon Dec 9 18:52:19 2002 UTC (6 years, 11 months ago) by celek
Branch: MAIN
Changes since 1.9: +1092 -1038 lines
Mon Dec 9 18:52:19 2002 UTC (6 years, 11 months ago) by celek
Branch: MAIN
Changes since 1.9: +1092 -1038 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: 12/09/2002 8:56AM - Version: 2.0.15</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.15<br>
</small>
<ul>
<li><small>added <site><feature> os,arch,nl,ws,patch tag</small><br>
</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 data that is part of the feature</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 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>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>
</body>
</html>
| help@eclipse.org | ViewVC Help |
| Powered by ViewVC 1.0.3 |