| 14 |
|
|
| 15 |
<h1> Eclipse Platform<br> |
<h1> Eclipse Platform<br> |
| 16 |
Update Packaging Conventions</h1> |
Update Packaging Conventions</h1> |
| 17 |
<font size="-1">Revision Date: 12/05/2002 3:30PM - Version: 2.0.14</font><br> |
<font size="-1">Revision Date: 12/09/2002 8:56AM - Version: 2.0.15</font><br> |
| 18 |
<a href="../../../../../hglegal.htm"><img src="ngibmcpy.gif" border="0" |
<a href="../../../../../hglegal.htm"><img src="ngibmcpy.gif" |
| 19 |
height="12" width="195"> |
border="0" height="12" width="195"> |
| 20 |
</a> |
</a> |
| 21 |
<p><b>Change History:</b> </p> |
<p><b>Change History:</b> </p> |
| 22 |
|
|
| 23 |
<ul> |
<ul> |
| 24 |
<li><small>2.0.14<br> |
<li><small>2.0.15<br> |
| 25 |
</small> |
</small> |
| 26 |
<ul> |
<ul> |
| 27 |
<li><small>added <site><feature> label tag</small><br> |
<li><small>added <site><feature> os,arch,nl,ws,patch tag</small><br> |
| 28 |
</li> |
</li> |
| 29 |
</ul> |
</ul> |
| 30 |
</li> |
</li> |
| 31 |
<li><font size="-1">2.0.13</font></li> |
<li><small>2.0.14<br> |
| 32 |
</ul> |
</small> |
| 33 |
<ul> |
<ul> |
| 34 |
|
<li><small>added <site><feature> label tag</small><br> |
| 35 |
|
</li> |
| 36 |
|
|
| 37 |
|
</ul> |
| 38 |
|
</li> |
| 39 |
|
<li><font size="-1">2.0.13</font> <small><br> |
| 40 |
|
</small> |
| 41 |
<ul> |
<ul> |
| 42 |
<li><small>added <includes name,optional,match,search_location</small> |
<li><small>added <includes name,optional,match,search_location</small> |
| 43 |
></li> |
></li> |
| 44 |
<li><small>added <import feature,patch></small></li> |
<li><small>added <import feature,patch></small></li> |
| 45 |
|
|
| 46 |
</ul> |
</ul> |
| 47 |
|
</li> |
| 48 |
|
|
| 49 |
|
</ul> |
| 50 |
|
|
| 51 |
|
<ul> |
| 52 |
<li><font size="-1">2.0.12</font></li> |
<li><font size="-1">2.0.12</font></li> |
| 53 |
|
|
| 54 |
<ul> |
<ul> |
| 126 |
<a href="#Introduction">Introduction</a> <br> |
<a href="#Introduction">Introduction</a> <br> |
| 127 |
<a href="#Changes_from_R1.0">Changes |
<a href="#Changes_from_R1.0">Changes |
| 128 |
from 1.0</a> <br> |
from 1.0</a> <br> |
| 129 |
<a href="#Concepts">Concepts</a> <br> |
<a href="#Concepts">Concepts</a> |
| 130 |
|
<br> |
| 131 |
<a href="#Framework">Framework</a> |
<a href="#Framework">Framework</a> |
| 132 |
<br> |
<br> |
| 133 |
<a href="#Packaging_Conventions">Packaging Conventions</a> <br> |
<a href="#Packaging_Conventions">Packaging Conventions</a> <br> |
| 135 |
Archive</a> <br> |
Archive</a> <br> |
| 136 |
<a href="#Plug-In_Archive">Plug-In |
<a href="#Plug-In_Archive">Plug-In |
| 137 |
Archive</a> <br> |
Archive</a> <br> |
| 138 |
<a href="#Packaging_NL">Packaging NL</a> |
<a href="#Packaging_NL">Packaging |
| 139 |
<br> |
NL</a> <br> |
| 140 |
<a |
<a |
| 141 |
href="#Translated_Feature_Information"> Translated Feature Information</a> |
href="#Translated_Feature_Information"> Translated Feature Information</a> |
| 142 |
<br> |
<br> |
| 155 |
<a |
<a |
| 156 |
href="#Packaging_Attribution_Information"> Custom Install Handling</a> |
href="#Packaging_Attribution_Information"> Custom Install Handling</a> |
| 157 |
<br> |
<br> |
| 158 |
<a href="#Security_Considerations">Security |
<a |
| 159 |
Considerations</a> <br> |
href="#Security_Considerations">Security Considerations</a> <br> |
| 160 |
<a href="#Update_Server">Update Server</a> <br> |
<a href="#Update_Server">Update Server</a> <br> |
| 161 |
<a href="#Site_Map">Site Map</a> <br> |
<a href="#Site_Map">Site Map</a> |
| 162 |
|
<br> |
| 163 |
<a href="#Default_Site_Layout">Default |
<a href="#Default_Site_Layout">Default |
| 164 |
Site Layout</a> <br> |
Site Layout</a> <br> |
| 165 |
<a href="#Controlling_Access">Controlling |
<a href="#Controlling_Access">Controlling |
| 186 |
<br> |
<br> |
| 187 |
In R2.0 Eclipse defines an extendable framework for installation and update, |
In R2.0 Eclipse defines an extendable framework for installation and update, |
| 188 |
allowing the support for alternate packaging and site management schemes. |
allowing the support for alternate packaging and site management schemes. |
| 189 |
R2.0 supplies a default concrete implementation of this framework. <li> <b> |
R2.0 supplies a default concrete implementation of this framework. <li> |
| 190 |
feature support</b></li> |
<b> feature support</b></li> |
| 191 |
<br> |
<br> |
| 192 |
In R2.0 the concept of a <i>component</i> and <i>configuration</i> is merged |
In R2.0 the concept of a <i>component</i> and <i>configuration</i> is merged |
| 193 |
into <i>feature</i>. Features define the packaging structure for a group of |
into <i>feature</i>. Features define the packaging structure for a group |
| 194 |
related plug-ins, plug-in fragments, and optionally non-plug-in files. Features |
of related plug-ins, plug-in fragments, and optionally non-plug-in files. |
| 195 |
are treated purely as an installation and packaging construct. They do not |
Features are treated purely as an installation and packaging construct. They |
| 196 |
play a role during Eclipse plug-in execution. Features do not nest. They |
do not play a role during Eclipse plug-in execution. Features do not nest. |
| 197 |
are simply an inclusive "manifest" of the plug-ins, fragments and other files |
They are simply an inclusive "manifest" of the plug-ins, fragments and other |
| 198 |
that make up that feature. If features are logically made up of plug-ins from |
files that make up that feature. If features are logically made up of plug-ins |
| 199 |
"sub-features", the top-level feature "manifest" must be fully resolved at |
from "sub-features", the top-level feature "manifest" must be fully resolved |
| 200 |
packaging time. <li> <b>default feature archive format</b></li> |
at packaging time. <li> <b>default feature archive format</b></li> |
| 201 |
<br> |
<br> |
| 202 |
R1.0 components were packaged as a single Java .jar containing the component |
R1.0 components were packaged as a single Java .jar containing the component |
| 203 |
manifest as well as the actual plug-in files. The problem with this approach |
manifest as well as the actual plug-in files. The problem with this approach |
| 204 |
is lack of granularity at download time. In R2.0, the feature archive consists |
is lack of granularity at download time. In R2.0, the feature archive consists |
| 205 |
of multiple separate .jars - one .jar per plug-in and fragment, plus one .jar |
of multiple separate .jars - one .jar per plug-in and fragment, plus one |
| 206 |
for the actual feature information. The Installation and Update support selectively |
.jar for the actual feature information. The Installation and Update support |
| 207 |
downloads only those jars required for the installation. <li> <b>site map</b></li> |
selectively downloads only those jars required for the installation. <li> |
| 208 |
|
<b>site map</b></li> |
| 209 |
<br> |
<br> |
| 210 |
Default Eclipse update server must contain a <i>site map</i> file (site.xml). |
Default Eclipse update server must contain a <i>site map</i> file (site.xml). |
| 211 |
This is an evolution of the R1.0 install.index support. The rationale for |
This is an evolution of the R1.0 install.index support. The rationale for |
| 212 |
using a structured site defined by the map rather than a "free form" web |
using a structured site defined by the map rather than a "free form" web |
| 213 |
site, is the ability to present a consistent installation experience for |
site, is the ability to present a consistent installation experience for the |
| 214 |
the user. Also, this provides the necessary structure for discovery of available |
user. Also, this provides the necessary structure for discovery of available |
| 215 |
updates. Additional support for "free form" browsing may be considered in |
updates. Additional support for "free form" browsing may be considered in |
| 216 |
future work. <li> <b>using native install/ uninstall</b></li> |
future work. <li> <b>using native install/ uninstall</b></li> |
| 217 |
<br> |
<br> |
| 219 |
built-in installation and update support. Some products may instead choose |
built-in installation and update support. Some products may instead choose |
| 220 |
to use native installer technology (eg. MSI, RPM, etc) to deliver Eclipse |
to use native installer technology (eg. MSI, RPM, etc) to deliver Eclipse |
| 221 |
features. However, native installers do not implement the required support |
features. However, native installers do not implement the required support |
| 222 |
for understanding the Eclipse installation structure. In particular, the native |
for understanding the Eclipse installation structure. In particular, the |
| 223 |
uninstallers will, by default, remove plug-in files that were installed using |
native uninstallers will, by default, remove plug-in files that were installed |
| 224 |
the native installer without regard to these plug-ins being needed by other |
using the native installer without regard to these plug-ins being needed |
| 225 |
features. As a result, features installed using native installers must be |
by other features. As a result, features installed using native installers |
| 226 |
written into private product-specific installation location and not the shared |
must be written into private product-specific installation location and not |
| 227 |
Eclipse installation location. The shared Eclipse is made aware of the produce-specific |
the shared Eclipse installation location. The shared Eclipse is made aware |
| 228 |
location via an installed "link file". <li> <b>custom install handling</b></li> |
of the produce-specific location via an installed "link file". <li> <b>custom |
| 229 |
|
install handling</b></li> |
| 230 |
<br> |
<br> |
| 231 |
In many cases the standard installation handling supplied by Eclipse is |
In many cases the standard installation handling supplied by Eclipse is |
| 232 |
not be sufficient to handle various custom requirements. To accommodate this, |
not be sufficient to handle various custom requirements. To accommodate this, |
| 246 |
<h3> <a name="Concepts"></a> Concepts</h3> |
<h3> <a name="Concepts"></a> Concepts</h3> |
| 247 |
<b>Plug-in</b> <br> |
<b>Plug-in</b> <br> |
| 248 |
Eclipse developers build plug-ins. Plug-ins are the base units of execution |
Eclipse developers build plug-ins. Plug-ins are the base units of execution |
| 249 |
recognized by the Eclipse runtime environment. In general, plug-ins are |
recognized by the Eclipse runtime environment. In general, plug-ins are not |
| 250 |
not exposed to users that select function during installation or update. |
exposed to users that select function during installation or update. The |
| 251 |
The reason is that plug-in boundaries are established by developers for development |
reason is that plug-in boundaries are established by developers for development |
| 252 |
reasons (like function reuse) and present the wrong level of granularity in |
reasons (like function reuse) and present the wrong level of granularity |
| 253 |
terms of what the user sees as the unit of function. |
in terms of what the user sees as the unit of function. |
| 254 |
<p>While plug-ins are being developed (ie. are frequently being changed), |
<p>While plug-ins are being developed (ie. are frequently being changed), |
| 255 |
their internal file structure will reflect what is convenient to the developer. |
their internal file structure will reflect what is convenient to the developer. |
| 256 |
This will generally depend on the particular development tool being used. |
This will generally depend on the particular development tool being used. |
| 263 |
|
|
| 264 |
<p>However, when the plug-in is ready to be packaged, it needs to be converted |
<p>However, when the plug-in is ready to be packaged, it needs to be converted |
| 265 |
to a form suitable for packaging and installation. Typically it means creation |
to a form suitable for packaging and installation. Typically it means creation |
| 266 |
of the runtime .jar(s) and removing any development-time files (source, |
of the runtime .jar(s) and removing any development-time files (source, exposed |
| 267 |
exposed .class files, etc). It also means updating the plugin.xml manifest |
.class files, etc). It also means updating the plugin.xml manifest with the |
| 268 |
with the formal plug-in version and reflecting the version in the plug-in |
formal plug-in version and reflecting the version in the plug-in directory |
| 269 |
directory name (see "Concurrent Plug-In Version Support" for details). </p> |
name (see "Concurrent Plug-In Version Support" for details). </p> |
| 270 |
|
|
| 271 |
<p><b>Plug-in Fragment</b> <br> |
<p><b>Plug-in Fragment</b> <br> |
| 272 |
Plug-in Fragments (or simply Fragments) allow independent packaging of certain |
Plug-in Fragments (or simply Fragments) allow independent packaging of |
| 273 |
aspects of the base plug-in. This includes (but may not be limited to) translated |
certain aspects of the base plug-in. This includes (but may not be limited |
| 274 |
resources for the plug-in, OS-specific or windowing-system-specific code. |
to) translated resources for the plug-in, OS-specific or windowing-system-specific |
| 275 |
At runtime, fragments are logically merged into the base plug-in. From a packaging |
code. At runtime, fragments are logically merged into the base plug-in. |
| 276 |
point of view, the install and update support does not really differentiate |
From a packaging point of view, the install and update support does not really |
| 277 |
between plug-ins and their related fragments. </p> |
differentiate between plug-ins and their related fragments. </p> |
| 278 |
|
|
| 279 |
<p><b>Feature</b> <br> |
<p><b>Feature</b> <br> |
| 280 |
A feature is an installation packaging mechanism used to define a group |
A feature is an installation packaging mechanism used to define a group |
| 281 |
of versioned plug-ins and/or plug-in fragments plus non-plug-in files that |
of versioned plug-ins and/or plug-in fragments plus non-plug-in files that |
| 282 |
is used to deliver some user function. A feature can also include other features. |
is used to deliver some user function. A feature can also include other features. |
| 283 |
Features are exposed to users as part of the packaging and installation process, |
Features are exposed to users as part of the packaging and installation |
| 284 |
because they represent a unit of function selection. Features also represent |
process, because they represent a unit of function selection. Features also |
| 285 |
a unit of installation. Features carry a version identifier.</p> |
represent a unit of installation. Features carry a version identifier.</p> |
| 286 |
|
|
| 287 |
<p>Features are packaged as a feature archive, referencing the required plug-ins, |
<p>Features are packaged as a feature archive, referencing the required plug-ins, |
| 288 |
plug-in fragments and optional non-plug-in files. The feature archives are |
plug-in fragments and optional non-plug-in files. The feature archives are |
| 289 |
placed on an update server for download and installation by the Eclipse update |
placed on an update server for download and installation by the Eclipse |
| 290 |
manager, or they can be used as the input into a formal packaging process |
update manager, or they can be used as the input into a formal packaging |
| 291 |
using one of the "traditional" installer technologies. The format of the feature |
process using one of the "traditional" installer technologies. The format |
| 292 |
archive is described later. </p> |
of the feature archive is described later. </p> |
| 293 |
|
|
| 294 |
<h3> <a name="Framework"></a> Framework</h3> |
<h3> <a name="Framework"></a> Framework</h3> |
| 295 |
The 2.0 installation and update support is provided as a framework that |
The 2.0 installation and update support is provided as a framework that |
| 341 |
|
|
| 342 |
<h3> <a name="Feature_Archive"></a> Feature Archive</h3> |
<h3> <a name="Feature_Archive"></a> Feature Archive</h3> |
| 343 |
The feature packaging information is placed into a separate Java .jar. |
The feature packaging information is placed into a separate Java .jar. |
| 344 |
Standard Java jar facilities are used for constructing feature archives. |
Standard Java jar facilities are used for constructing feature archives. Feature |
| 345 |
Feature archives reference separately packaged plug-in archives (see next |
archives reference separately packaged plug-in archives (see next section) |
| 346 |
section) and non-plug-in files. |
and non-plug-in files. |
| 347 |
<p>Features are identified using a structured identifier based on the provider |
<p>Features are identified using a structured identifier based on the provider |
| 348 |
internet domain name. For example, organization eclipse.org may produce |
internet domain name. For example, organization eclipse.org may produce feature |
| 349 |
feature org.eclipse.javatooling. The character set used for feature identifiers |
org.eclipse.javatooling. The character set used for feature identifiers is |
| 350 |
is as specified for plug-in identifiers (see reference information describing |
as specified for plug-in identifiers (see reference information describing |
| 351 |
the plug-in manifest). </p> |
the plug-in manifest). </p> |
| 352 |
|
|
| 353 |
<p>The recommended convention for naming the feature archives is <br> |
<p>The recommended convention for naming the feature archives is <br> |
| 378 |
|
|
| 379 |
<p><tt><?xml encoding="ISO-8859-1"?></tt> </p> |
<p><tt><?xml encoding="ISO-8859-1"?></tt> </p> |
| 380 |
|
|
| 381 |
<p><tt><!ELEMENT feature (install-handler?, description?, copyright?, |
<p><tt><!ELEMENT feature (install-handler?, description?, copyright?, license?, |
| 382 |
license?, url?, includes*, requires?, plugin*, data*)></tt> <br> |
url?, includes*, requires?, plugin*, data*)></tt> <br> |
| 383 |
<tt><!ATTLIST feature</tt> <br> |
<tt><!ATTLIST feature</tt> <br> |
| 384 |
<tt> id |
<tt> id |
| 385 |
CDATA #REQUIRED</tt> <br> |
CDATA #REQUIRED</tt> <br> |
| 461 |
<tt> optional </tt><tt> |
<tt> optional </tt><tt> |
| 462 |
(true | false) "false"</tt><tt> <br> |
(true | false) "false"</tt><tt> <br> |
| 463 |
</tt><tt> match |
</tt><tt> match |
| 464 |
(perfect | equivalent | compatible | greaterOrEqual) |
(perfect | equivalent | compatible | greaterOrEqual) "compatible"</tt><tt> |
| 465 |
"compatible"</tt><tt> </tt><br> |
</tt><br> |
| 466 |
<tt> search_location </tt><tt>(</tt><font |
<tt> search_location </tt><tt>(</tt><font |
| 467 |
color="#000000"><tt> root | self | both) "root"</tt></font><br> |
color="#000000"><tt> root | self | both) "root"</tt></font><br> |
| 468 |
<tt>></tt> </p> |
<tt>></tt> </p> |
| 476 |
<tt> feature CDATA #IMPLIED</tt><br> |
<tt> feature CDATA #IMPLIED</tt><br> |
| 477 |
<tt> version CDATA |
<tt> version CDATA |
| 478 |
#IMPLIED</tt> <br> |
#IMPLIED</tt> <br> |
| 479 |
<tt> match (perfect |
<tt> match |
| 480 |
| equivalent | compatible | greaterOrEqual) "compatible"</tt> <br> |
(perfect | equivalent | compatible | greaterOrEqual) "compatible"</tt> <br> |
| 481 |
<tt> patch </tt><tt> |
<tt> patch </tt><tt> |
| 482 |
(true | false) "false"</tt><tt> </tt><tt><br> |
(true | false) "false"</tt><tt> </tt><tt><br> |
| 483 |
></tt><br> |
></tt><br> |
| 530 |
<li> label - optional displayable label (name). Intended to be translated.</li> |
<li> label - optional displayable label (name). Intended to be translated.</li> |
| 531 |
<li> provider-name - optional display label identifying the organization |
<li> provider-name - optional display label identifying the organization |
| 532 |
providing this component. Intended to be translated.</li> |
providing this component. Intended to be translated.</li> |
| 533 |
<li> image - optional image to use when displaying information about the |
<li> image - optional image to use when displaying information about |
| 534 |
feature. Specified relative to the feature.xml.</li> |
the feature. Specified relative to the feature.xml.</li> |
| 535 |
<li> os - optional operating system specification. A comma-separated list |
<li> os - optional operating system specification. A comma-separated |
| 536 |
of os designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt> |
list of os designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt> |
| 537 |
. Indicates this feature should only be installed on one of the specified |
. Indicates this feature should only be installed on one of the specified |
| 538 |
os systems. If this attribute is not specified, the feature can be installed |
os systems. If this attribute is not specified, the feature can be installed |
| 539 |
on all systems (portable implementation). This information is used as a |
on all systems (portable implementation). This information is used as a hint |
| 540 |
hint by the installation and update support (user can force installation |
by the installation and update support (user can force installation of feature |
| 541 |
of feature regardless of this setting).</li> |
regardless of this setting).</li> |
| 542 |
<li> arch - optional machine architecture specification. A comma-separated |
<li> arch - optional machine architecture specification. A comma-separated |
| 543 |
list of architecture designators defined by Eclipse (see Javadoc for <tt> |
list of architecture designators defined by Eclipse (see Javadoc for <tt> |
| 544 |
org.eclipse.core.boot.BootLoader)</tt>. Indicates this feature should only |
org.eclipse.core.boot.BootLoader)</tt>. Indicates this feature should only |
| 546 |
the feature can be installed on all systems (portable implementation). This |
the feature can be installed on all systems (portable implementation). This |
| 547 |
information is used as a hint by the installation and update support (user |
information is used as a hint by the installation and update support (user |
| 548 |
can force installation of feature regardless of this setting).</li> |
can force installation of feature regardless of this setting).</li> |
| 549 |
<li> ws - optional windowing system specification. A comma-separated list |
<li> ws - optional windowing system specification. A comma-separated |
| 550 |
of ws designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt> |
list of ws designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt> |
| 551 |
. Indicates this feature should only be installed on one of the specified |
. Indicates this feature should only be installed on one of the specified |
| 552 |
ws systems. If this attribute is not specified, the feature can be installed |
ws systems. If this attribute is not specified, the feature can be installed |
| 553 |
on all systems (portable implementation). This information is used as a |
on all systems (portable implementation). This information is used as a hint |
| 554 |
hint by the installation and update support (user can force installation |
by the installation and update support (user can force installation of feature |
| 555 |
of feature regardless of this setting).</li> |
regardless of this setting).</li> |
| 556 |
<li> nl - optional locale specification. A comma-separated list of locale |
<li> nl - optional locale specification. A comma-separated list of locale |
| 557 |
designators defined by Java. Indicates this feature should only be installed |
designators defined by Java. Indicates this feature should only be installed |
| 558 |
on a system running with a compatible locale (using Java locale-matching rules). |
on a system running with a compatible locale (using Java locale-matching |
| 559 |
If this attribute is not specified, the feature can be installed on all systems |
rules). If this attribute is not specified, the feature can be installed |
| 560 |
(language-neutral implementation). This information is used as a hint by |
on all systems (language-neutral implementation). This information is used |
| 561 |
the installation and update support (user can force installation of feature |
as a hint by the installation and update support (user can force installation |
| 562 |
regardless of this setting).</li> |
of feature regardless of this setting).</li> |
| 563 |
<li> colocation-affinity - optional reference to another feature identifier |
<li> colocation-affinity - optional reference to another feature identifier |
| 564 |
used to select the default installation location for this feature. When |
used to select the default installation location for this feature. When this |
| 565 |
this feature is being installed as a new feature (no other versions of it |
feature is being installed as a new feature (no other versions of it are |
| 566 |
are installed), an attempt is made to install this feature in the same installation |
installed), an attempt is made to install this feature in the same installation |
| 567 |
location as the referenced feature.</li> |
location as the referenced feature.</li> |
| 568 |
<li> primary - optional indication specifying whether this feature can |
<li> primary - optional indication specifying whether this feature can |
| 569 |
be used as a <a href="#Dominant_Feature">primary feature</a> . Default if |
be used as a <a href="#Dominant_Feature">primary feature</a> . Default if |
| 581 |
<li> library - optional .jar library containing the install handler classes. |
<li> library - optional .jar library containing the install handler classes. |
| 582 |
If specified, the referenced .jar must be contained in the feature archive. |
If specified, the referenced .jar must be contained in the feature archive. |
| 583 |
It is specified as a path within the feature archive, relative to the feature.xml |
It is specified as a path within the feature archive, relative to the feature.xml |
| 584 |
entry. If not specified, the feature archive itself is used to load the |
entry. If not specified, the feature archive itself is used to load the install |
| 585 |
install handler classes. This attribute is only interpreted if <i>class</i> |
handler classes. This attribute is only interpreted if <i>class</i> attribute |
| 586 |
attribute is also specified</li> |
is also specified</li> |
| 587 |
<li> handler - optional identifier of the install handler. The value is |
<li> handler - optional identifier of the install handler. The value |
| 588 |
interpreted depending on the value of the <i>library</i> attribute. If <i> |
is interpreted depending on the value of the <i>library</i> attribute. If |
| 589 |
library</i> is specified, the value is interpreted as a fully qualified |
<i> library</i> is specified, the value is interpreted as a |
| 590 |
name of a class contained in the specified <i>library</i>. If <i>library</i> |
fully qualified name of a class contained in the specified <i>library</i>. |
| 591 |
is not specified, the value is is interpreted as an extension identifier |
If <i>library</i> is not specified, the value is is interpreted as an extension |
| 592 |
of an extension registered in the <i>org.eclipse.update.installHandlers</i> |
identifier of an extension registered in the <i>org.eclipse.update.installHandlers</i> |
| 593 |
extension point. In either case, the resulting class must implement the |
extension point. In either case, the resulting class must implement the |
| 594 |
<i> IInstallHandler</i> interface. The class is dynamically loaded |
<i> IInstallHandler</i> interface. The class is dynamically loaded and |
| 595 |
and called at specific points during feature processing. The handler has |
called at specific points during feature processing. The handler has visibility |
| 596 |
visibility to the API classes from the update plug-in, and Eclipse plug-ins |
to the API classes from the update plug-in, and Eclipse plug-ins required |
| 597 |
required by the update plugin.</li> |
by the update plugin.</li> |
| 598 |
|
|
| 599 |
</ul> |
</ul> |
| 600 |
<li> <description> - brief component description as simple text. |
<li> <description> - brief component description as simple text. |
| 601 |
Intended to be translated.</li> |
Intended to be translated.</li> |
| 602 |
|
|
| 603 |
<ul> |
<ul> |
| 604 |
<li> url - optional URL for the full description as HTML. The URL can be |
<li> url - optional URL for the full description as HTML. The URL can |
| 605 |
specified as absolute of relative. If relative, it is assumed to be relative |
be specified as absolute of relative. If relative, it is assumed to be relative |
| 606 |
to (and packaged in) the feature archive. Note, that for NL handling the URL |
to (and packaged in) the feature archive. Note, that for NL handling the |
| 607 |
value should be separated to allow alternate URLs to be specified for each |
URL value should be separated to allow alternate URLs to be specified for |
| 608 |
national language.</li> |
each national language.</li> |
| 609 |
|
|
| 610 |
</ul> |
</ul> |
| 611 |
<li> <copyright> - feature copyright as simple text. Intended to |
<li> <copyright> - feature copyright as simple text. Intended to |
| 612 |
be translated.</li> |
be translated.</li> |
| 613 |
|
|
| 614 |
<ul> |
<ul> |
| 615 |
<li> url - optional URL for the full description as HTML. The URL can be |
<li> url - optional URL for the full description as HTML. The URL can |
| 616 |
specified as absolute of relative. If relative, it is assumed to be relative |
be specified as absolute of relative. If relative, it is assumed to be relative |
| 617 |
to (and packaged in) the feature archive. Note, that for NL handling the URL |
to (and packaged in) the feature archive. Note, that for NL handling the |
| 618 |
value should be separated to allow alternate URLs to be specified for each |
URL value should be separated to allow alternate URLs to be specified for |
| 619 |
national language.</li> |
each national language.</li> |
| 620 |
|
|
| 621 |
</ul> |
</ul> |
| 622 |
<li> <license> - feature "click-through" license as simple text. |
<li> <license> - feature "click-through" license as simple text. |
| 623 |
Intended to be translated. It is displayed in a standard dialog with [Accept] |
Intended to be translated. It is displayed in a standard dialog with [Accept] |
| 624 |
[Reject] actions during the download/ installation process. Note, that click-through |
[Reject] actions during the download/ installation process. Note, that click-through |
| 625 |
license must be specified for any feature that will be selected for installation |
license must be specified for any feature that will be selected for installation |
| 626 |
or update using the Eclipse update manager. When using nested features, |
or update using the Eclipse update manager. When using nested features, only |
| 627 |
only the nesting parent (ie. the feature selected for installation or update) |
the nesting parent (ie. the feature selected for installation or update) must |
| 628 |
must have click-through license text defined. The license text is required |
have click-through license text defined. The license text is required even |
| 629 |
even if the optional <i>url</i> attribute is specified.</li> |
if the optional <i>url</i> attribute is specified.</li> |
| 630 |
|
|
| 631 |
<ul> |
<ul> |
| 632 |
<li> url - optional URL for the full description as HTML. The URL can be |
<li> url - optional URL for the full description as HTML. The URL can |
| 633 |
specified as absolute of relative. If relative, it is assumed to be relative |
be specified as absolute of relative. If relative, it is assumed to be relative |
| 634 |
to (and packaged in) the feature archive. Note, that for NL handling the URL |
to (and packaged in) the feature archive. Note, that for NL handling the |
| 635 |
value should be separated to allow alternate URLs to be specified for each |
URL value should be separated to allow alternate URLs to be specified for |
| 636 |
national language. Note, that the "content" of this URL is <b>not</b> what |
each national language. Note, that the "content" of this URL is <b>not</b> |
| 637 |
is presented as the click-through license during installation processing. |
what is presented as the click-through license during installation processing. |
| 638 |
The click-through license is the actual value of the <i><license></i> |
The click-through license is the actual value of the <i><license></i> |
| 639 |
element (eg. <tt><license>click through text</license></tt>)</li> |
element (eg. <tt><license>click through text</license></tt>)</li> |
| 640 |
|
|
| 682 |
consideration, while <samp>greaterOrEqual</samp> simply allows any version |
consideration, while <samp>greaterOrEqual</samp> simply allows any version |
| 683 |
that is more recent or identical to the one specified).</li> |
that is more recent or identical to the one specified).</li> |
| 684 |
<li>search_location - optional. Indicates whether the "New Updates" |
<li>search_location - optional. Indicates whether the "New Updates" |
| 685 |
action should search the update location determined by the nesting root feature |
action should search the update location determined by the nesting root |
| 686 |
(<tt>root</tt>, is the default), or the location defined by the nested feature |
feature (<tt>root</tt>, is the default), or the location defined by the |
| 687 |
(<tt>self</tt>), or search both (<tt>both</tt>) in that order (root first, |
nested feature (<tt>self</tt>), or search both (<tt>both</tt>) in that order |
| 688 |
self if nothing is found).</li> |
(root first, self if nothing is found).</li> |
| 689 |
|
|
| 690 |
</ul> |
</ul> |
| 691 |
<li> <requires> - optional feature dependency information. Is expressed |
<li> <requires> - optional feature dependency information. Is expressed |
| 702 |
are specified, plugin takes precedence upon feature. Feature or plugin must |
are specified, plugin takes precedence upon feature. Feature or plugin must |
| 703 |
be specified.</li> |
be specified.</li> |
| 704 |
<li> version - optional plug-in/feature version specification</li> |
<li> version - optional plug-in/feature version specification</li> |
| 705 |
<li>patch - optional specification indicating if this feature is a |
<li>patch - optional specification indicating if this feature is |
| 706 |
patch of the dependant feature. Default is "false". If patch is true, version |
a patch of the dependant feature. Default is "false". If patch is true, |
| 707 |
must be specified. If patch is true, only feature must be specified. If patch |
version must be specified. If patch is true, only feature must be specified. |
| 708 |
is true, and match is specified, it must be 'perfect'.<br> |
If patch is true, and match is specified, it must be 'perfect'.<br> |
| 709 |
</li> |
</li> |
| 710 |
<li> match - optional matching rule. Valid values and processing are as |
<li> match - optional matching rule. Valid values and processing are |
| 711 |
follows:</li> |
as follows:</li> |
| 712 |
|
|
| 713 |
<ul> |
<ul> |
| 714 |
<li> if version attribute is not specified, the match attribute (if specified) |
<li> if version attribute is not specified, the match attribute (if specified) |
| 720 |
</li> |
</li> |
| 721 |
<li> <b><i>perfect</i></b> - dependent plug-in version must match exactly |
<li> <b><i>perfect</i></b> - dependent plug-in version must match exactly |
| 722 |
the specified version.</li> |
the specified version.</li> |
| 723 |
<li> <b><i>equivalent</i></b> - dependent plug-in version must be at least |
<li> <b><i>equivalent</i></b> - dependent plug-in version must be at |
| 724 |
at the version specified, or at a higher service level (major and minor version |
least at the version specified, or at a higher service level (major and |
| 725 |
levels must equal the specified version).</li> |
minor version levels must equal the specified version).</li> |
| 726 |
<li> <b><i>compatible</i></b> - dependent plug-in version must be at least |
<li> <b><i>compatible</i></b> - dependent plug-in version must be at |
| 727 |
at the version specified, or at a higher service level or minor level (major |
least at the version specified, or at a higher service level or minor level |
| 728 |
version level must equal the specified version).</li> |
(major version level must equal the specified version).</li> |
| 729 |
<li> <b><i>greaterOrEqual</i></b> - dependent plug-in version must be |
<li> <b><i>greaterOrEqual</i></b> - dependent plug-in version must be |
| 730 |
at least at the version specified, or at a higher service, minor or major |
at least at the version specified, or at a higher service, minor or major |
| 731 |
level.</li> |
level.</li> |
| 740 |
<ul> |
<ul> |
| 741 |
<li> id - required plug-in identifier (from plugin.xml)</li> |
<li> id - required plug-in identifier (from plugin.xml)</li> |
| 742 |
<li> version - required plug-in version (from plugin.xml)</li> |
<li> version - required plug-in version (from plugin.xml)</li> |
| 743 |
<li> fragment - optional specification indicating if this entry is a plug-in |
<li> fragment - optional specification indicating if this entry is a |
| 744 |
fragment. Default is "false"</li> |
plug-in fragment. Default is "false"</li> |
| 745 |
<li> os - optional operating system specification. A comma-separated list |
<li> os - optional operating system specification. A comma-separated |
| 746 |
of os designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt> |
list of os designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt> |
| 747 |
. Indicates this entry should only be installed on one of the specified os |
. Indicates this entry should only be installed on one of the specified |
| 748 |
systems. If this attribute is not specified, the entry can be installed |
os systems. If this attribute is not specified, the entry can be installed |
| 749 |
on all systems (portable implementation). This information is used as a hint |
on all systems (portable implementation). This information is used as a hint |
| 750 |
by the installation and update support (user can force installation of entry |
by the installation and update support (user can force installation of entry |
| 751 |
regardless of this setting).</li> |
regardless of this setting).</li> |
| 756 |
the feature can be installed on all systems (portable implementation). This |
the feature can be installed on all systems (portable implementation). This |
| 757 |
information is used as a hint by the installation and update support (user |
information is used as a hint by the installation and update support (user |
| 758 |
can force installation of feature regardless of this setting).</li> |
can force installation of feature regardless of this setting).</li> |
| 759 |
<li> ws - optional windowing system specification. A comma-separated list |
<li> ws - optional windowing system specification. A comma-separated |
| 760 |
of ws designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt> |
list of ws designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt> |
| 761 |
. Indicates this entry should only be installed on one of the specified ws |
. Indicates this entry should only be installed on one of the specified |
| 762 |
systems. If this attribute is not specified, the entry can be installed |
ws systems. If this attribute is not specified, the entry can be installed |
| 763 |
on all systems (portable implementation). This information is used as a hint |
on all systems (portable implementation). This information is used as a hint |
| 764 |
by the installation and update support (user can force installation of entry |
by the installation and update support (user can force installation of entry |
| 765 |
regardless of this setting).</li> |
regardless of this setting).</li> |
| 766 |
<li> nl - optional locale specification. A comma-separated list of locale |
<li> nl - optional locale specification. A comma-separated list of locale |
| 767 |
designators defined by Java. Indicates this entry should only be installed |
designators defined by Java. Indicates this entry should only be installed |
| 768 |
on a system running with a compatible locale (using Java locale-matching rules). |
on a system running with a compatible locale (using Java locale-matching |
| 769 |
If this attribute is not specified, the entry can be installed on all systems |
rules). If this attribute is not specified, the entry can be installed on |
| 770 |
(language-neutral implementation). This information is used as a hint by |
all systems (language-neutral implementation). This information is used as |
| 771 |
the installation and update support (user can force installation of entry |
a hint by the installation and update support (user can force installation |
| 772 |
regardless of this setting).</li> |
of entry regardless of this setting).</li> |
| 773 |
<li> download-size - optional hint supplied by the feature packager, indicating |
<li> download-size - optional hint supplied by the feature packager, |
| 774 |
the download size in KBytes of the referenced plug-in archive. If not specified, |
indicating the download size in KBytes of the referenced plug-in archive. |
| 775 |
the download size is not known (<b>Implementation Note:</b> the implementation |
If not specified, the download size is not known (<b>Implementation Note:</b> |
| 776 |
needs to distinguish between "not known" and 0 size)</li> |
the implementation needs to distinguish between "not known" and 0 size)</li> |
| 777 |
<li> install-size - optional hint supplied by the feature packager, indicating |
<li> install-size - optional hint supplied by the feature packager, indicating |
| 778 |
the install size in KBytes of the referenced plug-in archive. If not specified, |
the install size in KBytes of the referenced plug-in archive. If not specified, |
| 779 |
the install size is not known (<b>Implementation Note:</b> the implementation |
the install size is not known (<b>Implementation Note:</b> the implementation |
| 784 |
|
|
| 785 |
<ul> |
<ul> |
| 786 |
<li> id - required data identifier in the form of a relative path.</li> |
<li> id - required data identifier in the form of a relative path.</li> |
| 787 |
<li> os - optional operating system specification. A comma-separated list |
<li> os - optional operating system specification. A comma-separated |
| 788 |
of os designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt> |
list of os designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt> |
| 789 |
. Indicates this entry should only be installed on one of the specified os |
. Indicates this entry should only be installed on one of the specified |
| 790 |
systems. If this attribute is not specified, the entry can be installed |
os systems. If this attribute is not specified, the entry can be installed |
| 791 |
on all systems (portable implementation). This information is used as a hint |
on all systems (portable implementation). This information is used as a hint |
| 792 |
by the installation and update support (user can force installation of entry |
by the installation and update support (user can force installation of entry |
| 793 |
regardless of this setting).</li> |
regardless of this setting).</li> |
| 798 |
the feature can be installed on all systems (portable implementation). This |
the feature can be installed on all systems (portable implementation). This |
| 799 |
information is used as a hint by the installation and update support (user |
information is used as a hint by the installation and update support (user |
| 800 |
can force installation of feature regardless of this setting).</li> |
can force installation of feature regardless of this setting).</li> |
| 801 |
<li> ws - optional windowing system specification. A comma-separated list |
<li> ws - optional windowing system specification. A comma-separated |
| 802 |
of ws designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt> |
list of ws designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt> |
| 803 |
. Indicates this entry should only be installed on one of the specified ws |
. Indicates this entry should only be installed on one of the specified |
| 804 |
systems. If this attribute is not specified, the entry can be installed |
ws systems. If this attribute is not specified, the entry can be installed |
| 805 |
on all systems (portable implementation). This information is used as a hint |
on all systems (portable implementation). This information is used as a hint |
| 806 |
by the installation and update support (user can force installation of entry |
by the installation and update support (user can force installation of entry |
| 807 |
regardless of this setting).</li> |
regardless of this setting).</li> |
| 808 |
<li> nl - optional locale specification. A comma-separated list of locale |
<li> nl - optional locale specification. A comma-separated list of locale |
| 809 |
designators defined by Java. Indicates this entry should only be installed |
designators defined by Java. Indicates this entry should only be installed |
| 810 |
on a system running with a compatible locale (using Java locale-matching rules). |
on a system running with a compatible locale (using Java locale-matching |
| 811 |
If this attribute is not specified, the entry can be installed on all systems |
rules). If this attribute is not specified, the entry can be installed on |
| 812 |
(language-neutral implementation). This information is used as a hint by |
all systems (language-neutral implementation). This information is used as |
| 813 |
the installation and update support (user can force installation of entry |
a hint by the installation and update support (user can force installation |
| 814 |
regardless of this setting).</li> |
of entry regardless of this setting).</li> |
| 815 |
<li> download-size - optional hint supplied by the feature packager, indicating |
<li> download-size - optional hint supplied by the feature packager, |
| 816 |
the download size in KBytes of the referenced data archive. If not specified, |
indicating the download size in KBytes of the referenced data archive. If |
| 817 |
the download size is not known (<b>Implementation Note:</b> the implementation |
not specified, the download size is not known (<b>Implementation Note:</b> |
| 818 |
needs to distinguish between "not known" and 0 size)</li> |
the implementation needs to distinguish between "not known" and 0 size)</li> |
| 819 |
<li> install-size - optional hint supplied by the feature packager, indicating |
<li> install-size - optional hint supplied by the feature packager, indicating |
| 820 |
the install size in KBytes of the referenced data archive. If not specified, |
the install size in KBytes of the referenced data archive. If not specified, |
| 821 |
the install size is not known (<b>Implementation Note:</b> the implementation |
the install size is not known (<b>Implementation Note:</b> the implementation |
| 839 |
" (for example, "f<tt>eatures/com.xyz.tools_2.3.1/examples.zip</tt>")</li> |
" (for example, "f<tt>eatures/com.xyz.tools_2.3.1/examples.zip</tt>")</li> |
| 840 |
|
|
| 841 |
</ul> |
</ul> |
| 842 |
Note, that in general the feature.xml manifest documents should specify |
Note, that in general the feature.xml manifest documents should |
| 843 |
UTF-8 encoding. For example |
specify UTF-8 encoding. For example |
| 844 |
<p><tt><?xml version="1.0" encoding="UTF-8"?></tt> </p> |
<p><tt><?xml version="1.0" encoding="UTF-8"?></tt> </p> |
| 845 |
|
|
| 846 |
<p>Translatable text contained in the feature.xml can be separated into feature<_locale>.properties |
<p>Translatable text contained in the feature.xml can be separated into feature<_locale>.properties |
| 866 |
<tt>org.eclipse.ui.nl_2.0.jar</tt> <br> |
<tt>org.eclipse.ui.nl_2.0.jar</tt> <br> |
| 867 |
<tt>my_plugin.jar</tt> </p> |
<tt>my_plugin.jar</tt> </p> |
| 868 |
|
|
| 869 |
<p>Internally, each plug-in archive packages all the relevant plug-in or |
<p>Internally, each plug-in archive packages all the relevant plug-in or fragment |
| 870 |
fragment files relative to its plug-in or fragment directory (but not including |
files relative to its plug-in or fragment directory (but not including the |
| 871 |
the directory path element). The archive has the following structure </p> |
directory path element). The archive has the following structure </p> |
| 872 |
|
|
| 873 |
<p><tt>plugin.xml *OR* fragment.xml</tt> <br> |
<p><tt>plugin.xml *OR* fragment.xml</tt> <br> |
| 874 |
<tt>other plug-in or feature files and subdirectories</tt> <br> |
<tt>other plug-in or feature files and subdirectories</tt> <br> |
| 883 |
|
|
| 884 |
<p>This mechanism cannot be used for translating the actual packaging information |
<p>This mechanism cannot be used for translating the actual packaging information |
| 885 |
that is part of the installation xml files. Consequently the standard Java |
that is part of the installation xml files. Consequently the standard Java |
| 886 |
translation conventions are used for the packaging information, and all |
translation conventions are used for the packaging information, and all necessary |
| 887 |
necessary translations must be available at the time the feature is packaged. |
translations must be available at the time the feature is packaged. </p> |
|
</p> |
|
| 888 |
|
|
| 889 |
<h4> <a name="Translated_Feature_Information"></a> Translated Feature Information</h4> |
<h4> <a name="Translated_Feature_Information"></a> Translated Feature Information</h4> |
| 890 |
<b>Note:</b> This section describes the conventions used for translating |
<b>Note:</b> This section describes the conventions used for translating |
| 905 |
value (following the %key) is used. </p> |
value (following the %key) is used. </p> |
| 906 |
|
|
| 907 |
<p>The property files are named as feature_<locale>.properties using |
<p>The property files are named as feature_<locale>.properties using |
| 908 |
the Java resource bundle naming conventions. Within the feature archive |
the Java resource bundle naming conventions. Within the feature archive .jar |
| 909 |
.jar they are placed in the same directory as their corresponding feature.xml |
they are placed in the same directory as their corresponding feature.xml file. |
| 910 |
file. </p> |
</p> |
| 911 |
|
|
| 912 |
<p><b>Implementation Note</b>: When accessing the resource bundles the Eclipse |
<p><b>Implementation Note</b>: When accessing the resource bundles the Eclipse |
| 913 |
installation and update code should create a class loader for accessing the |
installation and update code should create a class loader for accessing |
| 914 |
translated string. This way, the standard locale lookup algorithm implemented |
the translated string. This way, the standard locale lookup algorithm implemented |
| 915 |
by Java is automatically used. </p> |
by Java is automatically used. </p> |
| 916 |
|
|
| 917 |
<p><tt>ResourceBundle b;</tt> <br> |
<p><tt>ResourceBundle b;</tt> <br> |
| 926 |
</p> |
</p> |
| 927 |
|
|
| 928 |
<h4> <a name="Translated_Plug-In_Information"></a> Translated Plug-In Information</h4> |
<h4> <a name="Translated_Plug-In_Information"></a> Translated Plug-In Information</h4> |
| 929 |
No change from 1.0. Translated plug-in information should be packaged as |
No change from 1.0. Translated plug-in information should be packaged |
| 930 |
plug-in fragments. |
as plug-in fragments. |
| 931 |
<h3> <a name="Packaging_Target-Specific_Support"></a> Packaging Target-Specific |
<h3> <a name="Packaging_Target-Specific_Support"></a> Packaging Target-Specific |
| 932 |
Support</h3> |
Support</h3> |
| 933 |
No change from 1.0. Target-specific plug-in support (os, ws) should be |
No change from 1.0. Target-specific plug-in support (os, ws) should be |
| 954 |
during its processing. The install handler code has visibility to classes |
during its processing. The install handler code has visibility to classes |
| 955 |
from the installation and update support plug-in, and its prerequisite plug-ins. |
from the installation and update support plug-in, and its prerequisite plug-ins. |
| 956 |
|
|
| 957 |
<p><b>Implementation Note:</b> the detailed list of visible prerequisite |
<p><b>Implementation Note:</b> the detailed list of visible prerequisite plug-ins |
| 958 |
plug-ins is still evolving. It is expected to include <tt>org.eclipse.core.boot |
is still evolving. It is expected to include <tt>org.eclipse.core.boot </tt> |
| 959 |
</tt> and <tt>org.eclipse.core.runtime</tt> in all cases, plus <tt>org.eclipse.ui</tt> |
and <tt>org.eclipse.core.runtime</tt> in all cases, plus <tt>org.eclipse.ui</tt> |
| 960 |
and <tt>org.eclipse.swt</tt> when running with full workbench (ie. not "headless |
and <tt>org.eclipse.swt</tt> when running with full workbench (ie. not |
| 961 |
mode"). Also, it would be useful to always expose <tt>org.eclipse.core.ant</tt> |
"headless mode"). Also, it would be useful to always expose <tt>org.eclipse.core.ant</tt> |
| 962 |
so that build scripts can be used as part of the install handler implementation. |
so that build scripts can be used as part of the install handler implementation. |
| 963 |
</p> |
</p> |
| 964 |
|
|
| 982 |
other pre-install processing. On return this method indicates success |
other pre-install processing. On return this method indicates success |
| 983 |
(installation continues) or failure (installation is aborted).</li> |
(installation continues) or failure (installation is aborted).</li> |
| 984 |
<li> install-completion - the install handler is called after the feature |
<li> install-completion - the install handler is called after the feature |
| 985 |
information and the plug-ins were installed. It is expected to complete the |
information and the plug-ins were installed. It is expected to complete |
| 986 |
installation of any non-plug-in data that was part of the feature. On return |
the installation of any non-plug-in data that was part of the feature. On |
| 987 |
this method indicates success (returns custom install log) or failure (installation |
return this method indicates success (returns custom install log) or failure |
| 988 |
is aborted). On failure, the install handler is expected to perform any |
(installation is aborted). On failure, the install handler is expected to |
| 989 |
required cleanup.</li> |
perform any required cleanup.</li> |
| 990 |
<li> uninstall-initiated - the install handler is called when a feature |
<li> uninstall-initiated - the install handler is called when a feature |
| 991 |
is selected for removal, but before any of the standard uninstall processing |
is selected for removal, but before any of the standard uninstall processing |
| 992 |
has taken place. It is passed the custom install log created by the install |
has taken place. It is passed the custom install log created by the install |
| 996 |
by the install handler install-completion step.</li> |
by the install handler install-completion step.</li> |
| 997 |
|
|
| 998 |
</ul> |
</ul> |
| 999 |
Note, that as a general practice, install handlers should be provided in |
Note, that as a general practice, install handlers should be provided |
| 1000 |
their own jars (even though they could be just exposed in the feature archive |
in their own jars (even though they could be just exposed in the feature |
| 1001 |
jar). The jar should be signed, and sealed. |
archive jar). The jar should be signed, and sealed. |
| 1002 |
<h3> <a name="Security_Considerations"></a> Security Considerations</h3> |
<h3> <a name="Security_Considerations"></a> Security Considerations</h3> |
| 1003 |
The general approach is to use base Java jar signing for the feature and |
The general approach is to use base Java jar signing for the feature and |
| 1004 |
plug-in archive .jars. |
plug-in archive .jars. |
| 1028 |
(originator is trusted for this installation). |
(originator is trusted for this installation). |
| 1029 |
<h2> <a name="Update_Server"></a> Update Server</h2> |
<h2> <a name="Update_Server"></a> Update Server</h2> |
| 1030 |
The default Eclipse update server is any URL-accessible server. The default |
The default Eclipse update server is any URL-accessible server. The default |
| 1031 |
implementation assumes a fixed-layout server. The content of the server |
implementation assumes a fixed-layout server. The content of the server (in |
| 1032 |
(in terms of available features and plug-ins) is described in a site map |
terms of available features and plug-ins) is described in a site map file, |
| 1033 |
file, <i>site.xml</i>. This file can be manually maintained, or can be dynamically |
<i>site.xml</i>. This file can be manually maintained, or can be dynamically |
| 1034 |
computed by the server. |
computed by the server. |
| 1035 |
<h3> <a name="Site_Map"></a> Site Map</h3> |
<h3> <a name="Site_Map"></a> Site Map</h3> |
| 1036 |
The update server URL can be specified as a full URL to the site map file, |
The update server URL can be specified as a full URL to the site map file, |
| 1065 |
<tt> url |
<tt> url |
| 1066 |
CDATA #REQUIRED<br> |
CDATA #REQUIRED<br> |
| 1067 |
label CDATA #IMPLIED<br> |
label CDATA #IMPLIED<br> |
| 1068 |
></tt> </p> |
</tt><tt> os |
| 1069 |
|
CDATA #IMPLIED</tt> <br> |
| 1070 |
|
<tt> arch |
| 1071 |
|
CDATA #IMPLIED</tt> <br> |
| 1072 |
|
<tt> ws |
| 1073 |
|
CDATA #IMPLIED</tt> <br> |
| 1074 |
|
<tt> nl |
| 1075 |
|
CDATA #IMPLIED</tt><br> |
| 1076 |
|
<tt> patch </tt><tt> |
| 1077 |
|
(true | false) "false"</tt><br> |
| 1078 |
|
<tt> ></tt> </p> |
| 1079 |
|
|
| 1080 |
<p><tt><!ELEMENT archive EMPTY></tt> <br> |
<p><tt><!ELEMENT archive EMPTY></tt> <br> |
| 1081 |
<tt><!ATTLIST archive</tt> <br> |
<tt><!ATTLIST archive</tt> <br> |
| 1119 |
to be translated.</li> |
to be translated.</li> |
| 1120 |
|
|
| 1121 |
<ul> |
<ul> |
| 1122 |
<li> url - optional URL for the full description as HTML. The URL can be |
<li> url - optional URL for the full description as HTML. The URL can |
| 1123 |
specified as absolute of relative. If relative, If relative, is relative to |
be specified as absolute of relative. If relative, If relative, is relative |
| 1124 |
site.xml.</li> |
to site.xml.</li> |
| 1125 |
<br> |
<br> |
| 1126 |
Note, that for NL handling the URL value should be separated to allow alternate |
Note, that for NL handling the URL value should be separated to allow alternate |
| 1127 |
URLs to be specified for each national language. |
URLs to be specified for each national language. |
| 1132 |
<li> type - optional feature type specification. The value refers to a |
<li> type - optional feature type specification. The value refers to a |
| 1133 |
type string registered via the <a href="#Framework">install framework</a> |
type string registered via the <a href="#Framework">install framework</a> |
| 1134 |
extension point. If not specified, the type is assumed to be the default |
extension point. If not specified, the type is assumed to be the default |
| 1135 |
feature type for the site. If the site type is the default Eclipse site type, |
feature type for the site. If the site type is the default Eclipse site |
| 1136 |
the default feature type is the packaged feature type (as specified in this |
type, the default feature type is the packaged feature type (as specified |
| 1137 |
document).</li> |
in this document).</li> |
| 1138 |
<li> id - optional feature identifier. The information is used as a performance |
<li> id - optional feature identifier. The information is used as a performance |
| 1139 |
optimization to speed up searches for features. Must match the identifier |
optimization to speed up searches for features. Must match the identifier |
| 1140 |
specified in the feature.xml of the referenced archive (the url attribute). |
specified in the feature.xml of the referenced archive (the url attribute). |
| 1144 |
version specified in the feature.xml of the referenced archive (the url attribute). |
version specified in the feature.xml of the referenced archive (the url attribute). |
| 1145 |
If specified, the id attribute must also be specified.</li> |
If specified, the id attribute must also be specified.</li> |
| 1146 |
<li> url - required URL reference to the feature archive. Can be relative |
<li> url - required URL reference to the feature archive. Can be relative |
| 1147 |
or absolute. If relative, it is relative to the location of the site.xml file. |
or absolute. If relative, it is relative to the location of the site.xml |
| 1148 |
<b>Note</b>: the default site implementation allows features to be accessed |
file. <b>Note</b>: the default site implementation allows features |
| 1149 |
without being explicitly declared using a <feature> entry. By default, |
to be accessed without being explicitly declared using a <feature> |
| 1150 |
an undeclared features reference is interpreted as "features/<id>_<version>.jar"</li> |
entry. By default, an undeclared features reference is interpreted as "features/<id>_<version>.jar"</li> |
| 1151 |
<li>label - optional feature label. The value is used for optimization |
<li>label - optional feature label. The value is used for optimization |
| 1152 |
when browsing the site from the update manager. Intended to be translated.<br> |
when browsing the site from the update manager. Intended to be translated.<br> |
| 1153 |
</li> |
</li> |
| 1154 |
|
<li> os - optional operating system specification. A comma-separated |
| 1155 |
|
list of os designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt> |
| 1156 |
|
. Indicates this feature should only be installed on one of the specified |
| 1157 |
|
os systems. If this attribute is not specified, the feature can be installed |
| 1158 |
|
on all systems (portable implementation). This information is used as a hint |
| 1159 |
|
by the installation and update support (user can force installation of feature |
| 1160 |
|
regardless of this setting).</li> |
| 1161 |
|
<li> arch - optional machine architecture specification. A comma-separated |
| 1162 |
|
list of architecture designators defined by Eclipse (see Javadoc for <tt> |
| 1163 |
|
org.eclipse.core.boot.BootLoader)</tt>. Indicates this feature should only |
| 1164 |
|
be installed on one of the specified systems. If this attribute is not specified, |
| 1165 |
|
the feature can be installed on all systems (portable implementation). This |
| 1166 |
|
information is used as a hint by the installation and update support (user |
| 1167 |
|
can force installation of feature regardless of this setting).</li> |
| 1168 |
|
<li> ws - optional windowing system specification. A comma-separated |
| 1169 |
|
list of ws designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt> |
| 1170 |
|
. Indicates this feature should only be installed on one of the specified |
| 1171 |
|
ws systems. If this attribute is not specified, the feature can be installed |
| 1172 |
|
on all systems (portable implementation). This information is used as a hint |
| 1173 |
|
by the installation and update support (user can force installation of feature |
| 1174 |
|
regardless of this setting).</li> |
| 1175 |
|
<li> nl - optional locale specification. A comma-separated list of locale |
| 1176 |
|
designators defined by Java. Indicates this feature should only be installed |
| 1177 |
|
on a system running with a compatible locale (using Java locale-matching |
| 1178 |
|
rules). If this attribute is not specified, the feature can be installed |
| 1179 |
|
on all systems (language-neutral implementation). This information is used |
| 1180 |
|
as a hint by the installation and update support (user can force installation |
| 1181 |
|
of feature regardless of this setting).</li> |
| 1182 |
|
<li>patch - optional specification indicating if this feature is a patch. |
| 1183 |
|
Default is "false". </li> |
| 1184 |
|
|
| 1185 |
</ul> |
</ul> |
| 1186 |
<li> <archive> - identifies referenced "storage" archive (the actual |
<li> <archive> - identifies referenced "storage" archive (the actual |
| 1187 |
files referenced via the <tt><plugin></tt> or <tt><data></tt> |
files referenced via the <tt><plugin></tt> or <tt><data></tt> |
| 1188 |
elements in the feature manifest). The site simply manages archives as a |
elements in the feature manifest). The site simply manages archives as |
| 1189 |
path-to-URL map. The default Eclipse site implementation does not require |
a path-to-URL map. The default Eclipse site implementation does not require |
| 1190 |
the <archive> section to be included in the site map (site.xml). Any |
the <archive> section to be included in the site map (site.xml). Any |
| 1191 |
archive reference not explicitly defined as part of an <archive> section |
archive reference not explicitly defined as part of an <archive> section |
| 1192 |
is assumed to be mapped to a url in the form "<archivePath>" relative |
is assumed to be mapped to a url in the form "<archivePath>" relative |
| 1197 |
determined by the <a href="#Feature_Archive_Mapping_Id_To_Path">feature</a> |
determined by the <a href="#Feature_Archive_Mapping_Id_To_Path">feature</a> |
| 1198 |
referencing this archive and is not otherwise interpreted by the site (other |
referencing this archive and is not otherwise interpreted by the site (other |
| 1199 |
than as a lookup token).</li> |
than as a lookup token).</li> |
| 1200 |
<li> url - required URL reference to the archive. Can be relative or absolute. |
<li> url - required URL reference to the archive. Can be relative or |
| 1201 |
If relative, it is relative to the location of the site.xml file.</li> |
absolute. If relative, it is relative to the location of the site.xml file.</li> |
| 1202 |
|
|
| 1203 |
</ul> |
</ul> |
| 1204 |
<li> <category-def> - an optional definition of a category that |
<li> <category-def> - an optional definition of a category that |
| 1205 |
can be used by installation and update support to hierarchicaly organize |
can be used by installation and update support to hierarchicaly organize features</li> |
|
features</li> |
|
| 1206 |
|
|
| 1207 |
<ul> |
<ul> |
| 1208 |
<li> name - category name. Is specified as a path of name tokens separated |
<li> name - category name. Is specified as a path of name tokens separated |
| 1217 |
</ul> |
</ul> |
| 1218 |
|
|
| 1219 |
</ul> |
</ul> |
| 1220 |
Note, that in general the feature.xml manifest documents should specify |
Note, that in general the feature.xml manifest documents should |
| 1221 |
UTF-8 encoding. For example |
specify UTF-8 encoding. For example |
| 1222 |
<p><tt><?xml version="1.0" encoding="UTF-8"?></tt> </p> |
<p><tt><?xml version="1.0" encoding="UTF-8"?></tt> </p> |
| 1223 |
|
|
| 1224 |
<p>Translatable text contained in the site.xml can be separated into site<_locale>.properties |
<p>Translatable text contained in the site.xml can be separated into site<_locale>.properties |
| 1235 |
(eg. org.eclipse.javatools_1.0.1.jar)</tt> <br> |
(eg. org.eclipse.javatools_1.0.1.jar)</tt> <br> |
| 1236 |
<tt> <featureId>_<featureVersion>/ |
<tt> <featureId>_<featureVersion>/ |
| 1237 |
(optional)</tt> <br> |
(optional)</tt> <br> |
| 1238 |
<tt> non-plug-in |
<tt> |
| 1239 |
files for feature</tt> <br> |
non-plug-in files for feature</tt> <br> |
| 1240 |
<tt> plugins/</tt> <br> |
<tt> plugins/</tt> <br> |
| 1241 |
<tt> plug-in argives |
<tt> plug-in argives |
| 1242 |
(eg. org.eclipse.ui_1.0.3.jar)</tt> |
(eg. org.eclipse.ui_1.0.3.jar)</tt> |
| 1248 |
|
|
| 1249 |
<ul> |
<ul> |
| 1250 |
<li> by supplying server-side logic on the update server (eg. implementing |
<li> by supplying server-side logic on the update server (eg. implementing |
| 1251 |
servlets that compute the site.xml map, and control access to individual archives |
servlets that compute the site.xml map, and control access to individual |
| 1252 |
based on some user criteria)</li> |
archives based on some user criteria)</li> |
| 1253 |
<li> by supplying a custom concrete implementation of the site object |
<li> by supplying a custom concrete implementation of the site object |
| 1254 |
(installed on the client machine, update server specified <tt><site type=""></tt> |
(installed on the client machine, update server specified <tt><site type=""></tt> |
| 1255 |
). The custom concrete site implementation, together with any server-side |
). The custom concrete site implementation, together with any server-side |
| 1264 |
<tt><install root>/</tt> <br> |
<tt><install root>/</tt> <br> |
| 1265 |
<tt> install/</tt> <br> |
<tt> install/</tt> <br> |
| 1266 |
<tt> features/</tt> <br> |
<tt> features/</tt> <br> |
| 1267 |
<tt> <featureId>_<version>/</tt> |
<tt> |
| 1268 |
<br> |
<featureId>_<version>/</tt> <br> |
| 1269 |
<tt> |
<tt> |
| 1270 |
feature.xml</tt> <br> |
feature.xml</tt> <br> |
| 1271 |
<tt> |
<tt> |
| 1277 |
<p><tt> plugins/</tt> <br> |
<p><tt> plugins/</tt> <br> |
| 1278 |
<tt> <pluginORfragmentId>_<version>/</tt> |
<tt> <pluginORfragmentId>_<version>/</tt> |
| 1279 |
<br> |
<br> |
| 1280 |
<tt> plugin.xml |
<tt> |
| 1281 |
or fragment.xml</tt> <br> |
plugin.xml or fragment.xml</tt> <br> |
| 1282 |
<tt> other |
<tt> |
| 1283 |
plugin or fragment files</tt> <br> |
other plugin or fragment files</tt> <br> |
| 1284 |
<tt> META_INF/</tt> |
<tt> |
| 1285 |
</p> |
META_INF/</tt> </p> |
| 1286 |
|
|
| 1287 |
<p><b>Implementation Note:</b> we will go back to the original design of |
<p><b>Implementation Note:</b> we will go back to the original design of not |
| 1288 |
not splitting out fragments (ie. plugin and fragments go into the same install |
splitting out fragments (ie. plugin and fragments go into the same install |
| 1289 |
location) </p> |
location) </p> |
| 1290 |
|
|
| 1291 |
<h3> <a name="Unmanaged_Plugins"></a> "Unmanaged" Plug-Ins</h3> |
<h3> <a name="Unmanaged_Plugins"></a> "Unmanaged" Plug-Ins</h3> |
| 1293 |
that were directly installed into the Eclipse file tree without being part |
that were directly installed into the Eclipse file tree without being part |
| 1294 |
of a feature (eg. developer unzipping plug-in archive directly into the Eclipse |
of a feature (eg. developer unzipping plug-in archive directly into the Eclipse |
| 1295 |
file tree). |
file tree). |
| 1296 |
<p>Eclipse runtime recognizes these plugins during startup and loads the |
<p>Eclipse runtime recognizes these plugins during startup and loads the plug-in |
| 1297 |
plug-in information into the runtime registry following the standard plug-in |
information into the runtime registry following the standard plug-in binding |
| 1298 |
binding rules. The update support also recognizes the presence of this new |
rules. The update support also recognizes the presence of this new plug-in, |
| 1299 |
plug-in, but since this plug-in is not part of any feature it cannot be updated |
but since this plug-in is not part of any feature it cannot be updated using |
| 1300 |
using the update support (hence "unmanaged"). Unmanaged plug-in that become |
the update support (hence "unmanaged"). Unmanaged plug-in that become referenced |
| 1301 |
referenced by a feature as a result of some future installation or update |
by a feature as a result of some future installation or update action become |
| 1302 |
action become "managed" (can be updated as part of the feature). </p> |
"managed" (can be updated as part of the feature). </p> |
| 1303 |
|
|
| 1304 |
<p>Unmanaged plug-ins are not displayed as part of the installation and update |
<p>Unmanaged plug-ins are not displayed as part of the installation and update |
| 1305 |
UI. </p> |
UI. </p> |
| 1316 |
to be installed using native installers into the shared installation tree. |
to be installed using native installers into the shared installation tree. |
| 1317 |
Instead, native installers must establish their own installation root directory. |
Instead, native installers must establish their own installation root directory. |
| 1318 |
The subdirectory structure is the same as defined for base Eclipse. The private |
The subdirectory structure is the same as defined for base Eclipse. The private |
| 1319 |
root directory is logically linked into the shared Eclipse installation via |
root directory is logically linked into the shared Eclipse installation |
| 1320 |
a link file installed by the native installer. The file path for the link |
via a link file installed by the native installer. The file path for the |
| 1321 |
file is <tt><configRoot>/links/</tt>. The <tt><configRoot> </tt> |
link file is <tt><configRoot>/links/</tt>. The <tt><configRoot> |
| 1322 |
location is computed by Eclipse relative to the launch <a |
</tt> location is computed by Eclipse relative to the launch <a |
| 1323 |
href="#Multiple%20Launch%20Points"> configuration file</a> . By default, |
href="#Multiple%20Launch%20Points"> configuration file</a> . By default, |
| 1324 |
this is the <tt>install/</tt> directory in the shared Eclipse installation |
this is the <tt>install/</tt> directory in the shared Eclipse installation |
| 1325 |
tree. </p> |
tree. </p> |
| 1326 |
|
|
| 1327 |
<p>The name of the link file is not specified by Eclipse. The name is determined |
<p>The name of the link file is not specified by Eclipse. The name is determined |
| 1328 |
by the native installer. To minimize the potential for naming collisions, |
by the native installer. To minimize the potential for naming collisions, |
| 1329 |
it is recommended that the file name contain the identifier and version |
it is recommended that the file name contain the identifier and version of |
| 1330 |
of the feature being installed by the native installer. For example, <tt><featureId>_<featureVersion>.properties</tt> |
the feature being installed by the native installer. For example, <tt><featureId>_<featureVersion>.properties</tt> |
| 1331 |
. The file content is in the form of a Java properties file, with the following |
. The file content is in the form of a Java properties file, with the following |
| 1332 |
properties defined: </p> |
properties defined: </p> |
| 1333 |
|
|
| 1347 |
runtime ignores any links that cannot be resolved. <br> |
runtime ignores any links that cannot be resolved. <br> |
| 1348 |
</p> |
</p> |
| 1349 |
<br> |
<br> |
| 1350 |
|
<br> |
| 1351 |
</body> |
</body> |
| 1352 |
</html> |
</html> |
Parent Directory
| 
Revision Log
| 
Patch