| <!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 Bundle Plugin Frequently Asked Questions</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> » <a href="/documentation/faqs.html">Frequently Asked Questions</a> |
| </div> |
| |
| <h1>Apache Felix Bundle Plugin Frequently Asked Questions</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="toc"> |
| <ul> |
| <li><a href="#when-i-embed-a-dependency-why-do-i-see-duplicated-content">When I embed a dependency why do I see duplicated content?</a></li> |
| <li><a href="#why-do-i-see-more-classes-in-my-bundle-after-upgrading-to-maven-bundle-plugin-200">Why do I see more classes in my bundle after upgrading to maven-bundle-plugin 2.0.0?</a></li> |
| <li><a href="#why-do-i-get-an-exception-unsupported-majorminor-version-490-when-i-build-with-a-14-or-earlier-jdk">Why do I get an exception (Unsupported major.minor version 49.0) when I build with a 1.4 or earlier JDK?</a></li> |
| <li><a href="#when-i-build-a-bundle-some-classes-are-built-in-targetclasses-but-theyre-not-included-in-the-final-jar">When I build a bundle, some classes are built in "target/classes" but they're not included in the final jar.</a></li> |
| <li><a href="#how-do-i-remove-the-generated-maven-information-from-the-resulting-bundle-jar-file">How do I remove the generated Maven information from the resulting bundle JAR file?</a></li> |
| <li><a href="#why-do-some-generated-resources-such-as-declarative-services-xml-files-appear-in-the-final-jar-but-others-dont">Why do some generated resources (such as Declarative Services XML files) appear in the final jar, but others don't?</a></li> |
| <li><a href="#use-scr-metadata-generated-by-bnd-in-unit-tests">Use SCR metadata generated by BND in Unit Tests</a></li> |
| </ul> |
| </div> |
| <h2 id="when-i-embed-a-dependency-why-do-i-see-duplicated-content">When I embed a dependency why do I see duplicated content?<a class="headerlink" href="#when-i-embed-a-dependency-why-do-i-see-duplicated-content" title="Permanent link">¶</a></h2> |
| <p>Having two copies of classes, both unpacked and embedded as jars, is a sign that your Embed-Dependency and Export-Package instructions are overlapping. Export-Package tells BND to pull in classes found in the named packages from the build classpath and add them to the bundle, Embed-Dependency tells BND to embed (or inline if enabled) whole artifacts in the bundle.</p> |
| <p>so say I have:</p> |
| <div class="codehilite"><pre><span class="n">Export</span><span class="o">-</span><span class="n">Package</span><span class="p">:</span> <span class="n">org</span><span class="p">.</span><span class="n">objectweb</span><span class="p">.</span><span class="n">asm</span><span class="o">.*</span> |
| </pre></div> |
| |
| |
| <p>and I have the asm artifact as a compile scope dependency, then I would see the org.objectweb.asm classes unpacked in the bundle, ie. pulled in by BND.</p> |
| <p>say I now decide to embed asm as a jar, for example with:</p> |
| <div class="codehilite"><pre><span class="n">Embed</span><span class="o">-</span><span class="n">Dependency</span><span class="p">:</span> <span class="o">*</span><span class="p">;</span><span class="n">scope</span><span class="p">=</span><span class="n">compile</span><span class="o">|</span><span class="n">runtime</span> |
| </pre></div> |
| |
| |
| <p>I would now see the asm artifact embedded inside bundle - but I would also see the unpacked classes from before, because I'm still asking BND to pull them in (you will probably also see split package warnings during the build).</p> |
| <p>ok - so how do I embed asm as a jar, but mark its packages as exported without pulling in the unpacked classes... well, there is another export instruction added for exactly this reason:</p> |
| <div class="codehilite"><pre><span class="o">-</span><span class="n">exportcontents</span><span class="p">:</span> <span class="n">org</span><span class="p">.</span><span class="n">objectweb</span><span class="p">.</span><span class="n">asm</span><span class="o">.*</span> |
| </pre></div> |
| |
| |
| <p>(this is <_exportcontents> in the POM because a tag can't start with '-')</p> |
| <p>this instruction is merged with Export-Package, after BND has decided on the content of the bundle - that is, it works just like Export-Package except that it won't alter the content of the bundle.</p> |
| <p>So by removing org.objectweb.asm.* from Export-Package and using the -exportcontents instruction instead along with Embed-Dependency, I can now embed the asm artifact in my bundle and export its packages:</p> |
| <div class="codehilite"><pre><span class="n">Embed</span><span class="o">-</span><span class="n">Dependency</span><span class="p">:</span> <span class="o">*</span><span class="p">;</span><span class="n">scope</span><span class="p">=</span><span class="n">compile</span><span class="o">|</span><span class="n">runtime</span> |
| <span class="o">-</span><span class="n">exportcontents</span><span class="p">:</span> <span class="n">org</span><span class="p">.</span><span class="n">objectweb</span><span class="p">.</span><span class="n">asm</span><span class="o">.*</span> |
| </pre></div> |
| |
| |
| <h2 id="why-do-i-see-more-classes-in-my-bundle-after-upgrading-to-maven-bundle-plugin-200">Why do I see more classes in my bundle after upgrading to maven-bundle-plugin 2.0.0?<a class="headerlink" href="#why-do-i-see-more-classes-in-my-bundle-after-upgrading-to-maven-bundle-plugin-200" title="Permanent link">¶</a></h2> |
| <p>Before 2.0.0 the maven-bundle-plugin only passed local classes and compile scope dependencies to bnd. This was because the main BundlePlugin mojo used "@requiresDependencyResolution runtime" which asks Maven to only resolve dependencies of compile or runtime scope (the maven-bundle-plugin also explicitly filtered runtime scope dependencies from the classpath passed to bnd). Because bnd only had a fraction of the original classpath used to compile the bundle classes it meant that imported packages weren't augmented with additional information (such as versions and attributes) available from the complete classpath.</p> |
| <p>In 2.0.0 a conscious decision was made to pass the complete classpath to bnd so it would have the complete set of information used during compilation. To do this the @requiresDependencyResolution setting was changed to "test" so all dependencies will now be resolved. Furthermore only test scope artifacts are now filtered from the final classpath passed to bnd.</p> |
| <p>For most users passing more of the original compilation classpath to bnd simply means you get more accurate and consistent results. However, if you happened to rely on the old behaviour (perhaps by setting Private-Package: * to pull in all local and compile scope classes) then you will see more classes added to your bundle as the wildcard matches against additional content in the classpath.</p> |
| <p>There are two solutions when this happens:</p> |
| <ul> |
| <li>Change your Private-Package / Export-Package instructions to more accurately describe what you want in your bundle</li> |
| <li> |
| <p>Add the following setting to remove provided and runtime scope dependencies from the classpath passed to bnd:</p> |
| <p><plugin> |
| <groupId>org.apache.felix</groupId> |
| <artifactId>maven-bundle-plugin</artifactId> |
| <configuration> |
| <excludeDependencies>*;scope=provided|runtime</excludeDependencies> |
| </configuration> |
| </plugin></p> |
| </li> |
| </ul> |
| <p>This second option effectively switches the maven-bundle-plugin back to the old 1.X behaviour.</p> |
| <p>Please also note that since 2.0.0 the maven-bundle-plugin also sets default Export-Package and Private-Package instructions based on your local source files, so you might well find that simply removing any Private-Package and/or Export-Package instructions from your pom.xml will actually produce the correct result.</p> |
| <h2 id="why-do-i-get-an-exception-unsupported-majorminor-version-490-when-i-build-with-a-14-or-earlier-jdk">Why do I get an exception (Unsupported major.minor version 49.0) when I build with a 1.4 or earlier JDK?<a class="headerlink" href="#why-do-i-get-an-exception-unsupported-majorminor-version-490-when-i-build-with-a-14-or-earlier-jdk" title="Permanent link">¶</a></h2> |
| <p>The latest maven-bundle-plugin (2.0.0) uses a new release of bnd which requires Java5. This means you now have to build your bundle projects using a Java5 (or later) JDK. Note that you can still compile classes for earlier releases of the JVM by setting the appropriate source and target levels in your pom.xml:</p> |
| <div class="codehilite"><pre><span class="nt"><plugin></span> |
| <span class="nt"><artifactId></span>maven-compiler-plugin<span class="nt"></artifactId></span> |
| <span class="nt"><configuration></span> |
| <span class="nt"><source></span>1.4<span class="nt"></source></span> |
| <span class="nt"><target></span>1.4<span class="nt"></target></span> |
| <span class="nt"></configuration></span> |
| <span class="nt"></plugin></span> |
| </pre></div> |
| |
| |
| <h2 id="when-i-build-a-bundle-some-classes-are-built-in-targetclasses-but-theyre-not-included-in-the-final-jar">When I build a bundle, some classes are built in "target/classes" but they're not included in the final jar.<a class="headerlink" href="#when-i-build-a-bundle-some-classes-are-built-in-targetclasses-but-theyre-not-included-in-the-final-jar" title="Permanent link">¶</a></h2> |
| <p>The only classes that will appear in the bundle are the ones you ask it to include using Export-Package, Private-Package, Include-Resource, and Embed-Dependency - so just because a file exists under target/classes does NOT mean it will end up in the bundle. This is because this is the way the underlying <a href="http://bnd.bndtools.org/">BND</a> tool works (it is primarily pull-based).</p> |
| <p>Now the bundleplugin will look at your Maven project and add appropriate BND instructions to pull in resource files - and version 2.0.0 will also look at your source directory to set reasonable defaults for Export-Package and Private-Package (unless you set these yourself). So when using bundleplugin 2.0.0 I'd use the default Private-Package and Export-Package to begin with - I would then move towards using an explicit list of packages in Export-Package to add versioning, directives, etc.</p> |
| <p>The only time I would set Private-Package would be to have more control over what ends up in the bundle - either to remove certain packages or perhaps pull in additional packages not found by the source scanner. Also note that both Export-Package and Private-Package accept wildcards such as "org.example.*" which can reduce the number of entries in the list, but you should be careful not to set either the export or private instruction to "*" as this would pull in the entire classpath... dependencies and all!</p> |
| <h2 id="how-do-i-remove-the-generated-maven-information-from-the-resulting-bundle-jar-file">How do I remove the generated Maven information from the resulting bundle JAR file?<a class="headerlink" href="#how-do-i-remove-the-generated-maven-information-from-the-resulting-bundle-jar-file" title="Permanent link">¶</a></h2> |
| <p>Use the following archive setting:</p> |
| <div class="codehilite"><pre><span class="nt"><configuration></span> |
| <span class="nt"><archive></span> |
| <span class="nt"><addMavenDescriptor></span>false<span class="nt"></addMavenDescriptor></span> |
| <span class="nt"></archive></span> |
| <span class="nt"></configuration></span> |
| </pre></div> |
| |
| |
| <p>Put this in either the JAR or bundle plugin configuration.</p> |
| <h2 id="why-do-some-generated-resources-such-as-declarative-services-xml-files-appear-in-the-final-jar-but-others-dont">Why do some generated resources (such as Declarative Services XML files) appear in the final jar, but others don't?<a class="headerlink" href="#why-do-some-generated-resources-such-as-declarative-services-xml-files-appear-in-the-final-jar-but-others-dont" title="Permanent link">¶</a></h2> |
| <p>When you use the Service-Component instruction to specify Declarative Services the BND tool scans the project classpath for components and automatically adds its generated XML to the final bundle, therefore Include-Resource is not necessary. But if you generate files under OSGI-INF using another mechanism then they won't end up in the bundle unless you add that directory using Include-Resource (this goes back to the core design decision that BND pulls classes and resources into the bundle, rather than just taking everything under target/classes). We try to provide reasonable defaults on the Maven side in the bundleplugin so local classes and resources will end up in the bundle without additional configuration, but we do this by looking at the effective pom and src/ folder rather than the generated target/classes content.</p> |
| <h2 id="use-scr-metadata-generated-by-bnd-in-unit-tests">Use SCR metadata generated by BND in Unit Tests<a class="headerlink" href="#use-scr-metadata-generated-by-bnd-in-unit-tests" title="Permanent link">¶</a></h2> |
| <p>BND and the maven-bundle-plugin support the generation of SCR metadata for OSGi Declarative Service components annotated with the OSGi annotations from the Java package <code>org.osgi.service.component.annotations</code>.</p> |
| <p>To enable this you have to set two special instructions in your maven-bundle-plugin configuration:</p> |
| <div class="codehilite"><pre><span class="nt"><configuration></span> |
| <span class="nt"><instructions></span> |
| <span class="c"><!-- Enable processing of OSGI DS component annotations --></span> |
| <span class="nt"><_dsannotations></span>*<span class="nt"></_dsannotations></span> |
| <span class="c"><!-- Enable processing of OSGI metatype annotations --></span> |
| <span class="nt"><_metatypeannotations></span>*<span class="nt"></_metatypeannotations></span> |
| <span class="nt"></instructions></span> |
| <span class="nt"></configuration></span> |
| </pre></div> |
| |
| |
| <p>This generates the SCR metadata files at <code>/OSGI-INF</code> and <code>/OSGI-INF/metatype</code> when building the JAR file.</p> |
| <p>If you want to run unit test in the same maven projects that need these SCR metadata files when running the tests (e.g. when using <a href="http://sling.apache.org/documentation/development/osgi-mock.html">OSGi Mocks</a>) you need some special configurations to ensure the SCR metadata is also generated in the filesystem in the maven target folder, and is already available when the unit tests are executed and not only in the package phase:</p> |
| <div class="codehilite"><pre><span class="nt"><plugin></span> |
| <span class="nt"><groupId></span>org.apache.felix<span class="nt"></groupId></span> |
| <span class="nt"><artifactId></span>maven-bundle-plugin<span class="nt"></artifactId></span> |
| <span class="nt"><extensions></span>true<span class="nt"></extensions></span> |
| <span class="nt"><executions></span> |
| <span class="c"><!-- Configure extra execution of 'manifest' in process-classes phase to make sure SCR metadata is generated before unit test runs --></span> |
| <span class="nt"><execution></span> |
| <span class="nt"><id></span>scr-metadata<span class="nt"></id></span> |
| <span class="nt"><goals></span> |
| <span class="nt"><goal></span>manifest<span class="nt"></goal></span> |
| <span class="nt"></goals></span> |
| <span class="nt"><configuration></span> |
| <span class="nt"><supportIncrementalBuild></span>true<span class="nt"></supportIncrementalBuild></span> |
| <span class="nt"></configuration></span> |
| <span class="nt"></execution></span> |
| <span class="nt"></executions></span> |
| <span class="nt"><configuration></span> |
| <span class="nt"><exportScr></span>true<span class="nt"></exportScr></span> |
| <span class="nt"><instructions></span> |
| <span class="c"><!-- Enable processing of OSGI DS component annotations --></span> |
| <span class="nt"><_dsannotations></span>*<span class="nt"></_dsannotations></span> |
| <span class="c"><!-- Enable processing of OSGI metatype annotations --></span> |
| <span class="nt"><_metatypeannotations></span>*<span class="nt"></_metatypeannotations></span> |
| <span class="nt"></instructions></span> |
| <span class="nt"></configuration></span> |
| <span class="nt"></plugin></span> |
| </pre></div> |
| |
| |
| <p>The flag <code>supportIncrementalBuild</code> is only necessary when you are using Eclipse and m2e, it supports generating the appropriate metadata during incremental builds. When you also want to support the old-style Felix SCR annotations from Java package <code>org.apache.felix.scr.annotations</code> you can add this BND plugin:</p> |
| <div class="codehilite"><pre><span class="nt"><plugin></span> |
| <span class="nt"><groupId></span>org.apache.felix<span class="nt"></groupId></span> |
| <span class="nt"><artifactId></span>maven-bundle-plugin<span class="nt"></artifactId></span> |
| <span class="nt"><extensions></span>true<span class="nt"></extensions></span> |
| <span class="nt"><configuration></span> |
| <span class="nt"><instructions></span> |
| <span class="c"><!-- Support parsing of maven-scr-plugin annotations through the felix.scr.bnd plugin --></span> |
| <span class="nt"><_plugin></span>org.apache.felix.scrplugin.bnd.SCRDescriptorBndPlugin;destdir=<span class="cp">${</span><span class="n">project</span><span class="o">.</span><span class="n">build</span><span class="o">.</span><span class="n">outputDirectory</span><span class="cp">}</span><span class="nt"></_plugin></span> |
| <span class="nt"></instructions></span> |
| <span class="nt"></configuration></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.apache.felix.scr.bnd<span class="nt"></artifactId></span> |
| <span class="nt"><version></span>1.9.4<span class="nt"></version></span> |
| <span class="nt"></dependency></span> |
| <span class="nt"></dependencies></span> |
| <span class="nt"></plugin></span> |
| </pre></div> |
| <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;"> |
| Rev. 1860681 by sseifert on Wed, 5 Jun 2019 19:40:16 +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> |
