platform-update-home/doc/eclipse_update_packaging.html

Revision 1.19 - (view) (download) (as text)

1 :	droberts	1.6	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2 :	vlad	1.1	<html>
3 :			<head>
4 :	celek	1.18
5 :	celek	1.9	<meta http-equiv="Content-Type"
6 :			content="text/html; charset=iso-8859-1">
7 :	celek	1.18
8 :	celek	1.7	<meta name="Author" content="Lab User">
9 :	celek	1.18
10 :	celek	1.7	<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
11 :			<title>Eclipse Platform: Installation and Update</title>
12 :	vlad	1.1	</head>
13 :	celek	1.7	<body>
14 :	celek	1.18
15 :	celek	1.7	<h1> Eclipse Platform<br>
16 :	celek	1.18	Update Packaging Conventions</h1>
17 :			<font size="-1">Revision Date: 01/27/2003 9:00AM - Version:
18 :			2.0.19</font><br>
19 :			<a href="../../../../../hglegal.htm"><img
20 :			src="ngibmcpy.gif" border="0" height="12" width="195">
21 :			</a>
22 :	celek	1.9	<p><b>Change History:</b> </p>
23 :	celek	1.18
24 :	celek	1.7	<ul>
25 :	dejan	1.19	<li><small>2.0.20</small>
26 :			<ul>
27 :			<li><small>added <import id-match></small></li>
28 :			</ul>
29 :			<li><small>2.0.19</small>
30 :	celek	1.18	<ul>
31 :			<li><small>added <feature  discovery type></small></li>
32 :			</ul>
33 :			</li>
34 :			<li><small>2.0.18</small></li>
35 :
36 :	celek	1.14	<ul>
37 :	celek	1.18	<li><small>added <feature plugin=""></small></li>
38 :
39 :	celek	1.15	</ul>
40 :	celek	1.18	<li><small>2.0.17</small></li>
41 :
42 :	celek	1.15	<ul>
43 :	celek	1.18	<li><small>added $os$,$ws$,$arch$ and $nl$ for copyright, description
44 :			and license URL tag in feature.<br>
45 :			</small></li>
46 :
47 :	celek	1.14	</ul>
48 :	celek	1.18	<li><small>2.0.16</small> <small><br>
49 :			</small>
50 :	celek	1.11	<ul>
51 :	celek	1.18	<li><small>added <site><feature> os,arch,nl,ws
52 :			support "*"</small></li>
53 :
54 :	celek	1.11	</ul>
55 :	celek	1.18	</li>
56 :			<li><small>2.0.15</small>
57 :
58 :	celek	1.12	<ul>
59 :	celek	1.18	<li><small>added <site><feature> os,arch,nl,ws,patch
60 :			tag</small></li>
61 :
62 :	celek	1.12	</ul>
63 :	celek	1.18	</li>
64 :			<li><small>2.0.14<br>
65 :			</small>
66 :
67 :	celek	1.10	<ul>
68 :	celek	1.18	<li><small>added <site><feature> label tag</small><br>
69 :			</li>
70 :
71 :	celek	1.17	</ul>
72 :	celek	1.18	</li>
73 :			<li><small>2.0.13<br>
74 :			</small> </li>
75 :
76 :	celek	1.17	<ul>
77 :	celek	1.18	<li><small>added <includes name,optional,match,search-location</small>
78 :	celek	1.17	></li>
79 :	celek	1.18	<li><small>added <import feature,patch></small></li>
80 :
81 :	celek	1.17	</ul>
82 :	celek	1.18	<li><small>2.0.12<br>
83 :			</small></li>
84 :
85 :			<ul>
86 :			<li> <font size="-1">added reference to the <a
87 :			href="http://www.eclipse.org/legal/updatemanager.html"> Eclipse.org Update
88 :			Manager Agreement</a> </font></li>
89 :
90 :	celek	1.16	</ul>
91 :	celek	1.18	<li> <font size="-1">2.0.11</font></li>
92 :
93 :	celek	1.16	<ul>
94 :	celek	1.18	<li> <font size="-1"><feature> <license> is required</font></li>
95 :
96 :	celek	1.16	</ul>
97 :	celek	1.18	<li> <font size="-1">2.0.10</font></li>
98 :
99 :	celek	1.16	<ul>
100 :	celek	1.18	<li> <font size="-1"><feature colocation-affinity=""></font></li>
101 :
102 :	celek	1.16	</ul>
103 :	celek	1.18	<li> <font size="-1">2.0.9</font></li>
104 :
105 :	celek	1.16	<ul>
106 :	celek	1.18	<li> <font size="-1"><site> <feature> changes -
107 :			additional markup to optionally expose feature identification information
108 :	celek	1.17	to speed up searches</font></li>
109 :	celek	1.18	<li> <font size="-1">removed obsolete text</font></li>
110 :			<li> <font size="-1">web-triggered update not in 2.0</font></li>
111 :			<li> <font size="-1">no assist in 2.0 for license/ "key file"
112 :			handling (individual application/ plugin responsibility)</font></li>
113 :
114 :	celek	1.16	</ul>
115 :	celek	1.18	<li> <font size="-1">2.0.8</font></li>
116 :
117 :	celek	1.16	<ul>
118 :	celek	1.18	<li> <font size="-1"><feature> <includes></font></li>
119 :
120 :	celek	1.16	</ul>
121 :	celek	1.18	<li> <font size="-1">2.0.7</font></li>
122 :
123 :	celek	1.16	<ul>
124 :	celek	1.18	<li> <font size="-1">support explicit xml markup for primary
125 :			features</font></li>
126 :
127 :	celek	1.16	</ul>
128 :	celek	1.18	<li> <font size="-1">2.0.6</font></li>
129 :
130 :	celek	1.16	<ul>
131 :	celek	1.18	<li> <font size="-1">install handler markup changes</font></li>
132 :
133 :	celek	1.16	</ul>
134 :	celek	1.18	<li> <font size="-1">2.0.5</font></li>
135 :
136 :	celek	1.16	<ul>
137 :	celek	1.18	<li> <font size="-1">updates to security section</font></li>
138 :
139 :	celek	1.16	</ul>
140 :	celek	1.18	<li> <font size="-1">2.0.4</font></li>
141 :
142 :	celek	1.16	<ul>
143 :	celek	1.18	<li> <font size="-1">general text cleanup</font></li>
144 :			<li> <font size="-1"><feature><group> support
145 :			removed (will not be in Eclipse 2.0)</font></li>
146 :			<li> <font size="-1">arch= support added to <feature>
147 :			and <feature><plugin></font></li>
148 :			<li> <font size="-1">os=/ arch=/ ws=/ nl= added to <fetaure><data></font></li>
149 :			<li> <font size="-1"><site url=""> new semantics</font></li>
150 :			<li> <font size="-1">corrected errors in native installer
151 :			link support</font></li>
152 :			<li> <font size="-1">defined callback query strings for browser-triggered
153 :	celek	1.17	processing</font></li>
154 :	celek	1.18
155 :	celek	1.10	</ul>
156 :	celek	1.18
157 :	celek	1.7	</ul>
158 :	celek	1.18
159 :	celek	1.7	<h3> <font size="+2">Table of Contents</font></h3>
160 :	celek	1.18	<a href="#Introduction">Introduction</a> <br>
161 :			<a
162 :	celek	1.14	href="#Changes_from_R1.0">Changes from 1.0</a> <br>
163 :	celek	1.18	<a href="#Concepts">Concepts</a>
164 :			<br>
165 :			<a href="#Framework">Framework</a>
166 :	celek	1.17	<br>
167 :	celek	1.18	<a href="#Packaging_Conventions">Packaging Conventions</a>
168 :			<br>
169 :			<a
170 :	celek	1.15	href="#Feature_Archive">Feature Archive</a> <br>
171 :	celek	1.18	<a
172 :	celek	1.15	href="#Plug-In_Archive">Plug-In Archive</a> <br>
173 :	celek	1.18	<a
174 :			href="#Packaging_NL">Packaging NL</a> <br>
175 :
176 :			<a href="#Translated_Feature_Information"> Translated Feature Information</a>
177 :	celek	1.17	<br>
178 :	celek	1.18
179 :			<a href="#Translated_Plug-In_Information"> Translated Plug-In Information</a>
180 :	celek	1.17	<br>
181 :	celek	1.18	<a
182 :			href="#Packaging_Target-Specific_Support"> Packaging Target-Specific Support</a>
183 :	celek	1.17	<br>
184 :	celek	1.18	<a
185 :			href="#Packaging_Attribution_Information"> Packaging Attribution Information</a>
186 :	celek	1.17	<br>
187 :	celek	1.18	<a
188 :			href="#Packaging_Attribution_Information"> Packaging Non-Plug-In Files</a>
189 :	celek	1.17	<br>
190 :	celek	1.18	<a
191 :			href="#Packaging_Attribution_Information"> Custom Install Handling</a>
192 :			<br>
193 :			<a
194 :	celek	1.11	href="#Security_Considerations">Security Considerations</a> <br>
195 :	celek	1.18	<a href="#Update_Server">Update Server</a> <br>
196 :			<a href="#Site_Map">Site
197 :			Map</a> <br>
198 :			<a
199 :	celek	1.14	href="#Default_Site_Layout">Default Site Layout</a> <br>
200 :	celek	1.18	<a
201 :	celek	1.14	href="#Controlling_Access">Controlling Access</a> <br>
202 :	celek	1.18	<a href="#Eclipse_Install">Eclipse Install</a> <br>
203 :			<a
204 :	celek	1.11	href="#Default_Install_Layout">Default Install Layout</a> <br>
205 :	celek	1.18	<a
206 :	celek	1.14	href="#Unmanaged_Plugins">"Unmanaged" Plug-Ins</a> <br>
207 :	celek	1.18	<a
208 :			href="#Using_Native_Platform_Installers"> Using Native Platform Installers</a>
209 :
210 :	celek	1.9	<h2> <a name="Introduction"></a> Introduction</h2>
211 :	celek	1.18	This document outlines the support for managing the delivery
212 :			of function within the Eclipse platform. Also refer to the "<a
213 :			href="http://www.eclipse.org/legal/updatemanager.html"> Eclipse.org Update
214 :			Manager Agreement</a> " for additional legal information governing
215 :			the use of the Eclipse update manager function.
216 :	celek	1.9	<h3> <a name="Changes_from_R1.0"></a> Changes from R1.0</h3>
217 :	celek	1.18	This section describes the major design changes from the R1.0
218 :			Installation and Update support and supplies rationale for each design
219 :			change.
220 :	celek	1.7	<ul>
221 :	celek	1.18	<li> <b>extendable framework</b></li>
222 :			<br>
223 :			In R2.0 Eclipse defines an extendable framework for installation
224 :			and update, allowing the support for alternate packaging and site management
225 :			schemes. R2.0 supplies a default concrete implementation of this framework.
226 :	celek	1.17	<li> <b> feature support</b></li>
227 :	celek	1.18	<br>
228 :			In R2.0 the concept of a <i>component</i> and <i>configuration</i>
229 :			is merged into <i>feature</i>. Features define the packaging structure
230 :			for a group of related plug-ins, plug-in fragments, and optionally non-plug-in
231 :			files. Features are treated purely as an installation and packaging construct.
232 :			They do not play a role during Eclipse plug-in execution. Features do
233 :			not nest. They are simply an inclusive "manifest" of the plug-ins, fragments
234 :			and other files that make up that feature. If features are logically made
235 :			up of plug-ins from "sub-features", the top-level feature "manifest" must
236 :			be fully resolved at packaging time. <li> <b>default feature archive format</b></li>
237 :			<br>
238 :			R1.0 components were packaged as a single Java .jar containing
239 :			the component manifest as well as the actual plug-in files. The problem
240 :			with this approach is lack of granularity at download time. In R2.0,
241 :			the feature archive consists of multiple separate .jars - one .jar per
242 :			plug-in and fragment, plus one .jar for the actual feature information.
243 :			The Installation and Update support selectively downloads only those
244 :	celek	1.17	jars required for the installation. <li> <b>site map</b></li>
245 :	celek	1.18	<br>
246 :			Default Eclipse update server must contain a <i>site map</i>
247 :			file (site.xml). This is an evolution of the R1.0 install.index support.
248 :			The rationale for using a structured site defined by the map rather
249 :			than a "free form" web site, is the ability to present a consistent installation
250 :			experience for the user. Also, this provides the necessary structure
251 :			for discovery of available updates. Additional support for "free form"
252 :			browsing may be considered in future work. <li> <b>using native install/
253 :			uninstall</b></li>
254 :			<br>
255 :			The primary mechanism for installing and updating Eclipse features
256 :			is the built-in installation and update support. Some products may instead
257 :			choose to use native installer technology (eg. MSI, RPM, etc) to deliver
258 :			Eclipse features. However, native installers do not implement the required
259 :			support for understanding the Eclipse installation structure. In particular,
260 :			the native uninstallers will, by default, remove plug-in files that were
261 :			installed using the native installer without regard to these plug-ins
262 :			being needed by other features. As a result, features installed using
263 :			native installers must be written into private product-specific installation
264 :			location and not the shared Eclipse installation location. The shared
265 :			Eclipse is made aware of the produce-specific location via an installed
266 :			"link file". <li> <b>custom install handling</b></li>
267 :			<br>
268 :			In many cases the standard installation handling supplied by
269 :			Eclipse is not be sufficient to handle various custom requirements. To
270 :			accommodate this, R2.0 Eclipse supports custom install handlers packaged
271 :			as part of the feature and executed during the feature installation. <li>
272 :	celek	1.17	<b>path naming conventions</b></li>
273 :	celek	1.18	<br>
274 :			R1.0 mandated the use of the various identifiers and versions
275 :			inside the packaged archives (eg. directory path names for plug-ins).
276 :			This approach has proven to be ackward and error prone. In 2.0, the
277 :			packaging requirements no longer mandate that path names of packaged
278 :			files precisely reflect the contained identifiers and versions. The properly
279 :			identified install subdirectories are created by the Eclipse support
280 :			during the installation and update process based on the archive content
281 :			(rather than explicit jar path structure set up at packaging time)
282 :
283 :	celek	1.7	</ul>
284 :	celek	1.18
285 :	celek	1.9	<h3> <a name="Concepts"></a> Concepts</h3>
286 :	celek	1.18	<b>Plug-in</b> <br>
287 :			Eclipse developers build plug-ins. Plug-ins are the base units
288 :			of execution recognized by the Eclipse runtime environment. In general,
289 :			plug-ins are not exposed to users that select function during installation
290 :			or update. The reason is that plug-in boundaries are established by developers
291 :			for development reasons (like function reuse) and present the wrong
292 :			level of granularity in terms of what the user sees as the unit of function.
293 :
294 :			<p>While plug-ins are being developed (ie. are frequently being changed),
295 :			their internal file structure will reflect what is convenient to the
296 :			developer. This will generally depend on the particular development
297 :			tool being used. Typically, however, the developer will likely setup
298 :			the plug-in to execute from a directory tree containing exposed .class
299 :			files, rather than executing from a .jar (requires an extra step to
300 :			create the .jar and we all know developers hate extra steps). Also, at
301 :			this stage the developer does not pay particular attention to plug-in
302 :			versioning information, because the plug-in is continually changing. </p>
303 :
304 :			<p>However, when the plug-in is ready to be packaged, it needs to be converted
305 :			to a form suitable for packaging and installation. Typically it means
306 :			creation of the runtime .jar(s) and removing any development-time files
307 :			(source, exposed .class files, etc). It also means updating the plugin.xml
308 :			manifest with the formal plug-in version and reflecting the version in
309 :			the plug-in directory name (see "Concurrent Plug-In Version Support" for
310 :			details). </p>
311 :
312 :	celek	1.7	<p><b>Plug-in Fragment</b> <br>
313 :	celek	1.18	Plug-in Fragments (or simply Fragments) allow independent packaging
314 :			of certain aspects of the base plug-in. This includes (but may not
315 :			be limited to) translated resources for the plug-in, OS-specific or
316 :			windowing-system-specific code. At runtime, fragments are logically
317 :			merged into the base plug-in. From a packaging point of view, the install
318 :			and update support does not really differentiate between plug-ins and
319 :			their related fragments. </p>
320 :
321 :	celek	1.7	<p><b>Feature</b> <br>
322 :	celek	1.18	A feature is an installation packaging mechanism used to define
323 :			a group of versioned plug-ins and/or plug-in fragments plus non-plug-in
324 :			files that is used to deliver some user function. A feature can also
325 :			include other features. Features are exposed to users as part of the
326 :			packaging and installation process, because they represent a unit of
327 :			function selection. Features also represent a unit of installation. Features
328 :			carry a version identifier.</p>
329 :
330 :			<p>Features are packaged as a feature archive, referencing the required plug-ins,
331 :			plug-in fragments and optional non-plug-in files. The feature archives
332 :			are placed on an update server for download and installation by the Eclipse
333 :			update manager, or they can be used as the input into a formal packaging
334 :			process using one of the "traditional" installer technologies. The format
335 :			of the feature archive is described later. </p>
336 :
337 :	celek	1.9	<h3> <a name="Framework"></a> Framework</h3>
338 :	celek	1.18	The 2.0 installation and update support is provided as a framework
339 :			that allows custom implementations to be supplied for its key elements.
340 :			In particular, the following can be supplied:
341 :	vlad	1.1	<ul>
342 :	celek	1.18	<li> concrete implementations of feature (IFeature interface)
343 :			that can be used to support alternate packaging schemes. New concrete
344 :			feature types are registere via the "org.eclipse.update.featureTypes"
345 :	celek	1.17	extension point.</li>
346 :	celek	1.18	<li> concrete implementations of site (ISite interface) that
347 :			can be used to support alternate site layout, or site behavior. New concrete
348 :			site types are registered via the "org.eclipse.update.siteTypes" extension
349 :			point.</li>
350 :			<li> each feature can specify a custom install handler as
351 :			part of its feature manifest. Install handlers (IInstallHandler interface)
352 :			are dynamically invoked as part of the installation process to handle
353 :			non-plugin data, plus perform other custom processing allowed by the framework.</li>
354 :
355 :	celek	1.7	</ul>
356 :	celek	1.18	Eclipse provides default implementations of feature and site.
357 :	celek	1.17	These are described in the rest of this document. <br>
358 :	celek	1.18
359 :	celek	1.7	<table border="1" cols="1" width="100%">
360 :	celek	1.18	<tbody>
361 :			<tr>
362 :			<td><b>Note: <i>The reminder of this document describes the
363 :			default concrete implementation of the framework delivered with Eclipse.
364 :			It specifies the structure of the default feature implementation, as well
365 :			as the default site implementation, plus the corresponding xml files (feature.xml
366 :			and site.xml). Providers of alternate concrete implementations can extend
367 :			parts or all of the default Eclipse implementation. This includes providing
368 :			a mechanism for dynamic computation of the site map (site.xml)</i></b></td>
369 :			</tr>
370 :
371 :			</tbody>
372 :	vlad	1.1	</table>
373 :	celek	1.18
374 :	celek	1.9	<h2> <a name="Packaging_Conventions"></a> Packaging Conventions</h2>
375 :	celek	1.18	Default feature packages consist of several related files:
376 :
377 :	celek	1.7	<ul>
378 :	celek	1.18	<li> exactly one jar containing the feature manifest and related
379 :			files. This one is refered to as the "<b>feature archive</b>"</li>
380 :			<li> zero or more jars containing the feature plug-ins. These
381 :			are refered to as the "<b>plug-in archives</b>"</li>
382 :			<li> zero or more non-plug-in files associated with the feature.
383 :			They are used by feature custom install handlers and contain data not
384 :	celek	1.17	interpreted by Eclipse</li>
385 :	celek	1.18
386 :	celek	1.9	</ul>
387 :	celek	1.18
388 :	celek	1.9	<h3> <a name="Feature_Archive"></a> Feature Archive</h3>
389 :	celek	1.18	The feature packaging information is placed into a separate
390 :			Java .jar. Standard Java jar facilities are used for constructing feature
391 :			archives. Feature archives reference separately packaged plug-in archives
392 :			(see next section) and non-plug-in files.
393 :			<p>Features are identified using a structured identifier based on the provider
394 :			internet domain name. For example, organization eclipse.org may produce
395 :			feature org.eclipse.javatooling. The character set used for feature
396 :			identifiers is as specified for plug-in identifiers (see reference information
397 :			describing the plug-in manifest). </p>
398 :
399 :	celek	1.7	<p>The recommended convention for naming the feature archives is <br>
400 :	celek	1.18	<tt><id>_<version>.jar</tt> </p>
401 :
402 :			<p>Where <tt><id></tt> is the feature identifier and <tt><version></tt>
403 :			is the full version identifier contained in the respective feature.xml.
404 :			Note that this is a recommended convention that minimizes chance of
405 :			collisions, but is not required by the Eclipse architecture. For example,
406 :			the following are valid feature archive names </p>
407 :
408 :	celek	1.7	<p><tt>org.eclipse.javatooling_1.0.3.jar</tt> <br>
409 :	celek	1.18	<tt>org.eclipse.pde_2.0.jar</tt> <br>
410 :			<tt>my_feature.jar</tt> </p>
411 :
412 :			<p>Internally, each feature archive is packaged relative to its feature directory
413 :			(but not including the directory path element). The archive has the
414 :	celek	1.17	following structure </p>
415 :	celek	1.18
416 :	celek	1.7	<p><tt>feature.xml</tt> <br>
417 :	celek	1.18	<tt>feature<_locale>.properties (see "Translated Feature
418 :	celek	1.17	Information")</tt> <br>
419 :	celek	1.18	<tt>other feature files and subdirectories (TBD)</tt> <br>
420 :			<tt>META-INF/</tt> <br>
421 :			<tt>    Java jar manifest and security files</tt>
422 :	celek	1.17	</p>
423 :	celek	1.18
424 :	celek	1.7	<p>The feature install.xml format is defined by the following dtd: </p>
425 :	celek	1.18
426 :	celek	1.7	<p><tt><?xml encoding="ISO-8859-1"?></tt> </p>
427 :	celek	1.18
428 :			<p><tt><!ELEMENT feature (install-handler?, description?, copyright?,
429 :			license?, url?, includes, requires?, plugin, data*)></tt> <br>
430 :			<tt><!ATTLIST feature</tt> <br>
431 :			<tt>    id
432 :			CDATA #REQUIRED</tt> <br>
433 :			<tt>    version
434 :	celek	1.17	CDATA #REQUIRED</tt> <br>
435 :	celek	1.18	<tt>    label
436 :			CDATA #IMPLIED</tt> <br>
437 :			<tt>    provider-name CDATA #IMPLIED</tt> <br>
438 :			<tt>    image
439 :			CDATA #IMPLIED</tt> <br>
440 :			<tt>    os
441 :			CDATA #IMPLIED</tt> <br>
442 :			<tt>    arch
443 :			CDATA #IMPLIED</tt> <br>
444 :			<tt>    ws
445 :			CDATA #IMPLIED</tt> <br>
446 :			<tt>    nl
447 :			CDATA #IMPLIED</tt> <br>
448 :			<tt>    colocation-affinity</tt> <br>
449 :			<tt>
450 :			CDATA #IMPLIED</tt> <br>
451 :			<tt>    primary
452 :	celek	1.17	(true \| false) "false"</tt> <br>
453 :	celek	1.18	<tt>    application   CDATA #IMPLIED<br>
454 :			</tt>         <tt>plugin
455 :	celek	1.17	CDATA #IMPLIED</tt><br>
456 :	celek	1.18	<tt>></tt> </p>
457 :
458 :	celek	1.7	<p><tt><!ELEMENT install-handler EMPTY></tt> <br>
459 :	celek	1.18	<tt><!ATTLIST install-handler</tt> <br>
460 :			<tt>    library
461 :	celek	1.17	CDATA #IMPLIED</tt> <br>
462 :	celek	1.18	<tt>    handler
463 :	celek	1.17	CDATA #IMPLIED</tt> <br>
464 :	celek	1.18	<tt>></tt> </p>
465 :
466 :	celek	1.7	<p><tt><!ELEMENT description (#PCDATA)></tt> <br>
467 :	celek	1.18	<tt><!ATTLIST description</tt> <br>
468 :			<tt>    url
469 :			CDATA #IMPLIED</tt> <br>
470 :			<tt>></tt> </p>
471 :
472 :	celek	1.7	<p><tt><!ELEMENT copyright (#PCDATA)></tt> <br>
473 :	celek	1.18	<tt><!ATTLIST copyright</tt> <br>
474 :			<tt>    url
475 :			CDATA #IMPLIED</tt> <br>
476 :			<tt>></tt> </p>
477 :
478 :	celek	1.7	<p><tt><!ELEMENT license (#PCDATA)></tt> <br>
479 :	celek	1.18	<tt><!ATTLIST license</tt> <br>
480 :			<tt>    url
481 :			CDATA #IMPLIED</tt> <br>
482 :			<tt>></tt> </p>
483 :
484 :	celek	1.7	<p><tt><!ELEMENT url (update?, discovery*)></tt> </p>
485 :	celek	1.18
486 :	celek	1.7	<p><tt><!ELEMENT update EMPTY></tt> <br>
487 :	celek	1.18	<tt><!ATTLIST update</tt> <br>
488 :			<tt>    url
489 :			CDATA #REQUIRED</tt> <br>
490 :			<tt>    label
491 :			CDATA #IMPLIED</tt> <br>
492 :			<tt>></tt> </p>
493 :
494 :	celek	1.7	<p><tt><!ELEMENT discovery EMPTY></tt> <br>
495 :	celek	1.18	<tt><!ATTLIST discovery</tt> <br>
496 :			<tt>    url
497 :			CDATA #REQUIRED</tt> <br>
498 :			<tt>    label
499 :			CDATA #IMPLIED</tt> <br>
500 :			<tt>    type
501 :			(update\|web) "update"</tt><tt><br>
502 :			></tt> </p>
503 :			<p> </p>
504 :
505 :	celek	1.7	<p><tt><!ELEMENT includes EMPTY></tt> <br>
506 :	celek	1.18	<tt><!ATTLIST includes</tt> <br>
507 :			<tt>    id
508 :			CDATA #REQUIRED</tt> <br>
509 :			<tt>    version
510 :	celek	1.17	CDATA #REQUIRED</tt> <br>
511 :	celek	1.18	<tt>    name
512 :			CDATA #IMPLIED</tt> <br>
513 :			<tt>    optional      </tt><tt>
514 :	celek	1.17	(true \| false) "false"</tt><tt> <br>
515 :	celek	1.18	</tt><tt>    match
516 :			(perfect \| equivalent \| compatible \| greaterOrEqual)
517 :			"compatible"</tt><tt>       </tt><br>
518 :			<tt>    search-location   </tt><tt>(</tt><font
519 :	celek	1.9	color="#000000"><tt> root \| self \| both) "root"</tt></font><br>
520 :	celek	1.18	<tt>></tt> </p>
521 :
522 :	celek	1.7	<p><tt><!ELEMENT requires (import+)></tt> </p>
523 :	celek	1.18
524 :	celek	1.7	<p><tt><!ELEMENT import EMPTY></tt> <br>
525 :	celek	1.18	<tt><!ATTLIST import</tt> <br>
526 :			<tt>    plugin
527 :			CDATA #IMPLIED</tt><br>
528 :			<tt>    feature
529 :			CDATA #IMPLIED</tt><br>
530 :			<tt>    version
531 :	dejan	1.19	CDATA #IMPLIED<br>
532 :			id-match      (perfect
533 :			\| prefix) "perfect"</tt> <br>
534 :	celek	1.18	<tt>    match
535 :	celek	1.17	(perfect \| equivalent \| compatible \| greaterOrEqual) "compatible"</tt> <br>
536 :	celek	1.18	<tt>    patch      </tt><tt>
537 :	celek	1.17	(true \| false) "false"</tt><tt> </tt><tt><br>
538 :	celek	1.18	></tt><br>
539 :			</p>
540 :
541 :	celek	1.7	<p><tt><!ELEMENT plugin EMPTY></tt> <br>
542 :	celek	1.18	<tt><!ATTLIST plugin</tt> <br>
543 :			<tt>    id
544 :			CDATA #REQUIRED</tt> <br>
545 :			<tt>    version
546 :	celek	1.17	CDATA #REQUIRED</tt> <br>
547 :	celek	1.18	<tt>    fragment
548 :			(true \| false) "false"</tt> <br>
549 :			<tt>    os
550 :			CDATA #IMPLIED</tt> <br>
551 :			<tt>    arch
552 :			CDATA #IMPLIED</tt> <br>
553 :			<tt>    ws
554 :			CDATA #IMPLIED</tt> <br>
555 :			<tt>    nl
556 :			CDATA #IMPLIED</tt> <br>
557 :			<tt>    download-size CDATA #IMPLIED</tt> <br>
558 :			<tt>    install-size  CDATA #IMPLIED</tt>
559 :			<br>
560 :			<tt>></tt> </p>
561 :
562 :	celek	1.7	<p><tt><!ELEMENT data EMPTY></tt> <br>
563 :	celek	1.18	<tt><!ATTLIST data</tt> <br>
564 :			<tt>    id
565 :			CDATA #REQUIRED</tt> <br>
566 :			<tt>    os
567 :			CDATA #IMPLIED</tt> <br>
568 :			<tt>    arch
569 :			CDATA #IMPLIED</tt> <br>
570 :			<tt>    ws
571 :			CDATA #IMPLIED</tt> <br>
572 :			<tt>    nl
573 :			CDATA #IMPLIED</tt> <br>
574 :			<tt>    download-size CDATA #IMPLIED</tt> <br>
575 :			<tt>    install-size  CDATA #IMPLIED</tt>
576 :			<br>
577 :			<tt>></tt> </p>
578 :
579 :	celek	1.7	<p>The element and attribute definitions are as follows: </p>
580 :	celek	1.18
581 :	celek	1.7	<ul>
582 :	celek	1.18	<li> <feature> - defines the feature</li>
583 :
584 :	celek	1.7	<ul>
585 :	celek	1.18	<li> id - required feature identifier (eg. com.xyz.myfeature)</li>
586 :			<li> version - required component version (eg. 1.0.3)</li>
587 :			<li> label - optional displayable label (name). Intended to
588 :			be translated.</li>
589 :			<li> provider-name - optional display label identifying the
590 :			organization providing this component. Intended to be translated.</li>
591 :			<li> image - optional image to use when displaying information
592 :	celek	1.17	about the feature.  Specified relative to the feature.xml.</li>
593 :	celek	1.18	<li> os - optional operating system specification. A comma-separated
594 :			list of os designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt>
595 :			. Indicates this feature should only be installed on one of the specified
596 :			os systems. If this attribute is not specified, the feature can be
597 :			installed on all systems (portable implementation). This information
598 :			is used as a hint by the installation and update support (user can force
599 :			installation of feature regardless of this setting).</li>
600 :			<li> arch - optional machine architecture specification. A
601 :			comma-separated list of architecture designators defined by Eclipse
602 :			(see Javadoc for <tt> org.eclipse.core.boot.BootLoader)</tt>. Indicates
603 :			this feature should only be installed on one of the specified systems.
604 :			If this attribute is not specified, the feature can be installed on all
605 :			systems (portable implementation). This information is used as a hint
606 :			by the installation and update support (user can force installation of
607 :			feature regardless of this setting).</li>
608 :			<li> ws - optional windowing system specification. A comma-separated
609 :			list of ws designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt>
610 :			. Indicates this feature should only be installed on one of the specified
611 :			ws systems. If this attribute is not specified, the feature can be
612 :			installed on all systems (portable implementation). This information
613 :			is used as a hint by the installation and update support (user can force
614 :			installation of feature regardless of this setting).</li>
615 :			<li> nl - optional locale specification. A comma-separated
616 :			list of locale designators defined by Java. Indicates this feature should
617 :			only be installed on a system running with a compatible locale (using
618 :			Java locale-matching rules). If this attribute is not specified, the feature
619 :			can be installed on all systems (language-neutral implementation). This
620 :			information is used as a hint by the installation and update support (user
621 :			can force installation of feature regardless of this setting).</li>
622 :			<li> colocation-affinity - optional reference to another feature
623 :			identifier used to select the default installation location for this
624 :			feature. When this feature is being installed as a new feature (no other
625 :			versions of it are installed), an attempt is made to install this feature
626 :	celek	1.17	in the same installation location as the referenced feature.</li>
627 :	celek	1.18	<li> primary - optional indication specifying whether this
628 :			feature can be used as a <a href="#Dominant_Feature">primary feature</a>
629 :	celek	1.17	. Default if <i>false</i> (not a primary feature).</li>
630 :	celek	1.18	<li> application - optional identifier of the Eclipse application
631 :			that is to be used during startup when the declaring feature is the
632 :			<a href="#Dominant_Feature"> primary feature</a> . The application
633 :			identifier must represent a valid application registered in the <tt>org.eclipse.core.runtime.applications</tt>
634 :			extension point. Default is <tt>org.eclipse.ui.workbench</tt>.</li>
635 :			<li> plugin- optional identifier of the primary plugin associated
636 :			with this <a
637 :			href="file:///C:/OTI/workspace/plugins/platform-update-home/doc/eclipse_update_packaging.html#Dominant_Feature">primary
638 :			feature</a>. The primary plugin carries branding information. If the plugin
639 :			attribute is not declared, the primary plugin identifier used will be the
640 :	celek	1.17	same as the feature identifier. </li>
641 :	celek	1.18
642 :	celek	1.17	</ul>
643 :	celek	1.18	<li> <install-handler></li>
644 :
645 :	celek	1.17	<ul>
646 :	celek	1.18	<li> library - optional .jar library containing the install
647 :			handler classes. If specified, the referenced .jar must be contained
648 :			in the feature archive. It is specified as a path within the feature
649 :			archive, relative to the feature.xml entry. If not specified, the feature
650 :			archive itself is used to load the install handler classes. This attribute
651 :	celek	1.17	is only interpreted if <i>class</i> attribute is also specified</li>
652 :	celek	1.18	<li> handler - optional identifier of the install handler.
653 :			The value is interpreted depending on the value of the <i>library</i>
654 :			attribute. If <i> library</i> is specified,  the value is
655 :			interpreted as a fully qualified name of a class contained in the specified
656 :			<i>library</i>. If <i>library</i> is not specified, the
657 :			value is is interpreted as an extension identifier of an extension registered
658 :			in the <i>org.eclipse.update.installHandlers</i> extension point. In
659 :			either case, the resulting class must implement the <i> IInstallHandler</i>
660 :			interface. The class is dynamically loaded and called at specific points
661 :			during feature processing. The handler has visibility to the API classes
662 :	celek	1.17	from the update plug-in, and Eclipse plug-ins required by the update plugin.</li>
663 :	celek	1.18
664 :	celek	1.17	</ul>
665 :	celek	1.18	<li> <description> - brief component description as
666 :			simple text. Intended to be translated.</li>
667 :
668 :			<ul>
669 :			<li> url - optional URL for the full description as HTML. The
670 :			URL can be specified as absolute of relative. If relative, it is assumed
671 :			to be relative to (and packaged in) the feature archive. Note, that for
672 :			NL handling the URL value should be separated to allow alternate URLs to
673 :			be specified for each national language.  URL support keywords $os$,$ws$,$arch$
674 :			and $nl$ that will be replaced by the appropriate operating system, windowing
675 :			system, operating architecture or national language value.</li>
676 :
677 :	celek	1.17	</ul>
678 :	celek	1.18	<li> <copyright> - feature copyright as simple text.
679 :	celek	1.17	Intended to be translated.</li>
680 :	celek	1.18
681 :	celek	1.17	<ul>
682 :	celek	1.18	<li> url - optional URL for the full description as HTML. The
683 :			URL can be specified as absolute of relative. If relative, it is assumed
684 :			to be relative to (and packaged in) the feature archive. Note, that for
685 :			NL handling the URL value should be separated to allow alternate URLs to
686 :			be specified for each national language. URL support keywords $os$,$ws$,$arch$
687 :			and $nl$ that will be replaced by the appropriate operating system, windowing
688 :			system, operating architecture or national language value.</li>
689 :
690 :	celek	1.16	</ul>
691 :	celek	1.18	<li> <license> - feature "click-through" license as
692 :			simple text. Intended to be translated. It is displayed in a standard
693 :			dialog with [Accept] [Reject] actions during the download/ installation
694 :			process. Note, that click-through license must be specified for any feature
695 :			that will be selected for installation or update using the Eclipse update
696 :			manager. When using nested features, only the nesting parent (ie. the feature
697 :			selected for installation or update) must have click-through license text
698 :			defined. The license text is required even if the optional <i>url</i> attribute
699 :			is specified.</li>
700 :
701 :			<ul>
702 :			<li> url - optional URL for the full description as HTML. The
703 :			URL can be specified as absolute of relative. If relative, it is assumed
704 :			to be relative to (and packaged in) the feature archive. Note, that for
705 :			NL handling the URL value should be separated to allow alternate URLs to
706 :			be specified for each national language. Note, that the "content" of this
707 :			URL is <b>not</b> what is presented as the click-through license during
708 :			installation processing. The click-through license is the actual value
709 :			of the <i><license></i> element (eg. <tt><license>click
710 :			through text</license></tt>). URL support keywords $os$,$ws$,$arch$
711 :			and $nl$ that will be replaced by the appropriate operating system, windowing
712 :	celek	1.16	system, operating architecture or national language value.</li>
713 :	celek	1.18
714 :	celek	1.14	</ul>
715 :	celek	1.18	<li> <url> - optional URL specifying site(s) contain
716 :	celek	1.17	feature updates, or new features</li>
717 :	celek	1.18
718 :	celek	1.13	<ul>
719 :	celek	1.18	<li> <update> - URL to go to for updates to this feature</li>
720 :	celek	1.17
721 :	celek	1.18
722 :	celek	1.7	<ul>
723 :	celek	1.18	<li> url - actual URL</li>
724 :			<li> label - displayable label (name) for the referenced site</li>
725 :	celek	1.17
726 :	celek	1.18
727 :	celek	1.7	</ul>
728 :	celek	1.18	<li> <discovery> - URL to go to for new features. In
729 :			general, a provider can use this element to reference its own site(s),
730 :			or site(s) of partners that offer complementary features. Eclipse uses
731 :	celek	1.17	this element simply as a way to distribute new site URLs to the clients</li>
732 :
733 :	celek	1.18
734 :	celek	1.7	<ul>
735 :	celek	1.18	<li> url - actual URL</li>
736 :			<li> label - displayable label (name) for the referenced site</li>
737 :			<li>type - whether the site is an regular update site or a web site.
738 :			The web site may be a web-triggered-install web site. (<tt>update</tt> is
739 :			the default)<br>
740 :			</li>
741 :	celek	1.17
742 :	celek	1.18
743 :	celek	1.11	</ul>
744 :	celek	1.18
745 :	celek	1.7	</ul>
746 :	celek	1.18	<li> <includes> - optional reference to a nested feature
747 :			that is considered to be part of this feature. Nested features must be
748 :			located on the same update site as this feature</li>
749 :
750 :			<ul>
751 :			<li> id - required nested feature identifier</li>
752 :			<li> version - required nested feature version</li>
753 :			<li> name- optional displayable label (name). Intended to
754 :			be translated.</li>
755 :			<li>optional - optional specification indicating if this
756 :	celek	1.17	included feature can be optionally installed. Default is "false"<br>
757 :	celek	1.18	</li>
758 :			<li>match  - optional rule that will be applied when
759 :			resolving the feature reference. A <samp>perfect</samp> match (the
760 :			default that matches the 2.0.1 behavior) requires that the feature has
761 :			exactly the version specified by the version attribute. Other choices
762 :			progressively relax the rule (<samp> equivalent</samp> allows only service
763 :			part of the version to be more recent, <samp>compatible</samp>
764 :			also allows minor part to be included in the consideration, while <samp>greaterOrEqual</samp>
765 :			simply allows any version that is more recent or identical to the one
766 :	celek	1.17	specified).</li>
767 :	celek	1.18	<li>search-location  - optional. Indicates whether
768 :			the "New Updates" action should search the update location determined
769 :			by the nesting root feature (<tt>root</tt>, is the default), or the location
770 :			defined by the nested feature (<tt>self</tt>), or search both (<tt>both</tt>)
771 :	celek	1.17	in that order (root first, self if nothing is found).</li>
772 :	celek	1.18
773 :	celek	1.17	</ul>
774 :	celek	1.18	<li> <requires> - optional feature dependency information.
775 :			Is expressed in terms of plug-in dependencies. If specified, is enforced
776 :	celek	1.17	by the installation and update support at the time of installation</li>
777 :	celek	1.18
778 :	celek	1.14	<ul>
779 :	celek	1.18	<li> <import> - dependency entry. Specification and processing
780 :			is a subset of the <import> specification in plugin.xml</li>
781 :	celek	1.17
782 :	celek	1.18
783 :	celek	1.7	<ul>
784 :	celek	1.18	<li> plugin - identifier of dependent plug-in.</li>
785 :			<li> feature - identifier of dependent feature. If plugin
786 :			and feature are specified, plugin takes precedence upon feature. Feature
787 :			or plugin must be specified.</li>
788 :			<li> version - optional plug-in/feature version specification</li>
789 :			<li>patch - optional specification indicating if this
790 :			feature is a patch of the dependant feature. Default is "false". If
791 :			patch is true, version must be specified. If patch is true, only feature
792 :			must be specified. If patch is true, and match is specified, it must
793 :	dejan	1.19	be 'perfect'.
794 :	celek	1.18	</li>
795 :	dejan	1.19	<li>id-match - optional identifier matching rule. Valid values and
796 :			processing are as follows:
797 :			<ul>
798 :			<li><b><i>perfect</i></b> - dependent plug-in or feature id
799 :			will be directly compared to the specified identifier. This
800 :			is the default setting.</li>
801 :			<li><b><i>prefix</i></b> - dependent plug-in or feature
802 :			identifier has to be a valid prefix of the specified
803 :			identifier. For example, if feature is specified as "com.acme.product."
804 :			and id-match is set to "prefix", a detected
805 :			feature "com.acme.product.win32" will be
806 :			considered a positive match. This property can be used to
807 :			create patches that can be applied across multiple os/ws/arch
808 :			versions of the product. It should not be used for anything
809 :			else because lookup will stop at the first match, which may
810 :			yield unpredictable results in case there are more than one
811 :			feature that satisfies the search criteria.</li>
812 :			</ul>
813 :			</li>
814 :	celek	1.18	<li> match - optional matching rule. Valid values and processing
815 :	celek	1.17	are as follows:</li>
816 :	celek	1.14
817 :	celek	1.18
818 :	celek	1.7	<ul>
819 :	celek	1.18	<li> if version attribute is not specified, the match attribute
820 :	celek	1.17	(if specified) is ignored.</li>
821 :	celek	1.18	<li>if version is specified, match defaults to compatible.<br>
822 :			</li>
823 :			<li>if patch is true, and match is not specified, match
824 :			defaults to perfect.<br>
825 :			</li>
826 :			<li> <b><i>perfect</i></b> - dependent plug-in version must
827 :			match exactly the specified version.</li>
828 :			<li> <b><i>equivalent</i></b> - dependent plug-in version
829 :			must be at least at the version specified, or at a higher service level
830 :			(major and minor version levels must equal the specified version).</li>
831 :			<li> <b><i>compatible</i></b> - dependent plug-in version
832 :			must be at least at the version specified, or at a higher service level
833 :			or minor level (major version level must equal the specified version).</li>
834 :			<li> <b><i>greaterOrEqual</i></b> - dependent plug-in version
835 :			must be at least at the version specified, or at a higher service, minor
836 :			or major level.</li>
837 :	celek	1.14
838 :	celek	1.18
839 :	celek	1.12	</ul>
840 :	celek	1.17
841 :	celek	1.18
842 :	celek	1.11	</ul>
843 :	celek	1.18
844 :	celek	1.7	</ul>
845 :	celek	1.18	<li> <plugin> - identifies referenced plug-in</li>
846 :
847 :	celek	1.7	<ul>
848 :	celek	1.18	<li> id - required plug-in identifier (from plugin.xml)</li>
849 :			<li> version - required plug-in version (from plugin.xml)</li>
850 :			<li> fragment - optional specification indicating if this
851 :			entry is a plug-in fragment. Default is "false"</li>
852 :			<li> os - optional operating system specification. A comma-separated
853 :			list of os designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt>
854 :			. Indicates this entry should only be installed on one of the specified
855 :			os systems. If this attribute is not specified, the entry can be installed
856 :			on all systems (portable implementation). This information is used
857 :			as a hint by the installation and update support (user can force installation
858 :			of entry regardless of this setting).</li>
859 :			<li> arch - optional machine architecture specification. A
860 :			comma-separated list of architecture designators defined by Eclipse
861 :			(see Javadoc for <tt> org.eclipse.core.boot.BootLoader)</tt>. Indicates
862 :			this feature should only be installed on one of the specified systems.
863 :			If this attribute is not specified, the feature can be installed on all
864 :			systems (portable implementation). This information is used as a hint
865 :			by the installation and update support (user can force installation of
866 :			feature regardless of this setting).</li>
867 :			<li> ws - optional windowing system specification. A comma-separated
868 :			list of ws designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt>
869 :			. Indicates this entry should only be installed on one of the specified
870 :			ws systems. If this attribute is not specified, the entry can be installed
871 :			on all systems (portable implementation). This information is used
872 :			as a hint by the installation and update support (user can force installation
873 :			of entry regardless of this setting).</li>
874 :			<li> nl - optional locale specification. A comma-separated
875 :			list of locale designators defined by Java. Indicates this entry should
876 :			only be installed on a system running with a compatible locale (using
877 :			Java locale-matching rules). If this attribute is not specified, the entry
878 :			can be installed on all systems (language-neutral implementation). This
879 :			information is used as a hint by the installation and update support (user
880 :			can force installation of entry regardless of this setting).</li>
881 :			<li> download-size - optional hint supplied by the feature
882 :			packager, indicating the download size in KBytes of the referenced plug-in
883 :			archive.The size should not contain decimal. If not specified, the download
884 :			size is not known (<b>Implementation Note:</b> the implementation needs
885 :			to distinguish between "not known" and 0 size)</li>
886 :			<li> install-size - optional hint supplied by the feature
887 :			packager, indicating the install size in KBytes of the referenced
888 :			plug-in archive. The size should not contain decimal. If not specified,
889 :			the install size is not known (<b>Implementation Note:</b> the implementation
890 :			needs to distinguish between "not known" and 0 size)</li>
891 :
892 :	celek	1.16	</ul>
893 :	celek	1.18	<li> <data> - identifies non-plugin and non-feature
894 :			data that is part of the feature. Generally, data are post-install processed
895 :			using feature Install handler. Feature files like feature.properties are
896 :	celek	1.17	not considered data.</li>
897 :	celek	1.18
898 :	celek	1.16	<ul>
899 :	celek	1.18	<li> id - required data identifier in the form of a relative
900 :			path.</li>
901 :			<li> os - optional operating system specification. A comma-separated
902 :			list of os designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt>
903 :			. Indicates this entry should only be installed on one of the specified
904 :			os systems. If this attribute is not specified, the entry can be installed
905 :			on all systems (portable implementation). This information is used
906 :			as a hint by the installation and update support (user can force installation
907 :			of entry regardless of this setting).</li>
908 :			<li> arch - optional machine architecture specification. A
909 :			comma-separated list of architecture designators defined by Eclipse
910 :			(see Javadoc for <tt> org.eclipse.core.boot.BootLoader)</tt>. Indicates
911 :			this feature should only be installed on one of the specified systems.
912 :			If this attribute is not specified, the feature can be installed on all
913 :			systems (portable implementation). This information is used as a hint
914 :			by the installation and update support (user can force installation of
915 :			feature regardless of this setting).</li>
916 :			<li> ws - optional windowing system specification. A comma-separated
917 :			list of ws designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt>
918 :			. Indicates this entry should only be installed on one of the specified
919 :			ws systems. If this attribute is not specified, the entry can be installed
920 :			on all systems (portable implementation). This information is used
921 :			as a hint by the installation and update support (user can force installation
922 :			of entry regardless of this setting).</li>
923 :			<li> nl - optional locale specification. A comma-separated
924 :			list of locale designators defined by Java. Indicates this entry should
925 :			only be installed on a system running with a compatible locale (using
926 :			Java locale-matching rules). If this attribute is not specified, the entry
927 :			can be installed on all systems (language-neutral implementation). This
928 :			information is used as a hint by the installation and update support (user
929 :			can force installation of entry regardless of this setting).</li>
930 :			<li> download-size - optional hint supplied by the feature
931 :			packager, indicating the download size in KBytes of the referenced data
932 :			archive. If not specified, the download size is not known (<b>Implementation
933 :			Note:</b> the implementation needs to distinguish between "not known"
934 :			and 0 size)</li>
935 :			<li> install-size - optional hint supplied by the feature
936 :			packager, indicating the install size in KBytes of the referenced
937 :			data archive. If not specified, the install size is not known (<b>Implementation
938 :			Note:</b> the implementation needs to distinguish between "not known"
939 :	celek	1.17	and 0 size)</li>
940 :	celek	1.18
941 :	celek	1.10	</ul>
942 :	celek	1.18
943 :	celek	1.9	</ul>
944 :	celek	1.18	<a name="Feature_Archive_Mapping_Id_To_Path"></a> When interacting
945 :			with the update site, the feature implementation maps the <tt><plugin></tt>
946 :			and <tt><data></tt> elements into path identifiers used by the
947 :			site to determine the actual files to download and install. The default
948 :			feature implementation supplied by Eclipse constructs the path identifiers
949 :			as follows:
950 :	celek	1.7	<ul>
951 :	celek	1.18	<li> <tt><plugin></tt> element results in a path entry
952 :			in the form "<tt>plugins/<pluginId>_<pluginVersion>.jar</tt>"
953 :	celek	1.17	(for example, "<tt>plugins/org.eclipse.core.boot_1.0.3.jar</tt>")</li>
954 :	celek	1.18	<li> <tt><data></tt> element results in a path entry
955 :			in the form "<tt>features/<featureId>_<featureVersion>/<dataId></tt>
956 :	celek	1.17	" (for example, "f<tt>eatures/com.xyz.tools_2.3.1/examples.zip</tt>")</li>
957 :	celek	1.18
958 :	celek	1.7	</ul>
959 :	celek	1.18	Note, that in general the feature.xml  manifest documents
960 :			should specify UTF-8 encoding. For example
961 :	celek	1.7	<p><tt><?xml version="1.0" encoding="UTF-8"?></tt> </p>
962 :	celek	1.18
963 :			<p>Translatable text contained in the feature.xml can be separated into feature<_locale>.properties
964 :			files using Java property bundle conventions. Note that the translated
965 :			strings are used at installation time (ie. do not employ the plug-in
966 :	celek	1.17	fragment runtime mechanism). </p>
967 :	celek	1.18
968 :	celek	1.9	<h3> <a name="Plug-In_Archive"></a> Plug-In Archive</h3>
969 :	celek	1.18	Plug-ins and plug-in fragments are individually packaged as
970 :			separate Java .jars. Standard Java jar facilities are used for constructing
971 :			plug-in archives. There is no distinction made between a plug-in archive
972 :			containing a plug-in and one containing a plug-in fragment.
973 :
974 :	celek	1.7	<p>The recommended convention for naming the plug-in archives is <br>
975 :	celek	1.18	<tt><id>_<version>.jar</tt> </p>
976 :
977 :			<p>Where <tt><id></tt> is the plug-in or fragment identifier and <tt>
978 :			<version></tt> is the full version identifier contained in the
979 :			respective plugin.xml or fragment.xml. Note that this is a recommended
980 :			convention that minimizes chance of collisions, but is not required by
981 :			the Eclipse architecture. For example, the following are valid plug-in
982 :	celek	1.17	archive names </p>
983 :	celek	1.18
984 :	celek	1.7	<p><tt>org.eclipse.platform_1.0.3.jar</tt> <br>
985 :	celek	1.18	<tt>org.eclipse.ui.nl_2.0.jar</tt> <br>
986 :			<tt>my_plugin.jar</tt> </p>
987 :
988 :			<p>Internally, each plug-in archive packages all the relevant plug-in or
989 :			fragment files relative to its plug-in or fragment directory (but not including
990 :			the directory path element). The archive has the following structure </p>
991 :
992 :	celek	1.7	<p><tt>plugin.xml OR fragment.xml</tt> <br>
993 :	celek	1.18	<tt>other plug-in or feature files and subdirectories</tt> <br>
994 :			<tt>META-INF/</tt> <br>
995 :			<tt>    Java jar manifest and security files</tt>
996 :	celek	1.17	</p>
997 :	celek	1.18
998 :	celek	1.9	<h3> <a name="Packaging_NL"></a> Packaging NL</h3>
999 :	celek	1.18	In Eclipse, translated plug-in information is packaged either
1000 :			together with the base plug-in, or as a plug-in fragment. At runtime,
1001 :			Eclipse locates the translations for the required locale. The use of
1002 :			fragments allows translations to be added to the runtime without the need
1003 :			to repackage the base plug-ins.
1004 :			<p>This mechanism cannot be used for translating the actual packaging information
1005 :			that is part of the installation xml files. Consequently the standard
1006 :			Java translation conventions are used for the packaging information,
1007 :			and all necessary translations must be available at the time the feature
1008 :			is packaged. </p>
1009 :
1010 :	celek	1.9	<h4> <a name="Translated_Feature_Information"></a> Translated Feature Information</h4>
1011 :	celek	1.18	<b>Note:</b> This section describes the conventions used for
1012 :			translating the information contained within the feature manifest.
1013 :			It allows for the update client to select the correctly localized strings
1014 :			from the update server. This section specifically does not describe
1015 :			localization of individual plug-ins.
1016 :			<p>Several of the attributes within the feature manifest are strings intended
1017 :			for display through user interfaces. To facilitate translation, these
1018 :			attribute values use the convention defined for translatable attributes
1019 :			of plugin.xml. Strings beginning with % up to the first space are treated
1020 :			as resource identifier keys (without the %) and looked up in a properties
1021 :			file. For example </p>
1022 :
1023 :	celek	1.7	<p><tt>label="%cfg Tool Feature for Linux"</tt> </p>
1024 :	celek	1.18
1025 :			<p>results in a resource lookup in the correct property file with key "cfg".
1026 :			If no property files are supplied, or the key is not found the default
1027 :			string value (following the %key) is used. </p>
1028 :
1029 :			<p>The property files are named as feature_<locale>.properties using
1030 :			the Java resource bundle naming conventions. Within the feature archive
1031 :			.jar they are placed in the same directory as their corresponding feature.xml
1032 :			file. </p>
1033 :
1034 :			<p><b>Implementation Note</b>: When accessing the resource bundles the Eclipse
1035 :			installation and update code should create a class loader for accessing
1036 :			the translated string. This way, the standard locale lookup algorithm
1037 :	celek	1.17	implemented by Java is automatically used. </p>
1038 :	celek	1.18
1039 :	celek	1.7	<p><tt>ResourceBundle b;</tt> <br>
1040 :	celek	1.18	<tt>ClassLoader l;</tt> <br>
1041 :			<tt>l = new URLClassLoader(new URL[] {<targetDirectoryURL>},
1042 :	celek	1.17	null);</tt> <br>
1043 :	celek	1.18	<tt>b = ResourceBundle.getBundle("feature",Locale.getDefault(),l);</tt>
1044 :			</p>
1045 :
1046 :			<p>The resulting resource bundle can be used in <tt>IPluginDescriptor.getResourceString(String,ResourceBundle)</tt>
1047 :			to actually return the correct translated string for the manifest attribute.
1048 :			</p>
1049 :
1050 :	celek	1.9	<h4> <a name="Translated_Plug-In_Information"></a> Translated Plug-In Information</h4>
1051 :	celek	1.18	No change from 1.0. Translated plug-in information should be
1052 :			packaged as plug-in fragments.
1053 :			<h3> <a name="Packaging_Target-Specific_Support"></a> Packaging Target-Specific
1054 :			Support</h3>
1055 :			No change from 1.0. Target-specific plug-in support (os, ws)
1056 :			should be packaged as plug-in fragments.
1057 :			<h3> <a name="Packaging_Attribution_Information"></a> Packaging Attribution
1058 :			Information</h3>
1059 :			This topic is covered in separate documents available on the
1060 :			eclipse.org development resources page of the Update component.
1061 :
1062 :	celek	1.9	<h3> <a name="Packaging_Non_Plug_In_Files"></a> Packaging Non-Plug-In Files</h3>
1063 :	celek	1.18	Arbitrary non-plug-in files can be included as part of the
1064 :			feature definition using the <tt><data></tt> elements. Non-plug-in
1065 :			files typically also requires specification of a custom install handler.
1066 :			In general, the Eclipse support only downloads the referenced non-plug-in
1067 :			files and calls the custom install handler to perform any actual installation
1068 :			steps.
1069 :	celek	1.7	<p>Eclipse does not specify the format of the non-plug-in files. </p>
1070 :	celek	1.18
1071 :	celek	1.9	<h3> <a name="Custom_Install_Handling"></a> Custom Install Handling</h3>
1072 :	celek	1.18	Custom install handlers are written as a Java class and are
1073 :			packaged as part of the <a href="#Feature_Archive">feature archive</a>
1074 :			. The installer must implement the <tt>IInstallHandler</tt> interface
1075 :			(in most cases will extend the <tt>BaseInstallHandler</tt> abstract helper
1076 :			class which implements <tt>IInstallHandler</tt>). When required, the
1077 :			install handler is dynamically loaded by the installation and update
1078 :			code, and is called at specific points during its processing. The install
1079 :			handler code has visibility to classes from the installation and update
1080 :			support plug-in, and its prerequisite plug-ins.
1081 :			<p><b>Implementation Note:</b> the detailed list of visible prerequisite
1082 :			plug-ins is still evolving. It is expected to include <tt>org.eclipse.core.boot
1083 :			</tt> and <tt>org.eclipse.core.runtime</tt> in all cases, plus <tt>org.eclipse.ui</tt>
1084 :			and <tt>org.eclipse.swt</tt> when running with full workbench (ie.
1085 :			not "headless mode"). Also, it would be useful to always expose <tt>org.eclipse.core.ant</tt>
1086 :			so that build scripts can be used as part of the install handler implementation.
1087 :			</p>
1088 :
1089 :			<p>The IInstallHandler interface supports the following methods [<b>Implementation
1090 :			Note:</b> the detailed definition of the IInstallHandler interface
1091 :			is still evolving. The description below is not an API specification
1092 :			(simply a functional description)]: </p>
1093 :
1094 :	celek	1.7	<ul>
1095 :	celek	1.18	<li> install-initiated - the install handler is called after
1096 :			a feature was selected for installation, but before any files were
1097 :			downloaded. It is intended to implement any custom click-through or
1098 :			user registration dialogs. The base implementation of this method supplied
1099 :			with the abstract class <tt>BaseInstallHandler </tt>performs
1100 :			the default click-through processing using the license text supplied
1101 :			as part of the feature manifest. On return this method indicates success
1102 :			(installation continues) of failure (installation is aborted).</li>
1103 :			<li> install-downloaded - the install handler is called after
1104 :			all the required feature files were downloaded (feature, plugins,
1105 :			data) but before the actual installation is performed. The install
1106 :			handler is expected to perform verification of the non-plug-in data
1107 :			files (eg. security), or any other pre-install processing.  On
1108 :			return this method indicates success (installation continues) or failure
1109 :			(installation is aborted).</li>
1110 :			<li> install-completion - the install handler is called after
1111 :			the feature information and the plug-ins were installed. It is expected
1112 :			to complete the installation of any non-plug-in data that was part of
1113 :			the feature. On return this method indicates success (returns custom install
1114 :			log) or failure (installation is aborted). On failure, the install handler
1115 :			is expected to perform any required cleanup.</li>
1116 :			<li> uninstall-initiated - the install handler is called when
1117 :			a feature is selected for removal, but before any of the standard uninstall
1118 :			processing has taken place. It is passed the custom install log created
1119 :			by the install handler install-completion step.</li>
1120 :			<li> uninstall-completion - the install handler is called
1121 :			on completion of the standard uninstall steps. It is passed the custom
1122 :	celek	1.17	install log created by the install handler install-completion step.</li>
1123 :	celek	1.18
1124 :	celek	1.7	</ul>
1125 :	celek	1.18	Note, that as a general practice, install handlers should be
1126 :			provided in their own jars (even though they could be just exposed
1127 :			in the feature archive jar). The jar should be signed, and sealed.
1128 :
1129 :	celek	1.9	<h3> <a name="Security_Considerations"></a> Security Considerations</h3>
1130 :	celek	1.18	The general approach is to use base Java jar signing for the
1131 :			feature and plug-in archive .jars.
1132 :	celek	1.7	<p>Features are verified as follows: </p>
1133 :	celek	1.18
1134 :	celek	1.7	<ul>
1135 :	celek	1.18	<li> download and verify the feature archive (use base Java
1136 :	celek	1.17	jar verification)</li>
1137 :	celek	1.18	<li> for each plug-in archive</li>
1138 :
1139 :	celek	1.14	<ul>
1140 :	celek	1.18	<li> verify the archive jar content (use base Java jar verification)</li>
1141 :			<li> verify plug-in id and version from <tt><plugin></tt>
1142 :			entry in feature manifest matches downloaded plugin.xml</li>
1143 :
1144 :	celek	1.7	</ul>
1145 :	celek	1.18	<li> for each non-plugin file</li>
1146 :
1147 :	celek	1.7	<ul>
1148 :	celek	1.18	<li> call install handler to verify file</li>
1149 :
1150 :	celek	1.10	</ul>
1151 :	celek	1.18
1152 :	celek	1.9	</ul>
1153 :	celek	1.18	In general, when processing signed jars, the user will be prompted
1154 :			for each unrecognized certificate. The response choices will include
1155 :			aborting the installation (originator is not trusted), continuing the
1156 :			installation (originator is trusted for this installation).
1157 :
1158 :	celek	1.9	<h2> <a name="Update_Server"></a> Update Server</h2>
1159 :	celek	1.18	The default Eclipse update server is any URL-accessible server.
1160 :			The default implementation assumes a fixed-layout server. The content
1161 :			of the server (in terms of available features and plug-ins) is described
1162 :			in a site map file, <i>site.xml</i>. This file can be manually maintained,
1163 :			or can be dynamically computed by the server.
1164 :	celek	1.9	<h3> <a name="Site_Map"></a> Site Map</h3>
1165 :	celek	1.18	The update server URL can be specified as a full URL to the
1166 :			site map file, or a URL of a directory path containing the site map
1167 :			file (similar to index.html processing). The site map site.xml format
1168 :			is defined by the following dtd:
1169 :	celek	1.7	<p><tt><?xml encoding="ISO-8859-1"?></tt> </p>
1170 :	celek	1.18
1171 :			<p><tt><!ELEMENT site (description?, feature, archive, category-def*)></tt>
1172 :	celek	1.17	<br>
1173 :	celek	1.18	<tt><!ATTLIST site</tt> <br>
1174 :			<tt>    type
1175 :			CDATA #IMPLIED</tt> <br>
1176 :			<tt>    url
1177 :			CDATA #IMPLIED</tt> <br>
1178 :			<tt>></tt> </p>
1179 :
1180 :	celek	1.7	<p><tt><!ELEMENT description (#PCDATA)></tt> <br>
1181 :	celek	1.18	<tt><!ATTLIST description</tt> <br>
1182 :			<tt>    url
1183 :			CDATA #IMPLIED</tt> <br>
1184 :			<tt>></tt> </p>
1185 :
1186 :	celek	1.7	<p><tt><!ELEMENT feature (category*)></tt> <br>
1187 :	celek	1.18	<tt><!ATTLIST feature</tt> <br>
1188 :			<tt>    type
1189 :			CDATA #IMPLIED</tt> <br>
1190 :			<tt>    id
1191 :			CDATA #IMPLIED</tt> <br>
1192 :			<tt>    version
1193 :	celek	1.17	CDATA #IMPLIED</tt> <br>
1194 :	celek	1.18	<tt>    url
1195 :			CDATA #REQUIRED<br>
1196 :			label
1197 :			CDATA #IMPLIED<br>
1198 :			</tt><tt>    os
1199 :			CDATA #IMPLIED</tt> <br>
1200 :			<tt>    arch
1201 :			CDATA #IMPLIED</tt> <br>
1202 :			<tt>    ws
1203 :			CDATA #IMPLIED</tt> <br>
1204 :			<tt>    nl
1205 :			CDATA #IMPLIED</tt><br>
1206 :			<tt>    patch      </tt><tt>
1207 :	celek	1.17	(true \| false) "false"</tt><br>
1208 :	celek	1.18	<tt> ></tt> </p>
1209 :
1210 :	celek	1.7	<p><tt><!ELEMENT archive EMPTY></tt> <br>
1211 :	celek	1.18	<tt><!ATTLIST archive</tt> <br>
1212 :			<tt>    path
1213 :			CDATA #REQUIRED</tt> <br>
1214 :			<tt>    url
1215 :			CDATA #REQUIRED</tt> <br>
1216 :			<tt>></tt> </p>
1217 :
1218 :	celek	1.7	<p><tt><!ELEMENT category EMPTY></tt> <br>
1219 :	celek	1.18	<tt><!ATTLIST category</tt> <br>
1220 :			<tt>    name
1221 :			CDATA #REQUIRED</tt> <br>
1222 :			<tt>></tt> </p>
1223 :
1224 :	celek	1.7	<p><tt><!ELEMENT category-def (description?)></tt> <br>
1225 :	celek	1.18	<tt><!ATTLIST category-def</tt> <br>
1226 :			<tt>    name
1227 :			CDATA #REQUIRED</tt> <br>
1228 :			<tt>    label
1229 :			CDATA #REQUIRED</tt> <br>
1230 :			<tt>></tt> </p>
1231 :
1232 :	celek	1.7	<p>The element and attribute definitions are as follows: </p>
1233 :	celek	1.18
1234 :	celek	1.7	<ul>
1235 :	celek	1.18	<li> <site> - defines the site map</li>
1236 :
1237 :	celek	1.7	<ul>
1238 :	celek	1.18	<li> type - optional site type specification. The value refers
1239 :			to a type string registered via the <a href="#Framework">install framework</a>
1240 :			extension point. If not specified, the type is assumed to be the default
1241 :	celek	1.17	Eclipse site type (as specified in this document).</li>
1242 :	celek	1.18	<li> url - optional URL defining the update site baseline
1243 :			URL (used to determine individual <feature> and <archive>
1244 :			location).  Can be relative or absolute. If relative, is relative
1245 :			to site.xml. If not specified, the default is the URL location of the
1246 :			site.xml file.</li>
1247 :
1248 :	celek	1.17	</ul>
1249 :	celek	1.18	<li> <description> - brief description as simple text.
1250 :	celek	1.17	Intended to be translated.</li>
1251 :	celek	1.18
1252 :	celek	1.17	<ul>
1253 :	celek	1.18	<li> url - optional URL for the full description as HTML. The
1254 :			URL can be specified as absolute of relative. If relative, If relative,
1255 :	celek	1.17	is relative to site.xml.</li>
1256 :	celek	1.18	<br>
1257 :			Note, that for NL handling the URL value should be separated
1258 :			to allow alternate URLs to be specified for each national language.
1259 :
1260 :			</ul>
1261 :			<li> <feature> - identifies referenced feature archive</li>
1262 :
1263 :			<ul>
1264 :			<li> type - optional feature type specification. The value
1265 :			refers to a type string registered via the <a href="#Framework">install
1266 :			framework</a> extension point. If not specified, the type is assumed
1267 :			to be the default feature type for the site. If the site type is the
1268 :			default Eclipse site type, the default feature type is the packaged
1269 :			feature type (as specified in this document).</li>
1270 :			<li> id - optional feature identifier. The information is
1271 :			used as a performance optimization to speed up searches for features.
1272 :			Must match the identifier specified in the feature.xml of the referenced
1273 :			archive (the url attribute). If specified, the version attribute must
1274 :	celek	1.17	also be specified.</li>
1275 :	celek	1.18	<li> version - optional feature version. The information is
1276 :			used as a performance optimization to speed up searches for features.
1277 :			Must match the version specified in the feature.xml of the referenced
1278 :			archive (the url attribute). If specified, the id attribute must also be
1279 :			specified.</li>
1280 :			<li> url - required URL reference to the feature archive.
1281 :			Can be relative or absolute. If relative, it is relative to the location
1282 :			of the site.xml file. <b>Note</b>: the default site implementation
1283 :			allows features to be accessed without being explicitly declared using
1284 :			a <feature> entry. By default, an undeclared features reference is
1285 :	celek	1.17	interpreted as "features/<id>_<version>.jar"</li>
1286 :	celek	1.18	<li>label - optional feature label. The value is used for
1287 :			optimization when browsing the site from the update manager. Intended
1288 :	celek	1.17	to be translated.<br>
1289 :	celek	1.18	</li>
1290 :			<li> os - optional operating system specification. A comma-separated
1291 :			list of os designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt>
1292 :			. Indicates this feature should only be installed on one of the specified
1293 :			os systems. If this attribute is "*", the feature can be installed
1294 :			on all systems (portable implementation). This information is used as
1295 :			a hint by the installation and update support (user can force installation
1296 :			of feature regardless of this setting).</li>
1297 :			<li> arch - optional machine architecture specification. A
1298 :			comma-separated list of architecture designators defined by Eclipse
1299 :			(see Javadoc for <tt> org.eclipse.core.boot.BootLoader)</tt>. Indicates
1300 :			this feature should only be installed on one of the specified systems.
1301 :			If this attribute is "*", the feature can be installed on all systems
1302 :			(portable implementation). This information is used as a hint by the
1303 :			installation and update support (user can force installation of feature
1304 :			regardless of this setting).</li>
1305 :			<li> ws - optional windowing system specification. A comma-separated
1306 :			list of ws designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt>
1307 :			. Indicates this feature should only be installed on one of the specified
1308 :			ws systems. If this attribute is "*", the feature can be installed
1309 :			on all systems (portable implementation). This information is used
1310 :			as a hint by the installation and update support (user can force installation
1311 :			of feature regardless of this setting).</li>
1312 :			<li> nl - optional locale specification. A comma-separated
1313 :			list of locale designators defined by Java. Indicates this feature should
1314 :			only be installed on a system running with a compatible locale (using
1315 :			Java locale-matching rules). If this attribute is "*", the feature
1316 :			can be installed on all systems (language-neutral implementation). This
1317 :			information is used as a hint by the installation and update support (user
1318 :			can force installation of feature regardless of this setting).</li>
1319 :			<li>patch - optional specification indicating if this feature
1320 :			is a patch. Default is "false". </li>
1321 :
1322 :	celek	1.16	</ul>
1323 :	celek	1.18	<li> <archive> - identifies referenced "storage" archive
1324 :			(the actual files referenced via the <tt><plugin></tt> or <tt><data></tt>
1325 :			elements in the feature manifest). The site simply manages archives
1326 :			as a path-to-URL map. The default Eclipse site implementation does not
1327 :			require the <archive> section to be included in the site map (site.xml).
1328 :			Any archive reference not explicitly defined as part of an <archive>
1329 :			section is assumed to be mapped to a url in the form "<archivePath>"
1330 :	celek	1.17	relative to the location of the site.xml file.</li>
1331 :	celek	1.18
1332 :	celek	1.14	<ul>
1333 :	celek	1.18	<li> path - required archive path identifier. This is a string
1334 :			that is determined by the <a
1335 :			href="#Feature_Archive_Mapping_Id_To_Path">feature</a> referencing
1336 :			this archive and is not otherwise interpreted by the site (other than
1337 :			as a lookup token).</li>
1338 :			<li> url - required URL reference to the archive. Can be relative
1339 :			or absolute. If relative, it is relative to the location of the site.xml
1340 :			file.</li>
1341 :
1342 :	celek	1.16	</ul>
1343 :	celek	1.18	<li> <category-def> - an optional definition of a category
1344 :			that can be used by installation and update support to hierarchicaly
1345 :	celek	1.17	organize features</li>
1346 :	celek	1.18
1347 :	celek	1.16	<ul>
1348 :	celek	1.18	<li> name - category name. Is specified as a path of name tokens
1349 :			separated by /</li>
1350 :			<li> label - displayable label. Intended to be translated.</li>
1351 :
1352 :	celek	1.16	</ul>
1353 :	celek	1.18	<li> <category> - actual category specification for
1354 :			a feature entry</li>
1355 :
1356 :	celek	1.9	<ul>
1357 :	celek	1.18	name - category name
1358 :	celek	1.13	</ul>
1359 :	celek	1.18
1360 :	celek	1.7	</ul>
1361 :	celek	1.18	Note, that in general the feature.xml  manifest documents
1362 :			should specify UTF-8 encoding. For example
1363 :	celek	1.7	<p><tt><?xml version="1.0" encoding="UTF-8"?></tt> </p>
1364 :	celek	1.18
1365 :			<p>Translatable text contained in the site.xml can be separated into site<_locale>.properties
1366 :			files using Java property bundle conventions. Note that the translated
1367 :			strings are used at installation time (ie. do not employ the plug-in
1368 :			fragment runtime mechanism). The property bundles are located relative
1369 :			to the site.xml location. </p>
1370 :
1371 :	celek	1.9	<h3> <a name="Default_Site_Layout"></a> Default Site Layout</h3>
1372 :	celek	1.18	<tt><site root>/</tt> <br>
1373 :			<tt>    site.xml</tt> <br>
1374 :			<tt>    features/</tt> <br>
1375 :			<tt>        feature archives
1376 :			(eg. org.eclipse.javatools_1.0.1.jar)</tt> <br>
1377 :			<tt>        <featureId>_<featureVersion>/
1378 :			(optional)</tt> <br>
1379 :			<tt>
1380 :	celek	1.17	non-plug-in files for feature</tt> <br>
1381 :	celek	1.18	<tt>    plugins/</tt> <br>
1382 :			<tt>        plug-in argives
1383 :			(eg. org.eclipse.ui_1.0.3.jar)</tt>
1384 :	celek	1.9	<h3> <a name="Controlling_Access"></a> Controlling Access</h3>
1385 :	celek	1.18	The default Eclipse site implementation provides support for
1386 :			http access with basic user authentication (userid and password).
1387 :
1388 :			<p>Custom access control mechanisms can be added to base Eclipse in one of
1389 :	celek	1.17	2 ways: </p>
1390 :	celek	1.18
1391 :	celek	1.7	<ul>
1392 :	celek	1.18	<li> by supplying server-side logic on the update server (eg.
1393 :			implementing servlets that compute the site.xml map, and control access
1394 :	celek	1.17	to individual archives based on some user criteria)</li>
1395 :	celek	1.18	<li> by supplying a custom concrete implementation of the
1396 :			site object (installed on the client machine, update server specified
1397 :			<tt><site type=""></tt> ). The custom concrete site implementation,
1398 :			together with any server-side logic support the required control mechanisms.</li>
1399 :
1400 :	vlad	1.1	</ul>
1401 :	celek	1.18	Eclipse provides an example demonstrating an implementation
1402 :			of an access mechanism based on feature key files.
1403 :	celek	1.9	<h2> <a name="Eclipse_Install"></a> Eclipse Install</h2>
1404 :	celek	1.18
1405 :	celek	1.9	<h3> <a name="Default_Install_Layout"></a> Default Install Layout</h3>
1406 :	celek	1.18	<tt><install root>/</tt> <br>
1407 :			<tt>    install/</tt> <br>
1408 :			<tt>        features/</tt>
1409 :			<br>
1410 :			<tt>
1411 :	celek	1.17	<featureId>_<version>/</tt> <br>
1412 :	celek	1.18	<tt>
1413 :			feature.xml</tt> <br>
1414 :			<tt>
1415 :			other feature files</tt> <br>
1416 :			<tt>
1417 :			META-INF/</tt> <br>
1418 :			<tt>
1419 :			META-INF-ECLIPSE/</tt>
1420 :	celek	1.7	<p><tt>    plugins/</tt> <br>
1421 :	celek	1.18	<tt>        <pluginORfragmentId>_<version>/</tt>
1422 :	celek	1.17	<br>
1423 :	celek	1.18	<tt>
1424 :	celek	1.17	plugin.xml or fragment.xml</tt> <br>
1425 :	celek	1.18	<tt>
1426 :	celek	1.17	other plugin or fragment files</tt> <br>
1427 :	celek	1.18	<tt>
1428 :	celek	1.17	META_INF/</tt> </p>
1429 :	celek	1.18
1430 :			<p><b>Implementation Note:</b> we will go back to the original design of
1431 :			not splitting out fragments (ie. plugin and fragments go into the same install
1432 :	celek	1.17	location) </p>
1433 :	celek	1.18
1434 :	celek	1.9	<h3> <a name="Unmanaged_Plugins"></a> "Unmanaged" Plug-Ins</h3>
1435 :	celek	1.18	Eclipse supports a concept of "unmanaged" plug-ins. These are
1436 :			plug-ins that were directly installed into the Eclipse file tree without
1437 :			being part of a feature (eg. developer unzipping plug-in archive directly
1438 :			into the Eclipse file tree).
1439 :			<p>Eclipse runtime recognizes these plugins during startup and loads the
1440 :			plug-in information into the runtime registry following the standard plug-in
1441 :			binding rules. The update support also recognizes the presence of this new
1442 :			plug-in, but since this plug-in is not part of any feature it cannot be updated
1443 :			using the update support (hence "unmanaged"). Unmanaged plug-in that become
1444 :			referenced by a feature as a result of some future installation or update
1445 :			action become "managed" (can be updated as part of the feature). </p>
1446 :
1447 :			<p>Unmanaged plug-ins are not displayed as part of the installation and update
1448 :	celek	1.17	UI. </p>
1449 :	celek	1.18
1450 :			<h3> <a name="Using_Native_Platform_Installers"></a> Using Native Platform
1451 :			Installers</h3>
1452 :			The Eclipse installation contains plugins that can be shared
1453 :			across multiple features. When installing and uninstalling features
1454 :			using the Eclipse installation and update support, these relationship
1455 :			are correctly maintained. Only one copy of any version of a plug-in is
1456 :			used.
1457 :			<p>However, when using native platform installers, performing native uninstall
1458 :			creates problems because plug-ins would be removed without regard
1459 :			to any sharing relationships. As a result, Eclipse <b>does not allow</b>
1460 :			plug-ins to be installed using native installers into the shared installation
1461 :			tree. Instead, native installers must establish their own installation
1462 :			root directory. The subdirectory structure is the same as defined for
1463 :			base Eclipse. The private root directory is logically linked into the shared
1464 :			Eclipse installation via a link file installed by the native installer.
1465 :			The file path for the link file is <tt><configRoot>/links/</tt>.
1466 :			The <tt><configRoot> </tt> location is computed by Eclipse relative
1467 :			to the launch <a href="#Multiple%20Launch%20Points"> configuration file</a>
1468 :			. By default, this is the <tt>install/</tt> directory in the shared
1469 :			Eclipse installation tree. </p>
1470 :
1471 :			<p>The name of the link file is not specified by Eclipse. The name is determined
1472 :			by the native installer. To minimize the potential for naming collisions,
1473 :			it is recommended that the file name contain the identifier and version
1474 :			of the feature being installed by the native installer. For example,
1475 :			<tt><featureId>_<featureVersion>.properties</tt> . The file
1476 :			content is in the form of a Java properties file, with the following
1477 :			properties defined: </p>
1478 :
1479 :	celek	1.7	<p><tt>path=[r\|rw] install-path[,[r\|rw] install-path]*</tt> </p>
1480 :	celek	1.18
1481 :			<p>The property <tt>path</tt> is a comma-separated list of optionally annotated
1482 :			install paths. The property value <tt>install-path</tt> is a full
1483 :			file path to the installation directory root, specified in local OS
1484 :			format. The optional annotation <tt>r</tt> or <tt>rw</tt> indicates whether
1485 :			Eclipse update support should allow the specified location to be used
1486 :			for updates. Default is to allow updates  (w). </p>
1487 :
1488 :			<p>Eclipse does not manage the linked directories in any way. It simply detects
1489 :			their existence by the presence of the link files, and includes the
1490 :			linked plug-ins during the platform startup. The native installer is
1491 :			responsible for uninstalling the link when the corresponding directory
1492 :			is removed. Eclipse runtime ignores any links that cannot be resolved.
1493 :	celek	1.17	<br>
1494 :	celek	1.18	</p>
1495 :			<br>
1496 :	celek	1.17	<br>
1497 :	celek	1.16	<br>
1498 :	celek	1.15	<br>
1499 :	celek	1.14	<br>
1500 :			<br>
1501 :	celek	1.18	<br>
1502 :			<br>
1503 :	celek	1.17	<br>
1504 :	celek	1.16	<br>
1505 :	vlad	1.1	</body>
1506 :			</html>

help@eclipse.org	ViewVC Help
Powered by ViewVC 1.0.3

Eclipse

platform-update-home/doc/eclipse_update_packaging.html