CommonsOsgi

Commons OSGi

The [http://felix.apache.org/ Apache Felix] project have [http://commons.markmail.org/message/36xoo2bo5aabvy5c requested] that Commons components include [http://www.osgi.org/ OSGi] meta data in their jars so that they are 'ready-to-use' in an OSGi environment. This involves OSGi entries in the jar's manifest file.

The Felix project has developed a [http://felix.apache.org/site/maven-bundle-plugin-bnd.html Maven Plugin] which makes this easier (version 1.2.0 released Jan '08). Before that was released a number of components (Pool 1.4, FileUpload 1.2.1 and IO 1.4) were manually configured with OSGi manifest entries.

The purpose of this page is to record progress in Commons of OSGi-enabled releases and any notes on specific issues with configuration of the OSGi manifest entries.

Proper

Commons Logging

The things that commons-logging does with classloaders in order to try and work in various servlet engine configurations are not compatible with the classloaders that OSGi environments set up. Therefore adding OSGi attributes to commons-logging is not useful, as commons-logging is not usable in an OSGi environment. See [http://commons.markmail.org/message/kdnjlbokvuiigcew this thread] and
[http://wiki.ops4j.org/dokuwiki/doku.php?id=pax:logging Pax-logging]

Configuring OSGi with Maven2

There are two ways to do this:

• Bundle Plugin - using the Apache Felix project's bundle Plugin
• Manually - configuring the maven-jar-plugin with OSGi manifest entries
  

Felix's Maven2 Bundle Plugin

To configure the plugin, specify a

 <packaging>bundle</packaging> 

element in the pom and configure the plugin in the

 <build> 

section, for example for Commons Lang

      <plugin>
        <groupId>org.apache.felix</groupId>
        <artifactId>maven-bundle-plugin</artifactId>
        <version>1.2.0</version>
        <extensions>true</extensions>
        <configuration>
          <excludeDependencies>true</excludeDependencies>
          <instructions>
            <Bundle-SymbolicName>org.apache.commons.lang</Bundle-SymbolicName>
            <Export-Package>*;version=${pom.version}</Export-Package>
          </instructions>
        </configuration>
      </plugin>

Notes:

• <extensions>true</extensions> needs to be specified otherwise the

   <packaging>bundle</packaging> 

  is not recognized and causes an error with the message Cannot find lifecycle mapping for packaging 'bundle*_
• <excludeDependencies>true</excludeDependencies> prevents all the component's dependencies classes being included in the jar
• Other_* Manifest_* entries are inherited from the commons-parent pom
• Depending on the nature/structure of the project, some packages might contain private classes that are not meant to be used by client code. In these cases, <Export-Package> should list all public packages while <Private-Package> should contain the private packages.

Configuring via the jar plugin

      <plugin>
        <artifactId>maven-jar-plugin</artifactId>
        <configuration>
          <archive>
            <manifestEntries>
              <Bundle-SymbolicName>org.apache.commons.lang</Bundle-SymbolicName>
              <Bundle-License>http://www.apache.org/licenses/LICENSE-2.0.txt</Bundle-License>
              <Bundle-ManifestVersion>2</Bundle-ManifestVersion>
              <Bundle-Name>Apache Commons Lang Bundle</Bundle-Name>
              <Bundle-Vendor>${project.organization.name}</Bundle-Vendor>
              <Bundle-Version>${project.version}</Bundle-Version>
              <Export-Package>
org.apache.commons.lang;version=${project.version},
org.apache.commons.lang.builder;version=${project.version},
org.apache.commons.lang.enum;version=${project.version},
org.apache.commons.lang.enums;version=${project.version},
org.apache.commons.lang.exception;version=${project.version},
org.apache.commons.lang.math;version=${project.version},
org.apache.commons.lang.mutable;version=${project.version},
org.apache.commons.lang.text;version=${project.version},
org.apache.commons.lang.time;version=${project.version}
              </Export-Package>
              <Import-Package>
org.apache.commons.lang;version=${project.version},
org.apache.commons.lang.builder;version=${project.version},
org.apache.commons.lang.enum;version=${project.version},
org.apache.commons.lang.enums;version=${project.version},
org.apache.commons.lang.exception;version=${project.version},
org.apache.commons.lang.math;version=${project.version},
org.apache.commons.lang.mutable;version=${project.version},
org.apache.commons.lang.text;version=${project.version},
org.apache.commons.lang.time;version=${project.version}
              </Import-Package>
            </manifestEntries>
          </archive>
        </configuration>
      </plugin>

*Notes:_'

• As you can see by the example, you should always import everything you export.
• The note about private packages from above applies here of course as well.