Blame - bundleplugin/doc/apache-felix-maven-bundle-plugin-bnd.html - onos-felix

blob: be895cf4ef7b1e456a119f7ae060869cad4b2f77 [file] [log] [blame]

Karl Pauls	f87ac14	2007-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 McCulloch	981bd34	2008-05-03 12:49:39 +0000	[diff] [blame]	2	<html><head>
Karl Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	3
				4
				5
Stuart McCulloch	981bd34	2008-05-03 12:49:39 +0000	[diff] [blame]	6	<title>Apache Felix - Apache Felix Maven Bundle Plugin (BND)</title>
Stuart McCulloch	dd89cdb	2008-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 McCulloch	981bd34	2008-05-03 12:49:39 +0000	[diff] [blame]	8	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
				9	</head><body>
Stuart McCulloch	dd89cdb	2008-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 Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	11	<div class="menu">
Stuart McCulloch	a1a6363	2009-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	>
Stuart McCulloch	93de649	2007-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 McCulloch	93de649	2007-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 McCulloch	a1a6363	2009-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 McCulloch	93de649	2007-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 McCulloch	dd89cdb	2008-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 McCulloch	a1a6363	2009-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 McCulloch	dd89cdb	2008-05-03 08:13:09 +0000	[diff] [blame]	277	<!-- ApacheCon Ad -->
Stuart McCulloch	a1a6363	2009-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 McCulloch	dd89cdb	2008-05-03 08:13:09 +0000	[diff] [blame]	279	<p style="height: 100px;">
				280	<!-- ApacheCon Ad -->
Stuart McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	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
				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 Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	654	<div class="main">
Stuart McCulloch	dd89cdb	2008-05-03 08:13:09 +0000	[diff] [blame]	655	<h1><a name="ApacheFelixMavenBundlePlugin(BND)-BundlePluginforMaven"></a>Bundle Plugin for Maven</h1>
Karl Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	656
Stuart McCulloch	a1a6363	2009-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 Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	658	tool from Peter Kriens. The way BND works is by treating your project
				659	as a big collection of classes (e.g., project code, dependencies, and
				660	the class path). The way you create a bundle with BND is to tell it the
				661	content of the bundle's JAR file as a subset of the available classes.
				662	This plugin wraps BND to make it work specifically with the Maven 2
				663	project structure and to provide it with reasonable default behavior
				664	for Maven 2 projects.</p>
				665
Stuart McCulloch	a1a6363	2009-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 McCulloch	738a06d	2009-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 McCulloch	b4212cc	2008-08-05 06:36:05 +0000	[diff] [blame]	669
Stuart McCulloch	0340ae4	2008-02-22 11:27:18 +0000	[diff] [blame]	670	<p>Since the 1.4.0 release, this plugin also aims to automate OBR (OSGi
				671	Bundle Repository) management. It helps manage a local OBR for your
				672	local Maven repository, and also supports remote OBRs for bundle
				673	distribution. The plug-in automatically computes bundle capabilities
				674	and requirements, using a combination of Bindex and Maven metadata.</p>
				675
Stuart McCulloch	dd89cdb	2008-05-03 08:13:09 +0000	[diff] [blame]	676	<p><a name="ApacheFelixMavenBundlePlugin(BND)-simpleexample"></a></p>
Karl Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	677
Stuart McCulloch	dd89cdb	2008-05-03 08:13:09 +0000	[diff] [blame]	678	<h1><a name="ApacheFelixMavenBundlePlugin(BND)-SimpleExample"></a>Simple Example</h1>
Karl Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	679
				680	<p>Rather than going straight to a detailed list of plugin features, we
				681	will first look at a simple example of how to use the plugin to give an
Stuart McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	682	immediate flavor. A detailed "<a href="#ApacheFelixMavenBundlePlugin%2528BND%2529-howto">how to</a>" will follow.</p>
Karl Pauls	f87ac14	2007-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 McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	685
Stuart McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	686	<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Karl Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	687	<pre>org.foo.myproject.api
				688	org.foo.myproject.impl1
				689	org.foo.myproject.impl2
				690	...
				691	</pre>
				692	</div></div>
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	693
Karl Pauls	f87ac14	2007-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><plugins></tt> section of the POM file for this bundle project would look like this:</p>
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	695
Stuart McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	696	<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Karl Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	697	<pre>...
				698	<plugins>
				699	<plugin>
				700	<groupId>org.apache.felix</groupId>
				701	<artifactId>maven-bundle-plugin</artifactId>
				702	<extensions>true</extensions>
				703	<configuration>
				704	<instructions>
				705	<Export-Package>org.foo.myproject.api</Export-Package>
				706	<Private-Package>org.foo.myproject.*</Private-Package>
				707	<Bundle-Activator>org.foo.myproject.impl1.Activator</Bundle-Activator>
				708	</instructions>
				709	</configuration>
				710	</plugin>
				711	</plugins>
				712	...
				713	</pre>
				714	</div></div>
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	715
Karl Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	716	<p>The <tt><Export-Package></tt> and <tt><Private-Package></tt> instructions tell the plugin about the contents of the resulting bundle JAR file. The <tt><Export-Package></tt> instruction tells the plugin which of the available packages to copy into the bundle <b>and</b> export, while the <tt><Private-Package></tt> instruction indicates which of the available packages to copy into the bundle <b>but not</b>
				717	export. If the two sets overlap, as they do in the case, then the
				718	export takes precedence. Since we did not specify any values for any
				719	other bundle manifest headers, they will assume default values which
Stuart McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	720	are 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 Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	721	bundle manifest header based on the contents of the bundle, which means
				722	that you generally do not ever need to explicitly specify it yourself.
				723	That's it.</p>
				724
Stuart McCulloch	dd89cdb	2008-05-03 08:13:09 +0000	[diff] [blame]	725	<h1><a name="ApacheFelixMavenBundlePlugin(BND)-Features"></a>Features</h1>
Karl Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	726
				727	<p>The BND library underlying the plugin defines instructions to direct
				728	its behavior. For this Maven plugin, these instructions are issued in
Stuart McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	729	the 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 McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	730
Karl Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	731	<ol>
				732	<li><em>Manifest headers</em> - Any instruction that starts with
				733	a capital letter will appear in the resulting bundle's manifest file;
				734	the value for the header will either be copied, augmented, or generated
				735	by 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
				739	directive that informs BND to perform some special processing and is
				740	not copied to the manifest.</li>
				741	</ol>
				742
				743
Stuart McCulloch	a1a6363	2009-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 Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	745
Stuart McCulloch	dd89cdb	2008-05-03 08:13:09 +0000	[diff] [blame]	746	<p><a name="ApacheFelixMavenBundlePlugin(BND)-instructions"></a></p>
Karl Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	747
Stuart McCulloch	dd89cdb	2008-05-03 08:13:09 +0000	[diff] [blame]	748	<h2><a name="ApacheFelixMavenBundlePlugin(BND)-Instructions"></a>Instructions</h2>
Karl Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	749
Stuart McCulloch	dd89cdb	2008-05-03 08:13:09 +0000	[diff] [blame]	750	<h3><a name="ApacheFelixMavenBundlePlugin(BND)-{{<ExportPackage>}}"></a><tt><Export-Package></tt></h3>
Karl Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	751
				752	<p>The <tt><Export-Package></tt> instruction is a list of
				753	packages for the bundle to export. These packages are copied into the
				754	resulting bundle JAR file from the available classes (i.e., project
				755	classes, dependencies, and class path); thus, it is possible to include
				756	classes into your bundle that are not associated with source files in
				757	your project. <tt><Export-Package></tt> can be specified with
				758	package patterns using the '*' wildcard. Also, it is possible to
				759	exclude packages using negation by starting the package pattern with
				760	'!'. Thus, non-negated patterns indicate which of the available
				761	packages to include in the bundle, whereas negated patterns indicate
				762	which 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
				767	directives and attributes, which will be copied appropriately into the
				768	generated Export-Package manifest header. Besides explicitly listing
				769	package version attributes, BND will also determine package versions by
				770	examining the source JAR file or from <tt>packageinfo</tt> files in the package directory.</p>
				771
