| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <html> |
| <!-- |
| |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| https://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| <head> |
| <title>Apache Felix - Apache Felix Maven OSGi Plugin</title> |
| <link rel="icon" href="/res/favicon.ico"> |
| <link rel="stylesheet" href="/res/site.css" type="text/css" media="all"> |
| <link rel="stylesheet" href="/res/codehilite.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="https://felix.apache.org/"> |
| <img border="0" alt="Apache Felix" src="/res/logo.png"> |
| </a> |
| </div> |
| <div class="header"> |
| <a href="https://www.apache.org/"> |
| <img border="0" alt="Apache" src="/res/apache.png"> |
| </a> |
| </div> |
| </div> |
| |
| <div class="menu"> |
| <style type="text/css"> |
| /* The following code is added by mdx_elementid.py |
| It was originally lifted from http://subversion.apache.org/style/site.css */ |
| /* |
| * Hide class="elementid-permalink", except when an enclosing heading |
| * has the :hover property. |
| */ |
| .headerlink, .elementid-permalink { |
| visibility: hidden; |
| } |
| h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style> |
| <p><a href="/news.html">News</a> <br /> |
| <a href="/license.html">License</a> <br /> |
| <a href="/downloads.cgi">Downloads</a> <br /> |
| <a href="/documentation.html">Documentation</a> <br /> |
| <a href="/documentation/community/project-info.html">Project Info</a> <br /> |
| <a href="/documentation/community/contributing.html">Contributing</a> <br /> |
| <a href="/sitemap.html">Site Map</a> <br /> |
| <a href="https://www.apache.org/">ASF</a> <br /> |
| <a href="https://www.apache.org/security/">Security</a> <br /> |
| <a href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a> <br /> |
| <a href="https://www.apache.org/foundation/thanks.html">Sponsors</a> </p> |
| <iframe |
| src="https://www.apache.org/ads/button.html" |
| style="border-width:0; float: left" |
| frameborder="0" |
| scrolling="no" |
| width="135" |
| height="135"> |
| </iframe> |
| </div> |
| |
| <div class="main"> |
| <div class="breadcrump" style="font-size: 80%;"> |
| <a href="/">Home</a> » <a href="/documentation.html">Documentation</a> |
| </div> |
| |
| <h1>Apache Felix Maven OSGi Plugin</h1> |
| <style type="text/css"> |
| /* The following code is added by mdx_elementid.py |
| It was originally lifted from http://subversion.apache.org/style/site.css */ |
| /* |
| * Hide class="elementid-permalink", except when an enclosing heading |
| * has the :hover property. |
| */ |
| .headerlink, .elementid-permalink { |
| visibility: hidden; |
| } |
| h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style> |
| <div class="warning" markdown="1"> |
| The *maven-osgi-plugin* is *deprecated* and has been *replaced* by a new plugin: *[maven-bundle-plugin](/documentation/subprojects/apache-felix-maven-bundle-plugin-bnd.html)* |
| </div> |
| |
| <p>The OSGi plugin for Maven 2.0 is currently under development at the <a href="http://incubator.apache.org/felix">Apache Felix</a> project, and this page documents the plugin's current state of functionality and will serve as a how-to guide for its use.</p> |
| <p>The main task this plugin aims to accomplish is the generation of OSGi-compliant bundle archives. To this end, the plugin provides an integraton with Maven 2's project object model (POM) with particular focus on manipulation of the bundle's manifest and the automated generation of some headers (e.g., Bundle-ClassPath, Import-Package, and Bundle-Activator).</p> |
| <h3 id="current-plugin-functionality">Current Plugin Functionality<a class="headerlink" href="#current-plugin-functionality" title="Permanent link">¶</a></h3> |
| <h5 id="standard-features">Standard Features <a class="headerlink" href="#standard-features" title="Permanent link">¶</a></h5> |
| <p>The plugin provides the user with two ways to manipulate the contents of a bundle's manifest: |
| 1. Path and filename of a manifest.mf file in which the contents will be merged with the default entries generated by Maven 2. Note that <em>any</em> manifest entry can be added to the bundle's manifest using this technique - java-standard, osgi-standard, or custom entries. The path name is relative to the root of the Maven 2 project, and is specified using the following POM notation: |
| <DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>Manifest Example 1|borderStyle=solid</B></DIV><DIV class="codeContent panelContent"> |
| ... |
| <plugins> |
| <plugin> |
| <groupId>org.apache.felix.plugins</groupId> |
| <artifactId>maven-osgi-plugin</artifactId> |
| <extensions>true</extensions> |
| <version>0.3.0</version> |
| <configuration> |
| <manifestFile>resources/manifest.mf</manifestFile> |
| </configuration> |
| </plugin> |
| </plugins> |
| ...</p> |
| <ol> |
| <li> |
| <p>Individual plugin configuration attributes for OSGi manifest entries. Currently, only a subset of the standard OSGi manifest entries are supported so far. The intention is to implement the full set of OSGi specified manifest entries. OSGi manifest entries currently supported as plugin configuration attributes include:</p> |
| </li> |
| <li> |
| <p>Bundle-ManifestVersion</p> |
| </li> |
| <li>Bundle-ClassPath (can only be automatically generated)</li> |
| <li>Bundle-Activator (can be automatically generated if desired, otherwise will be verified if specified)</li> |
| <li>Bundle-Name</li> |
| <li>Bundle-Version</li> |
| <li>Bundle-Description</li> |
| <li>Bundle-Vendor</li> |
| <li>Bundle-Date</li> |
| <li>Bundle-UpdateLocation</li> |
| <li>Bundle-SymbolicName</li> |
| <li>Bundle-URL</li> |
| <li>Bundle-DocURL</li> |
| <li>Bundle-Source</li> |
| <li>Bundle-Category</li> |
| <li>Export-Service</li> |
| <li>Import-Service</li> |
| <li>Export-Package (will be verified if specified, cannot be automatically generated)</li> |
| <li>Import-Package (will be verified if specified, otherwise automatically generated)</li> |
| <li>DynamicImport-Package</li> |
| <li>Metadata-Location</li> |
| <li>Bundle-Copyright</li> |
| <li>Bundle-NativeCode</li> |
| <li>Bundle-ContactAddress</li> |
| <li>Bundle-RequiredExecutionEnvironment</li> |
| <li>Bundle-Localization</li> |
| <li>Require-Bundle</li> |
| <li>Fragment-Host</li> |
| <li>Service-Component</li> |
| </ol> |
| <p>These manifest entries are specified as plugin configuration attributes using the following POM notation: |
| <DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>Manifest Example 2|borderStyle=solid</B></DIV><DIV class="codeContent panelContent"> |
| ... |
| <plugins> |
| <plugin> |
| <groupId>org.apache.felix.plugins</groupId> |
| <artifactId>maven-osgi-plugin</artifactId> |
| <extensions>true</extensions> |
| <version>0.3.0</version> |
| <configuration> |
| <osgiManifest> |
| <bundleName>My OSGi Application</bundleName> |
| <bundleDescription>An example bundle application</bundleDescription> |
| <bundleActivator>org.safehaus.bundle.Activator</bundleActivator> |
| <importPackage>org.osgi.service.log</importPackage> |
| <bundleVendor>Safehaus</bundleVendor> |
| </osgiManifest> |
| </configuration> |
| </plugin> |
| </plugins> |
| ...</p> |
| <p>Additionally, the following OSGi manifest entries are automatically populated by the plugin: |
| <em> Bundle-Version |
| </em> Bundle-Classpath |
| <em> Import-Package |
| </em> Bundle-Activator</p> |
| <p>To auto-generate the Bundle-Activator manifest entries, you must explicitly specify "auto-detect", such as: |
| <DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>Manifest Example 3|borderStyle=solid</B></DIV><DIV class="codeContent panelContent"> |
| ... |
| <configuration> |
| <osgiManifest> |
| <bundleName>My OSGi Application</bundleName> |
| <bundleActivator>auto-detect</bundleActivator> |
| </osgiManifest> |
| </configuration> |
| ...</p> |
| <p>If you specify a value for Import-Package or Bundle-Activator, then the specified values will be verified against what is computed and warnings may be issued if discrepencies are found. The Export-Package header is also similarly verified, even though it cannot be automatically generated. The detection of the Bundle-Activator is currently simplistic and will not correctly detect cases where there are more than one potential activator, the activator is a subclass of subclass of activator, or the activator is imported.</p> |
| <p>Note: It is possible to use both methods of manifest manipulation simultaneously.</p> |
| <p>The plugin uses the Maven2 <scope/> dependency attribute in order to analyze which dependent JARs need to be embedded in the generated OSGi bundle. Maven2 dependencies specified in the project's POM that have the scope of <em>provided</em> or <em>test</em> <em>will not</em> be embedded in the OSGi bundle archive. Maven 2 dependencies that have scope of <em>compile</em> or <em>runtime</em> <em>will be</em> embedded in the OSGi bundle archive. Maven 2 dependencies have a default scope of <em>compile</em> when not explicitly specified in the POM.</p> |
| <p>If the plugin determines that dependent JARs will be embedded in the generated OSGi bundle archive, then the <em>Bundle-Classpath</em> manifest entry <em>will be</em> automatically created and populated with the path/filename(s) of the bundled dependencies.</p> |
| <p>The plugin automatically creates and populates the <em>Bundle-Version</em> manifest entry based on the POM's artifact version attribute.</p> |
| <h5 id="advanced-features">Advanced Features<a class="headerlink" href="#advanced-features" title="Permanent link">¶</a></h5> |
| <p>The plugin calculates the Import-Package manifest header by examining the byte code of the classes in the bundle. In some situations, it generates imports for packages that are not strictly necessary, such as if the bundle does not access all of the code of an embedded library. In those situations it is possible to specify <ignorePackage> tag. In some cases, the plugin does not calculate the precise set of imports. For such situations, the plugin supports a <explicitImportPackage> tag, which specifies a set of imported packages to be added to the calculated set.</p> |
| <p>The plugin automatically embeds any JAR file dependencies with a scope of <em>compile</em> or <em>runtime</em> into the bundle and will add these JAR files to the <em>Bundle-ClassPath</em> header. In some situations it is better to inline or unroll the dependent JAR files to that their files are simply included in the resulting bundle JAR file; this makes it possible to put the bundle JAR file on the class path like a standard JAR file. The <inlinedArtifacts> tag is used for this purpose.</p> |
| <p>Both the <ignorePackage> and <inlinedArtifacts> tags are set in the <configuration> section of the plugin, while <explicitImportPackage> is specified in the <osgiManifest> section, such as: |
| <DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>Manifest Example 3|borderStyle=solid</B></DIV><DIV class="codeContent panelContent"> |
| <project> |
| <modelVersion>4.0.0</modelVersion> |
| <groupId>my-osgi-bundles</groupId> |
| <artifactId>simple</artifactId> |
| <packaging>osgi-bundle</packaging> |
| <version>1.0</version> |
| <name>Simple Bundle</name> |
| <build> |
| <plugins> |
| <plugin> |
| <groupId>org.apache.felix.plugins</groupId> |
| <artifactId>maven-osgi-plugin</artifactId> |
| <extensions>true</extensions> |
| <version>0.3.0</version> |
| <configuration> |
| <inlinedArtifacts> |
| <inlinedArtifact>kxml2</inlinedArtifact> |
| </inlinedArtifacts> |
| <ignorePackage>javax.xml.parsers,org.xml.sax</ingorePackage> |
| <osgiManifest> |
| <bundleActivator>com.my.company.Activator</bundleActivator> |
| <bundleName>Simple Bundle</bundleName> |
| <bundleDescription>simple bundle</bundleDescription> |
| <bundleVendor>Me</bundleVendor> |
| <explicitImportPackage>org.foo.bar</explicitImportPackage> |
| </osgiManifest> |
| </configuration> |
| </plugin> |
| </plugins> |
| </build> |
| <dependencies> |
| <dependency> |
| <groupId>kxml2</groupId> |
| <artifactId>kmxl2</artifactId> |
| <version>2.2.2</version> |
| </dependency> |
| <dependency> |
| <groupId>org.apache.felix</groupId> |
| <artifactId>org.osgi.core</artifactId> |
| <version>??What value should be used here??</version> |
| <scope>provided</scope> |
| </dependency> |
| </dependencies> |
| </project></p> |
| <h3 id="how-to">How-To<a class="headerlink" href="#how-to" title="Permanent link">¶</a></h3> |
| <h5 id="get-the-maven-20-runtime">Get the Maven 2.0 Runtime<a class="headerlink" href="#get-the-maven-20-runtime" title="Permanent link">¶</a></h5> |
| <p>The first step in the process of using the Maven 2 OSGi plugin is downloading and installing the latest version of the Maven 2 runtime itself. The current latest release is Maven 2.0 and instuctions for getting started with Maven 2 can be found at <a href="http://maven.apache.org/maven2/index.html">http://maven.apache.org/maven2/index.html</a>.</p> |
| <h5 id="getting-the-maven-osgi-plugin">Getting the maven-osgi-plugin<a class="headerlink" href="#getting-the-maven-osgi-plugin" title="Permanent link">¶</a></h5> |
| <p>The Maven 2 OSGi plugin development is being hosted at the Apache Felix project. The remainder of this How-To section discusses how to obtain and install the OSGi plugin, and some of things that you need to do in order to effectively use the plugin to construct OSGi-compliant bundle archives from your Maven 2 projects.</p> |
| <p>The following steps describe how to get the maven-osgi-plugin installed in your local Maven 2 repository: |
| 1. Using the SVN client of your choice, checkout the <a href="https://svn.apache.org/repos/asf/incubator/felix/trunk/tools/maven2/maven-osgi-plugin">Maven 2 OSGi plugin project</a>.</p> |
| <div class="codehilite"><pre>$ <span class="n">svn</span> <span class="n">co</span> <span class="p">[</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">svn</span><span class="p">.</span><span class="n">apache</span><span class="p">.</span><span class="n">org</span><span class="o">/</span><span class="n">repos</span><span class="o">/</span><span class="n">asf</span><span class="o">/</span><span class="n">incubator</span><span class="o">/</span><span class="n">felix</span><span class="o">/</span><span class="n">trunk</span><span class="o">/</span><span class="n">tools</span><span class="o">/</span><span class="n">maven2</span><span class="o">/</span><span class="n">maven</span><span class="o">-</span><span class="n">osgi</span><span class="o">-</span><span class="n">plugin</span><span class="p">]</span> |
| </pre></div> |
| |
| |
| <ol> |
| <li> |
| <p>Using Maven 2, build and install the maven-osgi-plugin by issuing the following Maven 2 command in the root directory of the project you checked out in Step 1.</p> |
| <p>$ mvn install</p> |
| </li> |
| </ol> |
| <h5 id="adding-the-safehaus-maven-2-repository">Adding the Safehaus Maven 2 Repository <a class="headerlink" href="#adding-the-safehaus-maven-2-repository" title="Permanent link">¶</a></h5> |
| <p>If you have experience using Maven 1.0 or 2.0 to compile and build software artifacts, you probably understand that one of the goals of Maven to help developers with dependancy management. While this is certainly a strength that the Maven project model offers that a traditional Ant-based build system lacks, it does require that the developers of widely-distributed libraries publish their binary distributions to a centrally-managed Maven jar repository in adherence to some naming and grouping guidelines.</p> |
| <p>To date, none of the OSGi binaries have been published to a Maven jar repository either at the <a href="http://www.ibiblio.org/maven">Maven 1.0 Repository</a> or the [Maven 2.0 Repository|http://www.ibiblio.org/maven2]. Certainly, this will need to be addressed as the Apache Felix implementation moves forward. But, to begin using the maven-osgi-plugin today, you can use the published versions in the Safehaus Maven 2 Repository by adding the repository to your Maven 2 settings.xml. After these artifacts are published at iBiblio, this activity will no longer be required.</p> |
| <p>Add a custom Maven 2 repository by placing the following in your $HOME/.m2/settings.xml: |
| <DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>Adding a Repository to HOME/.m2/settings.xml|borderStyle=solid</B></DIV><DIV class="codeContent panelContent"> |
| <settings> |
| ... |
| <profiles> |
| <profile> |
| <id>myprofile</id> |
| <repositories> |
| <repository> |
| <id>safehaus-repository</id> |
| <name>Safehaus Repository</name> |
| <url>http://m2.safehaus.org</url> |
| </repository> |
| </repositories> |
| </profile> |
| </profiles> |
| <activeProfiles> |
| <activeProfile>myprofile</activeProfile> |
| </activeProfiles> |
| ... |
| </settings></p> |
| <p>Once this is configured, you may use the following dependencies for OSGi R3 or R4:</p> |
| <div class="codehilite"><pre><span class="nt"><groupId></span>org.osgi<span class="nt"></groupId></span> |
| <span class="nt"><artifactId></span>org.osgi<span class="nt"></artifactId></span> |
| <span class="nt"><version></span>3.0<span class="nt"></version></span> |
| |
| |
| <span class="nt"><groupId></span>org.apache.felix<span class="nt"></groupId></span> |
| <span class="nt"><artifactId></span>org.osgi.core<span class="nt"></artifactId></span> |
| <span class="nt"><version></span>??What value should be used here??<span class="nt"></version></span> |
| |
| |
| <span class="nt"><groupId></span>org.apache.felix<span class="nt"></groupId></span> |
| <span class="nt"><artifactId></span>org.osgi.compendium<span class="nt"></artifactId></span> |
| <span class="nt"><version></span>??What value should be used here??<span class="nt"></version></span> |
| </pre></div> |
| |
| |
| <h5 id="using-the-maven-osgi-plugin">Using the maven-osgi-plugin<a class="headerlink" href="#using-the-maven-osgi-plugin" title="Permanent link">¶</a></h5> |
| <p>To use the maven-osgi-plugin, you first need to add the plugin and some appropriate plugin configuration to your project's POM. Below is an example of a simple OSGi bundle POM for Maven 2:</p> |
| <div class="codehilite"><pre><span class="nt"><project></span> |
| <span class="nt"><modelVersion></span>4.0.0<span class="nt"></modelVersion></span> |
| <span class="nt"><groupId></span>my-osgi-bundles<span class="nt"></groupId></span> |
| <span class="nt"><artifactId></span>simple<span class="nt"></artifactId></span> |
| <span class="nt"><packaging></span>osgi-bundle<span class="nt"></packaging></span> |
| <span class="nt"><version></span>1.0<span class="nt"></version></span> |
| <span class="nt"><name></span>Simple Bundle<span class="nt"></name></span> |
| <span class="nt"><build></span> |
| <span class="nt"><plugins></span> |
| <span class="nt"><plugin></span> |
| <span class="nt"><groupId></span>org.apache.felix.plugins<span class="nt"></groupId></span> |
| <span class="nt"><artifactId></span>maven-osgi-plugin<span class="nt"></artifactId></span> |
| <span class="nt"><extensions></span>true<span class="nt"></extensions></span> |
| <span class="nt"><version></span>0.3.0<span class="nt"></version></span> |
| <span class="nt"><configuration></span> |
| <span class="nt"><osgiManifest></span> |
| <span class="nt"><bundleActivator></span>com.my.company.Activator<span class="nt"></bundleActivator></span> |
| <span class="nt"><bundleName></span>Simple Bundle<span class="nt"></bundleName></span> |
| <span class="nt"><bundleDescription></span>simple bundle<span class="nt"></bundleDescription></span> |
| <span class="nt"><bundleVendor></span>Me<span class="nt"></bundleVendor></span> |
| <span class="nt"></osgiManifest></span> |
| <span class="nt"></configuration></span> |
| <span class="nt"></plugin></span> |
| <span class="nt"></plugins></span> |
| <span class="nt"></build></span> |
| <span class="nt"><dependencies></span> |
| <span class="nt"><dependency></span> |
| <span class="nt"><groupId></span>org.apache.felix<span class="nt"></groupId></span> |
| <span class="nt"><artifactId></span>org.osgi.core<span class="nt"></artifactId></span> |
| <span class="nt"><version></span>??What value should be used here??<span class="nt"></version></span> |
| <span class="nt"><scope></span>provided<span class="nt"></scope></span> |
| <span class="nt"></dependency></span> |
| <span class="nt"></dependencies></span> |
| <span class="nt"></project></span> |
| </pre></div> |
| |
| |
| <p>Three things to note: (1) the <packaging> specifier, (2) the plugin and configuration specification, and (3) the <scope> specifier on the dependency. The org.osgi-3.0.jar is a compile-time dependency, but the scope specifier indicates that our OSGi container will provide the dependency at runtime so there is no need to embed the dependent jar into the bundle archive.</p> |
| <h5 id="issuing-maven-2-lifecycle-commands">Issuing Maven 2 Lifecycle Commands<a class="headerlink" href="#issuing-maven-2-lifecycle-commands" title="Permanent link">¶</a></h5> |
| <p>'mvn package' will compile the project code and generate a bundle jar archive of the project (in this case named simple-1.0.jar). If this jar is in turn a dependency of another project, it can still be included in another Maven 2 POM as usual.</p> |
| <div class="codehilite"><pre>$ <span class="n">mvn</span> <span class="n">package</span> |
| </pre></div> |
| |
| |
| <p>'mvn install' will compile the project code, generate a bundle jar archive, and install the jar in your local Maven 2 repo.</p> |
| <div class="codehilite"><pre>$ <span class="n">mvn</span> <span class="n">install</span> |
| </pre></div> |
| |
| |
| <p>'mvn deploy' will compile the project code, generate a bundle jar archive, install the jar in your local Maven 2 repo, and deploy the jar to any remote Maven 2 repos you have configured.</p> |
| <div class="codehilite"><pre>$ <span class="n">mvn</span> <span class="n">deploy</span> |
| </pre></div> |
| <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;"> |
| Rev. 1700393 by cziegeler on Tue, 1 Sep 2015 06:04:06 +0000 |
| </div> |
| <div class="trademarkFooter"> |
| Apache Felix, Felix, Apache, the Apache feather logo, and the Apache Felix project |
| logo are trademarks of The Apache Software Foundation. All other marks mentioned |
| may be trademarks or registered trademarks of their respective owners. |
| </div> |
| </div> |
| </body> |
| </html> |
