Update documentation
git-svn-id: https://svn.apache.org/repos/asf/felix/trunk@653014 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/bundleplugin/doc/apache-felix-maven-bundle-plugin-bnd.html b/bundleplugin/doc/apache-felix-maven-bundle-plugin-bnd.html
new file mode 100644
index 0000000..ae67807
--- /dev/null
+++ b/bundleplugin/doc/apache-felix-maven-bundle-plugin-bnd.html
@@ -0,0 +1,1085 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html><head><title>Apache Felix - Apache Felix Maven Bundle Plugin (BND)</title>
+
+
+
+
+ <link rel="stylesheet" href="apache-felix-maven-bundle-plugin-bnd_files/site.css" type="text/css" media="all">
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"></head><body>
+ <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>
+ <div class="menu">
+<ul>
+ <li><a href="http://felix.apache.org/site/news.html" title="news">news</a></li>
+ <li><a href="http://felix.apache.org/site/license.html" title="license">license</a></li>
+ <li><span class="nobr"><a href="http://felix.apache.org/site/downloads.cgi" title="Visit page outside Confluence" rel="nofollow">downloads<sup><img class="rendericon" src="apache-felix-maven-bundle-plugin-bnd_files/linkext7.gif" alt="" align="absmiddle" border="0" height="7" width="7"></sup></a></span></li>
+ <li><a href="http://felix.apache.org/site/documentation.html" title="documentation">documentation</a></li>
+ <li><a href="http://felix.apache.org/site/mailinglists.html" title="mailinglists">mailing lists</a></li>
+ <li><a href="http://felix.apache.org/site/contributing.html" title="Contributing">contributing</a></li>
+ <li><span class="nobr"><a href="http://www.apache.org/" title="Visit page outside Confluence" rel="nofollow">asf<sup><img class="rendericon" src="apache-felix-maven-bundle-plugin-bnd_files/linkext7.gif" alt="" align="absmiddle" border="0" height="7" width="7"></sup></a></span></li>
+ <li><span class="nobr"><a href="http://www.apache.org/foundation/sponsorship.html" title="Visit page outside Confluence" rel="nofollow">sponsorship<sup><img class="rendericon" src="apache-felix-maven-bundle-plugin-bnd_files/linkext7.gif" alt="" align="absmiddle" border="0" height="7" width="7"></sup></a></span></li>
+ <li><span class="nobr"><a href="http://www.apache.org/foundation/thanks.html" title="Visit page outside Confluence" rel="nofollow">sponsors<sup><img class="rendericon" src="apache-felix-maven-bundle-plugin-bnd_files/linkext7.gif" alt="" align="absmiddle" border="0" height="7" width="7"></sup></a></span>
+<!-- ApacheCon Ad -->
+<iframe src="apache-felix-maven-bundle-plugin-bnd_files/button.html" style="border-width: 0pt; float: left; display: none;" frameborder="0" height="135" scrolling="no" width="135"></iframe>
+<p style="height: 100px;">
+<!-- ApacheCon Ad -->
+</p></li></ul> </div>
+ <div class="main">
+<h1><a name="ApacheFelixMavenBundlePlugin(BND)-BundlePluginforMaven"></a>Bundle Plugin for Maven</h1>
+
+<p>This plugin for Maven 2 is based on the <span class="nobr"><a href="http://www.aqute.biz/Code/Bnd" title="Visit page outside Confluence" rel="nofollow">BND<sup><img class="rendericon" src="apache-felix-maven-bundle-plugin-bnd_files/linkext7.gif" alt="" align="absmiddle" border="0" height="7" width="7"></sup></a></span>
+tool from Peter Kriens. The way BND works is by treating your project
+as a big collection of classes (e.g., project code, dependencies, and
+the class path). The way you create a bundle with BND is to tell it the
+content of the bundle's JAR file as a subset of the available classes.
+This plugin wraps BND to make it work specifically with the Maven 2
+project structure and to provide it with reasonable default behavior
+for Maven 2 projects.</p>
+
+<p>Since the 1.4.0 release, this plugin also aims to automate OBR (OSGi
+Bundle Repository) management. It helps manage a local OBR for your
+local Maven repository, and also supports remote OBRs for bundle
+distribution. The plug-in automatically computes bundle capabilities
+and requirements, using a combination of Bindex and Maven metadata.</p>
+
+<p><a name="ApacheFelixMavenBundlePlugin(BND)-simpleexample"></a></p>
+
+<h1><a name="ApacheFelixMavenBundlePlugin(BND)-SimpleExample"></a>Simple Example</h1>
+
+<p>Rather than going straight to a detailed list of plugin features, we
+will first look at a simple example of how to use the plugin to give an
+immediate flavor. A detailed "<a href="#ApacheFelixMavenBundlePlugin%2528BND%2529-howto" title="how-to on Apache Felix Maven Bundle Plugin (BND)">how to</a>" will follow.</p>
+
+<p>Assume that we have a simple bundle project that has a pubic API package an several implementation packages, such as:</p>
+
+<div class="preformatted"><div class="preformattedContent">
+<pre>org.foo.myproject.api
+org.foo.myproject.impl1
+org.foo.myproject.impl2
+...
+</pre>
+</div></div>
+
+<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>
+
+<div class="preformatted"><div class="preformattedContent">
+<pre>...
+<plugins>
+ <plugin>
+ <groupId>org.apache.felix</groupId>
+ <artifactId>maven-bundle-plugin</artifactId>
+ <extensions>true</extensions>
+ <configuration>
+ <instructions>
+ <Export-Package>org.foo.myproject.api</Export-Package>
+ <Private-Package>org.foo.myproject.*</Private-Package>
+ <Bundle-Activator>org.foo.myproject.impl1.Activator</Bundle-Activator>
+ </instructions>
+ </configuration>
+ </plugin>
+</plugins>
+...
+</pre>
+</div></div>
+
+<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>
+export. If the two sets overlap, as they do in the case, then the
+export takes precedence. Since we did not specify any values for any
+other bundle manifest headers, they will assume default values which
+are described <a href="#ApacheFelixMavenBundlePlugin%2528BND%2529-defaultbehavior" title="default-behavior on Apache Felix Maven Bundle Plugin (BND)">below</a>. One specific behavior to highlight is that the plugin generates the <tt>Import-Package</tt>
+bundle manifest header based on the contents of the bundle, which means
+that you generally do not ever need to explicitly specify it yourself.
+That's it.</p>
+
+<h1><a name="ApacheFelixMavenBundlePlugin(BND)-Features"></a>Features</h1>
+
+<p>The BND library underlying the plugin defines instructions to direct
+its behavior. For this Maven plugin, these instructions are issued in
+the plugin configuration section of the POM file, as was illustrated <a href="#ApacheFelixMavenBundlePlugin%2528BND%2529-simpleexample" title="simple-example on Apache Felix Maven Bundle Plugin (BND)">above</a>. BND recognizes three types of instructions:</p>
+
+<ol>
+ <li><em>Manifest headers</em> - Any instruction that starts with
+a capital letter will appear in the resulting bundle's manifest file;
+the value for the header will either be copied, augmented, or generated
+by BND depending on the instruction.</li>
+ <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>
+ <li><em>Directives</em>
+- Any instruction starting with a '-' character is considered to be a
+directive that informs BND to perform some special processing and is
+not copied to the manifest.</li>
+</ol>
+
+
+<p>The remainder of this section covers the most important aspects of BND's instructions; for complete details refer to the <span class="nobr"><a href="http://www.aqute.biz/Code/Bnd" title="Visit page outside Confluence" rel="nofollow">BND documentation<sup><img class="rendericon" src="apache-felix-maven-bundle-plugin-bnd_files/linkext7.gif" alt="" align="absmiddle" border="0" height="7" width="7"></sup></a></span>.</p>
+
+<p><a name="ApacheFelixMavenBundlePlugin(BND)-instructions"></a></p>
+
+<h2><a name="ApacheFelixMavenBundlePlugin(BND)-Instructions"></a>Instructions</h2>
+
+<h3><a name="ApacheFelixMavenBundlePlugin(BND)-{{<ExportPackage>}}"></a><tt><Export-Package></tt></h3>
+
+<p>The <tt><Export-Package></tt> instruction is a list of
+packages for the bundle to export. These packages are copied into the
+resulting bundle JAR file from the available classes (i.e., project
+classes, dependencies, and class path); thus, it is possible to include
+classes into your bundle that are not associated with source files in
+your project. <tt><Export-Package></tt> can be specified with
+package patterns using the '*' wildcard. Also, it is possible to
+exclude packages using negation by starting the package pattern with
+'!'. Thus, non-negated patterns indicate which of the available
+packages to include in the bundle, whereas negated patterns indicate
+which should not be included in the bundle.</p>
+
+<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>
+
+<p>Following standard OSGi R4 syntax, package patterns can include both
+directives and attributes, which will be copied appropriately into the
+generated Export-Package manifest header. Besides explicitly listing
+package version attributes, BND will also determine package versions by
+examining the source JAR file or from <tt>packageinfo</tt> files in the package directory.</p>
+
+<h3><a name="ApacheFelixMavenBundlePlugin(BND)-{{<PrivatePackage>}}"></a><tt><Private-Package></tt></h3>
+
+<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>
+be exported by the bundle. If a package is selected by both the export
+and private package headers, then the export takes precedence.</p>
+
+<h3><a name="ApacheFelixMavenBundlePlugin(BND)-{{<IncludeResource>}}"></a><tt><Include-Resource></tt></h3>
+
+<p>The <tt><Include-Resource></tt> instruction is a list of
+arbitrary resources that should be copied into the bundle JAR file. The
+specified resources are declared as clauses that can have the following
+forms:</p>
+
+<div class="preformatted"><div class="preformattedContent">
+<pre>clause ::= assignment | inline | simple
+assignment ::= PATH '=' PATH
+simple ::= PATH
+inline ::= '@' PATH
+</pre>
+</div></div>
+
+<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>
+form will place the resource in the bundle JAR with only the file name,
+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>
+points to a directory, the entire directory hierarchy is copied into
+the resulting bundle JAR file relative to the specified directory. If a
+specific resource must be placed into a subdirectory of the bundle jar,
+then use the <tt>assignment</tt> form, where the first path is the the
+destination path (including file name if the resource is a file) and
+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>
+
+<p>If a resource clause is specified inside of "{ ... }" brackets, then
+variable substitution will be performed on the resource, where
+variables in the resources are denoted with "${ ... }" syntax.</p>
+
+<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>
+
+<h3><a name="ApacheFelixMavenBundlePlugin(BND)-{{<ImportPackage>}}"></a><tt><Import-Package></tt></h3>
+
+<p>The <tt><Import-Package></tt> instruction is a list of
+packages that are required by the bundle's contained packages. The
+default for this header is "*", resulting in importing all referred
+packages. This header rarely has to be explicitly specified. However,
+in certain cases when there is an unwanted import, such an import can
+be removed by using a negation package pattern. The package patterns
+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>
+
+<p><a name="ApacheFelixMavenBundlePlugin(BND)-defaultbehavior"></a></p>
+
+<h2><a name="ApacheFelixMavenBundlePlugin(BND)-DefaultBehavior"></a>Default Behavior</h2>
+
+<p>To use this plugin, very little information is required by BND. As
+part of the Maven integration, the plugin tries to set reasonable
+defaults for various instructions. For example:</p>
+
+<ul>
+ <li><tt><Bundle-SymbolicName></tt> is assumed to be "<tt>${groupId}.${artifactId</tt>}".</li>
+ <li><tt><Export-Package></tt> is assumed to be "<tt><Bundle-SymbolicName>.*</tt>", unless <tt><Private-Package></tt> is specified, then <tt><Export-Package></tt> is assumed to be empty.</li>
+ <li><tt><Private-Package></tt> is assumed to be empty by default.</li>
+ <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.</li>
+ <li><tt><Include-Resource></tt> is generated from the project's Maven resources, typically "<tt>src/main/resources/</tt>",
+which will copy the specified project directory hierarchy into the
+resulting bundle JAR file, mirroring standard Maven behavior.</li>
+ <li><tt><Bundle-Version></tt> is assumed to be "<tt>${pom.version</tt>}" with '-' character separator of the qualifier replaced with a '.' character.</li>
+ <li><tt><Bundle-Name></tt> is assumed to be "<tt>${pom.name</tt>}".</li>
+ <li><tt><Bundle-Description></tt> is assumed to be "<tt>${pom.description</tt>}".</li>
+ <li><tt><Bundle-License></tt> is assumed to be "<tt>${pom.licenses</tt>}".</li>
+ <li><tt><Bundle-Vendor></tt> is assumed to be "<tt>${pom.organization.name</tt>}".</li>
+ <li><tt><Bundle-DocURL></tt> is assumed to be "<tt>${pom.organization.url</tt>}".</li>
+</ul>
+
+
+<p>Since the plugin creates bundles for OSGi R4, it hard-codes <tt>Bundle-ManifestVersion</tt>
+to be '2'. Additionally, it generates imports for every export to
+ensure package substitutability, which is very important when working
+with collaborating services. It is possible to override any of these
+values (except <tt>Bundle-ManifestVersion</tt>) just by specifying the desired value in the plugin configuration section of the POM file.</p>
+
+<p><a name="ApacheFelixMavenBundlePlugin(BND)-howto"></a></p>
+
+<h1><a name="ApacheFelixMavenBundlePlugin(BND)-Detailed"HowTo""></a>Detailed "How To"</h1>
+
+<h2><a name="ApacheFelixMavenBundlePlugin(BND)-GetMaven2"></a>Get Maven2</h2>
+
+<p>The first step in the process of using the plugin is downloading and
+installing the latest version of the Maven2 runtime. The latest Maven2
+release and instuctions for getting started with Maven2 can be found at
+the <span class="nobr"><a href="http://maven.apache.org/index.html" title="Visit page outside Confluence" rel="nofollow">Maven website<sup><img class="rendericon" src="apache-felix-maven-bundle-plugin-bnd_files/linkext7.gif" alt="" align="absmiddle" border="0" height="7" width="7"></sup></a></span>.</p>
+
+<h2><a name="ApacheFelixMavenBundlePlugin(BND)-UsingthePlugin"></a>Using the Plugin</h2>
+
+<p>To use the maven-bundle-plugin, you first need to add the plugin and
+some appropriate plugin configuration to your bundle project's POM.
+Below is an example of a simple OSGi bundle POM for Maven2:</p>
+
+<div class="preformatted"><div class="preformattedContent">
+<pre><project>
+ <modelVersion>4.0.0</modelVersion>
+ <groupId>my-osgi-bundles</groupId>
+ <artifactId>examplebundle</artifactId>
+ <packaging>bundle</packaging> <!-- (1) -->
+ <version>1.0</version>
+ <name>Example Bundle</name>
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.felix</groupId>
+ <artifactId>org.osgi.core</artifactId>
+ <version>1.0.0</version>
+ </dependency>
+ </dependencies>
+ <build>
+ <plugins>
+ <plugin> <!-- (2) START -->
+ <groupId>org.apache.felix</groupId>
+ <artifactId>maven-bundle-plugin</artifactId>
+ <extensions>true</extensions>
+ <configuration>
+ <instructions>
+ <Export-Package>com.my.company.api</Export-Package>
+ <Private-Package>com.my.company.*</Private-Package>
+ <Bundle-Activator>com.my.company.Activator</Bundle-Activator>
+ </instructions>
+ </configuration>
+ </plugin> <!-- (2) END -->
+ </plugins>
+ </build>
+</project>
+</pre>
+</div></div>
+
+<p>There are two main things to note: (1) the <tt><packaging></tt>
+specifier must be "bundle" and (2) the plugin and configuration must be
+specified (the configuration section is where you will issue
+instructions to the plugin).</p>
+
+<h2><a name="ApacheFelixMavenBundlePlugin(BND)-RealWorldExample"></a>Real-World Example</h2>
+
+<p>Consider this more real-world example using Felix' Log Service
+implementation. The Log Service project is comprised of a single
+package: <tt>org.apache.felix.log.impl</tt>. It has a dependency on
+the core OSGi interfaces as well as a dependency on the compendium OSGi
+interfaces for the specific log service interfaces. The following is
+its POM file:</p>
+
+<div class="preformatted"><div class="preformattedContent">
+<pre><project>
+ <modelVersion>4.0.0</modelVersion>
+ <groupId>org.apache.felix</groupId>
+ <artifactId>org.apache.felix.log</artifactId>
+ <packaging>bundle</packaging>
+ <name>Apache Felix Log Service</name>
+ <version>0.8.0-SNAPSHOT</version>
+ <description>
+ This bundle provides an implementation of the OSGi R4 Log service.
+ </description>
+ <dependencies>
+ <dependency>
+ <groupId>${pom.groupId}</groupId>
+ <artifactId>org.osgi.core</artifactId>
+ <version>0.8.0-incubator</version>
+ </dependency>
+ <dependency>
+ <groupId>${pom.groupId}</groupId>
+ <artifactId>org.osgi.compendium</artifactId>
+ <version>0.9.0-incubator-SNAPSHOT</version>
+ </dependency>
+ </dependencies>
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.felix</groupId>
+ <artifactId>maven-bundle-plugin</artifactId>
+ <extensions>true</extensions>
+ <configuration>
+ <instructions>
+ <Export-Package>org.osgi.service.log</Export-Package>
+ <Private-Package>org.apache.felix.log.impl</Private-Package>
+ <Bundle-SymbolicName>${pom.artifactId}</Bundle-SymbolicName>
+ <Bundle-Activator>${pom.artifactId}.impl.Activator</Bundle-Activator>
+ <Export-Service>org.osgi.service.log.LogService,org.osgi.service.log.LogReaderService</Export-Service>
+ </instructions>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+</project>
+</pre>
+</div></div>
+
+<p>Notice that the <tt><Export-Package></tt> instruction
+specifies that the bundle exports the Log Service package, even though
+this package is not contained in the bundle project. By declaring this,
+the plugin will copy the Log Service package into the resulting bundle
+JAR file. This is useful in this case because now the bundle can
+resolve without having to download the entire compendium bundle. The
+resulting manifest for the Log Service bundle looks like this (notice
+how the imports/exports automatically have version information
+associated with them, which was obtained from packageinfo files in the
+source packages):</p>
+
+<div class="preformatted"><div class="preformattedContent">
+<pre>Manifest-Version: 1
+Bundle-License: http://www.apache.org/licenses/LICENSE-2.0.txt
+Bundle-Activator: org.apache.felix.log.impl.Activator
+Import-Package: org.osgi.framework;version=1.3, org.osgi.service.log;v
+ ersion=1.3
+Include-Resource: src/main/resources
+Export-Package: org.osgi.service.log;uses:=org.osgi.framework;version=
+ 1.3
+Bundle-Version: 0.8.0.SNAPSHOT
+Bundle-Name: Apache Felix Log Service
+Bundle-Description: This bundle provides an implementation of the OSGi
+ R4 Log service.
+Private-Package: org.apache.felix.log.impl
+Bundle-ManifestVersion: 2
+Export-Service: org.osgi.service.log.LogService,org.osgi.service.log.L
+ ogReaderService
+Bundle-SymbolicName: org.apache.felix.log
+</pre>
+</div></div>
+
+<p>The resulting bundle JAR file has the following content (notice how
+the LICENSE and NOTICE files were automatically copied from the <tt>src/main/resources/</tt> directory of the project):</p>
+
+<div class="preformatted"><div class="preformattedContent">
+<pre>META-INF/MANIFEST.MF
+LICENSE
+META-INF/
+META-INF/maven/
+META-INF/maven/org.apache.felix/
+META-INF/maven/org.apache.felix/org.apache.felix.log/
+META-INF/maven/org.apache.felix/org.apache.felix.log/pom.properties
+META-INF/maven/org.apache.felix/org.apache.felix.log/pom.xml
+NOTICE
+org/
+org/apache/
+org/apache/felix/
+org/apache/felix/log/
+org/apache/felix/log/impl/
+org/apache/felix/log/impl/Activator.class
+org/apache/felix/log/impl/Log.class
+org/apache/felix/log/impl/LogEntryImpl.class
+org/apache/felix/log/impl/LogException.class
+org/apache/felix/log/impl/LogListenerThread.class
+org/apache/felix/log/impl/LogNode.class
+org/apache/felix/log/impl/LogNodeEnumeration.class
+org/apache/felix/log/impl/LogReaderServiceFactory.class
+org/apache/felix/log/impl/LogReaderServiceImpl.class
+org/apache/felix/log/impl/LogServiceFactory.class
+org/apache/felix/log/impl/LogServiceImpl.class
+org/osgi/
+org/osgi/service/
+org/osgi/service/log/
+org/osgi/service/log/LogEntry.class
+org/osgi/service/log/LogListener.class
+org/osgi/service/log/LogReaderService.class
+org/osgi/service/log/LogService.class
+org/osgi/service/log/package.html
+org/osgi/service/log/packageinfo
+</pre>
+</div></div>
+
+<h2><a name="ApacheFelixMavenBundlePlugin(BND)-AddingOSGimetadatatoexistingprojectswithoutchangingthepackagingtype"></a>Adding OSGi metadata to existing projects without changing the packaging type</h2>
+
+<p>If you want to keep your project packaging type (for example "jar") but would like to add OSGi metadata<br>
+you can use the manifest goal to generate a bundle manifest. The maven-jar-plugin can then be used to<br>
+add this manifest to the final artifact. For example:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-xml"><span class="code-tag"><plugin></span>
+ <span class="code-tag"><artifactId></span>maven-jar-plugin<span class="code-tag"></artifactId></span>
+ <span class="code-tag"><configuration></span>
+ <span class="code-tag"><archive></span>
+ <span class="code-tag"><manifestFile></span>${project.build.outputDirectory}/META-INF/MANIFEST.MF<span class="code-tag"></manifestFile></span>
+ <span class="code-tag"></archive></span>
+ <span class="code-tag"></configuration></span>
+<span class="code-tag"></plugin></span>
+<span class="code-tag"><plugin></span>
+ <span class="code-tag"><groupId></span>org.apache.felix<span class="code-tag"></groupId></span>
+ <span class="code-tag"><artifactId></span>maven-bundle-plugin<span class="code-tag"></artifactId></span>
+ <span class="code-tag"><executions></span>
+ <span class="code-tag"><execution></span>
+ <span class="code-tag"><id></span>bundle-manifest<span class="code-tag"></id></span>
+ <span class="code-tag"><phase></span>process-classes<span class="code-tag"></phase></span>
+ <span class="code-tag"><goals></span>
+ <span class="code-tag"><goal></span>manifest<span class="code-tag"></goal></span>
+ <span class="code-tag"></goals></span>
+ <span class="code-tag"></execution></span>
+ <span class="code-tag"></executions></span>
+<span class="code-tag"></plugin></span></pre>
+</div></div>
+
+<h2><a name="ApacheFelixMavenBundlePlugin(BND)-BuildingthePlugin"></a>Building the Plugin</h2>
+
+<p>The plugin is hosted at the Apache Felix project. The following
+steps describe how to build and install the plugin into your local
+Maven2 repository.</p>
+
+<p>Using the SVN client of your choice, checkout the maven-bundle-plugin project.</p>
+
+<div class="preformatted"><div class="preformattedContent">
+<pre>$ svn co http://svn.apache.org/repos/asf/felix/trunk/bundleplugin
+</pre>
+</div></div>
+
+<p>Using Maven2, build and install the maven-bundle-plugin by issuing
+the following Maven2 command in the project directory that was created
+as a result of the previous step.</p>
+
+<div class="preformatted"><div class="preformattedContent">
+<pre>$ mvn install
+</pre>
+</div></div>
+
+<h1><a name="ApacheFelixMavenBundlePlugin(BND)-Goals"></a>Goals</h1>
+
+<p>The maven-bundle-plugin also provides additional functionality via
+some Maven goals. Command-line execution of a goal is performed as
+follows:</p>
+
+<div class="preformatted"><div class="preformattedContent">
+<pre>mvn org.apache.felix:maven-bundle-plugin:GOAL
+</pre>
+</div></div>
+
+<p>Where GOAL is one of the following:</p>
+
+<ul>
+ <li><b><tt>bundle</tt></b> - build an OSGi bundle jar for the current project<br>
+configuration options:
+ <ul>
+ <li><em><tt>manifestLocation</tt></em> defaults to ${project.build.outputDirectory}/META-INF</li>
+ <li><em><tt>unpackBundle</tt></em> unpack bundle contents to output directory, defaults to false</li>
+ <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)</li>
+ <li><em><tt>supportedProjectTypes</tt></em> defaults to "jar","bundle"</li>
+ <li><em><tt>classifier</tt></em> attach bundle to the project using the given classifier</li>
+ </ul>
+ </li>
+</ul>
+
+
+<ul>
+ <li><b><tt>bundleall</tt></b> - build OSGi bundle jars for all transitive dependencies<br>
+configuration options:
+ <ul>
+ <li><em><tt>supportedProjectTypes</tt></em> defaults to "jar","bundle"</li>
+ </ul>
+ </li>
+</ul>
+
+
+<ul>
+ <li><b><tt>wrap</tt></b> - as above, but limited to the first level of dependencies<br>
+configuration options:
+ <ul>
+ <li><em><tt>supportedProjectTypes</tt></em> defaults to "jar","bundle"</li>
+ </ul>
+ </li>
+</ul>
+
+
+<ul>
+ <li><b><tt>manifest</tt></b> - create an OSGi manifest for the current project<br>
+configuration options:
+ <ul>
+ <li><em><tt>manifestLocation</tt></em> defaults to ${project.build.outputDirectory}/META-INF</li>
+ <li><em><tt>supportedProjectTypes</tt></em> defaults to "jar","bundle"</li>
+ </ul>
+ </li>
+</ul>
+
+
+<ul>
+ <li><b><tt>install</tt></b> - adds the current bundle project to the local OBR<br>
+configuration options:
+ <ul>
+ <li><em><tt>obrRepository</tt></em> path to local OBR, defaults to <em><local-maven-repository></em><tt>/repository.xml</tt></li>
+ </ul>
+ </li>
+</ul>
+
+
+<p>More GOALs are available in the <b>1.4.0</b> release:</p>
+
+<ul>
+ <li><b><tt>ant</tt></b> - create an Ant build script to rebuild the bundle</li>
+</ul>
+
+
+<ul>
+ <li><b><tt>install-file</tt></b> - adds a local bundle file to the local OBR<br>
+configuration options:
+ <ul>
+ <li><em><tt>obrRepository</tt></em> path to local OBR, defaults to <em><local-maven-repository></em><tt>/repository.xml</tt></li>
+ <li><em><tt>groupId</tt></em> Maven groupId for the bundle, taken from <em>pomFile</em> if given</li>
+ <li><em><tt>artifactId</tt></em> Maven artifactId for the bundle, taken from <em>pomFile</em> if given</li>
+ <li><em><tt>version</tt></em> Maven version for the bundle, taken from <em>pomFile</em> if given</li>
+ <li><em><tt>packaging</tt></em> Maven packaging type for the bundle, taken from <em>pomFile</em> if given</li>
+ <li><em><tt>classifier</tt></em> Maven classifier type, defaults to none</li>
+ <li><em><tt>pomFile</tt></em> optional Pom file describing the bundle</li>
+ <li><em><tt>file</tt></em> bundle file, defaults to the bundle from the local Maven repository</li>
+ <li><em><tt>obrXml</tt></em> optional additional properties for the bundle</li>
+ </ul>
+ </li>
+</ul>
+
+
+<ul>
+ <li><b><tt>deploy</tt></b> - adds the current bundle project to a remote OBR<br>
+configuration options:
+ <ul>
+ <li><em><tt>remoteOBR</tt></em> name of remote OBR, defaults to NONE (which means no remote OBR deployment)</li>
+ <li><em><tt>obrRepository</tt></em> used when the remoteOBR name is blank, defaults to <tt>repository.xml</tt></li>
+ <li><em><tt>altDeploymentRepository</tt></em> alternative remote repository, <em>id::layout::url</em></li>
+ <li><em><tt>ignoreLock</tt></em> ignore remote locking when updating the OBR</li>
+ </ul>
+ </li>
+</ul>
+
+
+<ul>
+ <li><b><tt>deploy-file</tt></b> - adds a local bundle file to a remote OBR<br>
+configuration options:
+ <ul>
+ <li><em><tt>remoteOBR</tt></em> name of remote OBR, defaults to an empty string</li>
+ <li><em><tt>obrRepository</tt></em> used when the remoteOBR name is blank, defaults to <tt>repository.xml</tt></li>
+ <li><em><tt>repositoryId</tt></em> optional repository id, used to lookup authentication settings</li>
+ <li><em><tt>url</tt></em> remote repository transport URL, like
+<div class="preformatted"><div class="preformattedContent">
+<pre>scpexe://host/path/to/obr
+</pre>
+</div></div></li>
+ <li><em><tt>bundleUrl</tt></em> public URL of deployed bundle, like
+<div class="preformatted"><div class="preformattedContent">
+<pre>http://www.foo.org/bundles/foo.jar
+</pre>
+</div></div></li>
+ <li><em><tt>groupId</tt></em> Maven groupId for the bundle, taken from <em>pomFile</em> if given</li>
+ <li><em><tt>artifactId</tt></em> Maven artifactId for the bundle, taken from <em>pomFile</em> if given</li>
+ <li><em><tt>version</tt></em> Maven version for the bundle, taken from <em>pomFile</em> if given</li>
+ <li><em><tt>packaging</tt></em> Maven packaging type for the bundle, taken from <em>pomFile</em> if given</li>
+ <li><em><tt>classifier</tt></em> Maven classifier type, defaults to none</li>
+ <li><em><tt>pomFile</tt></em> optional Pom file describing the bundle</li>
+ <li><em><tt>file</tt></em> bundle file, defaults to the bundle from the local Maven repository</li>
+ <li><em><tt>obrXml</tt></em> optional additional properties for the bundle</li>
+ <li><em><tt>ignoreLock</tt></em> ignore remote locking when updating the OBR</li>
+ </ul>
+ </li>
+</ul>
+
+
+<ul>
+ <li><b><tt>clean</tt></b> - cleans the local OBR, removing missing bundles<br>
+configuration options:
+ <ul>
+ <li><em><tt>obrRepository</tt></em> path to local OBR, defaults to <em><local-maven-repository></em><tt>/repository.xml</tt></li>
+ </ul>
+ </li>
+</ul>
+
+
+<p>There are also new instructions available from the underlying BND
+tool, which continues to be improved independently; for the latest see <span class="nobr"><a href="http://aqute.biz/Code/Bnd" title="Visit page outside Confluence" rel="nofollow">BND documentation<sup><img class="rendericon" src="apache-felix-maven-bundle-plugin-bnd_files/linkext7.gif" alt="" align="absmiddle" border="0" height="7" width="7"></sup></a></span>.</p>
+
+<p>The default goal <b><tt>bundle</tt></b> will be initialized by setting the <packaging> entry to "bundle".</p>
+
+<h1><a name="ApacheFelixMavenBundlePlugin(BND)-Thefollowingfeaturesareonlyavailablefromversion1.2.0onwards"></a>The following features are only available from version 1.2.0 onwards</h1>
+
+<h2><a name="ApacheFelixMavenBundlePlugin(BND)-Embeddingdependencies"></a>Embedding dependencies</h2>
+
+<p>The Maven Bundle Plugin supports embedding of selected project dependencies inside the bundle by using the <tt><Embed-Dependency></tt> instruction:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-xml"><span class="code-tag"><Embed-Dependency></span>dependencies<span class="code-tag"></Embed-Dependency></span></pre>
+</div></div>
+
+<p>where:</p>
+
+<div class="preformatted"><div class="preformattedContent">
+<pre>dependencies ::= clause ( ',' clause ) *
+clause ::= MATCH ( ';' attr '=' MATCH | ';inline=true' )
+attr ::= 'groupId' | 'artifactId' | 'version' | 'scope' | 'type' | 'classifier'
+MATCH ::= <globbed regular expressions>
+</pre>
+</div></div>
+
+<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>
+clauses, which are then appended to the current set of instructions and
+passed onto BND. If you want the embedded dependencies to be at the
+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>
+
+<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>
+
+<p>some examples:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-xml"><span class="code-tag"><span class="code-comment"><!-- embed all compile and runtime scope dependencies --></span></span>
+<span class="code-tag"><Embed-Dependency></span>*;scope=compile|runtime<span class="code-tag"></Embed-Dependency></span>
+
+<span class="code-tag"><span class="code-comment"><!-- embed any dependencies with artifactId junit and scope test --></span></span>
+<span class="code-tag"><Embed-Dependency></span>junit;scope=test<span class="code-tag"></Embed-Dependency></span>
+
+<span class="code-tag"><span class="code-comment"><!-- inline all dependencies, except those with scope test --></span></span>
+<span class="code-tag"><Embed-Dependency></span>*;scope=!test;inline=true<span class="code-tag"></Embed-Dependency></span>
+
+<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>
+<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></pre>
+</div></div>
+
+<p>examples of using {<tt>maven-dependencies</tt>}:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-xml"><span class="code-tag"><Include-Resource></span>
+ {maven-resources}, {maven-dependencies},
+ org/foo/Example.class=target/classes/org/foo/Example.class
+<span class="code-tag"></Include-Resource></span>
+
+<span class="code-tag"><Bundle-ClassPath></span>.,{maven-dependencies},some.jar<span class="code-tag"></Bundle-ClassPath></span></pre>
+</div></div>
+
+<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>
+
+<ul>
+ <li><tt><Embed-StripVersion>true</Embed-StripVersion></tt> - removes the version from the file (ie. <em>artifactId.jar</em>)</li>
+ <li><tt><Embed-StripGroup>false</Embed-StripGroup></tt> - adds the groupId as a subdirectory (ie. <em>groupId/artifactId-version.jar</em>)</li>
+ <li><tt><Embed-Directory>directory</Embed-Directory></tt> - adds a subdirectory (ie. <em>directory/artifactId-version.jar</em>)</li>
+</ul>
+
+
+<p>Normally the plugin only checks direct dependencies, but this can be
+changed to include the complete set of transitive dependencies with the
+following option:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-xml"><span class="code-tag"><Embed-Transitive></span>true<span class="code-tag"></Embed-Transitive></span></pre>
+</div></div>
+
+<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>
+
+<div class="code"><div class="codeContent">
+<pre class="code-xml"><span class="code-tag"><Embed-Dependency></span>*;scope=compile|runtime;inline=true<span class="code-tag"></Embed-Dependency></span></pre>
+</div></div>
+
+<h3><a name="ApacheFelixMavenBundlePlugin(BND)-EmbedDependencyandExportPackage"></a>Embed-Dependency and Export-Package</h3>
+
+<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>
+instructions will result in classes being inlined in the bundle, even
+though they also exist inside the embedded jar. If you want to export
+packages from an embedded dependency without such duplication then you
+can either inline the dependency, or use a new BND instruction called <tt><_exportcontents></tt>.</p>
+
+<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>
+
+<h2><a name="ApacheFelixMavenBundlePlugin(BND)-OBRintegration"></a>OBR integration</h2>
+
+<p>The latest Maven Bundle Plugin automatically updates the local OBR
+repository.xml file during the install phase, using a default location
+of:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><LOCAL-MAVEN-REPOSITORY>/repository.xml</pre>
+</div></div>
+
+<p>You can configure the location of the OBR repository by using the command line:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java">mvn clean install -DobrRepository=<PATH_TO_OBR></pre>
+</div></div>
+
+<p>or in the configuration section for the maven-bundle-plugin in your Maven POM:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-xml"><span class="code-tag"><groupId></span>org.apache.felix<span class="code-tag"></groupId></span>
+<span class="code-tag"><artifactId></span>maven-bundle-plugin<span class="code-tag"></artifactId></span>
+<span class="code-tag"><extensions></span>true<span class="code-tag"></extensions></span>
+<span class="code-tag"><configuration></span>
+ <span class="code-tag"><obrRepository></span>PATH_TO_OBR<span class="code-tag"></obrRepository></span>
+ <span class="code-tag"><instructions></span>
+ <span class="code-tag"><span class="code-comment"><!-- bnd instructions --></span></span>
+ <span class="code-tag"></instructions></span>
+<span class="code-tag"></configuration></span></pre>
+</div></div>
+
+<p>to disable OBR installation set the obrRepository to NONE, for example:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-xml"><span class="code-tag"><groupId></span>org.apache.felix<span class="code-tag"></groupId></span>
+<span class="code-tag"><artifactId></span>maven-bundle-plugin<span class="code-tag"></artifactId></span>
+<span class="code-tag"><extensions></span>true<span class="code-tag"></extensions></span>
+<span class="code-tag"><configuration></span>
+ <span class="code-tag"><obrRepository></span>NONE<span class="code-tag"></obrRepository></span>
+ <span class="code-tag"><instructions></span>
+ <span class="code-tag"><span class="code-comment"><!-- bnd instructions --></span></span>
+ <span class="code-tag"></instructions></span>
+<span class="code-tag"></configuration></span></pre>
+</div></div>
+
+<h2><a name="ApacheFelixMavenBundlePlugin(BND)-Eclipse/PDEintegration"></a>Eclipse/PDE integration</h2>
+
+<p>It is possible to configure the Maven Bundle Plugin to put the
+bundle manifest where Eclipse/PDE expects it, and use the Maven
+Dependency Plugin to arrange for any embedded dependencies to appear in
+a local directory that matches the Bundle-ClassPath entries. Here is an
+example POM that does this:</p>
+
+<div class="preformatted"><div class="preformattedContent">
+<pre><project>
+
+ <properties>
+ <bundle.symbolicName>org.example</bundle.symbolicName>
+ <bundle.namespace>org.example</bundle.namespace>
+ </properties>
+
+ <modelVersion>4.0.0</modelVersion>
+ <groupId>examples</groupId>
+ <artifactId>org.example</artifactId>
+ <version>1.0-SNAPSHOT</version>
+
+ <name>${bundle.symbolicName} [${bundle.namespace}]</name>
+
+ <packaging>bundle</packaging>
+
+ <build>
+ <resources>
+ <resource>
+ <directory>src/main/resources</directory>
+ </resource>
+ <resource>
+ <directory>.</directory>
+ <includes>
+ <include>plugin.xml</include>
+ </includes>
+ </resource>
+ </resources>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.felix</groupId>
+ <artifactId>maven-bundle-plugin</artifactId>
+ <version>1.2.1</version>
+ <extensions>true</extensions>
+ <!--
+ the following instructions build a simple set of public/private classes into an OSGi bundle
+ -->
+ <configuration>
+ <manifestLocation>META-INF</manifestLocation>
+ <instructions>
+ <Bundle-SymbolicName>${bundle.symbolicName}</Bundle-SymbolicName>
+ <Bundle-Version>${pom.version}</Bundle-Version>
+ <!--
+ assume public classes are in the top package, and private classes are under ".internal"
+ -->
+ <Export-Package>!${bundle.namespace}.internal.*,${bundle.namespace}.*;version="${pom.version}"</Export-Package>
+ <Private-Package>${bundle.namespace}.internal.*</Private-Package>
+ <Bundle-Activator>${bundle.namespace}.internal.ExampleActivator</Bundle-Activator>
+ <!--
+ embed compile/runtime dependencies using path that matches the copied dependency folder
+ -->
+ <Embed-Dependency>*;scope=compile|runtime;inline=false</Embed-Dependency>
+ <Embed-Directory>target/dependency</Embed-Directory>
+ <Embed-StripGroup>true</Embed-StripGroup>
+ </instructions>
+ </configuration>
+ </plugin>
+ <plugin>
+ <artifactId>maven-dependency-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>copy-dependencies</id>
+ <phase>package</phase>
+ <goals>
+ <goal>copy-dependencies</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+
+ <dependencies>
+ <dependency>
+ <groupId>org.osgi</groupId>
+ <artifactId>osgi_R4_core</artifactId>
+ <version>1.0</version>
+ <scope>provided</scope>
+ <optional>true</optional>
+ </dependency>
+ <dependency>
+ <groupId>org.osgi</groupId>
+ <artifactId>osgi_R4_compendium</artifactId>
+ <version>1.0</version>
+ <scope>provided</scope>
+ <optional>true</optional>
+ </dependency>
+ <dependency>
+ <groupId>junit</groupId>
+ <artifactId>junit</artifactId>
+ <version>3.8.1</version>
+ <scope>compile</scope>
+ <optional>true</optional>
+ </dependency>
+ </dependencies>
+
+</project>
+</pre>
+</div></div>
+
+<p>To generate the Eclipse metadata use:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java">mvn clean <span class="code-keyword">package</span> eclipse:eclipse -Declipse.pde install</pre>
+</div></div>
+
+<p>and you should now be able to import this as an existing Eclipse project.</p>
+
+<p>FYI: the above POM was generated using the <tt>pax-create-bundle</tt> command from <span class="nobr"><a href="http://www.ops4j.org/projects/pax/construct/index.html" title="Visit page outside Confluence" rel="nofollow">Pax-Construct<sup><img class="rendericon" src="apache-felix-maven-bundle-plugin-bnd_files/linkext7.gif" alt="" align="absmiddle" border="0" height="7" width="7"></sup></a></span> and then tweaked to demonstrate using the Maven Dependency Plugin to handle embedded jars in Eclipse.</p>
+
+<p>With the original Pax-Construct generated POM you would simply use:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java">mvn clean <span class="code-keyword">package</span> pax:eclipse</pre>
+</div></div>
+
+<p>to create the appropriate Eclipse files and manifest, and also
+handle any embedded entries. The pax:eclipse goal extends
+eclipse:eclipse, and supports the same parameters.</p>
+
+<h2><a name="ApacheFelixMavenBundlePlugin(BND)-Unpackingbundlecontentsto'target/classes'"></a>Unpacking bundle contents to 'target/classes'</h2>
+
+<p>Once in a while you may create a bundle which contains additional classes to the ones compiled from <tt>src/main/java</tt>,
+for example when you embed the classes from another jar. This can
+sometimes cause unforeseen problems in Maven, as it will use the output
+directory (<tt>target/classes</tt>) rather than the final bundle, when compiling against projects in the same reactor (ie. the same build).</p>
+
+<p>The easiest way to get around this Maven 'feature' is to unpack the
+contents of the bundle to the output directory after the packaging
+step, so the additional classes will be found where Maven expects them.
+Thankfully there is now an easy option to do this in the bundle-plugin:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-xml"><span class="code-tag"><groupId></span>org.apache.felix<span class="code-tag"></groupId></span>
+<span class="code-tag"><artifactId></span>maven-bundle-plugin<span class="code-tag"></artifactId></span>
+<span class="code-tag"><extensions></span>true<span class="code-tag"></extensions></span>
+<span class="code-tag"><configuration></span>
+ <span class="code-tag"><unpackBundle></span>true<span class="code-tag"></unpackBundle></span>
+ <span class="code-tag"><instructions></span>
+ <span class="code-tag"><span class="code-comment"><!-- bnd instructions --></span></span>
+ <span class="code-tag"></instructions></span>
+<span class="code-tag"></configuration></span></pre>
+</div></div>
+
+<h2><a name="ApacheFelixMavenBundlePlugin(BND)-UsinganexistingMANIFEST.MFfile"></a>Using an existing MANIFEST.MF file</h2>
+
+<p>If you have an existing manifest, you can add this to the Bnd instructions, like so:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-xml"><span class="code-tag"><_include></span>src/main/resources/META-INF/MANIFEST.MF<span class="code-tag"></_include></span>
+<span class="code-tag"><Export-Package></span>org.example.*<span class="code-tag"></Export-Package></span></pre>
+</div></div>
+
+<p>Bnd will use it when calculating the bundle contents, and will also
+copy across all manifest attributes starting with a capital letter.<br>
+As shown in the above example, you could use this to include a non-OSGi
+manifest which you then customize with extra OSGi attributes.</p>
+
+<h1><a name="ApacheFelixMavenBundlePlugin(BND)-Thefollowingfeaturesareonlyavailablefromversion1.4.0onwards"></a>The following features are only available from version 1.4.0 onwards</h1>
+
+<h2><a name="ApacheFelixMavenBundlePlugin(BND)-bundle:ant"></a>bundle:ant</h2>
+
+<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>
+
+<p>The customized Ant script uses the BND tool to rebuild the bundle,
+so any source changes should be reflected in the (re)generated manifest.</p>
+
+<p>Example:</p>
+<div class="preformatted"><div class="preformattedContent">
+<pre>mvn ant:ant bundle:ant
+
+ant clean package
+</pre>
+</div></div>
+
+<h2><a name="ApacheFelixMavenBundlePlugin(BND)-bundle:installfile"></a>bundle:install-file</h2>
+
+<p>The <b>install-file</b> goal updates the local OBR with the details of a bundle from the local filesystem.</p>
+
+<p>configuration:</p>
+<ul>
+ <li><em>obrRepository</em> path to local OBR, defaults to <em><local-maven-repository></em><tt>/repository.xml</tt></li>
+ <li><em>groupId</em> Maven groupId for the bundle, taken from <em>pomFile</em> if given</li>
+ <li><em>artifactId</em> Maven artifactId for the bundle, taken from <em>pomFile</em> if given</li>
+ <li><em>version</em> Maven version for the bundle, taken from <em>pomFile</em> if given</li>
+ <li><em>packaging</em> Maven packaging type for the bundle, taken from <em>pomFile</em> if given</li>
+ <li><em>classifier</em> Maven classifier type, defaults to none</li>
+ <li><em>pomFile</em> optional Pom file describing the bundle</li>
+ <li><em>file</em> bundle file, defaults to the bundle from the local Maven repository</li>
+ <li><em>obrXml</em> optional additional properties for the bundle</li>
+</ul>
+
+
+<p>Example:</p>
+<div class="preformatted"><div class="preformattedContent">
+<pre>mvn org.apache.felix:maven-bundle-plugin:1.4.0:install-file \
+ -DpomFile=myPom.xml -Dfile=foo-1.0.jar
+</pre>
+</div></div>
+
+<h2><a name="ApacheFelixMavenBundlePlugin(BND)-bundle:deploy"></a>bundle:deploy</h2>
+
+<p>The <b>deploy goal</b> updates the remote OBR with the details of
+the deployed bundle from the local Maven repository. The remote OBR is
+found by querying the <tt><distributionManagement></tt> section of the project, unless <tt>-DaltDeploymentRepository</tt> is set. See <span class="nobr"><a href="http://maven.apache.org/plugins/maven-deploy-plugin/deploy-mojo.html" title="Visit page outside Confluence" rel="nofollow">http://maven.apache.org/plugins/maven-deploy-plugin/deploy-mojo.html<sup><img class="rendericon" src="apache-felix-maven-bundle-plugin-bnd_files/linkext7.gif" alt="" align="absmiddle" border="0" height="7" width="7"></sup></a></span> for more details about these particular settings.</p>
+
+<p>(If the project has an <tt>obr.xml</tt> file somewhere in its resources, then it will be automatically detected and applied.)</p>
+
+<p>configuration:</p>
+<ul>
+ <li><em>remoteOBR</em> name of remote OBR, defaults to NONE (which means no remote OBR deployment)</li>
+ <li><em>obrRepository</em> used when the remoteOBR name is blank, defaults to <tt>repository.xml</tt></li>
+ <li><em>altDeploymentRepository</em> alternative remote repository, <em>id::layout::url</em></li>
+ <li><em>ignoreLock</em> ignore remote locking when updating the OBR</li>
+</ul>
+
+
+<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>
+
+<h2><a name="ApacheFelixMavenBundlePlugin(BND)-bundle:deployfile"></a>bundle:deploy-file</h2>
+
+<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 <span class="nobr"><a href="http://maven.apache.org/plugins/maven-deploy-plugin/deploy-file-mojo.html" title="Visit page outside Confluence" rel="nofollow">http://maven.apache.org/plugins/maven-deploy-plugin/deploy-file-mojo.html<sup><img class="rendericon" src="apache-felix-maven-bundle-plugin-bnd_files/linkext7.gif" alt="" align="absmiddle" border="0" height="7" width="7"></sup></a></span> for more details about these particular settings.</p>
+
+<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>
+
+<p>configuration:</p>
+<ul>
+ <li><em>remoteOBR</em> name of remote OBR, defaults to an empty string</li>
+ <li><em>obrRepository</em> used when the remoteOBR name is blank, defaults to <tt>repository.xml</tt></li>
+ <li><em>repositoryId</em> optional repository id, used to lookup authentication settings</li>
+ <li><em>url</em> remote repository transport URL, like
+<div class="preformatted"><div class="preformattedContent">
+<pre>scpexe://host/path/to/obr
+</pre>
+</div></div></li>
+ <li><em>bundleUrl</em> public URL of deployed bundle, like
+<div class="preformatted"><div class="preformattedContent">
+<pre>http://www.foo.org/bundles/foo.jar
+</pre>
+</div></div></li>
+ <li><em>groupId</em> Maven groupId for the bundle, taken from <em>pomFile</em> if given</li>
+ <li><em>artifactId</em> Maven artifactId for the bundle, taken from <em>pomFile</em> if given</li>
+ <li><em>version</em> Maven version for the bundle, taken from <em>pomFile</em> if given</li>
+ <li><em>packaging</em> Maven packaging type for the bundle, taken from <em>pomFile</em> if given</li>
+ <li><em>classifier</em> Maven classifier type, defaults to none</li>
+ <li><em>pomFile</em> optional Pom file describing the bundle</li>
+ <li><em>file</em> bundle file, defaults to the bundle from the local Maven repository</li>
+ <li><em>obrXml</em> optional additional properties for the bundle</li>
+ <li><em>ignoreLock</em> ignore remote locking when updating the OBR</li>
+</ul>
+
+
+<p>Example:</p>
+<div class="preformatted"><div class="preformattedContent">
+<pre>mvn org.apache.felix:maven-bundle-plugin:1.4.0:deploy-file \
+ -DpomFile=myPom.xml -Dfile=foo-1.0.jar -Durl=file:/tmp/example/OBR \
+ -DbundleUrl=http://www.foo.org/bundles/foo.jar
+</pre>
+</div></div>
+
+<h2><a name="ApacheFelixMavenBundlePlugin(BND)-bundle:clean"></a>bundle:clean</h2>
+
+<p>Sometimes you would like to clean your local OBR because it contains
+bundles that are no longer in your local Maven repository. This case
+often occurs when artifacts were deleted manually. The
+maven-bundle-plugin provides a simple goal to check for missing
+bundles, and remove them from the local OBR.</p>
+
+<p>configuration:</p>
+<ul>
+ <li><em>obrRepository</em> path to local OBR, defaults to <em><local-maven-repository></em><tt>/repository.xml</tt></li>
+</ul>
+
+
+<p>Example:</p>
+<div class="preformatted"><div class="preformattedContent">
+<pre>mvn bundle:clean
+</pre>
+</div></div>
+
+<h2><a name="ApacheFelixMavenBundlePlugin(BND)-Concurrentupdates"></a>Concurrent updates</h2>
+
+<p>With a remote OBR, several uploads may occur at the same time.
+However, the remote OBR is centralized in one file, so concurrent
+modification must be avoided. To achieve this, the plug-in implements a
+locking system. Each time the plug-in tries to modify the file it sets
+a file based lock. If it can't take the lock, it will wait and retry.
+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>
+
+<h2><a name="ApacheFelixMavenBundlePlugin(BND)-FTPprotocol"></a>FTP protocol</h2>
+
+<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>
+<div class="code"><div class="codeContent">
+<pre class="code-xml"><span class="code-tag"><build></span>
+ <span class="code-tag"><extensions></span>
+ <span class="code-tag"><extension></span>
+ <span class="code-tag"><groupId></span>org.apache.maven.wagon<span class="code-tag"></groupId></span>
+ <span class="code-tag"><artifactId></span>wagon-ftp<span class="code-tag"></artifactId></span>
+ <span class="code-tag"><version></span>1.0-alpha-6<span class="code-tag"></version></span>
+ <span class="code-tag"></extension></span>
+ <span class="code-tag"></extensions></span>
+<span class="code-tag"></build></span></pre>
+</div></div>
+
+<h2><a name="ApacheFelixMavenBundlePlugin(BND)-Howtheplugincomputesthedescriptionofthebundle"></a>How the plug-in computes the description of the bundle</h2>
+
+<p>The description of the bundle comes from three different sources:</p>
+<ul>
+ <li>Bindex : Bindex is a tool that analyzes a bundle manifest to generate OBR description</li>
+ <li>pom.xml : by analyzing the pom file, various information is collected (symbolic name ...)</li>
+ <li>obr.xml : this file contains customized description and capabilities for the bundle</li>
+</ul>
+
+
+<p>These sources are merged together using the following precedence:</p>
+<div class="preformatted"><div class="preformattedContent">
+<pre>Bindex
+| (overrides)
+pom.xml
+| (overrides)
+obr.xml
+</pre>
+</div></div>
+<p>A warning message is displayed when existing information is overridden.</p>
+
+<h2><a name="ApacheFelixMavenBundlePlugin(BND)-Knownissues&limitations"></a>Known issues & limitations</h2>
+
+<ol>
+ <li>obr.xml (file given by the user to add properties not found
+by Bindex) must be correct, because the plug-in does not check its
+syntax.</li>
+</ol>
+
+
+<h1><a name="ApacheFelixMavenBundlePlugin(BND)-Feedback"></a>Feedback</h1>
+
+<p>Subscribe to the Felix users mailing list by sending a message to <span class="nobr"><a href="mailto:users-subscribe@felix.apache.org" title="Send mail to users-subscribe@felix.apache.org" rel="nofollow">users-subscribe@felix.apache.org<sup><img class="rendericon" src="apache-felix-maven-bundle-plugin-bnd_files/mail_small.gif" alt="" align="absmiddle" border="0" height="12" width="13"></sup></a></span>; after subscribing, email questions or feedback to <span class="nobr"><a href="mailto:users@felix.apache.org" title="Send mail to users@felix.apache.org" rel="nofollow">users@felix.apache.org<sup><img class="rendericon" src="apache-felix-maven-bundle-plugin-bnd_files/mail_small.gif" alt="" align="absmiddle" border="0" height="12" width="13"></sup></a></span>.</p>
+ </div>
+
+</body></html>
\ No newline at end of file