Stuart McCulloch	dd89cdb	2008-05-03 08:13:09 +0000	[diff] [blame]	772	<h3><a name="ApacheFelixMavenBundlePlugin(BND)-{{<PrivatePackage>}}"></a><tt><Private-Package></tt></h3>
Karl Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	773
				774	<p>The <tt><Private-Package></tt> instruction is similar in every way to the <tt><Export-Package></tt> instruction, except for the fact that these packages will <b>not</b>
				775	be exported by the bundle. If a package is selected by both the export
				776	and private package headers, then the export takes precedence.</p>
				777
Stuart McCulloch	dd89cdb	2008-05-03 08:13:09 +0000	[diff] [blame]	778	<h3><a name="ApacheFelixMavenBundlePlugin(BND)-{{<IncludeResource>}}"></a><tt><Include-Resource></tt></h3>
Karl Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	779
				780	<p>The <tt><Include-Resource></tt> instruction is a list of
				781	arbitrary resources that should be copied into the bundle JAR file. The
				782	specified resources are declared as clauses that can have the following
				783	forms:</p>
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	784
Stuart McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	785	<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Karl Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	786	<pre>clause ::= assignment \| inline \| simple
				787	assignment ::= PATH '=' PATH
				788	simple ::= PATH
				789	inline ::= '@' PATH
				790	</pre>
				791	</div></div>
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	792
Karl Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	793	<p>For the <tt><Include-Resource></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>
				794	form will place the resource in the bundle JAR with only the file name,
				795	i.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>
				796	points to a directory, the entire directory hierarchy is copied into
				797	the resulting bundle JAR file relative to the specified directory. If a
				798	specific resource must be placed into a subdirectory of the bundle jar,
				799	then use the <tt>assignment</tt> form, where the first path is the the
				800	destination path (including file name if the resource is a file) and
				801	the 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
				804	variable substitution will be performed on the resource, where
				805	variables in the resources are denoted with "${ ... }" syntax.</p>
				806
Stuart McCulloch	7c961f5	2008-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><Include-Resource></tt> instruction. If you specify your own <tt><Include-Resource></tt> instruction, this will replace the generated one. To include the generated list of Maven resources in your own <tt><Include-Resource></tt> instruction just add {<tt>maven-resources</tt>} to the list and it will be expanded automatically.</p>
				808
Stuart McCulloch	dd89cdb	2008-05-03 08:13:09 +0000	[diff] [blame]	809	<h3><a name="ApacheFelixMavenBundlePlugin(BND)-{{<ImportPackage>}}"></a><tt><Import-Package></tt></h3>
Karl Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	810
				811	<p>The <tt><Import-Package></tt> instruction is a list of
				812	packages that are required by the bundle's contained packages. The
				813	default for this header is "*", resulting in importing all referred
				814	packages. This header rarely has to be explicitly specified. However,
				815	in certain cases when there is an unwanted import, such an import can
				816	be removed by using a negation package pattern. The package patterns
				817	work in the same way as for <tt><Export-Package></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 McCulloch	dd89cdb	2008-05-03 08:13:09 +0000	[diff] [blame]	819	<p><a name="ApacheFelixMavenBundlePlugin(BND)-defaultbehavior"></a></p>
Karl Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	820
Stuart McCulloch	dd89cdb	2008-05-03 08:13:09 +0000	[diff] [blame]	821	<h2><a name="ApacheFelixMavenBundlePlugin(BND)-DefaultBehavior"></a>Default Behavior</h2>
Karl Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	822
				823	<p>To use this plugin, very little information is required by BND. As
				824	part of the Maven integration, the plugin tries to set reasonable
				825	defaults for various instructions. For example:</p>
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	826
Karl Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	827	<ul>
Stuart McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	828	<li><tt><Bundle-SymbolicName></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 McCulloch	b4212cc	2008-08-05 06:36:05 +0000	[diff] [blame]	829	Get the symbolic name as groupId + "." + artifactId, with the following exceptions:
				830	<ul>
				831	<li>if
				832	artifact.getFile is not null and the jar contains a OSGi Manifest with
				833	Bundle-SymbolicName property then that value is returned</li>
				834	<li>if
				835	groupId has only one section (no dots) and artifact.getFile is not null
				836	then the first package name with classes is returned. eg.
				837	commons-logging:commons-logging -> 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 -> org.apache.maven</li>
				839	<li>if
				840	artifactId starts with last section of groupId that portion is removed.
Stuart McCulloch	738a06d	2009-02-27 06:38:33 +0000	[diff] [blame]	841	eg. org.apache.maven:maven-core -> org.apache.maven.core<br>
				842	The 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 McCulloch	b4212cc	2008-08-05 06:36:05 +0000	[diff] [blame]	843	</ul>
				844	</li>
