Gitiles
Code Review Sign In
gerrit.onosproject.org / onos-felix / 9ceeebda4e43f8be39302c6658c025894cc54e43 / . / bundleplugin / doc / apache-felix-maven-bundle-plugin-bnd.html
blob: be895cf4ef7b1e456a119f7ae060869cad4b2f77 [file] [log] [blame]
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
Stuart McCulloch981bd342008-05-03 12:49:39 +0000[diff] [blame]2<html><head>
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]3
4
5
Stuart McCulloch981bd342008-05-03 12:49:39 +0000[diff] [blame]6 <title>Apache Felix - Apache Felix Maven Bundle Plugin (BND)</title>
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]7 <link rel="stylesheet" href="apache-felix-maven-bundle-plugin-bnd_files/site.css" type="text/css" media="all">
Stuart McCulloch981bd342008-05-03 12:49:39 +0000[diff] [blame]8 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
9 </head><body>
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]10 <div class="title"><div class="logo"><a href="http://felix.apache.org/site/index.html"><img alt="Apache Felix" src="apache-felix-maven-bundle-plugin-bnd_files/logo.png" border="0"></a></div><div class="header"><a href="http://www.apache.org/"><img alt="Apache" src="apache-felix-maven-bundle-plugin-bnd_files/apache.png" border="0"></a></div></div>
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]11 <div class="menu">
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]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 &gt;
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]268 <li><a href="http://felix.apache.org/site/news.html" title="news">news</a></li>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]269 <li><a href="http://felix.apache.org/site/license.html" title="license">license</a></li>
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]270 <li><a href="http://felix.apache.org/site/downloads.cgi" rel="nofollow">downloads</a></li>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]271 <li><a href="http://felix.apache.org/site/documentation.html" title="documentation">documentation</a></li>
272 <li><a href="http://felix.apache.org/site/mailinglists.html" title="mailinglists">mailing lists</a></li>
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]273 <li><a href="http://felix.apache.org/site/contributing.html" title="Contributing">contributing</a></li>
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]274 <li><a href="http://www.apache.org/" rel="nofollow">asf</a></li>
275 <li><a href="http://www.apache.org/foundation/sponsorship.html" rel="nofollow">sponsorship</a></li>
276 <li><a href="http://www.apache.org/foundation/thanks.html" rel="nofollow">sponsors</a>
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]277<!-- ApacheCon Ad -->
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]278<iframe src="apache-felix-maven-bundle-plugin-bnd_files/button.html" style="border-width: 0pt; float: left;" scrolling="no" width="135" frameborder="0" height="135"></iframe>
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]279<p style="height: 100px;">
280<!-- ApacheCon Ad -->
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]281&lt;
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
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653 </p></li></div>
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]654 <div class="main">
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]655<h1><a name="ApacheFelixMavenBundlePlugin(BND)-BundlePluginforMaven"></a>Bundle Plugin for Maven</h1>
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]656
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]657<p>This plugin for Maven 2 is based on the <a href="http://www.aqute.biz/Code/Bnd" rel="nofollow">BND</a>
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]658tool from Peter Kriens. The way BND works is by treating your project
659as a big collection of classes (e.g., project code, dependencies, and
660the class path). The way you create a bundle with BND is to tell it the
661content of the bundle's JAR file as a subset of the available classes.
662This plugin wraps BND to make it work specifically with the Maven 2
663project structure and to provide it with reasonable default behavior
664for Maven 2 projects.</p>
665
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]666<div class="panelMacro"><table class="infoMacro"><colgroup><col width="24"><col></colgroup><tbody><tr><td valign="top"><img src="apache-felix-maven-bundle-plugin-bnd_files/information.gif" alt="" align="absmiddle" border="0" width="16" height="16"></td><td>If you have questions about the maven-bundle-plugin please read the <a href="http://felix.apache.org/site/apache-felix-bundle-plugin-faq.html" rel="nofollow">FAQ</a> first. If you still have questions you can ask them on the <a href="http://felix.apache.org/site/mailinglists.html" rel="nofollow">Felix user list</a>.</td></tr></tbody></table></div>
667
Stuart McCulloch738a06d2009-02-27 06:38:33 +0000[diff] [blame]668<p><em>NOTE: test scoped dependencies are <b>not</b> included in the classpath seen by BND.</em></p>
Stuart McCullochb4212cc2008-08-05 06:36:05 +0000[diff] [blame]669
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000[diff] [blame]670<p>Since the 1.4.0 release, this plugin also aims to automate OBR (OSGi
671Bundle Repository) management. It helps manage a local OBR for your
672local Maven repository, and also supports remote OBRs for bundle
673distribution. The plug-in automatically computes bundle capabilities
674and requirements, using a combination of Bindex and Maven metadata.</p>
675
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]676<p><a name="ApacheFelixMavenBundlePlugin(BND)-simpleexample"></a></p>
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]677
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]678<h1><a name="ApacheFelixMavenBundlePlugin(BND)-SimpleExample"></a>Simple Example</h1>
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]679
680<p>Rather than going straight to a detailed list of plugin features, we
681will first look at a simple example of how to use the plugin to give an
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]682immediate flavor. A detailed "<a href="#ApacheFelixMavenBundlePlugin%2528BND%2529-howto">how to</a>" will follow.</p>
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]683
684<p>Assume that we have a simple bundle project that has a pubic API package an several implementation packages, such as:</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]685
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]686<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]687<pre>org.foo.myproject.api
688org.foo.myproject.impl1
689org.foo.myproject.impl2
690...
691</pre>
692</div></div>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]693
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]694<p>If we also assume that we have a bundle activator in one of the implementation packages, then the <tt>&lt;plugins&gt;</tt> section of the POM file for this bundle project would look like this:</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]695
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]696<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]697<pre>...
698&lt;plugins&gt;
699 &lt;plugin&gt;
700 &lt;groupId&gt;org.apache.felix&lt;/groupId&gt;
701 &lt;artifactId&gt;maven-bundle-plugin&lt;/artifactId&gt;
702 &lt;extensions&gt;true&lt;/extensions&gt;
703 &lt;configuration&gt;
704 &lt;instructions&gt;
705 &lt;Export-Package&gt;org.foo.myproject.api&lt;/Export-Package&gt;
706 &lt;Private-Package&gt;org.foo.myproject.*&lt;/Private-Package&gt;
707 &lt;Bundle-Activator&gt;org.foo.myproject.impl1.Activator&lt;/Bundle-Activator&gt;
708 &lt;/instructions&gt;
709 &lt;/configuration&gt;
710 &lt;/plugin&gt;
711&lt;/plugins&gt;
712...
713</pre>
714</div></div>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]715
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]716<p>The <tt>&lt;Export-Package&gt;</tt> and <tt>&lt;Private-Package&gt;</tt> instructions tell the plugin about the contents of the resulting bundle JAR file. The <tt>&lt;Export-Package&gt;</tt> instruction tells the plugin which of the available packages to copy into the bundle <b>and</b> export, while the <tt>&lt;Private-Package&gt;</tt> instruction indicates which of the available packages to copy into the bundle <b>but not</b>
717export. If the two sets overlap, as they do in the case, then the
718export takes precedence. Since we did not specify any values for any
719other bundle manifest headers, they will assume default values which
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]720are described <a href="#ApacheFelixMavenBundlePlugin%2528BND%2529-defaultbehavior">below</a>. One specific behavior to highlight is that the plugin generates the <tt>Import-Package</tt>
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]721bundle manifest header based on the contents of the bundle, which means
722that you generally do not ever need to explicitly specify it yourself.
723That's it.</p>
724
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]725<h1><a name="ApacheFelixMavenBundlePlugin(BND)-Features"></a>Features</h1>
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]726
727<p>The BND library underlying the plugin defines instructions to direct
728its behavior. For this Maven plugin, these instructions are issued in
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]729the plugin configuration section of the POM file, as was illustrated <a href="#ApacheFelixMavenBundlePlugin%2528BND%2529-simpleexample">above</a>. BND recognizes three types of instructions:</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]730
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]731<ol>
732 <li><em>Manifest headers</em> - Any instruction that starts with
733a capital letter will appear in the resulting bundle's manifest file;
734the value for the header will either be copied, augmented, or generated
735by BND depending on the instruction.</li>
736 <li><em>Variables</em> - Any instruction starting with a lowercase letter is assumed to be a variable in the form of a name-value pair, such as <tt>version=3.0</tt>, that can be used for property substitution, but is not copied to the manifest.</li>
737 <li><em>Directives</em>
738- Any instruction starting with a '-' character is considered to be a
739directive that informs BND to perform some special processing and is
740not copied to the manifest.</li>
741</ol>
742
743
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]744<p>The remainder of this section covers the most important aspects of BND's instructions; for complete details refer to the <a href="http://www.aqute.biz/Code/Bnd" rel="nofollow">BND documentation</a>.</p>
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]745
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]746<p><a name="ApacheFelixMavenBundlePlugin(BND)-instructions"></a></p>
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]747
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]748<h2><a name="ApacheFelixMavenBundlePlugin(BND)-Instructions"></a>Instructions</h2>
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]749
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]750<h3><a name="ApacheFelixMavenBundlePlugin(BND)-{{&lt;ExportPackage&gt;}}"></a><tt>&lt;Export-Package&gt;</tt></h3>
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]751
752<p>The <tt>&lt;Export-Package&gt;</tt> instruction is a list of
753packages for the bundle to export. These packages are copied into the
754resulting bundle JAR file from the available classes (i.e., project
755classes, dependencies, and class path); thus, it is possible to include
756classes into your bundle that are not associated with source files in
757your project. <tt>&lt;Export-Package&gt;</tt> can be specified with
758package patterns using the '*' wildcard. Also, it is possible to
759exclude packages using negation by starting the package pattern with
760'!'. Thus, non-negated patterns indicate which of the available
761packages to include in the bundle, whereas negated patterns indicate
762which should not be included in the bundle.</p>
763
764<p>The list of package patterns is ordered and earlier patterns are applied before later patterns. For example, if you specify "<tt>org.foo.*,!org.foo.impl</tt>" the second pattern has no effect since all <tt>org.foo</tt> packages have already been selected by the first pattern. Instead, you should specify "<tt>!org.foo.impl,org.foo.*</tt>", which will export all <tt>org.foo</tt> packages except <tt>org.foo.impl</tt>.</p>
765
766<p>Following standard OSGi R4 syntax, package patterns can include both
767directives and attributes, which will be copied appropriately into the
768generated Export-Package manifest header. Besides explicitly listing
769package version attributes, BND will also determine package versions by
770examining the source JAR file or from <tt>packageinfo</tt> files in the package directory.</p>
771
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]772<h3><a name="ApacheFelixMavenBundlePlugin(BND)-{{&lt;PrivatePackage&gt;}}"></a><tt>&lt;Private-Package&gt;</tt></h3>
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]773
774<p>The <tt>&lt;Private-Package&gt;</tt> instruction is similar in every way to the <tt>&lt;Export-Package&gt;</tt> instruction, except for the fact that these packages will <b>not</b>
775be exported by the bundle. If a package is selected by both the export
776and private package headers, then the export takes precedence.</p>
777
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]778<h3><a name="ApacheFelixMavenBundlePlugin(BND)-{{&lt;IncludeResource&gt;}}"></a><tt>&lt;Include-Resource&gt;</tt></h3>
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]779
780<p>The <tt>&lt;Include-Resource&gt;</tt> instruction is a list of
781arbitrary resources that should be copied into the bundle JAR file. The
782specified resources are declared as clauses that can have the following
783forms:</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]784
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]785<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]786<pre>clause ::= assignment | inline | simple
787assignment ::= PATH '=' PATH
788simple ::= PATH
789inline ::= '@' PATH
790</pre>
791</div></div>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]792
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]793<p>For the <tt>&lt;Include-Resource&gt;</tt> instruction, actual file paths are relative to the <tt>pom.xml</tt>, while file copy destinations are relative to the root of the resulting bundle JAR file. In the case of <tt>assignment</tt> or <tt>simple</tt> forms, the <tt>PATH</tt> parameter can point to a file or directory. The <tt>simple</tt>
794form will place the resource in the bundle JAR with only the file name,
795i.e., without any path component. For example, including <tt>src/main/resources/a/b.c</tt> will result in a resource <tt>b.c</tt> in the root of the bundle JAR. If the <tt>PATH</tt>
796points to a directory, the entire directory hierarchy is copied into
797the resulting bundle JAR file relative to the specified directory. If a
798specific resource must be placed into a subdirectory of the bundle jar,
799then use the <tt>assignment</tt> form, where the first path is the the
800destination path (including file name if the resource is a file) and
801the second path is the resource to copy. The <tt>inline</tt> form requires a ZIP or JAR file, which will be completely expanded in the bundle JAR.</p>
802
803<p>If a resource clause is specified inside of "{ ... }" brackets, then
804variable substitution will be performed on the resource, where
805variables in the resources are denoted with "${ ... }" syntax.</p>
806
Stuart McCulloch7c961f52008-01-02 08:56:07 +0000[diff] [blame]807<p>By default the bundle plugin converts the project's Maven resource directories into a single <tt>&lt;Include-Resource&gt;</tt> instruction. If you specify your own <tt>&lt;Include-Resource&gt;</tt> instruction, this will replace the generated one. To include the generated list of Maven resources in your own <tt>&lt;Include-Resource&gt;</tt> instruction just add {<tt>maven-resources</tt>} to the list and it will be expanded automatically.</p>
808
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]809<h3><a name="ApacheFelixMavenBundlePlugin(BND)-{{&lt;ImportPackage&gt;}}"></a><tt>&lt;Import-Package&gt;</tt></h3>
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]810
811<p>The <tt>&lt;Import-Package&gt;</tt> instruction is a list of
812packages that are required by the bundle's contained packages. The
813default for this header is "*", resulting in importing all referred
814packages. This header rarely has to be explicitly specified. However,
815in certain cases when there is an unwanted import, such an import can
816be removed by using a negation package pattern. The package patterns
817work in the same way as for <tt>&lt;Export-Package&gt;</tt>, which means they are ordered. For example, if you wanted to import all packages except <tt>org.foo.impl</tt> you would specify "<tt>!org.foo.impl,*</tt>"</p>
818
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]819<p><a name="ApacheFelixMavenBundlePlugin(BND)-defaultbehavior"></a></p>
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]820
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]821<h2><a name="ApacheFelixMavenBundlePlugin(BND)-DefaultBehavior"></a>Default Behavior</h2>
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]822
823<p>To use this plugin, very little information is required by BND. As
824part of the Maven integration, the plugin tries to set reasonable
825defaults for various instructions. For example:</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]826
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]827<ul>
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]828 <li><tt>&lt;Bundle-SymbolicName&gt;</tt> is computed using the shared <a href="http://svn.apache.org/repos/asf/maven/shared/trunk/maven-osgi/src/main/java/org/apache/maven/shared/osgi/DefaultMaven2OsgiConverter.java" rel="nofollow">Maven2OsgiConverter</a> component, which uses the following algorithm:<br>
Stuart McCullochb4212cc2008-08-05 06:36:05 +0000[diff] [blame]829Get the symbolic name as groupId + "." + artifactId, with the following exceptions:
830 <ul>
831 <li>if
832artifact.getFile is not null and the jar contains a OSGi Manifest with
833Bundle-SymbolicName property then that value is returned</li>
834 <li>if
835groupId has only one section (no dots) and artifact.getFile is not null
836then the first package name with classes is returned. eg.
837commons-logging:commons-logging -&gt; org.apache.commons.logging</li>
838 <li>if artifactId is equal to last section of groupId then groupId is returned. eg. org.apache.maven:maven -&gt; org.apache.maven</li>
839 <li>if
840artifactId starts with last section of groupId that portion is removed.
Stuart McCulloch738a06d2009-02-27 06:38:33 +0000[diff] [blame]841eg. org.apache.maven:maven-core -&gt; org.apache.maven.core<br>
842The computed symbolic name is also stored in the <tt>$(maven-symbolicname)</tt> property in case you want to add attributes or directives to it.</li>
Stuart McCullochb4212cc2008-08-05 06:36:05 +0000[diff] [blame]843 </ul>
844 </li>
Stuart McCulloch738a06d2009-02-27 06:38:33 +0000[diff] [blame]845 <li><tt>&lt;Export-Package&gt;</tt>
846is now assumed to be the set of packages in your local Java sources,
847excluding the default package '.' and any packages containing 'impl' or
848'internal'.<br>
849<em>(before version 2 of the bundleplugin it was based on the symbolic name)</em></li>
850 <li><tt>&lt;Private-Package&gt;</tt> is now assumed to be the set of packages in your local Java sources (note that any packages in both <tt>&lt;Export-Package&gt;</tt> and <tt>&lt;Private-Package&gt;</tt> will be exported).<br>
851<em>(before version 2 of the bundleplugin it was assumed to be empty by default)</em></li>
852 <li><tt>&lt;Import-Package&gt;</tt> is assumed to be "<tt>*</tt>", which imports everything referred to by the bundle content, but not contained in the bundle.<br>
853<em>Any exported packages are also imported by default, to ensure a consistent class space.</em></li>
Stuart McCulloch7c961f52008-01-02 08:56:07 +0000[diff] [blame]854 <li><tt>&lt;Include-Resource&gt;</tt> is generated from the project's Maven resources, typically "<tt>src/main/resources/</tt>",
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]855which will copy the specified project directory hierarchy into the
856resulting bundle JAR file, mirroring standard Maven behavior.</li>
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]857 <li><tt>&lt;Bundle-Version&gt;</tt> is assumed to be "<tt>${pom.version</tt>}" but is normalized to the OSGi version format of "<tt>MAJOR.MINOR.MICRO.QUALIFIER</tt>", for example "<tt>2.1-SNAPSHOT</tt>" would become "<tt>2.1.0.SNAPSHOT</tt>".</li>
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]858 <li><tt>&lt;Bundle-Name&gt;</tt> is assumed to be "<tt>${pom.name</tt>}".</li>
859 <li><tt>&lt;Bundle-Description&gt;</tt> is assumed to be "<tt>${pom.description</tt>}".</li>
860 <li><tt>&lt;Bundle-License&gt;</tt> is assumed to be "<tt>${pom.licenses</tt>}".</li>
861 <li><tt>&lt;Bundle-Vendor&gt;</tt> is assumed to be "<tt>${pom.organization.name</tt>}".</li>
862 <li><tt>&lt;Bundle-DocURL&gt;</tt> is assumed to be "<tt>${pom.organization.url</tt>}".</li>
863</ul>
864
865
Stuart McCulloch7c961f52008-01-02 08:56:07 +0000[diff] [blame]866<p>Since the plugin creates bundles for OSGi R4, it hard-codes <tt>Bundle-ManifestVersion</tt>
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]867to be '2'. Additionally, it generates imports for every export to
868ensure package substitutability, which is very important when working
869with collaborating services. It is possible to override any of these
870values (except <tt>Bundle-ManifestVersion</tt>) just by specifying the desired value in the plugin configuration section of the POM file.</p>
871
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]872<p><a name="ApacheFelixMavenBundlePlugin(BND)-howto"></a></p>
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]873
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]874<h1><a name="ApacheFelixMavenBundlePlugin(BND)-Detailed&quot;HowTo&quot;"></a>Detailed "How To"</h1>
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]875
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]876<h2><a name="ApacheFelixMavenBundlePlugin(BND)-GetMaven2"></a>Get Maven2</h2>
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]877
878<p>The first step in the process of using the plugin is downloading and
879installing the latest version of the Maven2 runtime. The latest Maven2
880release and instuctions for getting started with Maven2 can be found at
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]881the <a href="http://maven.apache.org/index.html" rel="nofollow">Maven website</a>.</p>
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]882
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]883<h2><a name="ApacheFelixMavenBundlePlugin(BND)-UsingthePlugin"></a>Using the Plugin</h2>
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]884
885<p>To use the maven-bundle-plugin, you first need to add the plugin and
886some appropriate plugin configuration to your bundle project's POM.
887Below is an example of a simple OSGi bundle POM for Maven2:</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]888
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]889<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]890<pre>&lt;project&gt;
891 &lt;modelVersion&gt;4.0.0&lt;/modelVersion&gt;
892 &lt;groupId&gt;my-osgi-bundles&lt;/groupId&gt;
893 &lt;artifactId&gt;examplebundle&lt;/artifactId&gt;
894 &lt;packaging&gt;bundle&lt;/packaging&gt; &lt;!-- (1) --&gt;
895 &lt;version&gt;1.0&lt;/version&gt;
896 &lt;name&gt;Example Bundle&lt;/name&gt;
897 &lt;dependencies&gt;
898 &lt;dependency&gt;
899 &lt;groupId&gt;org.apache.felix&lt;/groupId&gt;
900 &lt;artifactId&gt;org.osgi.core&lt;/artifactId&gt;
Stuart McCulloch7c961f52008-01-02 08:56:07 +0000[diff] [blame]901 &lt;version&gt;1.0.0&lt;/version&gt;
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]902 &lt;/dependency&gt;
903 &lt;/dependencies&gt;
904 &lt;build&gt;
905 &lt;plugins&gt;
906 &lt;plugin&gt; &lt;!-- (2) START --&gt;
907 &lt;groupId&gt;org.apache.felix&lt;/groupId&gt;
908 &lt;artifactId&gt;maven-bundle-plugin&lt;/artifactId&gt;
909 &lt;extensions&gt;true&lt;/extensions&gt;
910 &lt;configuration&gt;
911 &lt;instructions&gt;
912 &lt;Export-Package&gt;com.my.company.api&lt;/Export-Package&gt;
913 &lt;Private-Package&gt;com.my.company.*&lt;/Private-Package&gt;
914 &lt;Bundle-Activator&gt;com.my.company.Activator&lt;/Bundle-Activator&gt;
915 &lt;/instructions&gt;
916 &lt;/configuration&gt;
917 &lt;/plugin&gt; &lt;!-- (2) END --&gt;
918 &lt;/plugins&gt;
919 &lt;/build&gt;
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]920&lt;/project&gt;
921</pre>
922</div></div>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]923
924<p>There are two main things to note: (1) the <tt>&lt;packaging&gt;</tt>
925specifier must be "bundle" and (2) the plugin and configuration must be
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]926specified (the configuration section is where you will issue
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]927instructions to the plugin).</p>
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]928
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]929<h2><a name="ApacheFelixMavenBundlePlugin(BND)-RealWorldExample"></a>Real-World Example</h2>
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]930
931<p>Consider this more real-world example using Felix' Log Service
932implementation. The Log Service project is comprised of a single
933package: <tt>org.apache.felix.log.impl</tt>. It has a dependency on
934the core OSGi interfaces as well as a dependency on the compendium OSGi
935interfaces for the specific log service interfaces. The following is
936its POM file:</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]937
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]938<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]939<pre>&lt;project&gt;
940 &lt;modelVersion&gt;4.0.0&lt;/modelVersion&gt;
941 &lt;groupId&gt;org.apache.felix&lt;/groupId&gt;
942 &lt;artifactId&gt;org.apache.felix.log&lt;/artifactId&gt;
943 &lt;packaging&gt;bundle&lt;/packaging&gt;
944 &lt;name&gt;Apache Felix Log Service&lt;/name&gt;
945 &lt;version&gt;0.8.0-SNAPSHOT&lt;/version&gt;
946 &lt;description&gt;
947 This bundle provides an implementation of the OSGi R4 Log service.
948 &lt;/description&gt;
949 &lt;dependencies&gt;
950 &lt;dependency&gt;
951 &lt;groupId&gt;${pom.groupId}&lt;/groupId&gt;
952 &lt;artifactId&gt;org.osgi.core&lt;/artifactId&gt;
953 &lt;version&gt;0.8.0-incubator&lt;/version&gt;
954 &lt;/dependency&gt;
955 &lt;dependency&gt;
956 &lt;groupId&gt;${pom.groupId}&lt;/groupId&gt;
957 &lt;artifactId&gt;org.osgi.compendium&lt;/artifactId&gt;
958 &lt;version&gt;0.9.0-incubator-SNAPSHOT&lt;/version&gt;
959 &lt;/dependency&gt;
960 &lt;/dependencies&gt;
961 &lt;build&gt;
962 &lt;plugins&gt;
963 &lt;plugin&gt;
964 &lt;groupId&gt;org.apache.felix&lt;/groupId&gt;
965 &lt;artifactId&gt;maven-bundle-plugin&lt;/artifactId&gt;
966 &lt;extensions&gt;true&lt;/extensions&gt;
967 &lt;configuration&gt;
968 &lt;instructions&gt;
969 &lt;Export-Package&gt;org.osgi.service.log&lt;/Export-Package&gt;
970 &lt;Private-Package&gt;org.apache.felix.log.impl&lt;/Private-Package&gt;
971 &lt;Bundle-SymbolicName&gt;${pom.artifactId}&lt;/Bundle-SymbolicName&gt;
972 &lt;Bundle-Activator&gt;${pom.artifactId}.impl.Activator&lt;/Bundle-Activator&gt;
973 &lt;Export-Service&gt;org.osgi.service.log.LogService,org.osgi.service.log.LogReaderService&lt;/Export-Service&gt;
974 &lt;/instructions&gt;
975 &lt;/configuration&gt;
976 &lt;/plugin&gt;
977 &lt;/plugins&gt;
978 &lt;/build&gt;
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]979&lt;/project&gt;
980</pre>
981</div></div>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]982
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]983<p>Notice that the <tt>&lt;Export-Package&gt;</tt> instruction
984specifies that the bundle exports the Log Service package, even though
985this package is not contained in the bundle project. By declaring this,
986the plugin will copy the Log Service package into the resulting bundle
987JAR file. This is useful in this case because now the bundle can
988resolve without having to download the entire compendium bundle. The
989resulting manifest for the Log Service bundle looks like this (notice
990how the imports/exports automatically have version information
991associated with them, which was obtained from packageinfo files in the
992source packages):</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]993
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]994<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]995<pre>Manifest-Version: 1
996Bundle-License: http://www.apache.org/licenses/LICENSE-2.0.txt
997Bundle-Activator: org.apache.felix.log.impl.Activator
998Import-Package: org.osgi.framework;version=1.3, org.osgi.service.log;v
999 ersion=1.3
1000Include-Resource: src/main/resources
1001Export-Package: org.osgi.service.log;uses:=org.osgi.framework;version=
1002 1.3
1003Bundle-Version: 0.8.0.SNAPSHOT
1004Bundle-Name: Apache Felix Log Service
1005Bundle-Description: This bundle provides an implementation of the OSGi
1006 R4 Log service.
1007Private-Package: org.apache.felix.log.impl
1008Bundle-ManifestVersion: 2
1009Export-Service: org.osgi.service.log.LogService,org.osgi.service.log.L
1010 ogReaderService
1011Bundle-SymbolicName: org.apache.felix.log
1012</pre>
1013</div></div>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1014
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]1015<p>The resulting bundle JAR file has the following content (notice how
1016the LICENSE and NOTICE files were automatically copied from the <tt>src/main/resources/</tt> directory of the project):</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1017
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1018<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]1019<pre>META-INF/MANIFEST.MF
1020LICENSE
1021META-INF/
1022META-INF/maven/
1023META-INF/maven/org.apache.felix/
1024META-INF/maven/org.apache.felix/org.apache.felix.log/
1025META-INF/maven/org.apache.felix/org.apache.felix.log/pom.properties
1026META-INF/maven/org.apache.felix/org.apache.felix.log/pom.xml
1027NOTICE
1028org/
1029org/apache/
1030org/apache/felix/
1031org/apache/felix/log/
1032org/apache/felix/log/impl/
1033org/apache/felix/log/impl/Activator.class
1034org/apache/felix/log/impl/Log.class
1035org/apache/felix/log/impl/LogEntryImpl.class
1036org/apache/felix/log/impl/LogException.class
1037org/apache/felix/log/impl/LogListenerThread.class
1038org/apache/felix/log/impl/LogNode.class
1039org/apache/felix/log/impl/LogNodeEnumeration.class
1040org/apache/felix/log/impl/LogReaderServiceFactory.class
1041org/apache/felix/log/impl/LogReaderServiceImpl.class
1042org/apache/felix/log/impl/LogServiceFactory.class
1043org/apache/felix/log/impl/LogServiceImpl.class
1044org/osgi/
1045org/osgi/service/
1046org/osgi/service/log/
1047org/osgi/service/log/LogEntry.class
1048org/osgi/service/log/LogListener.class
1049org/osgi/service/log/LogReaderService.class
1050org/osgi/service/log/LogService.class
1051org/osgi/service/log/package.html
1052org/osgi/service/log/packageinfo
1053</pre>
1054</div></div>
1055
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]1056<h2><a name="ApacheFelixMavenBundlePlugin(BND)-AddingOSGimetadatatoexistingprojectswithoutchangingthepackagingtype"></a>Adding OSGi metadata to existing projects without changing the packaging type</h2>
Stuart McCullochdd4ae5f2008-02-05 12:38:46 +0000[diff] [blame]1057
1058<p>If you want to keep your project packaging type (for example "jar") but would like to add OSGi metadata<br>
1059you can use the manifest goal to generate a bundle manifest. The maven-jar-plugin can then be used to<br>
1060add this manifest to the final artifact. For example:</p>
1061
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1062<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
Stuart McCullochdd4ae5f2008-02-05 12:38:46 +0000[diff] [blame]1063<pre class="code-xml"><span class="code-tag">&lt;plugin&gt;</span>
1064 <span class="code-tag">&lt;artifactId&gt;</span>maven-jar-plugin<span class="code-tag">&lt;/artifactId&gt;</span>
1065 <span class="code-tag">&lt;configuration&gt;</span>
1066 <span class="code-tag">&lt;archive&gt;</span>
1067 <span class="code-tag">&lt;manifestFile&gt;</span>${project.build.outputDirectory}/META-INF/MANIFEST.MF<span class="code-tag">&lt;/manifestFile&gt;</span>
1068 <span class="code-tag">&lt;/archive&gt;</span>
1069 <span class="code-tag">&lt;/configuration&gt;</span>
1070<span class="code-tag">&lt;/plugin&gt;</span>
1071<span class="code-tag">&lt;plugin&gt;</span>
1072 <span class="code-tag">&lt;groupId&gt;</span>org.apache.felix<span class="code-tag">&lt;/groupId&gt;</span>
1073 <span class="code-tag">&lt;artifactId&gt;</span>maven-bundle-plugin<span class="code-tag">&lt;/artifactId&gt;</span>
1074 <span class="code-tag">&lt;executions&gt;</span>
1075 <span class="code-tag">&lt;execution&gt;</span>
1076 <span class="code-tag">&lt;id&gt;</span>bundle-manifest<span class="code-tag">&lt;/id&gt;</span>
1077 <span class="code-tag">&lt;phase&gt;</span>process-classes<span class="code-tag">&lt;/phase&gt;</span>
1078 <span class="code-tag">&lt;goals&gt;</span>
1079 <span class="code-tag">&lt;goal&gt;</span>manifest<span class="code-tag">&lt;/goal&gt;</span>
1080 <span class="code-tag">&lt;/goals&gt;</span>
1081 <span class="code-tag">&lt;/execution&gt;</span>
1082 <span class="code-tag">&lt;/executions&gt;</span>
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1083<span class="code-tag">&lt;/plugin&gt;</span>
1084</pre>
Stuart McCullochdd4ae5f2008-02-05 12:38:46 +0000[diff] [blame]1085</div></div>
1086
Stuart McCullochc9b81e12009-02-26 21:29:51 +0000[diff] [blame]1087<p>If you want to use packaging types other than "jar" and "bundle" then you also need to enable support<br>
1088for them in the bundleplugin configuration, for example if you want to use the plugin with WAR files:</p>
1089
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1090<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
Stuart McCullochc9b81e12009-02-26 21:29:51 +0000[diff] [blame]1091<pre class="code-xml"><span class="code-tag">&lt;plugin&gt;</span>
1092 <span class="code-tag">&lt;groupId&gt;</span>org.apache.felix<span class="code-tag">&lt;/groupId&gt;</span>
1093 <span class="code-tag">&lt;artifactId&gt;</span>maven-bundle-plugin<span class="code-tag">&lt;/artifactId&gt;</span>
1094 <span class="code-tag">&lt;executions&gt;</span>
1095 <span class="code-tag">&lt;execution&gt;</span>
1096 <span class="code-tag">&lt;id&gt;</span>bundle-manifest<span class="code-tag">&lt;/id&gt;</span>
1097 <span class="code-tag">&lt;phase&gt;</span>process-classes<span class="code-tag">&lt;/phase&gt;</span>
1098 <span class="code-tag">&lt;goals&gt;</span>
1099 <span class="code-tag">&lt;goal&gt;</span>manifest<span class="code-tag">&lt;/goal&gt;</span>
1100 <span class="code-tag">&lt;/goals&gt;</span>
1101 <span class="code-tag">&lt;/execution&gt;</span>
1102 <span class="code-tag">&lt;/executions&gt;</span>
1103 <span class="code-tag">&lt;configuration&gt;</span>
1104 <span class="code-tag">&lt;supportedProjectTypes&gt;</span>
1105 <span class="code-tag">&lt;supportedProjectType&gt;</span>jar<span class="code-tag">&lt;/supportedProjectType&gt;</span>
1106 <span class="code-tag">&lt;supportedProjectType&gt;</span>bundle<span class="code-tag">&lt;/supportedProjectType&gt;</span>
1107 <span class="code-tag">&lt;supportedProjectType&gt;</span>war<span class="code-tag">&lt;/supportedProjectType&gt;</span>
1108 <span class="code-tag">&lt;/supportedProjectTypes&gt;</span>
1109 <span class="code-tag">&lt;instructions&gt;</span>
1110 <span class="code-tag"><span class="code-comment">&lt;!-- ...etc... --&gt;</span></span>
1111 <span class="code-tag">&lt;/instructions&gt;</span>
1112 <span class="code-tag">&lt;/configuration&gt;</span>
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1113<span class="code-tag">&lt;/plugin&gt;</span>
1114</pre>
Stuart McCullochc9b81e12009-02-26 21:29:51 +0000[diff] [blame]1115</div></div>
1116
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]1117<h2><a name="ApacheFelixMavenBundlePlugin(BND)-BuildingthePlugin"></a>Building the Plugin</h2>
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]1118
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1119<p>The plugin is hosted at the Apache Felix project. The following
1120steps describe how to build and install the plugin into your local
1121Maven2 repository.</p>
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]1122
1123<p>Using the SVN client of your choice, checkout the maven-bundle-plugin project.</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1124
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1125<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1126<pre>$ svn co http://svn.apache.org/repos/asf/felix/trunk/bundleplugin
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]1127</pre>
1128</div></div>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1129
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]1130<p>Using Maven2, build and install the maven-bundle-plugin by issuing
1131the following Maven2 command in the project directory that was created
1132as a result of the previous step.</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1133
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1134<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]1135<pre>$ mvn install
1136</pre>
1137</div></div>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1138
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]1139<h1><a name="ApacheFelixMavenBundlePlugin(BND)-Goals"></a>Goals</h1>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1140
1141<p>The maven-bundle-plugin also provides additional functionality via
1142some Maven goals. Command-line execution of a goal is performed as
1143follows:</p>
1144
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1145<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1146<pre>mvn org.apache.felix:maven-bundle-plugin:GOAL
1147</pre>
1148</div></div>
1149
1150<p>Where GOAL is one of the following:</p>
1151
1152<ul>
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000[diff] [blame]1153 <li><b><tt>bundle</tt></b> - build an OSGi bundle jar for the current project<br>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1154configuration options:
1155 <ul>
Stuart McCullochdd4ae5f2008-02-05 12:38:46 +0000[diff] [blame]1156 <li><em><tt>manifestLocation</tt></em> defaults to ${project.build.outputDirectory}/META-INF</li>
1157 <li><em><tt>unpackBundle</tt></em> unpack bundle contents to output directory, defaults to false</li>
Stuart McCulloch738a06d2009-02-27 06:38:33 +0000[diff] [blame]1158 <li><em><tt>excludeDependencies</tt></em> comma-separated list of dependency artifactIds to exclude from the classpath passed to Bnd, use "true" to exclude everything.<br>
1159Version 2 of the bundleplugin now supports the same style of filter clauses in <tt>excludeDependencies</tt> as <tt>Embed-Dependency</tt>.</li>
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000[diff] [blame]1160 <li><em><tt>classifier</tt></em> attach bundle to the project using the given classifier</li>
Stuart McCullochc9b81e12009-02-26 21:29:51 +0000[diff] [blame]1161 <li><em><tt>supportedProjectTypes</tt></em> defaults to "jar","bundle"</li>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1162 </ul>
1163 </li>
Stuart McCullochdd4ae5f2008-02-05 12:38:46 +0000[diff] [blame]1164</ul>
1165
1166
1167<ul>
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000[diff] [blame]1168 <li><b><tt>bundleall</tt></b> - build OSGi bundle jars for all transitive dependencies<br>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1169configuration options:
1170 <ul>
Stuart McCulloch981bd342008-05-03 12:49:39 +0000[diff] [blame]1171 <li><em><tt>wrapImportPackage</tt></em> defaults to "*"</li>
Stuart McCullochc9b81e12009-02-26 21:29:51 +0000[diff] [blame]1172 <li><em><tt>supportedProjectTypes</tt></em> defaults to "jar","bundle"</li>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1173 </ul>
1174 </li>
Stuart McCullochdd4ae5f2008-02-05 12:38:46 +0000[diff] [blame]1175</ul>
1176
1177
1178<ul>
1179 <li><b><tt>wrap</tt></b> - as above, but limited to the first level of dependencies<br>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1180configuration options:
1181 <ul>
Stuart McCulloch981bd342008-05-03 12:49:39 +0000[diff] [blame]1182 <li><em><tt>wrapImportPackage</tt></em> defaults to "*"</li>
Stuart McCullochc9b81e12009-02-26 21:29:51 +0000[diff] [blame]1183 <li><em><tt>supportedProjectTypes</tt></em> defaults to "jar","bundle"</li>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1184 </ul>
1185 </li>
Stuart McCullochdd4ae5f2008-02-05 12:38:46 +0000[diff] [blame]1186</ul>
1187
1188
1189<ul>
1190 <li><b><tt>manifest</tt></b> - create an OSGi manifest for the current project<br>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1191configuration options:
1192 <ul>
Stuart McCullochdd4ae5f2008-02-05 12:38:46 +0000[diff] [blame]1193 <li><em><tt>manifestLocation</tt></em> defaults to ${project.build.outputDirectory}/META-INF</li>
1194 <li><em><tt>supportedProjectTypes</tt></em> defaults to "jar","bundle"</li>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1195 </ul>
1196 </li>
1197</ul>
1198
1199
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000[diff] [blame]1200<ul>
1201 <li><b><tt>install</tt></b> - adds the current bundle project to the local OBR<br>
1202configuration options:
1203 <ul>
1204 <li><em><tt>obrRepository</tt></em> path to local OBR, defaults to <em>&lt;local-maven-repository&gt;</em><tt>/repository.xml</tt></li>
Stuart McCullochc9b81e12009-02-26 21:29:51 +0000[diff] [blame]1205 <li><em><tt>supportedProjectTypes</tt></em> defaults to "jar","bundle"</li>
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000[diff] [blame]1206 </ul>
1207 </li>
1208</ul>
1209
1210
1211<p>More GOALs are available in the <b>1.4.0</b> release:</p>
1212
1213<ul>
1214 <li><b><tt>ant</tt></b> - create an Ant build script to rebuild the bundle</li>
1215</ul>
1216
1217
1218<ul>
1219 <li><b><tt>install-file</tt></b> - adds a local bundle file to the local OBR<br>
1220configuration options:
1221 <ul>
1222 <li><em><tt>obrRepository</tt></em> path to local OBR, defaults to <em>&lt;local-maven-repository&gt;</em><tt>/repository.xml</tt></li>
1223 <li><em><tt>groupId</tt></em> Maven groupId for the bundle, taken from <em>pomFile</em> if given</li>
1224 <li><em><tt>artifactId</tt></em> Maven artifactId for the bundle, taken from <em>pomFile</em> if given</li>
1225 <li><em><tt>version</tt></em> Maven version for the bundle, taken from <em>pomFile</em> if given</li>
1226 <li><em><tt>packaging</tt></em> Maven packaging type for the bundle, taken from <em>pomFile</em> if given</li>
1227 <li><em><tt>classifier</tt></em> Maven classifier type, defaults to none</li>
1228 <li><em><tt>pomFile</tt></em> optional Pom file describing the bundle</li>
1229 <li><em><tt>file</tt></em> bundle file, defaults to the bundle from the local Maven repository</li>
1230 <li><em><tt>obrXml</tt></em> optional additional properties for the bundle</li>
1231 </ul>
1232 </li>
1233</ul>
1234
1235
1236<ul>
1237 <li><b><tt>deploy</tt></b> - adds the current bundle project to a remote OBR<br>
1238configuration options:
1239 <ul>
1240 <li><em><tt>remoteOBR</tt></em> name of remote OBR, defaults to NONE (which means no remote OBR deployment)</li>
1241 <li><em><tt>obrRepository</tt></em> used when the remoteOBR name is blank, defaults to <tt>repository.xml</tt></li>
Stuart McCullochc9b81e12009-02-26 21:29:51 +0000[diff] [blame]1242 <li><em><tt>prefixUrl</tt></em> optional public URL prefix for the remote repository</li>
1243 <li><em><tt>bundleUrl</tt></em> optional public URL where the bundle has been deployed</li>
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000[diff] [blame]1244 <li><em><tt>altDeploymentRepository</tt></em> alternative remote repository, <em>id::layout::url</em></li>
Stuart McCullochc9b81e12009-02-26 21:29:51 +0000[diff] [blame]1245 <li><em><tt>obrDeploymentRepository</tt></em> optional OBR specific deployment repository.</li>
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000[diff] [blame]1246 <li><em><tt>ignoreLock</tt></em> ignore remote locking when updating the OBR</li>
Stuart McCullochc9b81e12009-02-26 21:29:51 +0000[diff] [blame]1247 <li><em><tt>supportedProjectTypes</tt></em> defaults to "jar","bundle"</li>
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000[diff] [blame]1248 </ul>
1249 </li>
1250</ul>
1251
1252
1253<ul>
1254 <li><b><tt>deploy-file</tt></b> - adds a local bundle file to a remote OBR<br>
1255configuration options:
1256 <ul>
1257 <li><em><tt>remoteOBR</tt></em> name of remote OBR, defaults to an empty string</li>
1258 <li><em><tt>obrRepository</tt></em> used when the remoteOBR name is blank, defaults to <tt>repository.xml</tt></li>
1259 <li><em><tt>repositoryId</tt></em> optional repository id, used to lookup authentication settings</li>
1260 <li><em><tt>url</tt></em> remote repository transport URL, like
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1261<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000[diff] [blame]1262<pre>scpexe://host/path/to/obr
1263</pre>
1264</div></div></li>
1265 <li><em><tt>bundleUrl</tt></em> public URL of deployed bundle, like
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1266<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000[diff] [blame]1267<pre>http://www.foo.org/bundles/foo.jar
1268</pre>
1269</div></div></li>
1270 <li><em><tt>groupId</tt></em> Maven groupId for the bundle, taken from <em>pomFile</em> if given</li>
1271 <li><em><tt>artifactId</tt></em> Maven artifactId for the bundle, taken from <em>pomFile</em> if given</li>
1272 <li><em><tt>version</tt></em> Maven version for the bundle, taken from <em>pomFile</em> if given</li>
1273 <li><em><tt>packaging</tt></em> Maven packaging type for the bundle, taken from <em>pomFile</em> if given</li>
1274 <li><em><tt>classifier</tt></em> Maven classifier type, defaults to none</li>
1275 <li><em><tt>pomFile</tt></em> optional Pom file describing the bundle</li>
1276 <li><em><tt>file</tt></em> bundle file, defaults to the bundle from the local Maven repository</li>
1277 <li><em><tt>obrXml</tt></em> optional additional properties for the bundle</li>
1278 <li><em><tt>ignoreLock</tt></em> ignore remote locking when updating the OBR</li>
1279 </ul>
1280 </li>
1281</ul>
1282
1283
1284<ul>
1285 <li><b><tt>clean</tt></b> - cleans the local OBR, removing missing bundles<br>
1286configuration options:
1287 <ul>
1288 <li><em><tt>obrRepository</tt></em> path to local OBR, defaults to <em>&lt;local-maven-repository&gt;</em><tt>/repository.xml</tt></li>
1289 </ul>
1290 </li>
1291</ul>
1292
1293
Stuart McCullochc9b81e12009-02-26 21:29:51 +0000[diff] [blame]1294<ul>
1295 <li><b><tt>remote-clean</tt></b> - cleans a remote OBR, removing missing bundles<br>
1296configuration options:
1297 <ul>
1298 <li><em><tt>remoteOBR</tt></em> name of remote OBR, defaults to NONE (which means no remote cleaning)</li>
1299 <li><em><tt>obrRepository</tt></em> used when the remoteOBR name is blank, defaults to <tt>repository.xml</tt></li>
1300 <li><em><tt>prefixUrl</tt></em> optional public URL prefix for the remote repository</li>
1301 <li><em><tt>altDeploymentRepository</tt></em> alternative remote repository, <em>id::layout::url</em></li>
1302 <li><em><tt>obrDeploymentRepository</tt></em> optional OBR specific deployment repository.</li>
1303 <li><em><tt>ignoreLock</tt></em> ignore remote locking when updating the OBR</li>
1304 </ul>
1305 </li>
1306</ul>
1307
1308
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1309<p>There are also new instructions available from the underlying BND
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1310tool, which continues to be improved independently; for the latest see <a href="http://aqute.biz/Code/Bnd" rel="nofollow">BND documentation</a>.</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1311
Stuart McCullochdd4ae5f2008-02-05 12:38:46 +0000[diff] [blame]1312<p>The default goal <b><tt>bundle</tt></b> will be initialized by setting the &lt;packaging&gt; entry to "bundle".</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1313
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]1314<h1><a name="ApacheFelixMavenBundlePlugin(BND)-Thefollowingfeaturesareonlyavailablefromversion1.2.0onwards"></a>The following features are only available from version 1.2.0 onwards</h1>
Stuart McCulloch7c961f52008-01-02 08:56:07 +0000[diff] [blame]1315
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]1316<h2><a name="ApacheFelixMavenBundlePlugin(BND)-Embeddingdependencies"></a>Embedding dependencies</h2>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1317
Stuart McCulloch7c961f52008-01-02 08:56:07 +0000[diff] [blame]1318<p>The Maven Bundle Plugin supports embedding of selected project dependencies inside the bundle by using the <tt>&lt;Embed-Dependency&gt;</tt> instruction:</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1319
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1320<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
1321<pre class="code-xml"><span class="code-tag">&lt;Embed-Dependency&gt;</span>dependencies<span class="code-tag">&lt;/Embed-Dependency&gt;</span>
1322</pre>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1323</div></div>
1324
1325<p>where:</p>
1326
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1327<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1328<pre>dependencies ::= clause ( ',' clause ) *
Stuart McCullochc9b81e12009-02-26 21:29:51 +0000[diff] [blame]1329clause ::= MATCH ( ';' attr '=' MATCH | ';inline=' inline )
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1330attr ::= 'groupId' | 'artifactId' | 'version' | 'scope' | 'type' | 'classifier' | 'optional'
Stuart McCullochc9b81e12009-02-26 21:29:51 +0000[diff] [blame]1331inline ::= 'true' | 'false' | PATH ( '|' PATH ) *
1332MATCH ::= &lt;globbed regular expression&gt;
1333PATH ::= &lt;Ant-style path expression&gt;
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1334</pre>
1335</div></div>
1336
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000[diff] [blame]1337<p>The plugin uses the <tt>&lt;Embed-Dependency&gt;</tt> instruction to transform the project dependencies into <tt>&lt;Include-Resource&gt;</tt> and <tt>&lt;Bundle-ClassPath&gt;</tt>
1338clauses, which are then appended to the current set of instructions and
1339passed onto BND. If you want the embedded dependencies to be at the
1340start or middle of <tt>&lt;Include-Resource&gt;</tt> or <tt>&lt;Bundle-ClassPath&gt;</tt> then you can use {<tt>maven-dependencies</tt>}, which will automatically expand to the relevant clauses.</p>
Stuart McCulloch7c961f52008-01-02 08:56:07 +0000[diff] [blame]1341
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]1342<p>The MATCH section accepts alternatives, separated by <b>|</b>, and can be negated by using <b>!</b> at the <em>beginning</em> of the MATCH. Use <b>*</b> to represent zero or more unknown characters and <b>?</b> to represent a single unknown character. There is no need to escape the <b>.</b> character inside MATCH. The first MATCH in a clause will filter against the artifactId.</p>
1343
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1344<p>some examples:</p>
1345
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1346<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]1347<pre class="code-xml"><span class="code-tag"><span class="code-comment">&lt;!-- embed all compile and runtime scope dependencies --&gt;</span></span>
1348<span class="code-tag">&lt;Embed-Dependency&gt;</span>*;scope=compile|runtime<span class="code-tag">&lt;/Embed-Dependency&gt;</span>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1349
Stuart McCullochc9b81e12009-02-26 21:29:51 +0000[diff] [blame]1350<span class="code-tag"><span class="code-comment">&lt;!-- embed any dependencies with artifactId junit and scope runtime --&gt;</span></span>
1351<span class="code-tag">&lt;Embed-Dependency&gt;</span>junit;scope=runtime<span class="code-tag">&lt;/Embed-Dependency&gt;</span>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1352
Stuart McCullochc9b81e12009-02-26 21:29:51 +0000[diff] [blame]1353<span class="code-tag"><span class="code-comment">&lt;!-- inline all non-pom dependencies, except those with scope runtime --&gt;</span></span>
1354<span class="code-tag">&lt;Embed-Dependency&gt;</span>*;scope=!runtime;type=!pom;inline=true<span class="code-tag">&lt;/Embed-Dependency&gt;</span>
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]1355
1356<span class="code-tag"><span class="code-comment">&lt;!-- embed all compile and runtime scope dependencies, except those with artifactIds in the given list --&gt;</span></span>
Stuart McCullochc9b81e12009-02-26 21:29:51 +0000[diff] [blame]1357<span class="code-tag">&lt;Embed-Dependency&gt;</span>*;scope=compile|runtime;inline=false;artifactId=!cli|lang|runtime|tidy|jsch<span class="code-tag">&lt;/Embed-Dependency&gt;</span>
1358
1359<span class="code-tag"><span class="code-comment">&lt;!-- inline contents of selected folders from all dependencies --&gt;</span></span>
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1360<span class="code-tag">&lt;Embed-Dependency&gt;</span>*;inline=images/**|icons/**<span class="code-tag">&lt;/Embed-Dependency&gt;</span>
1361</pre>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1362</div></div>
1363
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000[diff] [blame]1364<p>examples of using {<tt>maven-dependencies</tt>}:</p>
1365
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1366<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000[diff] [blame]1367<pre class="code-xml"><span class="code-tag">&lt;Include-Resource&gt;</span>
1368 {maven-resources}, {maven-dependencies},
1369 org/foo/Example.class=target/classes/org/foo/Example.class
1370<span class="code-tag">&lt;/Include-Resource&gt;</span>
1371
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1372<span class="code-tag">&lt;Bundle-ClassPath&gt;</span>.,{maven-dependencies},some.jar<span class="code-tag">&lt;/Bundle-ClassPath&gt;</span>
1373</pre>
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000[diff] [blame]1374</div></div>
1375
Stuart McCulloch7c961f52008-01-02 08:56:07 +0000[diff] [blame]1376<p>By default matched dependencies are embedded in the bundle as <tt>artifactId-version.jar</tt>. This behaviour can be modified using the following instructions:</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1377
1378<ul>
1379 <li><tt>&lt;Embed-StripVersion&gt;true&lt;/Embed-StripVersion&gt;</tt> - removes the version from the file (ie. <em>artifactId.jar</em>)</li>
1380 <li><tt>&lt;Embed-StripGroup&gt;false&lt;/Embed-StripGroup&gt;</tt> - adds the groupId as a subdirectory (ie. <em>groupId/artifactId-version.jar</em>)</li>
1381 <li><tt>&lt;Embed-Directory&gt;directory&lt;/Embed-Directory&gt;</tt> - adds a subdirectory (ie. <em>directory/artifactId-version.jar</em>)</li>
1382</ul>
1383
1384
1385<p>Normally the plugin only checks direct dependencies, but this can be
1386changed to include the complete set of transitive dependencies with the
1387following option:</p>
1388
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1389<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
1390<pre class="code-xml"><span class="code-tag">&lt;Embed-Transitive&gt;</span>true<span class="code-tag">&lt;/Embed-Transitive&gt;</span>
1391</pre>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1392</div></div>
1393
1394<p>If you want a dependency inlined instead of embedded add the <tt>inline=true</tt>. For example to inline all <em>compile</em> and <em>runtime</em> scoped dependencies use:</p>
1395
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1396<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
1397<pre class="code-xml"><span class="code-tag">&lt;Embed-Dependency&gt;</span>*;scope=compile|runtime;inline=true<span class="code-tag">&lt;/Embed-Dependency&gt;</span>
1398</pre>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1399</div></div>
1400
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]1401<h3><a name="ApacheFelixMavenBundlePlugin(BND)-EmbedDependencyandExportPackage"></a>Embed-Dependency and Export-Package</h3>
Stuart McCulloch7c961f52008-01-02 08:56:07 +0000[diff] [blame]1402
1403<p>If you embed a dependency with <tt>&lt;Embed-Dependency&gt;</tt>, and your <tt>&lt;Export-Package&gt;</tt> or <tt>&lt;Private-Package&gt;</tt> instructions match packages inside the embedded jar, you will see some duplication inside the bundle. This is because the <tt>&lt;Export-Package&gt;</tt> and <tt>&lt;Private-Package&gt;</tt>
1404instructions will result in classes being inlined in the bundle, even
1405though they also exist inside the embedded jar. If you want to export
1406packages from an embedded dependency without such duplication then you
1407can either inline the dependency, or use a new BND instruction called <tt>&lt;_exportcontents&gt;</tt>.</p>
1408
1409<p><tt>&lt;_exportcontents&gt;</tt> behaves just like Export-Package, except it doesn't change the content of the bundle, just what content should be exported.</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1410
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]1411<h2><a name="ApacheFelixMavenBundlePlugin(BND)-OBRintegration"></a>OBR integration</h2>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1412
1413<p>The latest Maven Bundle Plugin automatically updates the local OBR
1414repository.xml file during the install phase, using a default location
1415of:</p>
1416
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1417<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
1418<pre class="code-java">&lt;LOCAL-MAVEN-REPOSITORY&gt;/repository.xml
1419</pre>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1420</div></div>
1421
1422<p>You can configure the location of the OBR repository by using the command line:</p>
1423
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1424<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
1425<pre class="code-java">mvn clean install -DobrRepository=&lt;PATH_TO_OBR&gt;
1426</pre>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1427</div></div>
1428
1429<p>or in the configuration section for the maven-bundle-plugin in your Maven POM:</p>
1430
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1431<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1432<pre class="code-xml"><span class="code-tag">&lt;groupId&gt;</span>org.apache.felix<span class="code-tag">&lt;/groupId&gt;</span>
1433<span class="code-tag">&lt;artifactId&gt;</span>maven-bundle-plugin<span class="code-tag">&lt;/artifactId&gt;</span>
1434<span class="code-tag">&lt;extensions&gt;</span>true<span class="code-tag">&lt;/extensions&gt;</span>
1435<span class="code-tag">&lt;configuration&gt;</span>
1436 <span class="code-tag">&lt;obrRepository&gt;</span>PATH_TO_OBR<span class="code-tag">&lt;/obrRepository&gt;</span>
1437 <span class="code-tag">&lt;instructions&gt;</span>
1438 <span class="code-tag"><span class="code-comment">&lt;!-- bnd instructions --&gt;</span></span>
1439 <span class="code-tag">&lt;/instructions&gt;</span>
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1440<span class="code-tag">&lt;/configuration&gt;</span>
1441</pre>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1442</div></div>
1443
1444<p>to disable OBR installation set the obrRepository to NONE, for example:</p>
1445
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1446<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1447<pre class="code-xml"><span class="code-tag">&lt;groupId&gt;</span>org.apache.felix<span class="code-tag">&lt;/groupId&gt;</span>
1448<span class="code-tag">&lt;artifactId&gt;</span>maven-bundle-plugin<span class="code-tag">&lt;/artifactId&gt;</span>
1449<span class="code-tag">&lt;extensions&gt;</span>true<span class="code-tag">&lt;/extensions&gt;</span>
1450<span class="code-tag">&lt;configuration&gt;</span>
1451 <span class="code-tag">&lt;obrRepository&gt;</span>NONE<span class="code-tag">&lt;/obrRepository&gt;</span>
1452 <span class="code-tag">&lt;instructions&gt;</span>
1453 <span class="code-tag"><span class="code-comment">&lt;!-- bnd instructions --&gt;</span></span>
1454 <span class="code-tag">&lt;/instructions&gt;</span>
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1455<span class="code-tag">&lt;/configuration&gt;</span>
1456</pre>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1457</div></div>
1458
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]1459<h2><a name="ApacheFelixMavenBundlePlugin(BND)-Eclipse/PDEintegration"></a>Eclipse/PDE integration</h2>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1460
1461<p>It is possible to configure the Maven Bundle Plugin to put the
1462bundle manifest where Eclipse/PDE expects it, and use the Maven
1463Dependency Plugin to arrange for any embedded dependencies to appear in
1464a local directory that matches the Bundle-ClassPath entries. Here is an
1465example POM that does this:</p>
1466
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1467<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1468<pre>&lt;project&gt;
1469
1470 &lt;properties&gt;
1471 &lt;bundle.symbolicName&gt;org.example&lt;/bundle.symbolicName&gt;
1472 &lt;bundle.namespace&gt;org.example&lt;/bundle.namespace&gt;
1473 &lt;/properties&gt;
1474
1475 &lt;modelVersion&gt;4.0.0&lt;/modelVersion&gt;
1476 &lt;groupId&gt;examples&lt;/groupId&gt;
1477 &lt;artifactId&gt;org.example&lt;/artifactId&gt;
1478 &lt;version&gt;1.0-SNAPSHOT&lt;/version&gt;
1479
1480 &lt;name&gt;${bundle.symbolicName} [${bundle.namespace}]&lt;/name&gt;
1481
1482 &lt;packaging&gt;bundle&lt;/packaging&gt;
1483
1484 &lt;build&gt;
Stuart McCullochdd4ae5f2008-02-05 12:38:46 +0000[diff] [blame]1485 &lt;resources&gt;
1486 &lt;resource&gt;
1487 &lt;directory&gt;src/main/resources&lt;/directory&gt;
1488 &lt;/resource&gt;
1489 &lt;resource&gt;
1490 &lt;directory&gt;.&lt;/directory&gt;
1491 &lt;includes&gt;
1492 &lt;include&gt;plugin.xml&lt;/include&gt;
1493 &lt;/includes&gt;
1494 &lt;/resource&gt;
1495 &lt;/resources&gt;
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1496 &lt;plugins&gt;
1497 &lt;plugin&gt;
1498 &lt;groupId&gt;org.apache.felix&lt;/groupId&gt;
1499 &lt;artifactId&gt;maven-bundle-plugin&lt;/artifactId&gt;
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000[diff] [blame]1500 &lt;version&gt;1.2.1&lt;/version&gt;
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1501 &lt;extensions&gt;true&lt;/extensions&gt;
1502 &lt;!--
1503 the following instructions build a simple set of public/private classes into an OSGi bundle
1504 --&gt;
1505 &lt;configuration&gt;
1506 &lt;manifestLocation&gt;META-INF&lt;/manifestLocation&gt;
1507 &lt;instructions&gt;
1508 &lt;Bundle-SymbolicName&gt;${bundle.symbolicName}&lt;/Bundle-SymbolicName&gt;
1509 &lt;Bundle-Version&gt;${pom.version}&lt;/Bundle-Version&gt;
1510 &lt;!--
1511 assume public classes are in the top package, and private classes are under ".internal"
1512 --&gt;
Stuart McCullochdd4ae5f2008-02-05 12:38:46 +0000[diff] [blame]1513 &lt;Export-Package&gt;!${bundle.namespace}.internal.*,${bundle.namespace}.*;version="${pom.version}"&lt;/Export-Package&gt;
1514 &lt;Private-Package&gt;${bundle.namespace}.internal.*&lt;/Private-Package&gt;
1515 &lt;Bundle-Activator&gt;${bundle.namespace}.internal.ExampleActivator&lt;/Bundle-Activator&gt;
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1516 &lt;!--
1517 embed compile/runtime dependencies using path that matches the copied dependency folder
1518 --&gt;
1519 &lt;Embed-Dependency&gt;*;scope=compile|runtime;inline=false&lt;/Embed-Dependency&gt;
1520 &lt;Embed-Directory&gt;target/dependency&lt;/Embed-Directory&gt;
1521 &lt;Embed-StripGroup&gt;true&lt;/Embed-StripGroup&gt;
1522 &lt;/instructions&gt;
1523 &lt;/configuration&gt;
1524 &lt;/plugin&gt;
1525 &lt;plugin&gt;
1526 &lt;artifactId&gt;maven-dependency-plugin&lt;/artifactId&gt;
1527 &lt;executions&gt;
1528 &lt;execution&gt;
1529 &lt;id&gt;copy-dependencies&lt;/id&gt;
1530 &lt;phase&gt;package&lt;/phase&gt;
1531 &lt;goals&gt;
1532 &lt;goal&gt;copy-dependencies&lt;/goal&gt;
1533 &lt;/goals&gt;
1534 &lt;/execution&gt;
1535 &lt;/executions&gt;
1536 &lt;/plugin&gt;
1537 &lt;/plugins&gt;
1538 &lt;/build&gt;
1539
1540 &lt;dependencies&gt;
1541 &lt;dependency&gt;
1542 &lt;groupId&gt;org.osgi&lt;/groupId&gt;
1543 &lt;artifactId&gt;osgi_R4_core&lt;/artifactId&gt;
1544 &lt;version&gt;1.0&lt;/version&gt;
1545 &lt;scope&gt;provided&lt;/scope&gt;
1546 &lt;optional&gt;true&lt;/optional&gt;
1547 &lt;/dependency&gt;
1548 &lt;dependency&gt;
1549 &lt;groupId&gt;org.osgi&lt;/groupId&gt;
1550 &lt;artifactId&gt;osgi_R4_compendium&lt;/artifactId&gt;
1551 &lt;version&gt;1.0&lt;/version&gt;
1552 &lt;scope&gt;provided&lt;/scope&gt;
1553 &lt;optional&gt;true&lt;/optional&gt;
1554 &lt;/dependency&gt;
1555 &lt;dependency&gt;
1556 &lt;groupId&gt;junit&lt;/groupId&gt;
1557 &lt;artifactId&gt;junit&lt;/artifactId&gt;
1558 &lt;version&gt;3.8.1&lt;/version&gt;
1559 &lt;scope&gt;compile&lt;/scope&gt;
1560 &lt;optional&gt;true&lt;/optional&gt;
1561 &lt;/dependency&gt;
1562 &lt;/dependencies&gt;
1563
1564&lt;/project&gt;
1565</pre>
1566</div></div>
1567
1568<p>To generate the Eclipse metadata use:</p>
1569
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1570<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
1571<pre class="code-java">mvn clean <span class="code-keyword">package</span> eclipse:eclipse -Declipse.pde install
1572</pre>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1573</div></div>
1574
1575<p>and you should now be able to import this as an existing Eclipse project.</p>
1576
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1577<p>FYI: the above POM was generated using the <tt>pax-create-bundle</tt> command from <a href="http://www.ops4j.org/projects/pax/construct/index.html" rel="nofollow">Pax-Construct</a> and then tweaked to demonstrate using the Maven Dependency Plugin to handle embedded jars in Eclipse.</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1578
1579<p>With the original Pax-Construct generated POM you would simply use:</p>
1580
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1581<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
1582<pre class="code-java">mvn clean <span class="code-keyword">package</span> pax:eclipse
1583</pre>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1584</div></div>
1585
1586<p>to create the appropriate Eclipse files and manifest, and also
1587handle any embedded entries. The pax:eclipse goal extends
1588eclipse:eclipse, and supports the same parameters.</p>
1589
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]1590<h2><a name="ApacheFelixMavenBundlePlugin(BND)-Unpackingbundlecontentsto'target/classes'"></a>Unpacking bundle contents to 'target/classes'</h2>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1591
1592<p>Once in a while you may create a bundle which contains additional classes to the ones compiled from <tt>src/main/java</tt>,
1593for example when you embed the classes from another jar. This can
1594sometimes cause unforeseen problems in Maven, as it will use the output
1595directory (<tt>target/classes</tt>) rather than the final bundle, when compiling against projects in the same reactor (ie. the same build).</p>
1596
1597<p>The easiest way to get around this Maven 'feature' is to unpack the
1598contents of the bundle to the output directory after the packaging
1599step, so the additional classes will be found where Maven expects them.
1600Thankfully there is now an easy option to do this in the bundle-plugin:</p>
1601
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1602<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
Stuart McCullochdd4ae5f2008-02-05 12:38:46 +0000[diff] [blame]1603<pre class="code-xml"><span class="code-tag">&lt;groupId&gt;</span>org.apache.felix<span class="code-tag">&lt;/groupId&gt;</span>
1604<span class="code-tag">&lt;artifactId&gt;</span>maven-bundle-plugin<span class="code-tag">&lt;/artifactId&gt;</span>
1605<span class="code-tag">&lt;extensions&gt;</span>true<span class="code-tag">&lt;/extensions&gt;</span>
1606<span class="code-tag">&lt;configuration&gt;</span>
1607 <span class="code-tag">&lt;unpackBundle&gt;</span>true<span class="code-tag">&lt;/unpackBundle&gt;</span>
1608 <span class="code-tag">&lt;instructions&gt;</span>
1609 <span class="code-tag"><span class="code-comment">&lt;!-- bnd instructions --&gt;</span></span>
1610 <span class="code-tag">&lt;/instructions&gt;</span>
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1611<span class="code-tag">&lt;/configuration&gt;</span>
1612</pre>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1613</div></div>
1614
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]1615<h2><a name="ApacheFelixMavenBundlePlugin(BND)-UsinganexistingMANIFEST.MFfile"></a>Using an existing MANIFEST.MF file</h2>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1616
1617<p>If you have an existing manifest, you can add this to the Bnd instructions, like so:</p>
1618
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1619<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
Stuart McCullochdd4ae5f2008-02-05 12:38:46 +0000[diff] [blame]1620<pre class="code-xml"><span class="code-tag">&lt;_include&gt;</span>src/main/resources/META-INF/MANIFEST.MF<span class="code-tag">&lt;/_include&gt;</span>
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1621<span class="code-tag">&lt;Export-Package&gt;</span>org.example.*<span class="code-tag">&lt;/Export-Package&gt;</span>
1622</pre>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1623</div></div>
1624
1625<p>Bnd will use it when calculating the bundle contents, and will also
1626copy across all manifest attributes starting with a capital letter.<br>
1627As shown in the above example, you could use this to include a non-OSGi
1628manifest which you then customize with extra OSGi attributes.</p>
1629
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]1630<h1><a name="ApacheFelixMavenBundlePlugin(BND)-Thefollowingfeaturesareonlyavailablefromversion1.4.0onwards"></a>The following features are only available from version 1.4.0 onwards</h1>
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000[diff] [blame]1631
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]1632<h2><a name="ApacheFelixMavenBundlePlugin(BND)-bundle:ant"></a>bundle:ant</h2>
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000[diff] [blame]1633
1634<p>The <b>ant</b> goal creates a customized <tt>build.xml</tt> Ant script along with a collection of BND instructions and properties, taken from the current project and stored in <tt>maven-build.bnd</tt>. You also need to run <b><tt>ant:ant</tt></b> to create the standard Ant support tasks to download Maven dependencies and perform compilation, etc.</p>
1635
1636<p>The customized Ant script uses the BND tool to rebuild the bundle,
1637so any source changes should be reflected in the (re)generated manifest.</p>
1638
1639<p>Example:</p>
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1640<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000[diff] [blame]1641<pre>mvn ant:ant bundle:ant
1642
1643ant clean package
1644</pre>
1645</div></div>
1646
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]1647<h2><a name="ApacheFelixMavenBundlePlugin(BND)-bundle:installfile"></a>bundle:install-file</h2>
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000[diff] [blame]1648
1649<p>The <b>install-file</b> goal updates the local OBR with the details of a bundle from the local filesystem.</p>
1650
1651<p>configuration:</p>
1652<ul>
1653 <li><em>obrRepository</em> path to local OBR, defaults to <em>&lt;local-maven-repository&gt;</em><tt>/repository.xml</tt></li>
1654 <li><em>groupId</em> Maven groupId for the bundle, taken from <em>pomFile</em> if given</li>
1655 <li><em>artifactId</em> Maven artifactId for the bundle, taken from <em>pomFile</em> if given</li>
1656 <li><em>version</em> Maven version for the bundle, taken from <em>pomFile</em> if given</li>
1657 <li><em>packaging</em> Maven packaging type for the bundle, taken from <em>pomFile</em> if given</li>
1658 <li><em>classifier</em> Maven classifier type, defaults to none</li>
1659 <li><em>pomFile</em> optional Pom file describing the bundle</li>
1660 <li><em>file</em> bundle file, defaults to the bundle from the local Maven repository</li>
1661 <li><em>obrXml</em> optional additional properties for the bundle</li>
1662</ul>
1663
1664
1665<p>Example:</p>
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1666<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000[diff] [blame]1667<pre>mvn org.apache.felix:maven-bundle-plugin:1.4.0:install-file \
1668 -DpomFile=myPom.xml -Dfile=foo-1.0.jar
1669</pre>
1670</div></div>
1671
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]1672<h2><a name="ApacheFelixMavenBundlePlugin(BND)-bundle:deploy"></a>bundle:deploy</h2>
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000[diff] [blame]1673
1674<p>The <b>deploy goal</b> updates the remote OBR with the details of
1675the deployed bundle from the local Maven repository. The remote OBR is
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1676found by querying the <tt>&lt;distributionManagement&gt;</tt> section of the project, unless <tt>-DaltDeploymentRepository</tt> is set. See <a href="http://maven.apache.org/plugins/maven-deploy-plugin/deploy-mojo.html" rel="nofollow">http://maven.apache.org/plugins/maven-deploy-plugin/deploy-mojo.html</a> for more details about these particular settings.</p>
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000[diff] [blame]1677
1678<p>(If the project has an <tt>obr.xml</tt> file somewhere in its resources, then it will be automatically detected and applied.)</p>
1679
1680<p>configuration:</p>
1681<ul>
1682 <li><em>remoteOBR</em> name of remote OBR, defaults to NONE (which means no remote OBR deployment)</li>
1683 <li><em>obrRepository</em> used when the remoteOBR name is blank, defaults to <tt>repository.xml</tt></li>
1684 <li><em>altDeploymentRepository</em> alternative remote repository, <em>id::layout::url</em></li>
1685 <li><em>ignoreLock</em> ignore remote locking when updating the OBR</li>
1686</ul>
1687
1688
1689<p>This goal is part of the "bundle" packaging lifecycle, but is disabled by default - to enable just set the <tt>remoteOBR</tt> parameter.</p>
1690
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]1691<h2><a name="ApacheFelixMavenBundlePlugin(BND)-bundle:deployfile"></a>bundle:deploy-file</h2>
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000[diff] [blame]1692
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1693<p>The <b>deploy-file</b> goal updates the remote OBR with the details of a deployed bundle from the local filesystem. The remote OBR is found using the <tt>-DrepositoryId</tt> and <tt>-Durl</tt> parameters. See <a href="http://maven.apache.org/plugins/maven-deploy-plugin/deploy-file-mojo.html" rel="nofollow">http://maven.apache.org/plugins/maven-deploy-plugin/deploy-file-mojo.html</a> for more details about these particular settings.</p>
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000[diff] [blame]1694
1695<p>You can use the <tt>-DbundleUrl</tt> parameter to give the public location of the deployed bundle, which may differ from the remote OBR location.</p>
1696
1697<p>configuration:</p>
1698<ul>
1699 <li><em>remoteOBR</em> name of remote OBR, defaults to an empty string</li>
1700 <li><em>obrRepository</em> used when the remoteOBR name is blank, defaults to <tt>repository.xml</tt></li>
1701 <li><em>repositoryId</em> optional repository id, used to lookup authentication settings</li>
1702 <li><em>url</em> remote repository transport URL, like
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1703<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000[diff] [blame]1704<pre>scpexe://host/path/to/obr
1705</pre>
1706</div></div></li>
1707 <li><em>bundleUrl</em> public URL of deployed bundle, like
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1708<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000[diff] [blame]1709<pre>http://www.foo.org/bundles/foo.jar
1710</pre>
1711</div></div></li>
1712 <li><em>groupId</em> Maven groupId for the bundle, taken from <em>pomFile</em> if given</li>
1713 <li><em>artifactId</em> Maven artifactId for the bundle, taken from <em>pomFile</em> if given</li>
1714 <li><em>version</em> Maven version for the bundle, taken from <em>pomFile</em> if given</li>
1715 <li><em>packaging</em> Maven packaging type for the bundle, taken from <em>pomFile</em> if given</li>
1716 <li><em>classifier</em> Maven classifier type, defaults to none</li>
1717 <li><em>pomFile</em> optional Pom file describing the bundle</li>
1718 <li><em>file</em> bundle file, defaults to the bundle from the local Maven repository</li>
1719 <li><em>obrXml</em> optional additional properties for the bundle</li>
1720 <li><em>ignoreLock</em> ignore remote locking when updating the OBR</li>
1721</ul>
1722
1723
Stuart McCulloch738a06d2009-02-27 06:38:33 +0000[diff] [blame]1724
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000[diff] [blame]1725<p>Example:</p>
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1726<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000[diff] [blame]1727<pre>mvn org.apache.felix:maven-bundle-plugin:1.4.0:deploy-file \
1728 -DpomFile=myPom.xml -Dfile=foo-1.0.jar -Durl=file:/tmp/example/OBR \
1729 -DbundleUrl=http://www.foo.org/bundles/foo.jar
1730</pre>
1731</div></div>
1732
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]1733<h2><a name="ApacheFelixMavenBundlePlugin(BND)-bundle:clean"></a>bundle:clean</h2>
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000[diff] [blame]1734
1735<p>Sometimes you would like to clean your local OBR because it contains
1736bundles that are no longer in your local Maven repository. This case
1737often occurs when artifacts were deleted manually. The
1738maven-bundle-plugin provides a simple goal to check for missing
1739bundles, and remove them from the local OBR.</p>
1740
1741<p>configuration:</p>
1742<ul>
1743 <li><em>obrRepository</em> path to local OBR, defaults to <em>&lt;local-maven-repository&gt;</em><tt>/repository.xml</tt></li>
1744</ul>
1745
1746
1747<p>Example:</p>
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1748<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000[diff] [blame]1749<pre>mvn bundle:clean
1750</pre>
1751</div></div>
1752
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]1753<h2><a name="ApacheFelixMavenBundlePlugin(BND)-Concurrentupdates"></a>Concurrent updates</h2>
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000[diff] [blame]1754
1755<p>With a remote OBR, several uploads may occur at the same time.
1756However, the remote OBR is centralized in one file, so concurrent
1757modification must be avoided. To achieve this, the plug-in implements a
1758locking system. Each time the plug-in tries to modify the file it sets
1759a file based lock. If it can't take the lock, it will wait and retry.
1760After 3 attempts the upload process fails. To bypass this lock add <tt>-DignoreLock</tt> to the command-line (or add <tt>&lt;ignoreLock&gt;true&lt;ignoreLock&gt;</tt> to the configuration section of your Pom).</p>
1761
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]1762<h2><a name="ApacheFelixMavenBundlePlugin(BND)-FTPprotocol"></a>FTP protocol</h2>
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000[diff] [blame]1763
1764<p>Not all protocols are supported by Maven out of the box. For example the ftp protocol requires the <b>wagon-ftp</b> component. To enable the ftp protocol add this to your Pom:</p>
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1765<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000[diff] [blame]1766<pre class="code-xml"><span class="code-tag">&lt;build&gt;</span>
1767 <span class="code-tag">&lt;extensions&gt;</span>
1768 <span class="code-tag">&lt;extension&gt;</span>
1769 <span class="code-tag">&lt;groupId&gt;</span>org.apache.maven.wagon<span class="code-tag">&lt;/groupId&gt;</span>
1770 <span class="code-tag">&lt;artifactId&gt;</span>wagon-ftp<span class="code-tag">&lt;/artifactId&gt;</span>
1771 <span class="code-tag">&lt;version&gt;</span>1.0-alpha-6<span class="code-tag">&lt;/version&gt;</span>
1772 <span class="code-tag">&lt;/extension&gt;</span>
1773 <span class="code-tag">&lt;/extensions&gt;</span>
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1774<span class="code-tag">&lt;/build&gt;</span>
1775</pre>
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000[diff] [blame]1776</div></div>
1777
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]1778<h2><a name="ApacheFelixMavenBundlePlugin(BND)-Howtheplugincomputesthedescriptionofthebundle"></a>How the plug-in computes the description of the bundle</h2>
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000[diff] [blame]1779
1780<p>The description of the bundle comes from three different sources:</p>
1781<ul>
1782 <li>Bindex : Bindex is a tool that analyzes a bundle manifest to generate OBR description</li>
1783 <li>pom.xml : by analyzing the pom file, various information is collected (symbolic name ...)</li>
1784 <li>obr.xml : this file contains customized description and capabilities for the bundle</li>
1785</ul>
1786
1787
1788<p>These sources are merged together using the following precedence:</p>
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1789<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000[diff] [blame]1790<pre>Bindex
1791| (overrides)
1792pom.xml
1793| (overrides)
1794obr.xml
1795</pre>
1796</div></div>
1797<p>A warning message is displayed when existing information is overridden.</p>
1798
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]1799<h2><a name="ApacheFelixMavenBundlePlugin(BND)-Knownissues&amp;limitations"></a>Known issues &amp; limitations</h2>
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000[diff] [blame]1800
1801<ol>
1802 <li>obr.xml (file given by the user to add properties not found
1803by Bindex) must be correct, because the plug-in does not check its
1804syntax.</li>
1805</ol>
1806
1807
Stuart McCullochdd89cdb2008-05-03 08:13:09 +0000[diff] [blame]1808<h1><a name="ApacheFelixMavenBundlePlugin(BND)-Feedback"></a>Feedback</h1>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000[diff] [blame]1809
Stuart McCullocha1a63632009-09-16 09:47:50 +0000[diff] [blame]1810<p>Subscribe to the Felix users mailing list by sending a message to <a href="mailto:users-subscribe@felix.apache.org" rel="nofollow">users-subscribe@felix.apache.org</a>; after subscribing, email questions or feedback to <a href="mailto:users@felix.apache.org" rel="nofollow">users@felix.apache.org</a>.</p>
Karl Paulsf87ac142007-07-06 22:36:17 +0000[diff] [blame]1811 </div>
Stuart McCullochb4212cc2008-08-05 06:36:05 +0000[diff] [blame]1812 </body></html>