blob: 256a1bd646ff626192efcafb374e58ab35969b1c [file] [log] [blame]
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +00001<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
Stuart McCulloch5f3ddf72008-05-03 12:49:39 +00002<html><head>
Stuart McCulloch5f3ddf72008-05-03 12:49:39 +00003 <title>Apache Felix - Apache Felix Maven Bundle Plugin (BND)</title>
Stuart McCulloch3f38f732008-05-03 08:13:09 +00004 <link rel="stylesheet" href="apache-felix-maven-bundle-plugin-bnd_files/site.css" type="text/css" media="all">
Stuart McCulloch5f3ddf72008-05-03 12:49:39 +00005 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +00006 </head>
7 <body>
Stuart McCulloch3f38f732008-05-03 08:13:09 +00008 <div class="title"><div class="logo"><a href="http://felix.apache.org/site/index.html"><img alt="Apache Felix" src="apache-felix-maven-bundle-plugin-bnd_files/logo.png" border="0"></a></div><div class="header"><a href="http://www.apache.org/"><img alt="Apache" src="apache-felix-maven-bundle-plugin-bnd_files/apache.png" border="0"></a></div></div>
Karl Paulsf87ac142007-07-06 22:36:17 +00009 <div class="menu">
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +000010<ul>
Stuart McCulloch93de6492007-12-16 15:59:05 +000011 <li><a href="http://felix.apache.org/site/news.html" title="news">news</a></li>
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +000012 <li><a href="http://www.apache.org/licenses/" class="external-link" rel="nofollow">license</a></li>
13 <li><a href="http://felix.apache.org/site/downloads.cgi" class="external-link" rel="nofollow">downloads</a></li>
Stuart McCulloch93de6492007-12-16 15:59:05 +000014 <li><a href="http://felix.apache.org/site/documentation.html" title="documentation">documentation</a></li>
15 <li><a href="http://felix.apache.org/site/mailinglists.html" title="mailinglists">mailing lists</a></li>
Stuart McCulloch3f38f732008-05-03 08:13:09 +000016 <li><a href="http://felix.apache.org/site/contributing.html" title="Contributing">contributing</a></li>
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +000017 <li><a href="http://www.apache.org/" class="external-link" rel="nofollow">asf</a></li>
18 <li><a href="http://www.apache.org/security/" class="external-link" rel="nofollow">security</a></li>
19 <li><a href="http://www.apache.org/foundation/sponsorship.html" class="external-link" rel="nofollow">sponsorship</a></li>
20 <li><a href="http://www.apache.org/foundation/thanks.html" class="external-link" rel="nofollow">sponsors</a>
Stuart McCulloch3f38f732008-05-03 08:13:09 +000021<!-- ApacheCon Ad -->
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +000022<iframe src="apache-felix-maven-bundle-plugin-bnd_files/button.html" style="border-width: 0pt; float: left;" frameborder="0" height="135" scrolling="no" width="135"></iframe>
23<p style="height: 100px">
24<!-- ApacheCon Ad --></p></li>
25</ul>
26 </div>
Karl Paulsf87ac142007-07-06 22:36:17 +000027 <div class="main">
Stuart McCulloch3f38f732008-05-03 08:13:09 +000028<h1><a name="ApacheFelixMavenBundlePlugin(BND)-BundlePluginforMaven"></a>Bundle Plugin for Maven</h1>
Karl Paulsf87ac142007-07-06 22:36:17 +000029
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +000030<p>This plugin for Maven 2 is based on the <a href="http://www.aqute.biz/Bnd/Bnd" class="external-link" rel="nofollow">BND</a>
31 tool from Peter Kriens. The way BND works is by treating your project
32as a big collection of classes (e.g., project code, dependencies, and
33the class path). The way you create a bundle with BND is to tell it the
34content of the bundle's JAR file as a subset of the available classes.
35This plugin wraps BND to make it work specifically with the Maven 2
36project structure and to provide it with reasonable default behavior for
37 Maven 2 projects.</p>
Karl Paulsf87ac142007-07-06 22:36:17 +000038
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +000039<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" height="16" width="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" class="external-link" 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" class="external-link" rel="nofollow">Felix user list</a>.</td></tr></tbody></table></div>
Stuart McCullochefb03e42009-09-16 09:47:50 +000040
Stuart McCulloch2eb61122009-02-27 06:38:33 +000041<p><em>NOTE: test scoped dependencies are <b>not</b> included in the classpath seen by BND.</em></p>
Stuart McCulloche23ec842008-08-05 06:36:05 +000042
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +000043<p>Since the 1.4.0 release, this plugin also aims to automate OBR (OSGi
44Bundle Repository) management. It helps manage a local OBR for your
45local Maven repository, and also supports remote OBRs for bundle
46distribution. The plug-in automatically computes bundle capabilities and
47 requirements, using a combination of Bindex and Maven metadata.</p>
48
49<div class="panelMacro"><table class="tipMacro"><colgroup><col width="24"><col></colgroup><tbody><tr><td valign="top"><img src="apache-felix-maven-bundle-plugin-bnd_files/check.gif" alt="" align="absmiddle" border="0" height="16" width="16"></td><td><b><a href="http://svn.apache.org/repos/asf/felix/releases/maven-bundle-plugin-2.3.5/doc/site/index.html" class="external-link" rel="nofollow">Standard Maven Documentation is now available for maven-bundle-plugin 2.3.5</a></b></td></tr></tbody></table></div>
50
51<div class="panelMacro"><table class="tipMacro"><colgroup><col width="24"><col></colgroup><tbody><tr><td valign="top"><img src="apache-felix-maven-bundle-plugin-bnd_files/check.gif" alt="" align="absmiddle" border="0" height="16" width="16"></td><td><b><a href="http://www.aqute.biz/Bnd/Format" class="external-link" rel="nofollow">A complete list of instructions and their format is available from the BND website</a></b></td></tr></tbody></table></div>
Stuart McCulloch0340ae42008-02-22 11:27:18 +000052
Stuart McCulloch3f38f732008-05-03 08:13:09 +000053<p><a name="ApacheFelixMavenBundlePlugin(BND)-simpleexample"></a></p>
Karl Paulsf87ac142007-07-06 22:36:17 +000054
Stuart McCulloch3f38f732008-05-03 08:13:09 +000055<h1><a name="ApacheFelixMavenBundlePlugin(BND)-SimpleExample"></a>Simple Example</h1>
Karl Paulsf87ac142007-07-06 22:36:17 +000056
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +000057<p>Rather than going straight to a detailed list of plugin features, we
58will first look at a simple example of how to use the plugin to give an
Stuart McCullochefb03e42009-09-16 09:47:50 +000059immediate flavor. A detailed "<a href="#ApacheFelixMavenBundlePlugin%2528BND%2529-howto">how to</a>" will follow.</p>
Karl Paulsf87ac142007-07-06 22:36:17 +000060
61<p>Assume that we have a simple bundle project that has a pubic API package an several implementation packages, such as:</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +000062
Stuart McCullochefb03e42009-09-16 09:47:50 +000063<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Karl Paulsf87ac142007-07-06 22:36:17 +000064<pre>org.foo.myproject.api
65org.foo.myproject.impl1
66org.foo.myproject.impl2
67...
68</pre>
69</div></div>
Stuart McCulloch93de6492007-12-16 15:59:05 +000070
Karl Paulsf87ac142007-07-06 22:36:17 +000071<p>If we also assume that we have a bundle activator in one of the implementation packages, then the <tt>&lt;plugins&gt;</tt> section of the POM file for this bundle project would look like this:</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +000072
Stuart McCullochefb03e42009-09-16 09:47:50 +000073<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Karl Paulsf87ac142007-07-06 22:36:17 +000074<pre>...
75&lt;plugins&gt;
76 &lt;plugin&gt;
77 &lt;groupId&gt;org.apache.felix&lt;/groupId&gt;
78 &lt;artifactId&gt;maven-bundle-plugin&lt;/artifactId&gt;
79 &lt;extensions&gt;true&lt;/extensions&gt;
80 &lt;configuration&gt;
81 &lt;instructions&gt;
82 &lt;Export-Package&gt;org.foo.myproject.api&lt;/Export-Package&gt;
83 &lt;Private-Package&gt;org.foo.myproject.*&lt;/Private-Package&gt;
84 &lt;Bundle-Activator&gt;org.foo.myproject.impl1.Activator&lt;/Bundle-Activator&gt;
85 &lt;/instructions&gt;
86 &lt;/configuration&gt;
87 &lt;/plugin&gt;
88&lt;/plugins&gt;
89...
90</pre>
91</div></div>
Stuart McCulloch93de6492007-12-16 15:59:05 +000092
Karl Paulsf87ac142007-07-06 22:36:17 +000093<p>The <tt>&lt;Export-Package&gt;</tt> and <tt>&lt;Private-Package&gt;</tt> instructions tell the plugin about the contents of the resulting bundle JAR file. The <tt>&lt;Export-Package&gt;</tt> instruction tells the plugin which of the available packages to copy into the bundle <b>and</b> export, while the <tt>&lt;Private-Package&gt;</tt> instruction indicates which of the available packages to copy into the bundle <b>but not</b>
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +000094 export. If the two sets overlap, as they do in the case, then the
95export takes precedence. Since we did not specify any values for any
96other bundle manifest headers, they will assume default values which are
97 described <a href="#ApacheFelixMavenBundlePlugin%2528BND%2529-defaultbehavior">below</a>. One specific behavior to highlight is that the plugin generates the <tt>Import-Package</tt>
98 bundle manifest header based on the contents of the bundle, which means
99 that you generally do not ever need to explicitly specify it yourself.
Karl Paulsf87ac142007-07-06 22:36:17 +0000100That's it.</p>
101
Stuart McCulloch3f38f732008-05-03 08:13:09 +0000102<h1><a name="ApacheFelixMavenBundlePlugin(BND)-Features"></a>Features</h1>
Karl Paulsf87ac142007-07-06 22:36:17 +0000103
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +0000104<p>The BND library underlying the plugin defines instructions to direct
105its behavior. For this Maven plugin, these instructions are issued in
Stuart McCullochefb03e42009-09-16 09:47:50 +0000106the plugin configuration section of the POM file, as was illustrated <a href="#ApacheFelixMavenBundlePlugin%2528BND%2529-simpleexample">above</a>. BND recognizes three types of instructions:</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000107
Karl Paulsf87ac142007-07-06 22:36:17 +0000108<ol>
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +0000109 <li><em>Manifest headers</em> - Any instruction that starts with a
110capital letter will appear in the resulting bundle's manifest file; the
111value for the header will either be copied, augmented, or generated by
112BND depending on the instruction.</li>
Karl Paulsf87ac142007-07-06 22:36:17 +0000113 <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>
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +0000114 <li><em>Directives</em> - Any instruction starting with a '-' character
115 is considered to be a directive that informs BND to perform some
116special processing and is not copied to the manifest.</li>
Karl Paulsf87ac142007-07-06 22:36:17 +0000117</ol>
118
119
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +0000120<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" class="external-link" rel="nofollow">BND documentation</a>.</p>
Karl Paulsf87ac142007-07-06 22:36:17 +0000121
Stuart McCulloch3f38f732008-05-03 08:13:09 +0000122<p><a name="ApacheFelixMavenBundlePlugin(BND)-instructions"></a></p>
Karl Paulsf87ac142007-07-06 22:36:17 +0000123
Stuart McCulloch3f38f732008-05-03 08:13:09 +0000124<h2><a name="ApacheFelixMavenBundlePlugin(BND)-Instructions"></a>Instructions</h2>
Karl Paulsf87ac142007-07-06 22:36:17 +0000125
Stuart McCulloch3f38f732008-05-03 08:13:09 +0000126<h3><a name="ApacheFelixMavenBundlePlugin(BND)-{{&lt;ExportPackage&gt;}}"></a><tt>&lt;Export-Package&gt;</tt></h3>
Karl Paulsf87ac142007-07-06 22:36:17 +0000127
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +0000128<p>The <tt>&lt;Export-Package&gt;</tt> instruction is a list of packages
129 for the bundle to export. These packages are copied into the resulting
130bundle JAR file from the available classes (i.e., project classes,
131dependencies, and class path); thus, it is possible to include classes
132into your bundle that are not associated with source files in your
133project. <tt>&lt;Export-Package&gt;</tt> can be specified with package
134patterns using the '*' wildcard. Also, it is possible to exclude
135packages using negation by starting the package pattern with '!'. Thus,
136non-negated patterns indicate which of the available packages to include
137 in the bundle, whereas negated patterns indicate which should not be
138included in the bundle.</p>
Karl Paulsf87ac142007-07-06 22:36:17 +0000139
140<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>
141
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +0000142<p>Following standard OSGi R4 syntax, package patterns can include both
143directives and attributes, which will be copied appropriately into the
144generated Export-Package manifest header. Besides explicitly listing
145package version attributes, BND will also determine package versions by
Karl Paulsf87ac142007-07-06 22:36:17 +0000146examining the source JAR file or from <tt>packageinfo</tt> files in the package directory.</p>
147
Stuart McCulloch3f38f732008-05-03 08:13:09 +0000148<h3><a name="ApacheFelixMavenBundlePlugin(BND)-{{&lt;PrivatePackage&gt;}}"></a><tt>&lt;Private-Package&gt;</tt></h3>
Karl Paulsf87ac142007-07-06 22:36:17 +0000149
150<p>The <tt>&lt;Private-Package&gt;</tt> instruction is similar in every way to the <tt>&lt;Export-Package&gt;</tt> instruction, except for the fact that these packages will <b>not</b>
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +0000151 be exported by the bundle. If a package is selected by both the export
Karl Paulsf87ac142007-07-06 22:36:17 +0000152and private package headers, then the export takes precedence.</p>
153
Stuart McCulloch3f38f732008-05-03 08:13:09 +0000154<h3><a name="ApacheFelixMavenBundlePlugin(BND)-{{&lt;IncludeResource&gt;}}"></a><tt>&lt;Include-Resource&gt;</tt></h3>
Karl Paulsf87ac142007-07-06 22:36:17 +0000155
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +0000156<p>The <tt>&lt;Include-Resource&gt;</tt> instruction is a list of
157arbitrary resources that should be copied into the bundle JAR file. The
158specified resources are declared as clauses that can have the following
Karl Paulsf87ac142007-07-06 22:36:17 +0000159forms:</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000160
Stuart McCullochefb03e42009-09-16 09:47:50 +0000161<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Karl Paulsf87ac142007-07-06 22:36:17 +0000162<pre>clause ::= assignment | inline | simple
163assignment ::= PATH '=' PATH
164simple ::= PATH
165inline ::= '@' PATH
166</pre>
167</div></div>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000168
Karl Paulsf87ac142007-07-06 22:36:17 +0000169<p>For the <tt>&lt;Include-Resource&gt;</tt> instruction, actual file paths are relative to the <tt>pom.xml</tt>, while file copy destinations are relative to the root of the resulting bundle JAR file. In the case of <tt>assignment</tt> or <tt>simple</tt> forms, the <tt>PATH</tt> parameter can point to a file or directory. The <tt>simple</tt>
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +0000170 form will place the resource in the bundle JAR with only the file name,
171 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>
172 points to a directory, the entire directory hierarchy is copied into
173the resulting bundle JAR file relative to the specified directory. If a
174 specific resource must be placed into a subdirectory of the bundle jar,
175 then use the <tt>assignment</tt> form, where the first path is the the
176destination path (including file name if the resource is a file) and the
177 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>
Karl Paulsf87ac142007-07-06 22:36:17 +0000178
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +0000179<p>If a resource clause is specified inside of "{ ... }" brackets, then
180variable substitution will be performed on the resource, where variables
181 in the resources are denoted with "${ ... }" syntax.</p>
Karl Paulsf87ac142007-07-06 22:36:17 +0000182
Stuart McCulloch7c961f52008-01-02 08:56:07 +0000183<p>By default the bundle plugin converts the project's Maven resource directories into a single <tt>&lt;Include-Resource&gt;</tt> instruction. If you specify your own <tt>&lt;Include-Resource&gt;</tt> instruction, this will replace the generated one. To include the generated list of Maven resources in your own <tt>&lt;Include-Resource&gt;</tt> instruction just add {<tt>maven-resources</tt>} to the list and it will be expanded automatically.</p>
184
Stuart McCulloch3f38f732008-05-03 08:13:09 +0000185<h3><a name="ApacheFelixMavenBundlePlugin(BND)-{{&lt;ImportPackage&gt;}}"></a><tt>&lt;Import-Package&gt;</tt></h3>
Karl Paulsf87ac142007-07-06 22:36:17 +0000186
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +0000187<p>The <tt>&lt;Import-Package&gt;</tt> instruction is a list of packages
188 that are required by the bundle's contained packages. The default for
189this header is "*", resulting in importing all referred packages. This
190header rarely has to be explicitly specified. However, in certain cases
191when there is an unwanted import, such an import can be removed by using
192 a negation package pattern. The package patterns work in the same way
193as for <tt>&lt;Export-Package&gt;</tt>, which means they are ordered. For example, if you wanted to import all packages except <tt>org.foo.impl</tt> you would specify "<tt>!org.foo.impl,*</tt>"</p>
Karl Paulsf87ac142007-07-06 22:36:17 +0000194
Stuart McCulloch3f38f732008-05-03 08:13:09 +0000195<p><a name="ApacheFelixMavenBundlePlugin(BND)-defaultbehavior"></a></p>
Karl Paulsf87ac142007-07-06 22:36:17 +0000196
Stuart McCulloch3f38f732008-05-03 08:13:09 +0000197<h2><a name="ApacheFelixMavenBundlePlugin(BND)-DefaultBehavior"></a>Default Behavior</h2>
Karl Paulsf87ac142007-07-06 22:36:17 +0000198
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +0000199<p>To use this plugin, very little information is required by BND. As
200part of the Maven integration, the plugin tries to set reasonable
Karl Paulsf87ac142007-07-06 22:36:17 +0000201defaults for various instructions. For example:</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000202
Karl Paulsf87ac142007-07-06 22:36:17 +0000203<ul>
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +0000204 <li><tt>&lt;Bundle-SymbolicName&gt;</tt> is computed using the shared <a href="http://svn.apache.org/repos/asf/maven/shared/trunk/maven-osgi/src/main/java/org/apache/maven/shared/osgi/DefaultMaven2OsgiConverter.java" class="external-link" rel="nofollow">Maven2OsgiConverter</a> component, which uses the following algorithm:<br>
Stuart McCulloche23ec842008-08-05 06:36:05 +0000205Get the symbolic name as groupId + "." + artifactId, with the following exceptions:
206 <ul>
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +0000207 <li>if artifact.getFile is not null and the jar contains a OSGi
208Manifest with Bundle-SymbolicName property then that value is returned</li>
209 <li>if groupId has only one section (no dots) and artifact.getFile is
210not null then the first package name with classes is returned. eg.
Stuart McCulloche23ec842008-08-05 06:36:05 +0000211commons-logging:commons-logging -&gt; org.apache.commons.logging</li>
212 <li>if artifactId is equal to last section of groupId then groupId is returned. eg. org.apache.maven:maven -&gt; org.apache.maven</li>
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +0000213 <li>if artifactId starts with last section of groupId that portion is
214removed. eg. org.apache.maven:maven-core -&gt; org.apache.maven.core<br>
Stuart McCulloch2eb61122009-02-27 06:38:33 +0000215The 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 McCulloche23ec842008-08-05 06:36:05 +0000216 </ul>
217 </li>
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +0000218 <li><tt>&lt;Export-Package&gt;</tt> is now assumed to be the set of
219packages in your local Java sources, excluding the default package '.'
220and any packages containing 'impl' or 'internal'.<br>
Stuart McCulloch2eb61122009-02-27 06:38:33 +0000221<em>(before version 2 of the bundleplugin it was based on the symbolic name)</em></li>
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +0000222 <li>Since 2.2.0 you can also use {<tt>local-packages</tt>} inside <tt>&lt;Export-Package&gt;</tt> and it will be expanded to the set of local packages.</li>
Stuart McCulloch2eb61122009-02-27 06:38:33 +0000223 <li><tt>&lt;Private-Package&gt;</tt> is now assumed to be the set of packages in your local Java sources (note that any packages in both <tt>&lt;Export-Package&gt;</tt> and <tt>&lt;Private-Package&gt;</tt> will be exported).<br>
224<em>(before version 2 of the bundleplugin it was assumed to be empty by default)</em></li>
225 <li><tt>&lt;Import-Package&gt;</tt> is assumed to be "<tt>*</tt>", which imports everything referred to by the bundle content, but not contained in the bundle.<br>
226<em>Any exported packages are also imported by default, to ensure a consistent class space.</em></li>
Stuart McCulloch7c961f52008-01-02 08:56:07 +0000227 <li><tt>&lt;Include-Resource&gt;</tt> is generated from the project's Maven resources, typically "<tt>src/main/resources/</tt>",
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +0000228 which will copy the specified project directory hierarchy into the
Karl Paulsf87ac142007-07-06 22:36:17 +0000229resulting bundle JAR file, mirroring standard Maven behavior.</li>
Stuart McCullochefb03e42009-09-16 09:47:50 +0000230 <li><tt>&lt;Bundle-Version&gt;</tt> is assumed to be "<tt>${pom.version</tt>}" but is normalized to the OSGi version format of "<tt>MAJOR.MINOR.MICRO.QUALIFIER</tt>", for example "<tt>2.1-SNAPSHOT</tt>" would become "<tt>2.1.0.SNAPSHOT</tt>".</li>
Karl Paulsf87ac142007-07-06 22:36:17 +0000231 <li><tt>&lt;Bundle-Name&gt;</tt> is assumed to be "<tt>${pom.name</tt>}".</li>
232 <li><tt>&lt;Bundle-Description&gt;</tt> is assumed to be "<tt>${pom.description</tt>}".</li>
233 <li><tt>&lt;Bundle-License&gt;</tt> is assumed to be "<tt>${pom.licenses</tt>}".</li>
234 <li><tt>&lt;Bundle-Vendor&gt;</tt> is assumed to be "<tt>${pom.organization.name</tt>}".</li>
235 <li><tt>&lt;Bundle-DocURL&gt;</tt> is assumed to be "<tt>${pom.organization.url</tt>}".</li>
236</ul>
237
238
Stuart McCulloch7c961f52008-01-02 08:56:07 +0000239<p>Since the plugin creates bundles for OSGi R4, it hard-codes <tt>Bundle-ManifestVersion</tt>
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +0000240 to be '2'. Additionally, it generates imports for every export to
241ensure package substitutability, which is very important when working
242with collaborating services. It is possible to override any of these
Karl Paulsf87ac142007-07-06 22:36:17 +0000243values (except <tt>Bundle-ManifestVersion</tt>) just by specifying the desired value in the plugin configuration section of the POM file.</p>
244
Stuart McCulloch3f38f732008-05-03 08:13:09 +0000245<p><a name="ApacheFelixMavenBundlePlugin(BND)-howto"></a></p>
Karl Paulsf87ac142007-07-06 22:36:17 +0000246
Stuart McCulloch3f38f732008-05-03 08:13:09 +0000247<h1><a name="ApacheFelixMavenBundlePlugin(BND)-Detailed&quot;HowTo&quot;"></a>Detailed "How To"</h1>
Karl Paulsf87ac142007-07-06 22:36:17 +0000248
Stuart McCulloch3f38f732008-05-03 08:13:09 +0000249<h2><a name="ApacheFelixMavenBundlePlugin(BND)-GetMaven2"></a>Get Maven2</h2>
Karl Paulsf87ac142007-07-06 22:36:17 +0000250
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +0000251<p>The first step in the process of using the plugin is downloading and
252installing the latest version of the Maven2 runtime. The latest Maven2
253release and instuctions for getting started with Maven2 can be found at
254the <a href="http://maven.apache.org/index.html" class="external-link" rel="nofollow">Maven website</a>.</p>
Karl Paulsf87ac142007-07-06 22:36:17 +0000255
Stuart McCulloch3f38f732008-05-03 08:13:09 +0000256<h2><a name="ApacheFelixMavenBundlePlugin(BND)-UsingthePlugin"></a>Using the Plugin</h2>
Karl Paulsf87ac142007-07-06 22:36:17 +0000257
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +0000258<p>To use the maven-bundle-plugin, you first need to add the plugin and
259some appropriate plugin configuration to your bundle project's POM.
Karl Paulsf87ac142007-07-06 22:36:17 +0000260Below is an example of a simple OSGi bundle POM for Maven2:</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000261
Stuart McCullochefb03e42009-09-16 09:47:50 +0000262<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Karl Paulsf87ac142007-07-06 22:36:17 +0000263<pre>&lt;project&gt;
264 &lt;modelVersion&gt;4.0.0&lt;/modelVersion&gt;
265 &lt;groupId&gt;my-osgi-bundles&lt;/groupId&gt;
266 &lt;artifactId&gt;examplebundle&lt;/artifactId&gt;
267 &lt;packaging&gt;bundle&lt;/packaging&gt; &lt;!-- (1) --&gt;
268 &lt;version&gt;1.0&lt;/version&gt;
269 &lt;name&gt;Example Bundle&lt;/name&gt;
270 &lt;dependencies&gt;
271 &lt;dependency&gt;
272 &lt;groupId&gt;org.apache.felix&lt;/groupId&gt;
273 &lt;artifactId&gt;org.osgi.core&lt;/artifactId&gt;
Stuart McCulloch7c961f52008-01-02 08:56:07 +0000274 &lt;version&gt;1.0.0&lt;/version&gt;
Karl Paulsf87ac142007-07-06 22:36:17 +0000275 &lt;/dependency&gt;
276 &lt;/dependencies&gt;
277 &lt;build&gt;
278 &lt;plugins&gt;
279 &lt;plugin&gt; &lt;!-- (2) START --&gt;
280 &lt;groupId&gt;org.apache.felix&lt;/groupId&gt;
281 &lt;artifactId&gt;maven-bundle-plugin&lt;/artifactId&gt;
282 &lt;extensions&gt;true&lt;/extensions&gt;
283 &lt;configuration&gt;
284 &lt;instructions&gt;
285 &lt;Export-Package&gt;com.my.company.api&lt;/Export-Package&gt;
286 &lt;Private-Package&gt;com.my.company.*&lt;/Private-Package&gt;
287 &lt;Bundle-Activator&gt;com.my.company.Activator&lt;/Bundle-Activator&gt;
288 &lt;/instructions&gt;
289 &lt;/configuration&gt;
290 &lt;/plugin&gt; &lt;!-- (2) END --&gt;
291 &lt;/plugins&gt;
292 &lt;/build&gt;
Karl Paulsf87ac142007-07-06 22:36:17 +0000293&lt;/project&gt;
294</pre>
295</div></div>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000296
297<p>There are two main things to note: (1) the <tt>&lt;packaging&gt;</tt>
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +0000298 specifier must be "bundle" and (2) the plugin and configuration must be
299 specified (the configuration section is where you will issue
Stuart McCulloch93de6492007-12-16 15:59:05 +0000300instructions to the plugin).</p>
Karl Paulsf87ac142007-07-06 22:36:17 +0000301
Stuart McCulloch3f38f732008-05-03 08:13:09 +0000302<h2><a name="ApacheFelixMavenBundlePlugin(BND)-RealWorldExample"></a>Real-World Example</h2>
Karl Paulsf87ac142007-07-06 22:36:17 +0000303
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +0000304<p>Consider this more real-world example using Felix' Log Service
305implementation. The Log Service project is comprised of a single
306package: <tt>org.apache.felix.log.impl</tt>. It has a dependency on the
307core OSGi interfaces as well as a dependency on the compendium OSGi
308interfaces for the specific log service interfaces. The following is its
309 POM file:</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000310
Stuart McCullochefb03e42009-09-16 09:47:50 +0000311<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Karl Paulsf87ac142007-07-06 22:36:17 +0000312<pre>&lt;project&gt;
313 &lt;modelVersion&gt;4.0.0&lt;/modelVersion&gt;
314 &lt;groupId&gt;org.apache.felix&lt;/groupId&gt;
315 &lt;artifactId&gt;org.apache.felix.log&lt;/artifactId&gt;
316 &lt;packaging&gt;bundle&lt;/packaging&gt;
317 &lt;name&gt;Apache Felix Log Service&lt;/name&gt;
318 &lt;version&gt;0.8.0-SNAPSHOT&lt;/version&gt;
319 &lt;description&gt;
320 This bundle provides an implementation of the OSGi R4 Log service.
321 &lt;/description&gt;
322 &lt;dependencies&gt;
323 &lt;dependency&gt;
324 &lt;groupId&gt;${pom.groupId}&lt;/groupId&gt;
325 &lt;artifactId&gt;org.osgi.core&lt;/artifactId&gt;
326 &lt;version&gt;0.8.0-incubator&lt;/version&gt;
327 &lt;/dependency&gt;
328 &lt;dependency&gt;
329 &lt;groupId&gt;${pom.groupId}&lt;/groupId&gt;
330 &lt;artifactId&gt;org.osgi.compendium&lt;/artifactId&gt;
331 &lt;version&gt;0.9.0-incubator-SNAPSHOT&lt;/version&gt;
332 &lt;/dependency&gt;
333 &lt;/dependencies&gt;
334 &lt;build&gt;
335 &lt;plugins&gt;
336 &lt;plugin&gt;
337 &lt;groupId&gt;org.apache.felix&lt;/groupId&gt;
338 &lt;artifactId&gt;maven-bundle-plugin&lt;/artifactId&gt;
339 &lt;extensions&gt;true&lt;/extensions&gt;
340 &lt;configuration&gt;
341 &lt;instructions&gt;
342 &lt;Export-Package&gt;org.osgi.service.log&lt;/Export-Package&gt;
343 &lt;Private-Package&gt;org.apache.felix.log.impl&lt;/Private-Package&gt;
344 &lt;Bundle-SymbolicName&gt;${pom.artifactId}&lt;/Bundle-SymbolicName&gt;
345 &lt;Bundle-Activator&gt;${pom.artifactId}.impl.Activator&lt;/Bundle-Activator&gt;
346 &lt;Export-Service&gt;org.osgi.service.log.LogService,org.osgi.service.log.LogReaderService&lt;/Export-Service&gt;
347 &lt;/instructions&gt;
348 &lt;/configuration&gt;
349 &lt;/plugin&gt;
350 &lt;/plugins&gt;
351 &lt;/build&gt;
Karl Paulsf87ac142007-07-06 22:36:17 +0000352&lt;/project&gt;
353</pre>
354</div></div>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000355
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +0000356<p>Notice that the <tt>&lt;Export-Package&gt;</tt> instruction specifies
357 that the bundle exports the Log Service package, even though this
358package is not contained in the bundle project. By declaring this, the
359plugin will copy the Log Service package into the resulting bundle JAR
360file. This is useful in this case because now the bundle can resolve
361without having to download the entire compendium bundle. The resulting
362manifest for the Log Service bundle looks like this (notice how the
363imports/exports automatically have version information associated with
364them, which was obtained from packageinfo files in the source packages):</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000365
Stuart McCullochefb03e42009-09-16 09:47:50 +0000366<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Karl Paulsf87ac142007-07-06 22:36:17 +0000367<pre>Manifest-Version: 1
368Bundle-License: http://www.apache.org/licenses/LICENSE-2.0.txt
369Bundle-Activator: org.apache.felix.log.impl.Activator
370Import-Package: org.osgi.framework;version=1.3, org.osgi.service.log;v
371 ersion=1.3
372Include-Resource: src/main/resources
373Export-Package: org.osgi.service.log;uses:=org.osgi.framework;version=
374 1.3
375Bundle-Version: 0.8.0.SNAPSHOT
376Bundle-Name: Apache Felix Log Service
377Bundle-Description: This bundle provides an implementation of the OSGi
378 R4 Log service.
379Private-Package: org.apache.felix.log.impl
380Bundle-ManifestVersion: 2
381Export-Service: org.osgi.service.log.LogService,org.osgi.service.log.L
382 ogReaderService
383Bundle-SymbolicName: org.apache.felix.log
384</pre>
385</div></div>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000386
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +0000387<p>The resulting bundle JAR file has the following content (notice how
Karl Paulsf87ac142007-07-06 22:36:17 +0000388the LICENSE and NOTICE files were automatically copied from the <tt>src/main/resources/</tt> directory of the project):</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000389
Stuart McCullochefb03e42009-09-16 09:47:50 +0000390<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Karl Paulsf87ac142007-07-06 22:36:17 +0000391<pre>META-INF/MANIFEST.MF
392LICENSE
393META-INF/
394META-INF/maven/
395META-INF/maven/org.apache.felix/
396META-INF/maven/org.apache.felix/org.apache.felix.log/
397META-INF/maven/org.apache.felix/org.apache.felix.log/pom.properties
398META-INF/maven/org.apache.felix/org.apache.felix.log/pom.xml
399NOTICE
400org/
401org/apache/
402org/apache/felix/
403org/apache/felix/log/
404org/apache/felix/log/impl/
405org/apache/felix/log/impl/Activator.class
406org/apache/felix/log/impl/Log.class
407org/apache/felix/log/impl/LogEntryImpl.class
408org/apache/felix/log/impl/LogException.class
409org/apache/felix/log/impl/LogListenerThread.class
410org/apache/felix/log/impl/LogNode.class
411org/apache/felix/log/impl/LogNodeEnumeration.class
412org/apache/felix/log/impl/LogReaderServiceFactory.class
413org/apache/felix/log/impl/LogReaderServiceImpl.class
414org/apache/felix/log/impl/LogServiceFactory.class
415org/apache/felix/log/impl/LogServiceImpl.class
416org/osgi/
417org/osgi/service/
418org/osgi/service/log/
419org/osgi/service/log/LogEntry.class
420org/osgi/service/log/LogListener.class
421org/osgi/service/log/LogReaderService.class
422org/osgi/service/log/LogService.class
423org/osgi/service/log/package.html
424org/osgi/service/log/packageinfo
425</pre>
426</div></div>
427
Stuart McCulloch3f38f732008-05-03 08:13:09 +0000428<h2><a name="ApacheFelixMavenBundlePlugin(BND)-AddingOSGimetadatatoexistingprojectswithoutchangingthepackagingtype"></a>Adding OSGi metadata to existing projects without changing the packaging type</h2>
Stuart McCullochdd4ae5f2008-02-05 12:38:46 +0000429
430<p>If you want to keep your project packaging type (for example "jar") but would like to add OSGi metadata<br>
431you can use the manifest goal to generate a bundle manifest. The maven-jar-plugin can then be used to<br>
432add this manifest to the final artifact. For example:</p>
433
Stuart McCullochefb03e42009-09-16 09:47:50 +0000434<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
Stuart McCullochdd4ae5f2008-02-05 12:38:46 +0000435<pre class="code-xml"><span class="code-tag">&lt;plugin&gt;</span>
436 <span class="code-tag">&lt;artifactId&gt;</span>maven-jar-plugin<span class="code-tag">&lt;/artifactId&gt;</span>
437 <span class="code-tag">&lt;configuration&gt;</span>
438 <span class="code-tag">&lt;archive&gt;</span>
439 <span class="code-tag">&lt;manifestFile&gt;</span>${project.build.outputDirectory}/META-INF/MANIFEST.MF<span class="code-tag">&lt;/manifestFile&gt;</span>
440 <span class="code-tag">&lt;/archive&gt;</span>
441 <span class="code-tag">&lt;/configuration&gt;</span>
442<span class="code-tag">&lt;/plugin&gt;</span>
443<span class="code-tag">&lt;plugin&gt;</span>
444 <span class="code-tag">&lt;groupId&gt;</span>org.apache.felix<span class="code-tag">&lt;/groupId&gt;</span>
445 <span class="code-tag">&lt;artifactId&gt;</span>maven-bundle-plugin<span class="code-tag">&lt;/artifactId&gt;</span>
446 <span class="code-tag">&lt;executions&gt;</span>
447 <span class="code-tag">&lt;execution&gt;</span>
448 <span class="code-tag">&lt;id&gt;</span>bundle-manifest<span class="code-tag">&lt;/id&gt;</span>
449 <span class="code-tag">&lt;phase&gt;</span>process-classes<span class="code-tag">&lt;/phase&gt;</span>
450 <span class="code-tag">&lt;goals&gt;</span>
451 <span class="code-tag">&lt;goal&gt;</span>manifest<span class="code-tag">&lt;/goal&gt;</span>
452 <span class="code-tag">&lt;/goals&gt;</span>
453 <span class="code-tag">&lt;/execution&gt;</span>
454 <span class="code-tag">&lt;/executions&gt;</span>
Stuart McCullochefb03e42009-09-16 09:47:50 +0000455<span class="code-tag">&lt;/plugin&gt;</span>
456</pre>
Stuart McCullochdd4ae5f2008-02-05 12:38:46 +0000457</div></div>
458
Stuart McCulloch1bcd7952009-02-26 21:29:51 +0000459<p>If you want to use packaging types other than "jar" and "bundle" then you also need to enable support<br>
460for them in the bundleplugin configuration, for example if you want to use the plugin with WAR files:</p>
461
Stuart McCullochefb03e42009-09-16 09:47:50 +0000462<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
Stuart McCulloch1bcd7952009-02-26 21:29:51 +0000463<pre class="code-xml"><span class="code-tag">&lt;plugin&gt;</span>
464 <span class="code-tag">&lt;groupId&gt;</span>org.apache.felix<span class="code-tag">&lt;/groupId&gt;</span>
465 <span class="code-tag">&lt;artifactId&gt;</span>maven-bundle-plugin<span class="code-tag">&lt;/artifactId&gt;</span>
466 <span class="code-tag">&lt;executions&gt;</span>
467 <span class="code-tag">&lt;execution&gt;</span>
468 <span class="code-tag">&lt;id&gt;</span>bundle-manifest<span class="code-tag">&lt;/id&gt;</span>
469 <span class="code-tag">&lt;phase&gt;</span>process-classes<span class="code-tag">&lt;/phase&gt;</span>
470 <span class="code-tag">&lt;goals&gt;</span>
471 <span class="code-tag">&lt;goal&gt;</span>manifest<span class="code-tag">&lt;/goal&gt;</span>
472 <span class="code-tag">&lt;/goals&gt;</span>
473 <span class="code-tag">&lt;/execution&gt;</span>
474 <span class="code-tag">&lt;/executions&gt;</span>
475 <span class="code-tag">&lt;configuration&gt;</span>
476 <span class="code-tag">&lt;supportedProjectTypes&gt;</span>
477 <span class="code-tag">&lt;supportedProjectType&gt;</span>jar<span class="code-tag">&lt;/supportedProjectType&gt;</span>
478 <span class="code-tag">&lt;supportedProjectType&gt;</span>bundle<span class="code-tag">&lt;/supportedProjectType&gt;</span>
479 <span class="code-tag">&lt;supportedProjectType&gt;</span>war<span class="code-tag">&lt;/supportedProjectType&gt;</span>
480 <span class="code-tag">&lt;/supportedProjectTypes&gt;</span>
481 <span class="code-tag">&lt;instructions&gt;</span>
482 <span class="code-tag"><span class="code-comment">&lt;!-- ...etc... --&gt;</span></span>
483 <span class="code-tag">&lt;/instructions&gt;</span>
484 <span class="code-tag">&lt;/configuration&gt;</span>
Stuart McCullochefb03e42009-09-16 09:47:50 +0000485<span class="code-tag">&lt;/plugin&gt;</span>
486</pre>
Stuart McCulloch1bcd7952009-02-26 21:29:51 +0000487</div></div>
488
Stuart McCulloch3f38f732008-05-03 08:13:09 +0000489<h2><a name="ApacheFelixMavenBundlePlugin(BND)-BuildingthePlugin"></a>Building the Plugin</h2>
Karl Paulsf87ac142007-07-06 22:36:17 +0000490
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +0000491<p>The plugin is hosted at the Apache Felix project. The following steps
492 describe how to build and install the plugin into your local Maven2
493repository.</p>
Karl Paulsf87ac142007-07-06 22:36:17 +0000494
495<p>Using the SVN client of your choice, checkout the maven-bundle-plugin project.</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000496
Stuart McCullochefb03e42009-09-16 09:47:50 +0000497<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Stuart McCulloch93de6492007-12-16 15:59:05 +0000498<pre>$ svn co http://svn.apache.org/repos/asf/felix/trunk/bundleplugin
Karl Paulsf87ac142007-07-06 22:36:17 +0000499</pre>
500</div></div>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000501
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +0000502<p>Using Maven2, build and install the maven-bundle-plugin by issuing
503the following Maven2 command in the project directory that was created
Karl Paulsf87ac142007-07-06 22:36:17 +0000504as a result of the previous step.</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000505
Stuart McCullochefb03e42009-09-16 09:47:50 +0000506<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Karl Paulsf87ac142007-07-06 22:36:17 +0000507<pre>$ mvn install
508</pre>
509</div></div>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000510
Stuart McCulloch3f38f732008-05-03 08:13:09 +0000511<h1><a name="ApacheFelixMavenBundlePlugin(BND)-Goals"></a>Goals</h1>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000512
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +0000513<p>The maven-bundle-plugin also provides additional functionality via
514some Maven goals. Command-line execution of a goal is performed as
Stuart McCulloch93de6492007-12-16 15:59:05 +0000515follows:</p>
516
Stuart McCullochefb03e42009-09-16 09:47:50 +0000517<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Stuart McCulloch93de6492007-12-16 15:59:05 +0000518<pre>mvn org.apache.felix:maven-bundle-plugin:GOAL
519</pre>
520</div></div>
521
522<p>Where GOAL is one of the following:</p>
523
524<ul>
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000525 <li><b><tt>bundle</tt></b> - build an OSGi bundle jar for the current project<br>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000526configuration options:
527 <ul>
Stuart McCullochdd4ae5f2008-02-05 12:38:46 +0000528 <li><em><tt>manifestLocation</tt></em> defaults to ${project.build.outputDirectory}/META-INF</li>
529 <li><em><tt>unpackBundle</tt></em> unpack bundle contents to output directory, defaults to false</li>
Stuart McCulloch2eb61122009-02-27 06:38:33 +0000530 <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>
531Version 2 of the bundleplugin now supports the same style of filter clauses in <tt>excludeDependencies</tt> as <tt>Embed-Dependency</tt>.</li>
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000532 <li><em><tt>classifier</tt></em> attach bundle to the project using the given classifier</li>
Stuart McCulloch1bcd7952009-02-26 21:29:51 +0000533 <li><em><tt>supportedProjectTypes</tt></em> defaults to "jar","bundle"</li>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000534 </ul>
535 </li>
Stuart McCullochdd4ae5f2008-02-05 12:38:46 +0000536</ul>
537
538
539<ul>
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000540 <li><b><tt>bundleall</tt></b> - build OSGi bundle jars for all transitive dependencies<br>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000541configuration options:
542 <ul>
Stuart McCulloch5f3ddf72008-05-03 12:49:39 +0000543 <li><em><tt>wrapImportPackage</tt></em> defaults to "*"</li>
Stuart McCulloch1bcd7952009-02-26 21:29:51 +0000544 <li><em><tt>supportedProjectTypes</tt></em> defaults to "jar","bundle"</li>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000545 </ul>
546 </li>
Stuart McCullochdd4ae5f2008-02-05 12:38:46 +0000547</ul>
548
549
550<ul>
551 <li><b><tt>wrap</tt></b> - as above, but limited to the first level of dependencies<br>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000552configuration options:
553 <ul>
Stuart McCulloch5f3ddf72008-05-03 12:49:39 +0000554 <li><em><tt>wrapImportPackage</tt></em> defaults to "*"</li>
Stuart McCulloch1bcd7952009-02-26 21:29:51 +0000555 <li><em><tt>supportedProjectTypes</tt></em> defaults to "jar","bundle"</li>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000556 </ul>
557 </li>
Stuart McCullochdd4ae5f2008-02-05 12:38:46 +0000558</ul>
559
560
561<ul>
562 <li><b><tt>manifest</tt></b> - create an OSGi manifest for the current project<br>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000563configuration options:
564 <ul>
Stuart McCullochdd4ae5f2008-02-05 12:38:46 +0000565 <li><em><tt>manifestLocation</tt></em> defaults to ${project.build.outputDirectory}/META-INF</li>
566 <li><em><tt>supportedProjectTypes</tt></em> defaults to "jar","bundle"</li>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000567 </ul>
568 </li>
569</ul>
570
571
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000572<ul>
573 <li><b><tt>install</tt></b> - adds the current bundle project to the local OBR<br>
574configuration options:
575 <ul>
576 <li><em><tt>obrRepository</tt></em> path to local OBR, defaults to <em>&lt;local-maven-repository&gt;</em><tt>/repository.xml</tt></li>
Stuart McCulloch1bcd7952009-02-26 21:29:51 +0000577 <li><em><tt>supportedProjectTypes</tt></em> defaults to "jar","bundle"</li>
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000578 </ul>
579 </li>
580</ul>
581
582
583<p>More GOALs are available in the <b>1.4.0</b> release:</p>
584
585<ul>
586 <li><b><tt>ant</tt></b> - create an Ant build script to rebuild the bundle</li>
587</ul>
588
589
590<ul>
591 <li><b><tt>install-file</tt></b> - adds a local bundle file to the local OBR<br>
592configuration options:
593 <ul>
594 <li><em><tt>obrRepository</tt></em> path to local OBR, defaults to <em>&lt;local-maven-repository&gt;</em><tt>/repository.xml</tt></li>
595 <li><em><tt>groupId</tt></em> Maven groupId for the bundle, taken from <em>pomFile</em> if given</li>
596 <li><em><tt>artifactId</tt></em> Maven artifactId for the bundle, taken from <em>pomFile</em> if given</li>
597 <li><em><tt>version</tt></em> Maven version for the bundle, taken from <em>pomFile</em> if given</li>
598 <li><em><tt>packaging</tt></em> Maven packaging type for the bundle, taken from <em>pomFile</em> if given</li>
599 <li><em><tt>classifier</tt></em> Maven classifier type, defaults to none</li>
600 <li><em><tt>pomFile</tt></em> optional Pom file describing the bundle</li>
601 <li><em><tt>file</tt></em> bundle file, defaults to the bundle from the local Maven repository</li>
602 <li><em><tt>obrXml</tt></em> optional additional properties for the bundle</li>
603 </ul>
604 </li>
605</ul>
606
607
608<ul>
609 <li><b><tt>deploy</tt></b> - adds the current bundle project to a remote OBR<br>
610configuration options:
611 <ul>
612 <li><em><tt>remoteOBR</tt></em> name of remote OBR, defaults to NONE (which means no remote OBR deployment)</li>
613 <li><em><tt>obrRepository</tt></em> used when the remoteOBR name is blank, defaults to <tt>repository.xml</tt></li>
Stuart McCulloch1bcd7952009-02-26 21:29:51 +0000614 <li><em><tt>prefixUrl</tt></em> optional public URL prefix for the remote repository</li>
615 <li><em><tt>bundleUrl</tt></em> optional public URL where the bundle has been deployed</li>
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000616 <li><em><tt>altDeploymentRepository</tt></em> alternative remote repository, <em>id::layout::url</em></li>
Stuart McCulloch1bcd7952009-02-26 21:29:51 +0000617 <li><em><tt>obrDeploymentRepository</tt></em> optional OBR specific deployment repository.</li>
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000618 <li><em><tt>ignoreLock</tt></em> ignore remote locking when updating the OBR</li>
Stuart McCulloch1bcd7952009-02-26 21:29:51 +0000619 <li><em><tt>supportedProjectTypes</tt></em> defaults to "jar","bundle"</li>
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000620 </ul>
621 </li>
622</ul>
623
624
625<ul>
626 <li><b><tt>deploy-file</tt></b> - adds a local bundle file to a remote OBR<br>
627configuration options:
628 <ul>
629 <li><em><tt>remoteOBR</tt></em> name of remote OBR, defaults to an empty string</li>
630 <li><em><tt>obrRepository</tt></em> used when the remoteOBR name is blank, defaults to <tt>repository.xml</tt></li>
631 <li><em><tt>repositoryId</tt></em> optional repository id, used to lookup authentication settings</li>
632 <li><em><tt>url</tt></em> remote repository transport URL, like
Stuart McCullochefb03e42009-09-16 09:47:50 +0000633<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000634<pre>scpexe://host/path/to/obr
635</pre>
636</div></div></li>
637 <li><em><tt>bundleUrl</tt></em> public URL of deployed bundle, like
Stuart McCullochefb03e42009-09-16 09:47:50 +0000638<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000639<pre>http://www.foo.org/bundles/foo.jar
640</pre>
641</div></div></li>
642 <li><em><tt>groupId</tt></em> Maven groupId for the bundle, taken from <em>pomFile</em> if given</li>
643 <li><em><tt>artifactId</tt></em> Maven artifactId for the bundle, taken from <em>pomFile</em> if given</li>
644 <li><em><tt>version</tt></em> Maven version for the bundle, taken from <em>pomFile</em> if given</li>
645 <li><em><tt>packaging</tt></em> Maven packaging type for the bundle, taken from <em>pomFile</em> if given</li>
646 <li><em><tt>classifier</tt></em> Maven classifier type, defaults to none</li>
647 <li><em><tt>pomFile</tt></em> optional Pom file describing the bundle</li>
648 <li><em><tt>file</tt></em> bundle file, defaults to the bundle from the local Maven repository</li>
649 <li><em><tt>obrXml</tt></em> optional additional properties for the bundle</li>
650 <li><em><tt>ignoreLock</tt></em> ignore remote locking when updating the OBR</li>
651 </ul>
652 </li>
653</ul>
654
655
656<ul>
657 <li><b><tt>clean</tt></b> - cleans the local OBR, removing missing bundles<br>
658configuration options:
659 <ul>
660 <li><em><tt>obrRepository</tt></em> path to local OBR, defaults to <em>&lt;local-maven-repository&gt;</em><tt>/repository.xml</tt></li>
661 </ul>
662 </li>
663</ul>
664
665
Stuart McCulloch1bcd7952009-02-26 21:29:51 +0000666<ul>
667 <li><b><tt>remote-clean</tt></b> - cleans a remote OBR, removing missing bundles<br>
668configuration options:
669 <ul>
670 <li><em><tt>remoteOBR</tt></em> name of remote OBR, defaults to NONE (which means no remote cleaning)</li>
671 <li><em><tt>obrRepository</tt></em> used when the remoteOBR name is blank, defaults to <tt>repository.xml</tt></li>
672 <li><em><tt>prefixUrl</tt></em> optional public URL prefix for the remote repository</li>
673 <li><em><tt>altDeploymentRepository</tt></em> alternative remote repository, <em>id::layout::url</em></li>
674 <li><em><tt>obrDeploymentRepository</tt></em> optional OBR specific deployment repository.</li>
675 <li><em><tt>ignoreLock</tt></em> ignore remote locking when updating the OBR</li>
676 </ul>
677 </li>
678</ul>
679
680
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +0000681<p>There are also new instructions available from the underlying BND
682tool, which continues to be improved independently; for the latest see <a href="http://aqute.biz/Code/Bnd" class="external-link" rel="nofollow">BND documentation</a>.</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000683
Stuart McCullochdd4ae5f2008-02-05 12:38:46 +0000684<p>The default goal <b><tt>bundle</tt></b> will be initialized by setting the &lt;packaging&gt; entry to "bundle".</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000685
Stuart McCulloch3f38f732008-05-03 08:13:09 +0000686<h1><a name="ApacheFelixMavenBundlePlugin(BND)-Thefollowingfeaturesareonlyavailablefromversion1.2.0onwards"></a>The following features are only available from version 1.2.0 onwards</h1>
Stuart McCulloch7c961f52008-01-02 08:56:07 +0000687
Stuart McCulloch3f38f732008-05-03 08:13:09 +0000688<h2><a name="ApacheFelixMavenBundlePlugin(BND)-Embeddingdependencies"></a>Embedding dependencies</h2>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000689
Stuart McCulloch7c961f52008-01-02 08:56:07 +0000690<p>The Maven Bundle Plugin supports embedding of selected project dependencies inside the bundle by using the <tt>&lt;Embed-Dependency&gt;</tt> instruction:</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000691
Stuart McCullochefb03e42009-09-16 09:47:50 +0000692<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
693<pre class="code-xml"><span class="code-tag">&lt;Embed-Dependency&gt;</span>dependencies<span class="code-tag">&lt;/Embed-Dependency&gt;</span>
694</pre>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000695</div></div>
696
697<p>where:</p>
698
Stuart McCullochefb03e42009-09-16 09:47:50 +0000699<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Stuart McCulloch93de6492007-12-16 15:59:05 +0000700<pre>dependencies ::= clause ( ',' clause ) *
Stuart McCulloch1bcd7952009-02-26 21:29:51 +0000701clause ::= MATCH ( ';' attr '=' MATCH | ';inline=' inline )
Stuart McCullochefb03e42009-09-16 09:47:50 +0000702attr ::= 'groupId' | 'artifactId' | 'version' | 'scope' | 'type' | 'classifier' | 'optional'
Stuart McCulloch1bcd7952009-02-26 21:29:51 +0000703inline ::= 'true' | 'false' | PATH ( '|' PATH ) *
704MATCH ::= &lt;globbed regular expression&gt;
705PATH ::= &lt;Ant-style path expression&gt;
Stuart McCulloch93de6492007-12-16 15:59:05 +0000706</pre>
707</div></div>
708
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000709<p>The plugin uses the <tt>&lt;Embed-Dependency&gt;</tt> instruction to transform the project dependencies into <tt>&lt;Include-Resource&gt;</tt> and <tt>&lt;Bundle-ClassPath&gt;</tt>
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +0000710 clauses, which are then appended to the current set of instructions and
711 passed onto BND. If you want the embedded dependencies to be at the
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000712start or middle of <tt>&lt;Include-Resource&gt;</tt> or <tt>&lt;Bundle-ClassPath&gt;</tt> then you can use {<tt>maven-dependencies</tt>}, which will automatically expand to the relevant clauses.</p>
Stuart McCulloch7c961f52008-01-02 08:56:07 +0000713
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +0000714<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 zero or one character. You can also use standard Java <a href="http://java.sun.com/javase/6/docs/api/java/util/regex/Pattern.html" class="external-link" rel="nofollow">regexp</a> constructs. There is no need to escape the <b>.</b> character inside MATCH. The first MATCH in a clause will filter against the artifactId.</p>
Stuart McCulloch3f38f732008-05-03 08:13:09 +0000715
Stuart McCulloch93de6492007-12-16 15:59:05 +0000716<p>some examples:</p>
717
Stuart McCullochefb03e42009-09-16 09:47:50 +0000718<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
Stuart McCulloch3f38f732008-05-03 08:13:09 +0000719<pre class="code-xml"><span class="code-tag"><span class="code-comment">&lt;!-- embed all compile and runtime scope dependencies --&gt;</span></span>
720<span class="code-tag">&lt;Embed-Dependency&gt;</span>*;scope=compile|runtime<span class="code-tag">&lt;/Embed-Dependency&gt;</span>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000721
Stuart McCulloch1bcd7952009-02-26 21:29:51 +0000722<span class="code-tag"><span class="code-comment">&lt;!-- embed any dependencies with artifactId junit and scope runtime --&gt;</span></span>
723<span class="code-tag">&lt;Embed-Dependency&gt;</span>junit;scope=runtime<span class="code-tag">&lt;/Embed-Dependency&gt;</span>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000724
Stuart McCulloch1bcd7952009-02-26 21:29:51 +0000725<span class="code-tag"><span class="code-comment">&lt;!-- inline all non-pom dependencies, except those with scope runtime --&gt;</span></span>
726<span class="code-tag">&lt;Embed-Dependency&gt;</span>*;scope=!runtime;type=!pom;inline=true<span class="code-tag">&lt;/Embed-Dependency&gt;</span>
Stuart McCulloch3f38f732008-05-03 08:13:09 +0000727
728<span class="code-tag"><span class="code-comment">&lt;!-- embed all compile and runtime scope dependencies, except those with artifactIds in the given list --&gt;</span></span>
Stuart McCulloch1bcd7952009-02-26 21:29:51 +0000729<span class="code-tag">&lt;Embed-Dependency&gt;</span>*;scope=compile|runtime;inline=false;artifactId=!cli|lang|runtime|tidy|jsch<span class="code-tag">&lt;/Embed-Dependency&gt;</span>
730
731<span class="code-tag"><span class="code-comment">&lt;!-- inline contents of selected folders from all dependencies --&gt;</span></span>
Stuart McCullochefb03e42009-09-16 09:47:50 +0000732<span class="code-tag">&lt;Embed-Dependency&gt;</span>*;inline=images/**|icons/**<span class="code-tag">&lt;/Embed-Dependency&gt;</span>
733</pre>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000734</div></div>
735
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000736<p>examples of using {<tt>maven-dependencies</tt>}:</p>
737
Stuart McCullochefb03e42009-09-16 09:47:50 +0000738<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000739<pre class="code-xml"><span class="code-tag">&lt;Include-Resource&gt;</span>
740 {maven-resources}, {maven-dependencies},
741 org/foo/Example.class=target/classes/org/foo/Example.class
742<span class="code-tag">&lt;/Include-Resource&gt;</span>
743
Stuart McCullochefb03e42009-09-16 09:47:50 +0000744<span class="code-tag">&lt;Bundle-ClassPath&gt;</span>.,{maven-dependencies},some.jar<span class="code-tag">&lt;/Bundle-ClassPath&gt;</span>
745</pre>
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000746</div></div>
747
Stuart McCulloch7c961f52008-01-02 08:56:07 +0000748<p>By default matched dependencies are embedded in the bundle as <tt>artifactId-version.jar</tt>. This behaviour can be modified using the following instructions:</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000749
750<ul>
751 <li><tt>&lt;Embed-StripVersion&gt;true&lt;/Embed-StripVersion&gt;</tt> - removes the version from the file (ie. <em>artifactId.jar</em>)</li>
752 <li><tt>&lt;Embed-StripGroup&gt;false&lt;/Embed-StripGroup&gt;</tt> - adds the groupId as a subdirectory (ie. <em>groupId/artifactId-version.jar</em>)</li>
753 <li><tt>&lt;Embed-Directory&gt;directory&lt;/Embed-Directory&gt;</tt> - adds a subdirectory (ie. <em>directory/artifactId-version.jar</em>)</li>
754</ul>
755
756
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +0000757<p>Normally the plugin only checks direct dependencies, but this can be
758changed to include the complete set of transitive dependencies with the
Stuart McCulloch93de6492007-12-16 15:59:05 +0000759following option:</p>
760
Stuart McCullochefb03e42009-09-16 09:47:50 +0000761<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
762<pre class="code-xml"><span class="code-tag">&lt;Embed-Transitive&gt;</span>true<span class="code-tag">&lt;/Embed-Transitive&gt;</span>
763</pre>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000764</div></div>
765
766<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>
767
Stuart McCullochefb03e42009-09-16 09:47:50 +0000768<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
769<pre class="code-xml"><span class="code-tag">&lt;Embed-Dependency&gt;</span>*;scope=compile|runtime;inline=true<span class="code-tag">&lt;/Embed-Dependency&gt;</span>
770</pre>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000771</div></div>
772
Stuart McCulloch3f38f732008-05-03 08:13:09 +0000773<h3><a name="ApacheFelixMavenBundlePlugin(BND)-EmbedDependencyandExportPackage"></a>Embed-Dependency and Export-Package</h3>
Stuart McCulloch7c961f52008-01-02 08:56:07 +0000774
775<p>If you embed a dependency with <tt>&lt;Embed-Dependency&gt;</tt>, and your <tt>&lt;Export-Package&gt;</tt> or <tt>&lt;Private-Package&gt;</tt> instructions match packages inside the embedded jar, you will see some duplication inside the bundle. This is because the <tt>&lt;Export-Package&gt;</tt> and <tt>&lt;Private-Package&gt;</tt>
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +0000776 instructions will result in classes being inlined in the bundle, even
777though they also exist inside the embedded jar. If you want to export
778packages from an embedded dependency without such duplication then you
Stuart McCulloch7c961f52008-01-02 08:56:07 +0000779can either inline the dependency, or use a new BND instruction called <tt>&lt;_exportcontents&gt;</tt>.</p>
780
781<p><tt>&lt;_exportcontents&gt;</tt> behaves just like Export-Package, except it doesn't change the content of the bundle, just what content should be exported.</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000782
Stuart McCulloch3f38f732008-05-03 08:13:09 +0000783<h2><a name="ApacheFelixMavenBundlePlugin(BND)-OBRintegration"></a>OBR integration</h2>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000784
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +0000785<p>The latest Maven Bundle Plugin automatically updates the local OBR
786repository.xml file during the install phase, using a default location
Stuart McCulloch93de6492007-12-16 15:59:05 +0000787of:</p>
788
Stuart McCullochefb03e42009-09-16 09:47:50 +0000789<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
790<pre class="code-java">&lt;LOCAL-MAVEN-REPOSITORY&gt;/repository.xml
791</pre>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000792</div></div>
793
794<p>You can configure the location of the OBR repository by using the command line:</p>
795
Stuart McCullochefb03e42009-09-16 09:47:50 +0000796<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
797<pre class="code-java">mvn clean install -DobrRepository=&lt;PATH_TO_OBR&gt;
798</pre>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000799</div></div>
800
801<p>or in the configuration section for the maven-bundle-plugin in your Maven POM:</p>
802
Stuart McCullochefb03e42009-09-16 09:47:50 +0000803<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
Stuart McCulloch93de6492007-12-16 15:59:05 +0000804<pre class="code-xml"><span class="code-tag">&lt;groupId&gt;</span>org.apache.felix<span class="code-tag">&lt;/groupId&gt;</span>
805<span class="code-tag">&lt;artifactId&gt;</span>maven-bundle-plugin<span class="code-tag">&lt;/artifactId&gt;</span>
806<span class="code-tag">&lt;extensions&gt;</span>true<span class="code-tag">&lt;/extensions&gt;</span>
807<span class="code-tag">&lt;configuration&gt;</span>
808 <span class="code-tag">&lt;obrRepository&gt;</span>PATH_TO_OBR<span class="code-tag">&lt;/obrRepository&gt;</span>
809 <span class="code-tag">&lt;instructions&gt;</span>
810 <span class="code-tag"><span class="code-comment">&lt;!-- bnd instructions --&gt;</span></span>
811 <span class="code-tag">&lt;/instructions&gt;</span>
Stuart McCullochefb03e42009-09-16 09:47:50 +0000812<span class="code-tag">&lt;/configuration&gt;</span>
813</pre>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000814</div></div>
815
816<p>to disable OBR installation set the obrRepository to NONE, for example:</p>
817
Stuart McCullochefb03e42009-09-16 09:47:50 +0000818<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
Stuart McCulloch93de6492007-12-16 15:59:05 +0000819<pre class="code-xml"><span class="code-tag">&lt;groupId&gt;</span>org.apache.felix<span class="code-tag">&lt;/groupId&gt;</span>
820<span class="code-tag">&lt;artifactId&gt;</span>maven-bundle-plugin<span class="code-tag">&lt;/artifactId&gt;</span>
821<span class="code-tag">&lt;extensions&gt;</span>true<span class="code-tag">&lt;/extensions&gt;</span>
822<span class="code-tag">&lt;configuration&gt;</span>
823 <span class="code-tag">&lt;obrRepository&gt;</span>NONE<span class="code-tag">&lt;/obrRepository&gt;</span>
824 <span class="code-tag">&lt;instructions&gt;</span>
825 <span class="code-tag"><span class="code-comment">&lt;!-- bnd instructions --&gt;</span></span>
826 <span class="code-tag">&lt;/instructions&gt;</span>
Stuart McCullochefb03e42009-09-16 09:47:50 +0000827<span class="code-tag">&lt;/configuration&gt;</span>
828</pre>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000829</div></div>
830
Stuart McCulloch3f38f732008-05-03 08:13:09 +0000831<h2><a name="ApacheFelixMavenBundlePlugin(BND)-Eclipse/PDEintegration"></a>Eclipse/PDE integration</h2>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000832
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +0000833<p>It is possible to configure the Maven Bundle Plugin to put the bundle
834 manifest where Eclipse/PDE expects it, and use the Maven Dependency
835Plugin to arrange for any embedded dependencies to appear in a local
836directory that matches the Bundle-ClassPath entries. Here is an example
837POM that does this:</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000838
Stuart McCullochefb03e42009-09-16 09:47:50 +0000839<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Stuart McCulloch93de6492007-12-16 15:59:05 +0000840<pre>&lt;project&gt;
841
842 &lt;properties&gt;
843 &lt;bundle.symbolicName&gt;org.example&lt;/bundle.symbolicName&gt;
844 &lt;bundle.namespace&gt;org.example&lt;/bundle.namespace&gt;
845 &lt;/properties&gt;
846
847 &lt;modelVersion&gt;4.0.0&lt;/modelVersion&gt;
848 &lt;groupId&gt;examples&lt;/groupId&gt;
849 &lt;artifactId&gt;org.example&lt;/artifactId&gt;
850 &lt;version&gt;1.0-SNAPSHOT&lt;/version&gt;
851
852 &lt;name&gt;${bundle.symbolicName} [${bundle.namespace}]&lt;/name&gt;
853
854 &lt;packaging&gt;bundle&lt;/packaging&gt;
855
856 &lt;build&gt;
Stuart McCullochdd4ae5f2008-02-05 12:38:46 +0000857 &lt;resources&gt;
858 &lt;resource&gt;
859 &lt;directory&gt;src/main/resources&lt;/directory&gt;
860 &lt;/resource&gt;
861 &lt;resource&gt;
862 &lt;directory&gt;.&lt;/directory&gt;
863 &lt;includes&gt;
864 &lt;include&gt;plugin.xml&lt;/include&gt;
865 &lt;/includes&gt;
866 &lt;/resource&gt;
867 &lt;/resources&gt;
Stuart McCulloch93de6492007-12-16 15:59:05 +0000868 &lt;plugins&gt;
869 &lt;plugin&gt;
870 &lt;groupId&gt;org.apache.felix&lt;/groupId&gt;
871 &lt;artifactId&gt;maven-bundle-plugin&lt;/artifactId&gt;
Stuart McCulloch0340ae42008-02-22 11:27:18 +0000872 &lt;version&gt;1.2.1&lt;/version&gt;
Stuart McCulloch93de6492007-12-16 15:59:05 +0000873 &lt;extensions&gt;true&lt;/extensions&gt;
874 &lt;!--
875 the following instructions build a simple set of public/private classes into an OSGi bundle
876 --&gt;
877 &lt;configuration&gt;
878 &lt;manifestLocation&gt;META-INF&lt;/manifestLocation&gt;
879 &lt;instructions&gt;
880 &lt;Bundle-SymbolicName&gt;${bundle.symbolicName}&lt;/Bundle-SymbolicName&gt;
881 &lt;Bundle-Version&gt;${pom.version}&lt;/Bundle-Version&gt;
882 &lt;!--
883 assume public classes are in the top package, and private classes are under ".internal"
884 --&gt;
Stuart McCullochdd4ae5f2008-02-05 12:38:46 +0000885 &lt;Export-Package&gt;!${bundle.namespace}.internal.*,${bundle.namespace}.*;version="${pom.version}"&lt;/Export-Package&gt;
886 &lt;Private-Package&gt;${bundle.namespace}.internal.*&lt;/Private-Package&gt;
887 &lt;Bundle-Activator&gt;${bundle.namespace}.internal.ExampleActivator&lt;/Bundle-Activator&gt;
Stuart McCulloch93de6492007-12-16 15:59:05 +0000888 &lt;!--
889 embed compile/runtime dependencies using path that matches the copied dependency folder
890 --&gt;
891 &lt;Embed-Dependency&gt;*;scope=compile|runtime;inline=false&lt;/Embed-Dependency&gt;
892 &lt;Embed-Directory&gt;target/dependency&lt;/Embed-Directory&gt;
893 &lt;Embed-StripGroup&gt;true&lt;/Embed-StripGroup&gt;
894 &lt;/instructions&gt;
895 &lt;/configuration&gt;
896 &lt;/plugin&gt;
897 &lt;plugin&gt;
898 &lt;artifactId&gt;maven-dependency-plugin&lt;/artifactId&gt;
899 &lt;executions&gt;
900 &lt;execution&gt;
901 &lt;id&gt;copy-dependencies&lt;/id&gt;
902 &lt;phase&gt;package&lt;/phase&gt;
903 &lt;goals&gt;
904 &lt;goal&gt;copy-dependencies&lt;/goal&gt;
905 &lt;/goals&gt;
906 &lt;/execution&gt;
907 &lt;/executions&gt;
908 &lt;/plugin&gt;
909 &lt;/plugins&gt;
910 &lt;/build&gt;
911
912 &lt;dependencies&gt;
913 &lt;dependency&gt;
914 &lt;groupId&gt;org.osgi&lt;/groupId&gt;
915 &lt;artifactId&gt;osgi_R4_core&lt;/artifactId&gt;
916 &lt;version&gt;1.0&lt;/version&gt;
917 &lt;scope&gt;provided&lt;/scope&gt;
918 &lt;optional&gt;true&lt;/optional&gt;
919 &lt;/dependency&gt;
920 &lt;dependency&gt;
921 &lt;groupId&gt;org.osgi&lt;/groupId&gt;
922 &lt;artifactId&gt;osgi_R4_compendium&lt;/artifactId&gt;
923 &lt;version&gt;1.0&lt;/version&gt;
924 &lt;scope&gt;provided&lt;/scope&gt;
925 &lt;optional&gt;true&lt;/optional&gt;
926 &lt;/dependency&gt;
927 &lt;dependency&gt;
928 &lt;groupId&gt;junit&lt;/groupId&gt;
929 &lt;artifactId&gt;junit&lt;/artifactId&gt;
930 &lt;version&gt;3.8.1&lt;/version&gt;
931 &lt;scope&gt;compile&lt;/scope&gt;
932 &lt;optional&gt;true&lt;/optional&gt;
933 &lt;/dependency&gt;
934 &lt;/dependencies&gt;
935
936&lt;/project&gt;
937</pre>
938</div></div>
939
940<p>To generate the Eclipse metadata use:</p>
941
Stuart McCullochefb03e42009-09-16 09:47:50 +0000942<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
943<pre class="code-java">mvn clean <span class="code-keyword">package</span> eclipse:eclipse -Declipse.pde install
944</pre>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000945</div></div>
946
947<p>and you should now be able to import this as an existing Eclipse project.</p>
948
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +0000949<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" class="external-link" rel="nofollow">Pax-Construct</a> and then tweaked to demonstrate using the Maven Dependency Plugin to handle embedded jars in Eclipse.</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000950
951<p>With the original Pax-Construct generated POM you would simply use:</p>
952
Stuart McCullochefb03e42009-09-16 09:47:50 +0000953<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
954<pre class="code-java">mvn clean <span class="code-keyword">package</span> pax:eclipse
955</pre>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000956</div></div>
957
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +0000958<p>to create the appropriate Eclipse files and manifest, and also handle
959 any embedded entries. The pax:eclipse goal extends eclipse:eclipse, and
960 supports the same parameters.</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000961
Stuart McCulloch3f38f732008-05-03 08:13:09 +0000962<h2><a name="ApacheFelixMavenBundlePlugin(BND)-Unpackingbundlecontentsto'target/classes'"></a>Unpacking bundle contents to 'target/classes'</h2>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000963
964<p>Once in a while you may create a bundle which contains additional classes to the ones compiled from <tt>src/main/java</tt>,
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +0000965 for example when you embed the classes from another jar. This can
966sometimes cause unforeseen problems in Maven, as it will use the output
Stuart McCulloch93de6492007-12-16 15:59:05 +0000967directory (<tt>target/classes</tt>) rather than the final bundle, when compiling against projects in the same reactor (ie. the same build).</p>
968
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +0000969<p>The easiest way to get around this Maven 'feature' is to unpack the
970contents of the bundle to the output directory after the packaging step,
971 so the additional classes will be found where Maven expects them.
Stuart McCulloch93de6492007-12-16 15:59:05 +0000972Thankfully there is now an easy option to do this in the bundle-plugin:</p>
973
Stuart McCullochefb03e42009-09-16 09:47:50 +0000974<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
Stuart McCullochdd4ae5f2008-02-05 12:38:46 +0000975<pre class="code-xml"><span class="code-tag">&lt;groupId&gt;</span>org.apache.felix<span class="code-tag">&lt;/groupId&gt;</span>
976<span class="code-tag">&lt;artifactId&gt;</span>maven-bundle-plugin<span class="code-tag">&lt;/artifactId&gt;</span>
977<span class="code-tag">&lt;extensions&gt;</span>true<span class="code-tag">&lt;/extensions&gt;</span>
978<span class="code-tag">&lt;configuration&gt;</span>
979 <span class="code-tag">&lt;unpackBundle&gt;</span>true<span class="code-tag">&lt;/unpackBundle&gt;</span>
980 <span class="code-tag">&lt;instructions&gt;</span>
981 <span class="code-tag"><span class="code-comment">&lt;!-- bnd instructions --&gt;</span></span>
982 <span class="code-tag">&lt;/instructions&gt;</span>
Stuart McCullochefb03e42009-09-16 09:47:50 +0000983<span class="code-tag">&lt;/configuration&gt;</span>
984</pre>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000985</div></div>
986
Stuart McCulloch3f38f732008-05-03 08:13:09 +0000987<h2><a name="ApacheFelixMavenBundlePlugin(BND)-UsinganexistingMANIFEST.MFfile"></a>Using an existing MANIFEST.MF file</h2>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000988
989<p>If you have an existing manifest, you can add this to the Bnd instructions, like so:</p>
990
Stuart McCullochefb03e42009-09-16 09:47:50 +0000991<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
Stuart McCullochdd4ae5f2008-02-05 12:38:46 +0000992<pre class="code-xml"><span class="code-tag">&lt;_include&gt;</span>src/main/resources/META-INF/MANIFEST.MF<span class="code-tag">&lt;/_include&gt;</span>
Stuart McCullochefb03e42009-09-16 09:47:50 +0000993<span class="code-tag">&lt;Export-Package&gt;</span>org.example.*<span class="code-tag">&lt;/Export-Package&gt;</span>
994</pre>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000995</div></div>
996
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +0000997<p>Bnd will use it when calculating the bundle contents, and will also
Stuart McCulloch93de6492007-12-16 15:59:05 +0000998copy across all manifest attributes starting with a capital letter.<br>
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +0000999As shown in the above example, you could use this to include a non-OSGi
Stuart McCulloch93de6492007-12-16 15:59:05 +00001000manifest which you then customize with extra OSGi attributes.</p>
1001
Stuart McCulloch3f38f732008-05-03 08:13:09 +00001002<h1><a name="ApacheFelixMavenBundlePlugin(BND)-Thefollowingfeaturesareonlyavailablefromversion1.4.0onwards"></a>The following features are only available from version 1.4.0 onwards</h1>
Stuart McCulloch0340ae42008-02-22 11:27:18 +00001003
Stuart McCulloch3f38f732008-05-03 08:13:09 +00001004<h2><a name="ApacheFelixMavenBundlePlugin(BND)-bundle:ant"></a>bundle:ant</h2>
Stuart McCulloch0340ae42008-02-22 11:27:18 +00001005
1006<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>
1007
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +00001008<p>The customized Ant script uses the BND tool to rebuild the bundle, so
1009 any source changes should be reflected in the (re)generated manifest.</p>
Stuart McCulloch0340ae42008-02-22 11:27:18 +00001010
1011<p>Example:</p>
Stuart McCullochefb03e42009-09-16 09:47:50 +00001012<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Stuart McCulloch0340ae42008-02-22 11:27:18 +00001013<pre>mvn ant:ant bundle:ant
1014
1015ant clean package
1016</pre>
1017</div></div>
1018
Stuart McCulloch3f38f732008-05-03 08:13:09 +00001019<h2><a name="ApacheFelixMavenBundlePlugin(BND)-bundle:installfile"></a>bundle:install-file</h2>
Stuart McCulloch0340ae42008-02-22 11:27:18 +00001020
1021<p>The <b>install-file</b> goal updates the local OBR with the details of a bundle from the local filesystem.</p>
1022
1023<p>configuration:</p>
1024<ul>
1025 <li><em>obrRepository</em> path to local OBR, defaults to <em>&lt;local-maven-repository&gt;</em><tt>/repository.xml</tt></li>
1026 <li><em>groupId</em> Maven groupId for the bundle, taken from <em>pomFile</em> if given</li>
1027 <li><em>artifactId</em> Maven artifactId for the bundle, taken from <em>pomFile</em> if given</li>
1028 <li><em>version</em> Maven version for the bundle, taken from <em>pomFile</em> if given</li>
1029 <li><em>packaging</em> Maven packaging type for the bundle, taken from <em>pomFile</em> if given</li>
1030 <li><em>classifier</em> Maven classifier type, defaults to none</li>
1031 <li><em>pomFile</em> optional Pom file describing the bundle</li>
1032 <li><em>file</em> bundle file, defaults to the bundle from the local Maven repository</li>
1033 <li><em>obrXml</em> optional additional properties for the bundle</li>
1034</ul>
1035
1036
1037<p>Example:</p>
Stuart McCullochefb03e42009-09-16 09:47:50 +00001038<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Stuart McCulloch0340ae42008-02-22 11:27:18 +00001039<pre>mvn org.apache.felix:maven-bundle-plugin:1.4.0:install-file \
1040 -DpomFile=myPom.xml -Dfile=foo-1.0.jar
1041</pre>
1042</div></div>
1043
Stuart McCulloch3f38f732008-05-03 08:13:09 +00001044<h2><a name="ApacheFelixMavenBundlePlugin(BND)-bundle:deploy"></a>bundle:deploy</h2>
Stuart McCulloch0340ae42008-02-22 11:27:18 +00001045
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +00001046<p>The <b>deploy goal</b> updates the remote OBR with the details of the
1047 deployed bundle from the local Maven repository. The remote OBR is
1048found by querying the <tt>&lt;distributionManagement&gt;</tt> section of the project, unless <tt>-DaltDeploymentRepository</tt> is set. See <a href="http://maven.apache.org/plugins/maven-deploy-plugin/deploy-mojo.html" class="external-link" rel="nofollow">http://maven.apache.org/plugins/maven-deploy-plugin/deploy-mojo.html</a> for more details about these particular settings.</p>
Stuart McCulloch0340ae42008-02-22 11:27:18 +00001049
1050<p>(If the project has an <tt>obr.xml</tt> file somewhere in its resources, then it will be automatically detected and applied.)</p>
1051
1052<p>configuration:</p>
1053<ul>
1054 <li><em>remoteOBR</em> name of remote OBR, defaults to NONE (which means no remote OBR deployment)</li>
1055 <li><em>obrRepository</em> used when the remoteOBR name is blank, defaults to <tt>repository.xml</tt></li>
1056 <li><em>altDeploymentRepository</em> alternative remote repository, <em>id::layout::url</em></li>
1057 <li><em>ignoreLock</em> ignore remote locking when updating the OBR</li>
1058</ul>
1059
1060
1061<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>
1062
Stuart McCulloch3f38f732008-05-03 08:13:09 +00001063<h2><a name="ApacheFelixMavenBundlePlugin(BND)-bundle:deployfile"></a>bundle:deploy-file</h2>
Stuart McCulloch0340ae42008-02-22 11:27:18 +00001064
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +00001065<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" class="external-link" rel="nofollow">http://maven.apache.org/plugins/maven-deploy-plugin/deploy-file-mojo.html</a> for more details about these particular settings.</p>
Stuart McCulloch0340ae42008-02-22 11:27:18 +00001066
1067<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>
1068
1069<p>configuration:</p>
1070<ul>
1071 <li><em>remoteOBR</em> name of remote OBR, defaults to an empty string</li>
1072 <li><em>obrRepository</em> used when the remoteOBR name is blank, defaults to <tt>repository.xml</tt></li>
1073 <li><em>repositoryId</em> optional repository id, used to lookup authentication settings</li>
1074 <li><em>url</em> remote repository transport URL, like
Stuart McCullochefb03e42009-09-16 09:47:50 +00001075<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Stuart McCulloch0340ae42008-02-22 11:27:18 +00001076<pre>scpexe://host/path/to/obr
1077</pre>
1078</div></div></li>
1079 <li><em>bundleUrl</em> public URL of deployed bundle, like
Stuart McCullochefb03e42009-09-16 09:47:50 +00001080<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Stuart McCulloch0340ae42008-02-22 11:27:18 +00001081<pre>http://www.foo.org/bundles/foo.jar
1082</pre>
1083</div></div></li>
1084 <li><em>groupId</em> Maven groupId for the bundle, taken from <em>pomFile</em> if given</li>
1085 <li><em>artifactId</em> Maven artifactId for the bundle, taken from <em>pomFile</em> if given</li>
1086 <li><em>version</em> Maven version for the bundle, taken from <em>pomFile</em> if given</li>
1087 <li><em>packaging</em> Maven packaging type for the bundle, taken from <em>pomFile</em> if given</li>
1088 <li><em>classifier</em> Maven classifier type, defaults to none</li>
1089 <li><em>pomFile</em> optional Pom file describing the bundle</li>
1090 <li><em>file</em> bundle file, defaults to the bundle from the local Maven repository</li>
1091 <li><em>obrXml</em> optional additional properties for the bundle</li>
1092 <li><em>ignoreLock</em> ignore remote locking when updating the OBR</li>
1093</ul>
1094
1095
Stuart McCulloch2eb61122009-02-27 06:38:33 +00001096
Stuart McCulloch0340ae42008-02-22 11:27:18 +00001097<p>Example:</p>
Stuart McCullochefb03e42009-09-16 09:47:50 +00001098<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Stuart McCulloch0340ae42008-02-22 11:27:18 +00001099<pre>mvn org.apache.felix:maven-bundle-plugin:1.4.0:deploy-file \
1100 -DpomFile=myPom.xml -Dfile=foo-1.0.jar -Durl=file:/tmp/example/OBR \
1101 -DbundleUrl=http://www.foo.org/bundles/foo.jar
1102</pre>
1103</div></div>
1104
Stuart McCulloch3f38f732008-05-03 08:13:09 +00001105<h2><a name="ApacheFelixMavenBundlePlugin(BND)-bundle:clean"></a>bundle:clean</h2>
Stuart McCulloch0340ae42008-02-22 11:27:18 +00001106
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +00001107<p>Sometimes you would like to clean your local OBR because it contains
1108bundles that are no longer in your local Maven repository. This case
1109often occurs when artifacts were deleted manually. The
1110maven-bundle-plugin provides a simple goal to check for missing bundles,
1111 and remove them from the local OBR.</p>
Stuart McCulloch0340ae42008-02-22 11:27:18 +00001112
1113<p>configuration:</p>
1114<ul>
1115 <li><em>obrRepository</em> path to local OBR, defaults to <em>&lt;local-maven-repository&gt;</em><tt>/repository.xml</tt></li>
1116</ul>
1117
1118
1119<p>Example:</p>
Stuart McCullochefb03e42009-09-16 09:47:50 +00001120<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Stuart McCulloch0340ae42008-02-22 11:27:18 +00001121<pre>mvn bundle:clean
1122</pre>
1123</div></div>
1124
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +00001125<h2><a name="ApacheFelixMavenBundlePlugin(BND)-bundle:index"></a>bundle:index</h2>
1126
1127<p>The <tt>index</tt> goal allows the creation of an OBR repository based on a set of jars in a maven repository.</p>
1128
1129<p>Configuration:</p>
1130<ul>
1131 <li><em>obrRepository</em> path to local OBR, defaults to <em>&lt;local-maven-repository&gt;</em><tt>/repository.xml</tt></li>
1132 <li><em>urlTemplate</em> template for generating urls for OBR resources</li>
1133 <li><em>mavenRepository</em> path to the maven repository, defaults to <em>&lt;local-maven-repository&gt;</em></li>
1134</ul>
1135
1136
1137<p>Possible values for the <tt>urlTemplate</tt> are:</p>
1138<ul>
1139 <li><em>maven</em> this will create a maven based url such as <tt>mvn:groupid/artifactid/version</tt></li>
1140 <li>pattern with the following placeholders:
1141 <ul>
1142 <li><tt>%v</tt> bundle version</li>
1143 <li><tt>%s</tt> bundle symbolic name</li>
1144 <li><tt>%f</tt> file name</li>
1145 <li><tt>%p</tt> file path</li>
1146 </ul>
1147 </li>
1148</ul>
1149
1150
Stuart McCulloch3f38f732008-05-03 08:13:09 +00001151<h2><a name="ApacheFelixMavenBundlePlugin(BND)-Concurrentupdates"></a>Concurrent updates</h2>
Stuart McCulloch0340ae42008-02-22 11:27:18 +00001152
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +00001153<p>With a remote OBR, several uploads may occur at the same time.
1154However, the remote OBR is centralized in one file, so concurrent
1155modification must be avoided. To achieve this, the plug-in implements a
1156locking system. Each time the plug-in tries to modify the file it sets a
1157 file based lock. If it can't take the lock, it will wait and retry.
Stuart McCulloch0340ae42008-02-22 11:27:18 +00001158After 3 attempts the upload process fails. To bypass this lock add <tt>-DignoreLock</tt> to the command-line (or add <tt>&lt;ignoreLock&gt;true&lt;ignoreLock&gt;</tt> to the configuration section of your Pom).</p>
1159
Stuart McCulloch3f38f732008-05-03 08:13:09 +00001160<h2><a name="ApacheFelixMavenBundlePlugin(BND)-FTPprotocol"></a>FTP protocol</h2>
Stuart McCulloch0340ae42008-02-22 11:27:18 +00001161
1162<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 McCullochefb03e42009-09-16 09:47:50 +00001163<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
Stuart McCulloch0340ae42008-02-22 11:27:18 +00001164<pre class="code-xml"><span class="code-tag">&lt;build&gt;</span>
1165 <span class="code-tag">&lt;extensions&gt;</span>
1166 <span class="code-tag">&lt;extension&gt;</span>
1167 <span class="code-tag">&lt;groupId&gt;</span>org.apache.maven.wagon<span class="code-tag">&lt;/groupId&gt;</span>
1168 <span class="code-tag">&lt;artifactId&gt;</span>wagon-ftp<span class="code-tag">&lt;/artifactId&gt;</span>
1169 <span class="code-tag">&lt;version&gt;</span>1.0-alpha-6<span class="code-tag">&lt;/version&gt;</span>
1170 <span class="code-tag">&lt;/extension&gt;</span>
1171 <span class="code-tag">&lt;/extensions&gt;</span>
Stuart McCullochefb03e42009-09-16 09:47:50 +00001172<span class="code-tag">&lt;/build&gt;</span>
1173</pre>
Stuart McCulloch0340ae42008-02-22 11:27:18 +00001174</div></div>
1175
Stuart McCulloch3f38f732008-05-03 08:13:09 +00001176<h2><a name="ApacheFelixMavenBundlePlugin(BND)-Howtheplugincomputesthedescriptionofthebundle"></a>How the plug-in computes the description of the bundle</h2>
Stuart McCulloch0340ae42008-02-22 11:27:18 +00001177
1178<p>The description of the bundle comes from three different sources:</p>
1179<ul>
1180 <li>Bindex : Bindex is a tool that analyzes a bundle manifest to generate OBR description</li>
1181 <li>pom.xml : by analyzing the pom file, various information is collected (symbolic name ...)</li>
1182 <li>obr.xml : this file contains customized description and capabilities for the bundle</li>
1183</ul>
1184
1185
1186<p>These sources are merged together using the following precedence:</p>
Stuart McCullochefb03e42009-09-16 09:47:50 +00001187<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
Stuart McCulloch0340ae42008-02-22 11:27:18 +00001188<pre>Bindex
1189| (overrides)
1190pom.xml
1191| (overrides)
1192obr.xml
1193</pre>
1194</div></div>
1195<p>A warning message is displayed when existing information is overridden.</p>
1196
Stuart McCulloch3f38f732008-05-03 08:13:09 +00001197<h2><a name="ApacheFelixMavenBundlePlugin(BND)-Knownissues&amp;limitations"></a>Known issues &amp; limitations</h2>
Stuart McCulloch0340ae42008-02-22 11:27:18 +00001198
1199<ol>
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +00001200 <li>obr.xml (file given by the user to add properties not found by
1201Bindex) must be correct, because the plug-in does not check its syntax.</li>
Stuart McCulloch0340ae42008-02-22 11:27:18 +00001202</ol>
1203
1204
Stuart McCulloch3f38f732008-05-03 08:13:09 +00001205<h1><a name="ApacheFelixMavenBundlePlugin(BND)-Feedback"></a>Feedback</h1>
Stuart McCulloch93de6492007-12-16 15:59:05 +00001206
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +00001207<p>Subscribe to the Felix users mailing list by sending a message to <a href="mailto:users-subscribe@felix.apache.org" class="external-link" rel="nofollow">users-subscribe@felix.apache.org</a>; after subscribing, email questions or feedback to <a href="mailto:users@felix.apache.org" class="external-link" rel="nofollow">users@felix.apache.org</a>.</p>
1208 <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
1209Last modified by mcculls on Fri Nov 18 12:18:15 EST 2011
1210 </div>
1211 <div class="trademarkFooter">
1212Apache Felix, Felix, Apache, the Apache feather logo, and the Apache
1213Felix project logo are trademarks of The Apache Software Foundation. All
1214 other marks mentioned may be trademarks or registered trademarks of
1215their respective owners.
1216 </div>
Karl Paulsf87ac142007-07-06 22:36:17 +00001217 </div>
Stuart McCulloch0bb7aba2011-11-28 15:58:52 +00001218
1219
1220</body></html>