Stuart McCulloch	738a06d	2009-02-27 06:38:33 +0000	[diff] [blame]	845	<li><tt><Export-Package></tt>
				846	is now assumed to be the set of packages in your local Java sources,
				847	excluding 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><Private-Package></tt> is now assumed to be the set of packages in your local Java sources (note that any packages in both <tt><Export-Package></tt> and <tt><Private-Package></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><Import-Package></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 McCulloch	7c961f5	2008-01-02 08:56:07 +0000	[diff] [blame]	854	<li><tt><Include-Resource></tt> is generated from the project's Maven resources, typically "<tt>src/main/resources/</tt>",
Karl Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	855	which will copy the specified project directory hierarchy into the
				856	resulting bundle JAR file, mirroring standard Maven behavior.</li>
Stuart McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	857	<li><tt><Bundle-Version></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 Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	858	<li><tt><Bundle-Name></tt> is assumed to be "<tt>${pom.name</tt>}".</li>
				859	<li><tt><Bundle-Description></tt> is assumed to be "<tt>${pom.description</tt>}".</li>
				860	<li><tt><Bundle-License></tt> is assumed to be "<tt>${pom.licenses</tt>}".</li>
				861	<li><tt><Bundle-Vendor></tt> is assumed to be "<tt>${pom.organization.name</tt>}".</li>
				862	<li><tt><Bundle-DocURL></tt> is assumed to be "<tt>${pom.organization.url</tt>}".</li>
				863	</ul>
				864
				865
Stuart McCulloch	7c961f5	2008-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 Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	867	to be '2'. Additionally, it generates imports for every export to
				868	ensure package substitutability, which is very important when working
				869	with collaborating services. It is possible to override any of these
				870	values (except <tt>Bundle-ManifestVersion</tt>) just by specifying the desired value in the plugin configuration section of the POM file.</p>
				871
Stuart McCulloch	dd89cdb	2008-05-03 08:13:09 +0000	[diff] [blame]	872	<p><a name="ApacheFelixMavenBundlePlugin(BND)-howto"></a></p>
Karl Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	873
Stuart McCulloch	dd89cdb	2008-05-03 08:13:09 +0000	[diff] [blame]	874	<h1><a name="ApacheFelixMavenBundlePlugin(BND)-Detailed"HowTo""></a>Detailed "How To"</h1>
Karl Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	875
Stuart McCulloch	dd89cdb	2008-05-03 08:13:09 +0000	[diff] [blame]	876	<h2><a name="ApacheFelixMavenBundlePlugin(BND)-GetMaven2"></a>Get Maven2</h2>
Karl Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	877
				878	<p>The first step in the process of using the plugin is downloading and
				879	installing the latest version of the Maven2 runtime. The latest Maven2
				880	release and instuctions for getting started with Maven2 can be found at
Stuart McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	881	the <a href="http://maven.apache.org/index.html" rel="nofollow">Maven website</a>.</p>
Karl Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	882
Stuart McCulloch	dd89cdb	2008-05-03 08:13:09 +0000	[diff] [blame]	883	<h2><a name="ApacheFelixMavenBundlePlugin(BND)-UsingthePlugin"></a>Using the Plugin</h2>
Karl Pauls	f87ac14	2007-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
				886	some appropriate plugin configuration to your bundle project's POM.
				887	Below is an example of a simple OSGi bundle POM for Maven2:</p>
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	888
Stuart McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	889	<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Karl Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	890	<pre><project>
				891	<modelVersion>4.0.0</modelVersion>
				892	<groupId>my-osgi-bundles</groupId>
				893	<artifactId>examplebundle</artifactId>
				894	<packaging>bundle</packaging> <!-- (1) -->
				895	<version>1.0</version>
				896	<name>Example Bundle</name>
				897	<dependencies>
				898	<dependency>
				899	<groupId>org.apache.felix</groupId>
				900	<artifactId>org.osgi.core</artifactId>
Stuart McCulloch	7c961f5	2008-01-02 08:56:07 +0000	[diff] [blame]	901	<version>1.0.0</version>
Karl Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	902	</dependency>
				903	</dependencies>
				904	<build>
				905	<plugins>
				906	<plugin> <!-- (2) START -->
				907	<groupId>org.apache.felix</groupId>
				908	<artifactId>maven-bundle-plugin</artifactId>
				909	<extensions>true</extensions>
				910	<configuration>
				911	<instructions>
				912	<Export-Package>com.my.company.api</Export-Package>
				913	<Private-Package>com.my.company.*</Private-Package>
				914	<Bundle-Activator>com.my.company.Activator</Bundle-Activator>
				915	</instructions>
				916	</configuration>
				917	</plugin> <!-- (2) END -->
				918	</plugins>
				919	</build>
Karl Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	920	</project>
				921	</pre>
				922	</div></div>
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	923
				924	<p>There are two main things to note: (1) the <tt><packaging></tt>
				925	specifier must be "bundle" and (2) the plugin and configuration must be
Karl Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	926	specified (the configuration section is where you will issue
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	927	instructions to the plugin).</p>
Karl Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	928
Stuart McCulloch	dd89cdb	2008-05-03 08:13:09 +0000	[diff] [blame]	929	<h2><a name="ApacheFelixMavenBundlePlugin(BND)-RealWorldExample"></a>Real-World Example</h2>
Karl Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	930
				931	<p>Consider this more real-world example using Felix' Log Service
				932	implementation. The Log Service project is comprised of a single
				933	package: <tt>org.apache.felix.log.impl</tt>. It has a dependency on
				934	the core OSGi interfaces as well as a dependency on the compendium OSGi
				935	interfaces for the specific log service interfaces. The following is
				936	its POM file:</p>
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	937
Stuart McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	938	<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Karl Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	939	<pre><project>
				940	<modelVersion>4.0.0</modelVersion>
				941	<groupId>org.apache.felix</groupId>
				942	<artifactId>org.apache.felix.log</artifactId>
				943	<packaging>bundle</packaging>
				944	<name>Apache Felix Log Service</name>
				945	<version>0.8.0-SNAPSHOT</version>
				946	<description>
				947	This bundle provides an implementation of the OSGi R4 Log service.
				948	</description>
				949	<dependencies>
				950	<dependency>
				951	<groupId>${pom.groupId}</groupId>
				952	<artifactId>org.osgi.core</artifactId>
				953	<version>0.8.0-incubator</version>
				954	</dependency>
				955	<dependency>
				956	<groupId>${pom.groupId}</groupId>
				957	<artifactId>org.osgi.compendium</artifactId>
				958	<version>0.9.0-incubator-SNAPSHOT</version>
				959	</dependency>
				960	</dependencies>
				961	<build>
				962	<plugins>
				963	<plugin>
				964	<groupId>org.apache.felix</groupId>
				965	<artifactId>maven-bundle-plugin</artifactId>
				966	<extensions>true</extensions>
				967	<configuration>
				968	<instructions>
				969	<Export-Package>org.osgi.service.log</Export-Package>
				970	<Private-Package>org.apache.felix.log.impl</Private-Package>
				971	<Bundle-SymbolicName>${pom.artifactId}</Bundle-SymbolicName>
				972	<Bundle-Activator>${pom.artifactId}.impl.Activator</Bundle-Activator>
				973	<Export-Service>org.osgi.service.log.LogService,org.osgi.service.log.LogReaderService</Export-Service>
				974	</instructions>
				975	</configuration>
				976	</plugin>
				977	</plugins>
				978	</build>
Karl Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	979	</project>
				980	</pre>
				981	</div></div>
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	982
Karl Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	983	<p>Notice that the <tt><Export-Package></tt> instruction
				984	specifies that the bundle exports the Log Service package, even though
				985	this package is not contained in the bundle project. By declaring this,
				986	the plugin will copy the Log Service package into the resulting bundle
				987	JAR file. This is useful in this case because now the bundle can
				988	resolve without having to download the entire compendium bundle. The
				989	resulting manifest for the Log Service bundle looks like this (notice
				990	how the imports/exports automatically have version information
				991	associated with them, which was obtained from packageinfo files in the
				992	source packages):</p>
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	993
Stuart McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	994	<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Karl Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	995	<pre>Manifest-Version: 1
				996	Bundle-License: http://www.apache.org/licenses/LICENSE-2.0.txt
				997	Bundle-Activator: org.apache.felix.log.impl.Activator
				998	Import-Package: org.osgi.framework;version=1.3, org.osgi.service.log;v
				999	ersion=1.3
				1000	Include-Resource: src/main/resources
				1001	Export-Package: org.osgi.service.log;uses:=org.osgi.framework;version=
				1002	1.3
				1003	Bundle-Version: 0.8.0.SNAPSHOT
				1004	Bundle-Name: Apache Felix Log Service
				1005	Bundle-Description: This bundle provides an implementation of the OSGi
				1006	R4 Log service.
				1007	Private-Package: org.apache.felix.log.impl
				1008	Bundle-ManifestVersion: 2
				1009	Export-Service: org.osgi.service.log.LogService,org.osgi.service.log.L
				1010	ogReaderService
				1011	Bundle-SymbolicName: org.apache.felix.log
				1012	</pre>
				1013	</div></div>
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	1014
Karl Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	1015	<p>The resulting bundle JAR file has the following content (notice how
				1016	the LICENSE and NOTICE files were automatically copied from the <tt>src/main/resources/</tt> directory of the project):</p>
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	1017
Stuart McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	1018	<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Karl Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	1019	<pre>META-INF/MANIFEST.MF
				1020	LICENSE
				1021	META-INF/
				1022	META-INF/maven/
				1023	META-INF/maven/org.apache.felix/
				1024	META-INF/maven/org.apache.felix/org.apache.felix.log/
				1025	META-INF/maven/org.apache.felix/org.apache.felix.log/pom.properties
				1026	META-INF/maven/org.apache.felix/org.apache.felix.log/pom.xml
				1027	NOTICE
				1028	org/
				1029	org/apache/
				1030	org/apache/felix/
				1031	org/apache/felix/log/
				1032	org/apache/felix/log/impl/
				1033	org/apache/felix/log/impl/Activator.class
				1034	org/apache/felix/log/impl/Log.class
				1035	org/apache/felix/log/impl/LogEntryImpl.class
				1036	org/apache/felix/log/impl/LogException.class
				1037	org/apache/felix/log/impl/LogListenerThread.class
				1038	org/apache/felix/log/impl/LogNode.class
				1039	org/apache/felix/log/impl/LogNodeEnumeration.class
				1040	org/apache/felix/log/impl/LogReaderServiceFactory.class
				1041	org/apache/felix/log/impl/LogReaderServiceImpl.class
				1042	org/apache/felix/log/impl/LogServiceFactory.class
				1043	org/apache/felix/log/impl/LogServiceImpl.class
				1044	org/osgi/
				1045	org/osgi/service/
				1046	org/osgi/service/log/
				1047	org/osgi/service/log/LogEntry.class
				1048	org/osgi/service/log/LogListener.class
				1049	org/osgi/service/log/LogReaderService.class
				1050	org/osgi/service/log/LogService.class
				1051	org/osgi/service/log/package.html
				1052	org/osgi/service/log/packageinfo
				1053	</pre>
				1054	</div></div>
				1055
Stuart McCulloch	dd89cdb	2008-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 McCulloch	dd4ae5f	2008-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>
				1059	you can use the manifest goal to generate a bundle manifest. The maven-jar-plugin can then be used to<br>
				1060	add this manifest to the final artifact. For example:</p>
				1061
Stuart McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	1062	<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
Stuart McCulloch	dd4ae5f	2008-02-05 12:38:46 +0000	[diff] [blame]	1063	<pre class="code-xml"><span class="code-tag"><plugin></span>
				1064	<span class="code-tag"><artifactId></span>maven-jar-plugin<span class="code-tag"></artifactId></span>
				1065	<span class="code-tag"><configuration></span>
				1066	<span class="code-tag"><archive></span>
				1067	<span class="code-tag"><manifestFile></span>${project.build.outputDirectory}/META-INF/MANIFEST.MF<span class="code-tag"></manifestFile></span>
				1068	<span class="code-tag"></archive></span>
				1069	<span class="code-tag"></configuration></span>
				1070	<span class="code-tag"></plugin></span>
				1071	<span class="code-tag"><plugin></span>
				1072	<span class="code-tag"><groupId></span>org.apache.felix<span class="code-tag"></groupId></span>
				1073	<span class="code-tag"><artifactId></span>maven-bundle-plugin<span class="code-tag"></artifactId></span>
				1074	<span class="code-tag"><executions></span>
				1075	<span class="code-tag"><execution></span>
				1076	<span class="code-tag"><id></span>bundle-manifest<span class="code-tag"></id></span>
				1077	<span class="code-tag"><phase></span>process-classes<span class="code-tag"></phase></span>
				1078	<span class="code-tag"><goals></span>
				1079	<span class="code-tag"><goal></span>manifest<span class="code-tag"></goal></span>
				1080	<span class="code-tag"></goals></span>
				1081	<span class="code-tag"></execution></span>
				1082	<span class="code-tag"></executions></span>
Stuart McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	1083	<span class="code-tag"></plugin></span>
				1084	</pre>
Stuart McCulloch	dd4ae5f	2008-02-05 12:38:46 +0000	[diff] [blame]	1085	</div></div>
				1086
Stuart McCulloch	c9b81e1	2009-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>
				1088	for them in the bundleplugin configuration, for example if you want to use the plugin with WAR files:</p>
				1089
Stuart McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	1090	<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
Stuart McCulloch	c9b81e1	2009-02-26 21:29:51 +0000	[diff] [blame]	1091	<pre class="code-xml"><span class="code-tag"><plugin></span>
				1092	<span class="code-tag"><groupId></span>org.apache.felix<span class="code-tag"></groupId></span>
				1093	<span class="code-tag"><artifactId></span>maven-bundle-plugin<span class="code-tag"></artifactId></span>
				1094	<span class="code-tag"><executions></span>
				1095	<span class="code-tag"><execution></span>
				1096	<span class="code-tag"><id></span>bundle-manifest<span class="code-tag"></id></span>
				1097	<span class="code-tag"><phase></span>process-classes<span class="code-tag"></phase></span>
				1098	<span class="code-tag"><goals></span>
				1099	<span class="code-tag"><goal></span>manifest<span class="code-tag"></goal></span>
				1100	<span class="code-tag"></goals></span>
				1101	<span class="code-tag"></execution></span>
				1102	<span class="code-tag"></executions></span>
				1103	<span class="code-tag"><configuration></span>
				1104	<span class="code-tag"><supportedProjectTypes></span>
				1105	<span class="code-tag"><supportedProjectType></span>jar<span class="code-tag"></supportedProjectType></span>
				1106	<span class="code-tag"><supportedProjectType></span>bundle<span class="code-tag"></supportedProjectType></span>
				1107	<span class="code-tag"><supportedProjectType></span>war<span class="code-tag"></supportedProjectType></span>
				1108	<span class="code-tag"></supportedProjectTypes></span>
				1109	<span class="code-tag"><instructions></span>
				1110	<span class="code-tag"><span class="code-comment"><!-- ...etc... --></span></span>
				1111	<span class="code-tag"></instructions></span>
				1112	<span class="code-tag"></configuration></span>
Stuart McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	1113	<span class="code-tag"></plugin></span>
				1114	</pre>
Stuart McCulloch	c9b81e1	2009-02-26 21:29:51 +0000	[diff] [blame]	1115	</div></div>
				1116
Stuart McCulloch	dd89cdb	2008-05-03 08:13:09 +0000	[diff] [blame]	1117	<h2><a name="ApacheFelixMavenBundlePlugin(BND)-BuildingthePlugin"></a>Building the Plugin</h2>
Karl Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	1118
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	1119	<p>The plugin is hosted at the Apache Felix project. The following
				1120	steps describe how to build and install the plugin into your local
				1121	Maven2 repository.</p>
Karl Pauls	f87ac14	2007-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 McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	1124
Stuart McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	1125	<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	1126	<pre>$ svn co http://svn.apache.org/repos/asf/felix/trunk/bundleplugin
Karl Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	1127	</pre>
				1128	</div></div>
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	1129
Karl Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	1130	<p>Using Maven2, build and install the maven-bundle-plugin by issuing
				1131	the following Maven2 command in the project directory that was created
				1132	as a result of the previous step.</p>
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	1133
Stuart McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	1134	<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Karl Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	1135	<pre>$ mvn install
				1136	</pre>
				1137	</div></div>
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	1138
Stuart McCulloch	dd89cdb	2008-05-03 08:13:09 +0000	[diff] [blame]	1139	<h1><a name="ApacheFelixMavenBundlePlugin(BND)-Goals"></a>Goals</h1>
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	1140
				1141	<p>The maven-bundle-plugin also provides additional functionality via
				1142	some Maven goals. Command-line execution of a goal is performed as
				1143	follows:</p>
				1144
Stuart McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	1145	<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Stuart McCulloch	93de649	2007-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 McCulloch	0340ae4	2008-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 McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	1154	configuration options:
				1155	<ul>
Stuart McCulloch	dd4ae5f	2008-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 McCulloch	738a06d	2009-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>
				1159	Version 2 of the bundleplugin now supports the same style of filter clauses in <tt>excludeDependencies</tt> as <tt>Embed-Dependency</tt>.</li>
Stuart McCulloch	0340ae4	2008-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 McCulloch	c9b81e1	2009-02-26 21:29:51 +0000	[diff] [blame]	1161	<li><em><tt>supportedProjectTypes</tt></em> defaults to "jar","bundle"</li>
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	1162	</ul>
				1163	</li>
Stuart McCulloch	dd4ae5f	2008-02-05 12:38:46 +0000	[diff] [blame]	1164	</ul>
				1165
				1166
				1167	<ul>
Stuart McCulloch	0340ae4	2008-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 McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	1169	configuration options:
				1170	<ul>
Stuart McCulloch	981bd34	2008-05-03 12:49:39 +0000	[diff] [blame]	1171	<li><em><tt>wrapImportPackage</tt></em> defaults to "*"</li>
Stuart McCulloch	c9b81e1	2009-02-26 21:29:51 +0000	[diff] [blame]	1172	<li><em><tt>supportedProjectTypes</tt></em> defaults to "jar","bundle"</li>
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	1173	</ul>
				1174	</li>
Stuart McCulloch	dd4ae5f	2008-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 McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	1180	configuration options:
				1181	<ul>
Stuart McCulloch	981bd34	2008-05-03 12:49:39 +0000	[diff] [blame]	1182	<li><em><tt>wrapImportPackage</tt></em> defaults to "*"</li>
Stuart McCulloch	c9b81e1	2009-02-26 21:29:51 +0000	[diff] [blame]	1183	<li><em><tt>supportedProjectTypes</tt></em> defaults to "jar","bundle"</li>
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	1184	</ul>
				1185	</li>
Stuart McCulloch	dd4ae5f	2008-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 McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	1191	configuration options:
				1192	<ul>
Stuart McCulloch	dd4ae5f	2008-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 McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	1195	</ul>
				1196	</li>
				1197	</ul>
				1198
				1199
Stuart McCulloch	0340ae4	2008-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>
				1202	configuration options:
				1203	<ul>
				1204	<li><em><tt>obrRepository</tt></em> path to local OBR, defaults to <em><local-maven-repository></em><tt>/repository.xml</tt></li>
Stuart McCulloch	c9b81e1	2009-02-26 21:29:51 +0000	[diff] [blame]	1205	<li><em><tt>supportedProjectTypes</tt></em> defaults to "jar","bundle"</li>
Stuart McCulloch	0340ae4	2008-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>
				1220	configuration options:
				1221	<ul>
				1222	<li><em><tt>obrRepository</tt></em> path to local OBR, defaults to <em><local-maven-repository></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>
				1238	configuration 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 McCulloch	c9b81e1	2009-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 McCulloch	0340ae4	2008-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 McCulloch	c9b81e1	2009-02-26 21:29:51 +0000	[diff] [blame]	1245	<li><em><tt>obrDeploymentRepository</tt></em> optional OBR specific deployment repository.</li>
Stuart McCulloch	0340ae4	2008-02-22 11:27:18 +0000	[diff] [blame]	1246	<li><em><tt>ignoreLock</tt></em> ignore remote locking when updating the OBR</li>
Stuart McCulloch	c9b81e1	2009-02-26 21:29:51 +0000	[diff] [blame]	1247	<li><em><tt>supportedProjectTypes</tt></em> defaults to "jar","bundle"</li>
Stuart McCulloch	0340ae4	2008-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>
				1255	configuration 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 McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	1261	<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Stuart McCulloch	0340ae4	2008-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 McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	1266	<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Stuart McCulloch	0340ae4	2008-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>
				1286	configuration options:
				1287	<ul>
				1288	<li><em><tt>obrRepository</tt></em> path to local OBR, defaults to <em><local-maven-repository></em><tt>/repository.xml</tt></li>
				1289	</ul>
				1290	</li>
				1291	</ul>
				1292
				1293
Stuart McCulloch	c9b81e1	2009-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>
				1296	configuration 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 McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	1309	<p>There are also new instructions available from the underlying BND
Stuart McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	1310	tool, which continues to be improved independently; for the latest see <a href="http://aqute.biz/Code/Bnd" rel="nofollow">BND documentation</a>.</p>
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	1311
Stuart McCulloch	dd4ae5f	2008-02-05 12:38:46 +0000	[diff] [blame]	1312	<p>The default goal <b><tt>bundle</tt></b> will be initialized by setting the <packaging> entry to "bundle".</p>
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	1313
Stuart McCulloch	dd89cdb	2008-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 McCulloch	7c961f5	2008-01-02 08:56:07 +0000	[diff] [blame]	1315
Stuart McCulloch	dd89cdb	2008-05-03 08:13:09 +0000	[diff] [blame]	1316	<h2><a name="ApacheFelixMavenBundlePlugin(BND)-Embeddingdependencies"></a>Embedding dependencies</h2>
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	1317
Stuart McCulloch	7c961f5	2008-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><Embed-Dependency></tt> instruction:</p>
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	1319
Stuart McCulloch	a1a6363	2009-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"><Embed-Dependency></span>dependencies<span class="code-tag"></Embed-Dependency></span>
				1322	</pre>
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	1323	</div></div>
				1324
				1325	<p>where:</p>
				1326
Stuart McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	1327	<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	1328	<pre>dependencies ::= clause ( ',' clause ) *
Stuart McCulloch	c9b81e1	2009-02-26 21:29:51 +0000	[diff] [blame]	1329	clause ::= MATCH ( ';' attr '=' MATCH \| ';inline=' inline )
Stuart McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	1330	attr ::= 'groupId' \| 'artifactId' \| 'version' \| 'scope' \| 'type' \| 'classifier' \| 'optional'
Stuart McCulloch	c9b81e1	2009-02-26 21:29:51 +0000	[diff] [blame]	1331	inline ::= 'true' \| 'false' \| PATH ( '\|' PATH ) *
				1332	MATCH ::= <globbed regular expression>
				1333	PATH ::= <Ant-style path expression>
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	1334	</pre>
				1335	</div></div>
				1336
Stuart McCulloch	0340ae4	2008-02-22 11:27:18 +0000	[diff] [blame]	1337	<p>The plugin uses the <tt><Embed-Dependency></tt> instruction to transform the project dependencies into <tt><Include-Resource></tt> and <tt><Bundle-ClassPath></tt>
				1338	clauses, which are then appended to the current set of instructions and
				1339	passed onto BND. If you want the embedded dependencies to be at the
				1340	start or middle of <tt><Include-Resource></tt> or <tt><Bundle-ClassPath></tt> then you can use {<tt>maven-dependencies</tt>}, which will automatically expand to the relevant clauses.</p>
Stuart McCulloch	7c961f5	2008-01-02 08:56:07 +0000	[diff] [blame]	1341
Stuart McCulloch	dd89cdb	2008-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 McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	1344	<p>some examples:</p>
				1345
Stuart McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	1346	<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
Stuart McCulloch	dd89cdb	2008-05-03 08:13:09 +0000	[diff] [blame]	1347	<pre class="code-xml"><span class="code-tag"><span class="code-comment"><!-- embed all compile and runtime scope dependencies --></span></span>
				1348	<span class="code-tag"><Embed-Dependency></span>*;scope=compile\|runtime<span class="code-tag"></Embed-Dependency></span>
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	1349
Stuart McCulloch	c9b81e1	2009-02-26 21:29:51 +0000	[diff] [blame]	1350	<span class="code-tag"><span class="code-comment"><!-- embed any dependencies with artifactId junit and scope runtime --></span></span>
				1351	<span class="code-tag"><Embed-Dependency></span>junit;scope=runtime<span class="code-tag"></Embed-Dependency></span>
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	1352
Stuart McCulloch	c9b81e1	2009-02-26 21:29:51 +0000	[diff] [blame]	1353	<span class="code-tag"><span class="code-comment"><!-- inline all non-pom dependencies, except those with scope runtime --></span></span>
				1354	<span class="code-tag"><Embed-Dependency></span>*;scope=!runtime;type=!pom;inline=true<span class="code-tag"></Embed-Dependency></span>
Stuart McCulloch	dd89cdb	2008-05-03 08:13:09 +0000	[diff] [blame]	1355
				1356	<span class="code-tag"><span class="code-comment"><!-- embed all compile and runtime scope dependencies, except those with artifactIds in the given list --></span></span>
Stuart McCulloch	c9b81e1	2009-02-26 21:29:51 +0000	[diff] [blame]	1357	<span class="code-tag"><Embed-Dependency></span>*;scope=compile\|runtime;inline=false;artifactId=!cli\|lang\|runtime\|tidy\|jsch<span class="code-tag"></Embed-Dependency></span>
				1358
				1359	<span class="code-tag"><span class="code-comment"><!-- inline contents of selected folders from all dependencies --></span></span>
Stuart McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	1360	<span class="code-tag"><Embed-Dependency></span>;inline=images/\|icons/*<span class="code-tag"></Embed-Dependency></span>
				1361	</pre>
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	1362	</div></div>
				1363
Stuart McCulloch	0340ae4	2008-02-22 11:27:18 +0000	[diff] [blame]	1364	<p>examples of using {<tt>maven-dependencies</tt>}:</p>
				1365
Stuart McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	1366	<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
Stuart McCulloch	0340ae4	2008-02-22 11:27:18 +0000	[diff] [blame]	1367	<pre class="code-xml"><span class="code-tag"><Include-Resource></span>
				1368	{maven-resources}, {maven-dependencies},
				1369	org/foo/Example.class=target/classes/org/foo/Example.class
				1370	<span class="code-tag"></Include-Resource></span>
				1371
Stuart McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	1372	<span class="code-tag"><Bundle-ClassPath></span>.,{maven-dependencies},some.jar<span class="code-tag"></Bundle-ClassPath></span>
				1373	</pre>
Stuart McCulloch	0340ae4	2008-02-22 11:27:18 +0000	[diff] [blame]	1374	</div></div>
				1375
Stuart McCulloch	7c961f5	2008-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 McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	1377
				1378	<ul>
				1379	<li><tt><Embed-StripVersion>true</Embed-StripVersion></tt> - removes the version from the file (ie. <em>artifactId.jar</em>)</li>
				1380	<li><tt><Embed-StripGroup>false</Embed-StripGroup></tt> - adds the groupId as a subdirectory (ie. <em>groupId/artifactId-version.jar</em>)</li>
				1381	<li><tt><Embed-Directory>directory</Embed-Directory></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
				1386	changed to include the complete set of transitive dependencies with the
				1387	following option:</p>
				1388
Stuart McCulloch	a1a6363	2009-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"><Embed-Transitive></span>true<span class="code-tag"></Embed-Transitive></span>
				1391	</pre>
Stuart McCulloch	93de649	2007-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 McCulloch	a1a6363	2009-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"><Embed-Dependency></span>*;scope=compile\|runtime;inline=true<span class="code-tag"></Embed-Dependency></span>
				1398	</pre>
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	1399	</div></div>
				1400
Stuart McCulloch	dd89cdb	2008-05-03 08:13:09 +0000	[diff] [blame]	1401	<h3><a name="ApacheFelixMavenBundlePlugin(BND)-EmbedDependencyandExportPackage"></a>Embed-Dependency and Export-Package</h3>
Stuart McCulloch	7c961f5	2008-01-02 08:56:07 +0000	[diff] [blame]	1402
				1403	<p>If you embed a dependency with <tt><Embed-Dependency></tt>, and your <tt><Export-Package></tt> or <tt><Private-Package></tt> instructions match packages inside the embedded jar, you will see some duplication inside the bundle. This is because the <tt><Export-Package></tt> and <tt><Private-Package></tt>
				1404	instructions will result in classes being inlined in the bundle, even
				1405	though they also exist inside the embedded jar. If you want to export
				1406	packages from an embedded dependency without such duplication then you
				1407	can either inline the dependency, or use a new BND instruction called <tt><_exportcontents></tt>.</p>
				1408
				1409	<p><tt><_exportcontents></tt> behaves just like Export-Package, except it doesn't change the content of the bundle, just what content should be exported.</p>
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	1410
Stuart McCulloch	dd89cdb	2008-05-03 08:13:09 +0000	[diff] [blame]	1411	<h2><a name="ApacheFelixMavenBundlePlugin(BND)-OBRintegration"></a>OBR integration</h2>
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	1412
				1413	<p>The latest Maven Bundle Plugin automatically updates the local OBR
				1414	repository.xml file during the install phase, using a default location
				1415	of:</p>
				1416
Stuart McCulloch	a1a6363	2009-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"><LOCAL-MAVEN-REPOSITORY>/repository.xml
				1419	</pre>
Stuart McCulloch	93de649	2007-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 McCulloch	a1a6363	2009-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=<PATH_TO_OBR>
				1426	</pre>
Stuart McCulloch	93de649	2007-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 McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	1431	<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	1432	<pre class="code-xml"><span class="code-tag"><groupId></span>org.apache.felix<span class="code-tag"></groupId></span>
				1433	<span class="code-tag"><artifactId></span>maven-bundle-plugin<span class="code-tag"></artifactId></span>
				1434	<span class="code-tag"><extensions></span>true<span class="code-tag"></extensions></span>
				1435	<span class="code-tag"><configuration></span>
				1436	<span class="code-tag"><obrRepository></span>PATH_TO_OBR<span class="code-tag"></obrRepository></span>
				1437	<span class="code-tag"><instructions></span>
				1438	<span class="code-tag"><span class="code-comment"><!-- bnd instructions --></span></span>
				1439	<span class="code-tag"></instructions></span>
Stuart McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	1440	<span class="code-tag"></configuration></span>
				1441	</pre>
Stuart McCulloch	93de649	2007-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 McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	1446	<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	1447	<pre class="code-xml"><span class="code-tag"><groupId></span>org.apache.felix<span class="code-tag"></groupId></span>
				1448	<span class="code-tag"><artifactId></span>maven-bundle-plugin<span class="code-tag"></artifactId></span>
				1449	<span class="code-tag"><extensions></span>true<span class="code-tag"></extensions></span>
				1450	<span class="code-tag"><configuration></span>
				1451	<span class="code-tag"><obrRepository></span>NONE<span class="code-tag"></obrRepository></span>
				1452	<span class="code-tag"><instructions></span>
				1453	<span class="code-tag"><span class="code-comment"><!-- bnd instructions --></span></span>
				1454	<span class="code-tag"></instructions></span>
Stuart McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	1455	<span class="code-tag"></configuration></span>
				1456	</pre>
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	1457	</div></div>
				1458
Stuart McCulloch	dd89cdb	2008-05-03 08:13:09 +0000	[diff] [blame]	1459	<h2><a name="ApacheFelixMavenBundlePlugin(BND)-Eclipse/PDEintegration"></a>Eclipse/PDE integration</h2>
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	1460
				1461	<p>It is possible to configure the Maven Bundle Plugin to put the
				1462	bundle manifest where Eclipse/PDE expects it, and use the Maven
				1463	Dependency Plugin to arrange for any embedded dependencies to appear in
				1464	a local directory that matches the Bundle-ClassPath entries. Here is an
				1465	example POM that does this:</p>
				1466
Stuart McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	1467	<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	1468	<pre><project>
				1469
				1470	<properties>
				1471	<bundle.symbolicName>org.example</bundle.symbolicName>
				1472	<bundle.namespace>org.example</bundle.namespace>
				1473	</properties>
				1474
				1475	<modelVersion>4.0.0</modelVersion>
				1476	<groupId>examples</groupId>
				1477	<artifactId>org.example</artifactId>
				1478	<version>1.0-SNAPSHOT</version>
				1479
				1480	<name>${bundle.symbolicName} [${bundle.namespace}]</name>
				1481
				1482	<packaging>bundle</packaging>
				1483
				1484	<build>
Stuart McCulloch	dd4ae5f	2008-02-05 12:38:46 +0000	[diff] [blame]	1485	<resources>
				1486	<resource>
				1487	<directory>src/main/resources</directory>
				1488	</resource>
				1489	<resource>
				1490	<directory>.</directory>
				1491	<includes>
				1492	<include>plugin.xml</include>
				1493	</includes>
				1494	</resource>
				1495	</resources>
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	1496	<plugins>
				1497	<plugin>
				1498	<groupId>org.apache.felix</groupId>
				1499	<artifactId>maven-bundle-plugin</artifactId>
Stuart McCulloch	0340ae4	2008-02-22 11:27:18 +0000	[diff] [blame]	1500	<version>1.2.1</version>
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	1501	<extensions>true</extensions>
				1502	<!--
				1503	the following instructions build a simple set of public/private classes into an OSGi bundle
				1504	-->
				1505	<configuration>
				1506	<manifestLocation>META-INF</manifestLocation>
				1507	<instructions>
				1508	<Bundle-SymbolicName>${bundle.symbolicName}</Bundle-SymbolicName>
				1509	<Bundle-Version>${pom.version}</Bundle-Version>
				1510	<!--
				1511	assume public classes are in the top package, and private classes are under ".internal"
				1512	-->
Stuart McCulloch	dd4ae5f	2008-02-05 12:38:46 +0000	[diff] [blame]	1513	<Export-Package>!${bundle.namespace}.internal.,${bundle.namespace}.;version="${pom.version}"</Export-Package>
				1514	<Private-Package>${bundle.namespace}.internal.*</Private-Package>
				1515	<Bundle-Activator>${bundle.namespace}.internal.ExampleActivator</Bundle-Activator>
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	1516	<!--
				1517	embed compile/runtime dependencies using path that matches the copied dependency folder
				1518	-->
				1519	<Embed-Dependency>*;scope=compile\|runtime;inline=false</Embed-Dependency>
				1520	<Embed-Directory>target/dependency</Embed-Directory>
				1521	<Embed-StripGroup>true</Embed-StripGroup>
				1522	</instructions>
				1523	</configuration>
				1524	</plugin>
				1525	<plugin>
				1526	<artifactId>maven-dependency-plugin</artifactId>
				1527	<executions>
				1528	<execution>
				1529	<id>copy-dependencies</id>
				1530	<phase>package</phase>
				1531	<goals>
				1532	<goal>copy-dependencies</goal>
				1533	</goals>
				1534	</execution>
				1535	</executions>
				1536	</plugin>
				1537	</plugins>
				1538	</build>
				1539
				1540	<dependencies>
				1541	<dependency>
				1542	<groupId>org.osgi</groupId>
				1543	<artifactId>osgi_R4_core</artifactId>
				1544	<version>1.0</version>
				1545	<scope>provided</scope>
				1546	<optional>true</optional>
				1547	</dependency>
				1548	<dependency>
				1549	<groupId>org.osgi</groupId>
				1550	<artifactId>osgi_R4_compendium</artifactId>
				1551	<version>1.0</version>
				1552	<scope>provided</scope>
				1553	<optional>true</optional>
				1554	</dependency>
				1555	<dependency>
				1556	<groupId>junit</groupId>
				1557	<artifactId>junit</artifactId>
				1558	<version>3.8.1</version>
				1559	<scope>compile</scope>
				1560	<optional>true</optional>
				1561	</dependency>
				1562	</dependencies>
				1563
				1564	</project>
				1565	</pre>
				1566	</div></div>
				1567
				1568	<p>To generate the Eclipse metadata use:</p>
				1569
Stuart McCulloch	a1a6363	2009-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 McCulloch	93de649	2007-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 McCulloch	a1a6363	2009-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 McCulloch	93de649	2007-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 McCulloch	a1a6363	2009-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 McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	1584	</div></div>
				1585
				1586	<p>to create the appropriate Eclipse files and manifest, and also
				1587	handle any embedded entries. The pax:eclipse goal extends
				1588	eclipse:eclipse, and supports the same parameters.</p>
				1589
Stuart McCulloch	dd89cdb	2008-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 McCulloch	93de649	2007-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>,
				1593	for example when you embed the classes from another jar. This can
				1594	sometimes cause unforeseen problems in Maven, as it will use the output
				1595	directory (<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
				1598	contents of the bundle to the output directory after the packaging
				1599	step, so the additional classes will be found where Maven expects them.
				1600	Thankfully there is now an easy option to do this in the bundle-plugin:</p>
				1601
Stuart McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	1602	<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
Stuart McCulloch	dd4ae5f	2008-02-05 12:38:46 +0000	[diff] [blame]	1603	<pre class="code-xml"><span class="code-tag"><groupId></span>org.apache.felix<span class="code-tag"></groupId></span>
				1604	<span class="code-tag"><artifactId></span>maven-bundle-plugin<span class="code-tag"></artifactId></span>
				1605	<span class="code-tag"><extensions></span>true<span class="code-tag"></extensions></span>
				1606	<span class="code-tag"><configuration></span>
				1607	<span class="code-tag"><unpackBundle></span>true<span class="code-tag"></unpackBundle></span>
				1608	<span class="code-tag"><instructions></span>
				1609	<span class="code-tag"><span class="code-comment"><!-- bnd instructions --></span></span>
				1610	<span class="code-tag"></instructions></span>
Stuart McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	1611	<span class="code-tag"></configuration></span>
				1612	</pre>
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	1613	</div></div>
				1614
Stuart McCulloch	dd89cdb	2008-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 McCulloch	93de649	2007-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 McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	1619	<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
Stuart McCulloch	dd4ae5f	2008-02-05 12:38:46 +0000	[diff] [blame]	1620	<pre class="code-xml"><span class="code-tag"><_include></span>src/main/resources/META-INF/MANIFEST.MF<span class="code-tag"></_include></span>
Stuart McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	1621	<span class="code-tag"><Export-Package></span>org.example.*<span class="code-tag"></Export-Package></span>
				1622	</pre>
Stuart McCulloch	93de649	2007-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
				1626	copy across all manifest attributes starting with a capital letter.<br>
				1627	As shown in the above example, you could use this to include a non-OSGi
				1628	manifest which you then customize with extra OSGi attributes.</p>
				1629
Stuart McCulloch	dd89cdb	2008-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 McCulloch	0340ae4	2008-02-22 11:27:18 +0000	[diff] [blame]	1631
Stuart McCulloch	dd89cdb	2008-05-03 08:13:09 +0000	[diff] [blame]	1632	<h2><a name="ApacheFelixMavenBundlePlugin(BND)-bundle:ant"></a>bundle:ant</h2>
Stuart McCulloch	0340ae4	2008-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,
				1637	so any source changes should be reflected in the (re)generated manifest.</p>
				1638
				1639	<p>Example:</p>
Stuart McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	1640	<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Stuart McCulloch	0340ae4	2008-02-22 11:27:18 +0000	[diff] [blame]	1641	<pre>mvn ant:ant bundle:ant
				1642
				1643	ant clean package
				1644	</pre>
				1645	</div></div>
				1646
Stuart McCulloch	dd89cdb	2008-05-03 08:13:09 +0000	[diff] [blame]	1647	<h2><a name="ApacheFelixMavenBundlePlugin(BND)-bundle:installfile"></a>bundle:install-file</h2>
Stuart McCulloch	0340ae4	2008-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><local-maven-repository></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 McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	1666	<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Stuart McCulloch	0340ae4	2008-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 McCulloch	dd89cdb	2008-05-03 08:13:09 +0000	[diff] [blame]	1672	<h2><a name="ApacheFelixMavenBundlePlugin(BND)-bundle:deploy"></a>bundle:deploy</h2>
Stuart McCulloch	0340ae4	2008-02-22 11:27:18 +0000	[diff] [blame]	1673
				1674	<p>The <b>deploy goal</b> updates the remote OBR with the details of
				1675	the deployed bundle from the local Maven repository. The remote OBR is
Stuart McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	1676	found by querying the <tt><distributionManagement></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 McCulloch	0340ae4	2008-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 McCulloch	dd89cdb	2008-05-03 08:13:09 +0000	[diff] [blame]	1691	<h2><a name="ApacheFelixMavenBundlePlugin(BND)-bundle:deployfile"></a>bundle:deploy-file</h2>
Stuart McCulloch	0340ae4	2008-02-22 11:27:18 +0000	[diff] [blame]	1692
Stuart McCulloch	a1a6363	2009-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 McCulloch	0340ae4	2008-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 McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	1703	<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Stuart McCulloch	0340ae4	2008-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 McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	1708	<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Stuart McCulloch	0340ae4	2008-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 McCulloch	738a06d	2009-02-27 06:38:33 +0000	[diff] [blame]	1724
Stuart McCulloch	0340ae4	2008-02-22 11:27:18 +0000	[diff] [blame]	1725	<p>Example:</p>
Stuart McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	1726	<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Stuart McCulloch	0340ae4	2008-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 McCulloch	dd89cdb	2008-05-03 08:13:09 +0000	[diff] [blame]	1733	<h2><a name="ApacheFelixMavenBundlePlugin(BND)-bundle:clean"></a>bundle:clean</h2>
Stuart McCulloch	0340ae4	2008-02-22 11:27:18 +0000	[diff] [blame]	1734
				1735	<p>Sometimes you would like to clean your local OBR because it contains
				1736	bundles that are no longer in your local Maven repository. This case
				1737	often occurs when artifacts were deleted manually. The
				1738	maven-bundle-plugin provides a simple goal to check for missing
				1739	bundles, 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><local-maven-repository></em><tt>/repository.xml</tt></li>
				1744	</ul>
				1745
				1746
				1747	<p>Example:</p>
Stuart McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	1748	<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Stuart McCulloch	0340ae4	2008-02-22 11:27:18 +0000	[diff] [blame]	1749	<pre>mvn bundle:clean
				1750	</pre>
				1751	</div></div>
				1752
Stuart McCulloch	dd89cdb	2008-05-03 08:13:09 +0000	[diff] [blame]	1753	<h2><a name="ApacheFelixMavenBundlePlugin(BND)-Concurrentupdates"></a>Concurrent updates</h2>
Stuart McCulloch	0340ae4	2008-02-22 11:27:18 +0000	[diff] [blame]	1754
				1755	<p>With a remote OBR, several uploads may occur at the same time.
				1756	However, the remote OBR is centralized in one file, so concurrent
				1757	modification must be avoided. To achieve this, the plug-in implements a
				1758	locking system. Each time the plug-in tries to modify the file it sets
				1759	a file based lock. If it can't take the lock, it will wait and retry.
				1760	After 3 attempts the upload process fails. To bypass this lock add <tt>-DignoreLock</tt> to the command-line (or add <tt><ignoreLock>true<ignoreLock></tt> to the configuration section of your Pom).</p>
				1761
Stuart McCulloch	dd89cdb	2008-05-03 08:13:09 +0000	[diff] [blame]	1762	<h2><a name="ApacheFelixMavenBundlePlugin(BND)-FTPprotocol"></a>FTP protocol</h2>
Stuart McCulloch	0340ae4	2008-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 McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	1765	<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
Stuart McCulloch	0340ae4	2008-02-22 11:27:18 +0000	[diff] [blame]	1766	<pre class="code-xml"><span class="code-tag"><build></span>
				1767	<span class="code-tag"><extensions></span>
				1768	<span class="code-tag"><extension></span>
				1769	<span class="code-tag"><groupId></span>org.apache.maven.wagon<span class="code-tag"></groupId></span>
				1770	<span class="code-tag"><artifactId></span>wagon-ftp<span class="code-tag"></artifactId></span>
				1771	<span class="code-tag"><version></span>1.0-alpha-6<span class="code-tag"></version></span>
				1772	<span class="code-tag"></extension></span>
				1773	<span class="code-tag"></extensions></span>
Stuart McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	1774	<span class="code-tag"></build></span>
				1775	</pre>
Stuart McCulloch	0340ae4	2008-02-22 11:27:18 +0000	[diff] [blame]	1776	</div></div>
				1777
Stuart McCulloch	dd89cdb	2008-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 McCulloch	0340ae4	2008-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 McCulloch	a1a6363	2009-09-16 09:47:50 +0000	[diff] [blame]	1789	<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Stuart McCulloch	0340ae4	2008-02-22 11:27:18 +0000	[diff] [blame]	1790	<pre>Bindex
				1791	\| (overrides)
				1792	pom.xml
				1793	\| (overrides)
				1794	obr.xml
				1795	</pre>
				1796	</div></div>
				1797	<p>A warning message is displayed when existing information is overridden.</p>
				1798
Stuart McCulloch	dd89cdb	2008-05-03 08:13:09 +0000	[diff] [blame]	1799	<h2><a name="ApacheFelixMavenBundlePlugin(BND)-Knownissues&limitations"></a>Known issues & limitations</h2>
Stuart McCulloch	0340ae4	2008-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
				1803	by Bindex) must be correct, because the plug-in does not check its
				1804	syntax.</li>
				1805	</ol>
				1806
				1807
Stuart McCulloch	dd89cdb	2008-05-03 08:13:09 +0000	[diff] [blame]	1808	<h1><a name="ApacheFelixMavenBundlePlugin(BND)-Feedback"></a>Feedback</h1>
Stuart McCulloch	93de649	2007-12-16 15:59:05 +0000	[diff] [blame]	1809
Stuart McCulloch	a1a6363	2009-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 Pauls	f87ac14	2007-07-06 22:36:17 +0000	[diff] [blame]	1811	</div>
Stuart McCulloch	b4212cc	2008-08-05 06:36:05 +0000	[diff] [blame]	1812	</body></html>