platform-update-home/doc/eclipse_update_packaging.html

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

help@eclipse.org	ViewVC Help
Powered by ViewVC 1.0.3

Eclipse

platform-update-home/doc/eclipse_update_packaging.html