-
Notifications
You must be signed in to change notification settings - Fork 66
/
bundle_manifest.html
477 lines (388 loc) · 17 KB
/
bundle_manifest.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html lang="en">
<head>
<meta name="copyright" content="Copyright (c) IBM Corporation and others 2005, 2011. This page is made available under license. Full for details see the LEGAL in the documentation book that contains this page." >
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<link REL="STYLESHEET" HREF="../../book.css" CHARSET="ISO-8859-1" TYPE="text/css">
<title>OSGi Bundle Manifest</title>
</head>
<body>
<div class="Section1">
<h1>OSGi Bundle Manifest Headers</h1>
<p><i>Version 3.3 - Last revised April 27, 2011</i></p>
<p>
A bundle can carry descriptive information about itself in the manifest file
named META-INF/MANIFEST.MF. The OSGi R7 Framework specification defines a set of
manifest headers such as Export-Package and Bundle-Classpath, which bundle developers
use to supply descriptive information about a bundle. The Equinox OSGi Framework
implements the complete OSGi R7 Framework specification and all of the Core Framework
services. The OSGi R7 Core Framework services include the following:</p>
<ul>
<li>Package Admin Service Specification (deprecated) - consider using the new org.osgi.framework.wiring package</li>
<li>URL Handlers Service Specification</li>
<li>Start Level Service Specification(deprecated) - consider using the new org.osgi.framework.startlevel package</li>
<li>Conditional Permission Admin Specification</li>
<li>Permission Admin Service Specification</li>
</ul>
<p> There are a number of optional services defined in the OSGi R7 compendium specification.
The optional services are not included with the Equinox OSGi Framework implementation.
For information on OSGi R7 manifest headers and services refer to the <a href="https://docs.osgi.org/specification/">OSGi
specifications</a>. </p>
<h2>Eclipse Bundle Manifest Headers</h2>
<p>
The Eclipse OSGi Framework supports a number of additional bundle manifest headers
and directives. A bundle developer may use these additional headers and directives
to take advantage of some additional features of the Eclipse OSGi Framework which
are not specified as part of a standard OSGi Framework.
</p>
<h3>Additional Export-Package Directives</h3>
<p>
The Eclipse OSGi Framework supports additional directives on the Export-Package
header. These directives are used to specify the access restriction rules of an
exported package. See <a href="runtime-options.html#osgiresolvermode">osgi.resolverMode</a>
to configure the Eclipse OSGi Framework to enforce the access restriction rules at
runtime.
</p>
<h4>The x-internal Directive</h4>
<p>
The x-internal directive can be used in an Export-Package header to specify whether
the package is an internal package. The Plug-in Development Environment will discourage
other bundles from using an internal package. If the x-internal directive is not
specified then a default value of 'false' is used. The x-internal directive must
use the following syntax:
</p>
<pre>
x-internal ::= ( 'true' | 'false' )
</pre>
<p>
The following is an example of the x-internal directive:
</p>
<pre>
Export-Package: org.eclipse.foo.internal; x-internal:=true
</pre>
<h4>The x-friends Directive</h4>
<p>
The x-friends directive can be used in an Export-Package header to specify a list
of bundles which are allowed access to the package. The Plug-in Development
Environment will discourage other bundles from using the package. The x-friends
directive must use the following syntax:
</p>
<pre>
x-friends ::= '"' ( target-bundle ) ( ',' target-bundle ) * '"'
target-bundle ::= a bundle symbolic name
</pre>
<p>
The following is an example of the x-friends directive:
</p>
<pre>
Export-Package: org.eclipse.foo.formyfriends; x-friends:="org.eclipse.foo.friend1, org.eclipse.foo.friend2"
</pre>
<p>
The example specifies that only the bundles org.eclipse.foo.friend1 and
org.eclipse.foo.friend2 should be encouraged to use the org.eclipse.foo.formyfriends
package. The x-internal package takes priority over the x-friends directive. If
the x-internal directive specifies 'true' then The Plug-in Development
Environment will discourage all bundles from using the package even if they are
specified as a friend.
</p>
<h3>The Eclipse-LazyStart Header</h3>
<p>
The Eclipse-LazyStart header is used to specify if a bundle should be started
before the first class or resource is accessed from that bundle.
This feature allows Eclipse to activate bundles lazily the first time they are
needed. Using this model Eclipse can startup with as few active bundles as
possible. The Eclipse-LazyStart header must use the following syntax:
</p>
<pre>
Eclipse-LazyStart ::= ( 'true' | 'false' ) ( ';' 'exceptions' '=' '"' exceptions-list '"' ) ?
exceptions-list ::= a comma ',' separated list of packages
</pre>
<p>
When Eclipse-LazyStart is true, the 'exceptions' attribute specifies a list of
packages that <b>will not</b> cause the bundle to be activated when classes are
loaded from them.
When Eclipse-LazyStart is false, the 'exceptions' attribute specifies a list of
packages that <b>will</b> cause the bundle to be activated when classes are
loaded from them.
The exception rules apply to all classes in the listed packages. When a bundle
is activated the bundle's BundleActivator.start(BundleContext) method will be
called.
</p>
<p>
If the Eclipse-LazyStart header is not defined in the bundle manifest then a default
value of 'false' is used. The following is an example of the Eclipse-LazyStart header:
</p>
<pre>
Eclipse-LazyStart: true; exceptions="org.eclipse.foo1, org.eclipse.foo2"
</pre>
<p>
The example specifies that this bundle must be activated for any classes
that are loaded from this bundle, except the classes in the packages
'org.eclipse.foo1' and 'org.eclipse.foo2'.
</p>
<p>
The Eclipse-AutoStart and Eclipse-LazyStart headers have been deprecated in Eclipse 3.4.
As of the OSGi R4.1 specification the lazy activation policy has been adopted by the OSGi
specification. The new OSGi bundle manifest header Bundle-ActivationPolicy can be used to
specify a lazy activation policy.
</p>
<p>
The Equinox Framework version 3.4 or later will continue to support the deprecated Eclipse-LazyStart and
Eclipse-AutoStart headers. Bundle developers that want their bundles to work across other OSGi
Framework implementations should add the Bundle-ActivationPolicy header to their manifest. In most cases you can simply add the following header:
</p>
<pre>
Bundle-ActivationPolicy: lazy
</pre>
<p>
If the 'exceptions' attribute is used with the Eclipse-LazyStart or Eclipse-AutoStart header then the 'include' or 'exclude' directive can be used
with the Bundle-ActivationPolicy header. Consider the following Eclipse-LazyStart header:
</p>
<pre>
Eclipse-LazyStart: true; exceptions="org.eclipse.foo1, org.eclipse.foo2"
</pre>
<p>
The equivalent Bundle-ActivationPolicy header would be the following:
</p>
<pre>
Bundle-ActivationPolicy: lazy; exclude:="org.eclipse.foo1, org.eclipse.foo2"
</pre>
<p>
The following is an example Eclipse-LazyStart header that uses a false value with the exceptions attribute:
</p>
<pre>
Eclipse-LazyStart: false; exceptions="org.eclipse.foo1, org.eclipse.foo2"
</pre>
<p>
The equivalent Bundle-ActivationPolicy header would be the following:
</p>
<pre>
Bundle-ActivationPolicy: lazy; include:="org.eclipse.foo1, org.eclipse.foo2"
</pre>
<h3>The Eclipse-PlatformFilter Header</h3>
<p>
The Eclipse-PlatformFilter is used to specify a platform filter for a bundle. A platform
filter must evaluate to true in a running platform in order for a bundle to be allowed
to resolve. The Eclipse-PlatformFilter header must use the following syntax:
</p>
<pre>
Eclipse-PlatformFilter ::= a valid LDAP filter string
</pre>
<p>
The Framework supports filtering on the following system properties:
</p>
<ul type="disc">
<li><b>osgi.nl</b> - the platform language setting.</li>
<li><b>osgi.os</b> - the platform operating system.</li>
<li><b>osgi.arch</b> - the platform architecture.</li>
<li><b>osgi.ws</b> - the platform windowing system.</li>
</ul>
<p>
The following is an example of the Eclipse-PlatformFilter header:
</p>
<pre>
Eclipse-PlatformFilter: (& (osgi.ws=win32) (osgi.os=win32) (osgi.arch=x86))
</pre>
<p>
This example specifies that this bundle can only be resolved if the platform
properties are osgi.ws=win32 and osgi.os=win32 and osgi.arch=x86. In other words
a platform running on an x86 architecture, using a win32 operating system and
the win32 windowing system.
</p>
<h3>The Eclipse-BuddyPolicy Header</h3>
<p>
The Eclipse-BuddyPolicy header is used to specify the buddy classloading policies for a bundle.
The Eclipse-BuddyPolicy header must use the following syntax:
</p>
<pre>
Eclipse-BuddyPolicy ::= ( policy-name ) ( ',' policy-name ) *
policy-name ::= ( 'dependent' | 'global' | 'registered' |
'app' | 'ext' | 'boot' | 'parent' )
</pre>
<p>
The following is an example of the Eclipse-BuddyPolicy header:
</p>
<pre>
Eclipse-BuddyPolicy: dependent
</pre>
<h3>The Eclipse-RegisterBuddy Header</h3>
<p>
The Eclipse-RegisterBuddy header is used to declare a comma-separated list of symbolic names of
bundles that this bundle should be a registered buddy to. The bundles with the specified
symbolic names must use the <b>registered</b> buddy policy (specified by the Eclipse-BuddyPolicy)
header) in order for this bundle to be a registered buddy.
</p>
<p>
Note that the following conditions must be met before a bundle <b>X</b> can become a registered
buddy of another bundle <b>Y</b>:
</p>
<ul>
<li>The bundle <b>Y</b> must specify the <b>registered</b> buddy policy (i.e. Eclipse-BuddyPolicy:
registered) </li>
<li>The bundle <b>X</b> must specify the symbolic name of <b>Y</b> in the Eclipse-RegisterBuddy
header (i.e Eclipse-RegisterBuddy: Y) </li>
<li>The bundle <b>X</b> must be dependent on a package exported by bundle <b>Y</b>. This can
happen through either a Require-Bundle or Import-Package constraint. </li>
</ul>
<p>
The syntax of the Eclipse-RegisterBuddy header is the following:
</p>
<pre>
Eclipse-RegisterBuddy ::= ( target-bundle ) ( ',' target-bundle ) *
target-bundle ::= a bundle symbolic name
</pre>
<p>
The following is an example of the Eclipse-RegisterBuddy header:
</p>
<pre>
Eclipse-RegisterBuddy: org.eclipse.foo.bundle1, org.eclipse.foo.bundle2
</pre>
<h3>The Eclipse-ExtensibleAPI Header</h3>
<p>
The Eclipse-ExtensibleAPI is used to specify whether a host bundle allows fragment bundles
to add additional API to the host. This header should be used if a host bundle wants to allow
fragments to add additional packages to the API of the host. If this header is not
specified then a default value of 'false' is used. Note that this header is only used by tooling
(PDE) to construct proper class paths for building. <b>The runtime does not use this header
at all.</b> At runtime a fragment is always allowed to add additional packages, classes and
resources to the API of the host. The Eclipse-ExtensibleAPI header must use the following
syntax:
</p>
<pre>
Eclipse-ExtensibleAPI ::= ( 'true' | 'false' )
</pre>
<p>
The following is an example of the Eclipse-ExtensibleAPI header:
</p>
<pre>
Eclipse-ExtensibleAPI: true
</pre>
<h3>The Eclipse-BundleShape Header</h3>
<p>
The Eclipse-BundleShape header is used to specify the deployment shape a bundle should use when
the bundle is provisioned to an Eclipse installation.
<b>The runtime does not use this header at all.</b> This header is only used by the build and
provisioning systems to determine how to deploy a bundle. The Eclipse-BundleShape header must
use the following syntax:
</p>
<pre>
Eclipse-BundleShape ::= ( 'jar' | 'dir' )
</pre>
<p>
The "jar" value indicates that the bundle should be deployed as a jar. The "dir"
value indicates that the bundle should be unpacked into a directory when deployed to an Eclipse installation.
</p>
<p>
If a product uses PDE to build a feature based product then, if specified, the value of the unpack attribute in the feature.xml file
takes precedence over the Eclipse-BundleShape header.
</p>
<p>
The following is an example of the Eclipse-BundleShape header:
</p>
<pre>
Eclipse-BundleShape: jar
</pre>
<h3>The Eclipse-GenericCapability Header</h3>
<p>
<b>Note:</b> the Eclipse-GenericCapability header has been deprecated. The OSGi R4.3 Core Framework
specification includes a new header <b>Provide-Capability</b> which can be used to specify
generic capabilities provided by a bundle. Equinox will continue to support both the
Eclipse-GenericCapability header and the new OSGi Provide-Capability header.
</p>
<p>
The Eclipse-GenericCapability header is used to specify a generic capability
of a bundle. Generic capabilities can be used to describe features of your
bundle which can be required by other bundles in the system (using the
Eclipse-GenericRequire header). Generic capabilities are given a name
and a capability type. Capability types are defined by the bundle which is
offering the capability. Capabilities can also have a set of typed matching
attributes which are used to match against when resolving Eclipse-GenericRequire
headers. Matching attributes may be one of the following types;
[string | version | uri | long | double | set]. The set type can be used
to define a set of strings as a comma separated list of strings.
The Eclipse-GenericCapability header must use the following syntax:
</p>
<pre>
Eclipse-GenericCapability ::= capability ( ',' capability ) *
capability ::= typed-name ( ';' typed-name ) *
( ';' typed-param ) *
typed-name ::= name ( ':' capability-type )
typed-param ::= typed-key '=' quouted-string
typed-key ::= name ( ':'
[string | version | uri | long | double | set] )</pre>
<p>
The following is an example of the Eclipse-GenericCapability header that could be used
to specify a bundle with an OSGi service org.acme.stuff.SomeService implementation:
</p>
<pre>
Eclipse-GenericCapability:
org.acme.stuff.SomeService:osgi.service;
version:version="1.0.1"</pre>
<h3>The Eclipse-GenericRequire Header</h3>
<p>
<b>Note:</b> the Eclipse-GenericRequire header has been deprecated. The OSGi R4.3 Core Framework
specification includes a new header <b>Require-Capability</b> which can be used to specify
a requirement on a generic capabilities provided by another bundle. Equinox will continue to
support both the Eclipse-GenericRequire header and the new OSGi Require-Capability header.
</p>
<p>
The Eclipse-GenericRequire header is used to specify a requirement on a generic
capability which is offered by another bundle (using the Eclipse-GenericCapability
header). Generic requirements are given a name and a capability type. Capability
types are defined by the bundle which is offering the capability. Generic
requirements can specify an LDAP filter string which is used as a selection filter
to resolve against matching generic capabilities.
The Eclipse-GenericRequire header must use the following syntax:
</p>
<pre>
Eclipse-GenericRequire ::= generic-require ( ',' generic-require ) *
generic-require ::= typed-name ( ';' typed-name ) *
( ';' selection-filter '=' quoated-ldapFilter )
( ';' optional '=' [true|false] )
( ';' multiple '=' [true|false] )
typed-name ::= name ( ':' capability-type )</pre>
<p>
The following is an example of the Eclipse-GenericRequire header that could be used
to specify a bundle that depends on an OSGi service org.acme.stuff.SomeService
implementation:
</p>
<pre>
Eclipse-GenericRequire:
org.acme.stuff.SomeService:osgi.service;
selection-filter="(version>=1.0.1)"</pre>
<h3>Generic Aliases</h3>
<p>
The <a href="runtime-options.html#osgigenericAliases">osgi.genericAliases</a> option
can be used to map existing OSGi manifest headers onto Eclipse-GenericCapability and
Eclipse-GenericRequire manifest headers. For example, consider the following manifest
headers
</p>
<pre>
Export-Service: org.acme.stuff.SomeService
Import-Service: org.acme.stuff.SomeService</pre>
<p>
These headers can be mapped to Eclipse-GenericCapability and Eclipse-GenericRequire
headers using the following property:
</p>
<pre> osgi.genericAliases=Export-Service:Import-Service:osgi.service</pre>
<p>
Under the covers this would translate into the following generic headers:
</p>
<pre>
Eclipse-GenericRequire: org.acme.stuff.SomeService:osgi.service
Eclipse-GenericCapability: org.acme.stuff.SomeService:osgi.service
</pre>
<h3>The Plugin-Class Header</h3>
<p>
The Plugin-Class header is only used to support plugins developed for the Eclipse 2.1
platform. This header is used to specify a class name that will be used to activate
a plug-in using the old Eclipse 2.1 activation model. New bundles developed for
Eclipse 3.0 or greater should not use this header.
The following is an example of the Plugin-Class header:
</p>
<pre>
Plugin-Class: org.eclipse.foo.FooPlugin
</pre>
</div>
</body>
</html>