Bundlor User Guide

With the increasing focus on OSGi in Enterprise Java, there has been increasing focus on creating OSGi bundles for deployment. When a development team is creating their own bundles, it is easy for them to focus on identifying Imports and Exports and ensuring that their manifests are correct. When it comes time to use third-party enterprise libraries however, things start to break down.

Many of these libraries are not packaged as OSGi bundles. In fact, many of them have internal architectures and designs that do not lend themselves to controls that OSGi provides. In this case, a user must retrofit OSGi directives to the library before use.

This is where SpringSource Bundlor comes in. It can be very hard for a developer to know exactly what dependencies are needed by a library using simple inspection. Bundlor is a tool that automates the detection of dependencies and the creation of OSGi manifest directives for JARs after their creation. Bundlor takes as input a JAR and a template consisting of a superset of the standard OSGi manifest headers. Bundlor analyses the source code and support files contained in the JAR, applies the template to the results, and generates a manifest.

The use of Bundlor can take different forms, from tasks for Apache ANT and plugins for Apache Maven, to simple command line execution for integration into any existing build system.

Before you start using Bundlor, please take a moment to look at the SpringSource Enterprise Bundle Repository; you may find that what you are looking for has already been updated. If you convert a library for your own use and think that it might be useful to the community at large, please submit your bundle information to the Enterprise Bundle Repository for inclusion.

SpringSource Bundlor is distributed as a ZIP file.

SpringSource Bundlor can be obtained from an Ivy repository

SpringSource Bundlor can be obtained from a Maven repository

The command line client allows Bundlor to be run from the command line of any platform

% ./bundlor.sh \
-i ./org.springframework.integration.jar \
-m ./template.mf \
-o ./target/org.springframework.integration.jar

Transformed bundle written to ./target/org.springframework.integration.jar
%

The ANT task allows Bundlor to be run from inside any ANT based build system

The Maven plugin allows Bundlor to be run from inside any Maven project.

The command line client allows Bundlor to be run from the command line of any platform

$BUNDLOR_HOME/bin/bundlor.sh [options] 

%BUNDLOR_HOME%\bin\bundlor.bat [options] 

% ./bundlor.sh \
-i ./org.springframework.integration.jar \
-m ./template.mf \
-o ./target/org.springframework.integration.jar \
-Dname="Spring Integration"

Transformed bundle written to ./target/org.springframework.integration.jar
%

% ./bundlor.sh \
-i ./org.springframework.integration.jar \
-m ./template.mf \
-o ./target/org.springframework.integration.jar

Transformed bundle written to ./target/org.springframework.integration.jar
%

% ./bundlor.sh \
-i ./org.springframework.integration.jar \
-m ./template.mf \
-o ./target/org.springframework.integration.jar \
-Dname="Spring Integration"

Transformed bundle written to ./target/org.springframework.integration.jar
%

The ANT task allows you to run Bundlor from inside any ANT based build system

<bundlor:bundlor>
  <manifestTemplate>
Bundle-ManifestVersion: 2
Bundle-Name: Bundlor Core
Bundle-Vendor: SpringSource Inc.
Bundle-SymbolicName: com.springsource.bundlor
Bundle-Version: 0
  </manifestTemplate>
</bundlor:bundlor>

<bundlor:bundlor>
  <osgiProfile>
org.osgi.framework.system.packages = \
  javax.accessibility,\
  javax.activation,\
  javax.activation;version="1.1.0",\
  javax.activity,\
  javax.annotation,\
...
  
org.osgi.framework.bootdelegation = \
  com_cenqua_clover,\
  com.cenqua.*,\
  com.yourkit.*,\
...
  </osgiProfile>
</bundlor:bundlor>

<bundlor:bundlor>
  <property name="bundle.name" value="Kernel test bundle"/>
  <property name="bundle.version" value="1.0.2.BUILD-${timestamp}"/>
  <propertyset>
    <propertyref builtin="all"/>
  </propertyset>
</bundlor:bundlor>

<bundlor:bundlor
   inputPath="${basedir}/target/classes"
   outputPath="${basedir}/target/classes"
   bundleVersion="1.0.2.BUILD-${timestamp}"
   manifestTemplatePath="${basedir}/template.mf"/>

<bundlor:bundlor
    inputPath="${basedir}/target/classes"
    outputPath="${basedir}/target/target/classes"
    bundleVersion="1.0.2.BUILD-${timestamp}"
    manifestTemplatePath="${basedir}/template.mf">
  <property name="bundle.name" value="Kernel test bundle"/>
  <property name="bundle.version" value="1.0.2.BUILD-${timestamp}"/>
</bundlor:bundlor>

The Maven plugin allows Bundlor to be run from inside any Maven project.

<execution>
  <id>bundlor</id>
  <goals>
    <goal>bundlor</goal>
  </goals>
  <configuration>
    <manifestTemplate>
Bundle-ManifestVersion: 2
Bundle-Name: Bundlor Core
Bundle-Vendor: SpringSource Inc.
Bundle-SymbolicName: com.springsource.bundlor
Bundle-Version: 0
    </manifestTemplate>
  </configuration>
</execution>

<execution>
  <id>bundlor</id>
  <goals>
    <goal>bundlor</goal>
  </goals>
  <configuration>
    <osgiProfile>
org.osgi.framework.system.packages = \
  javax.accessibility,\
  javax.activation,\
  javax.activation;version="1.1.0",\
  javax.activity,\
  javax.annotation,\
...
  
org.osgi.framework.bootdelegation = \
  com_cenqua_clover,\
  com.cenqua.*,\
  com.yourkit.*,\
...
    </osgiProfile>
  </configuration>
</execution>

<project>
  ...
  <properties>
    <bundle.name>${project.name}</bundle.name>
    <bundle.version>2.0.0.RELEASE</bundle.version>
  </properties>
  ...
</project>

<project>
...
  <build>
    <plugins>
      <plugin>
        <groupId>com.springsource.bundlor</groupId>
        <artifactId>com.springsource.bundlor.maven</artifactId>
        <executions>
          <execution>
            <id>bundlor</id>
            <goals>
              <goal>bundlor</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
...
</project>

<project>
...
  <properties>
    <bundle.name>${project.name}</bundle.name>
    <bundle.version>2.0.0.RELEASE</bundle.version>
  </properties>
...
  <build>
    <plugins>
      <plugin>
        <groupId>com.springsource.bundlor</groupId>
        <artifactId>com.springsource.bundlor.maven</artifactId>
        <executions>
          <execution>
            <id>bundlor</id>
            <goals>
              <goal>bundlor</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
...
</project>

A manifest template is a file that Bundlor uses during the generation of OSGi-compliant manifest entries in a JAR's manifest. The format of the manifest template is the same as that of a standard Java manifest file, i.e. a series of 'key: value' pairs.

From this template, Bundlor recognizes a specific set of directives and uses them to generate the OSGi-compliant manifest entries. Bundlor will also add any other headers that are specified in the template to the generated manifest. This is typically used to specify things like the bundle's symbolic name and version.

You can also specify property placeholders, or variables, in your manifest template that Bundlor substitutes with real values at runtime. With this feature, your manifest templates become more dynamic and useful across a variety of your projects. A particularly useful use case for this feature is to tell Bundlor to automatically expand versions of imports based on a pattern of your choosing. See Section 5.3, “Specifying property placeholders” for details.

The following table lists the headers you can add to the manifest template, in addition to the standard manifest headers.

A wilcard '*' at the end of the package name is supported to match multiple packages. For example, the header Import-Template: com.foo;version=[1.0,2.0);resolution:=optional,com.bar.*;version="[1.5,1.6)" will cause any import generated for the com.foo package to be versioned at 1.0 (inclusive) to 2.0 (exclusive) and to be considered optional, and for any import of com.bar or its sub-packages to be versioned at 1.5 (inclusive) to 1.6 (exclusive).

To specify a property placeholder in your manifest template, use the form ${property.name}, where property.name refers to the name of the property placeholder. The method in which the manifest template actually gets the value of the property placeholder at runtime depends on the Bundlor front end you use (command line, ANT, or Maven); the details are described later.

The following example shows how to use a property placeholder for the Bundle-Name manifest header rather than a literal.

Bundle-Name: ${bundle.name}

When you use the Import-Template template header to augment package imports that Bundlor generates in the manifest file, you use the version directive to specify a version or version range of the imported package.

Import-Template: 
 com.springsource.kernel*;version="[1.2.0, 2.0.0)"
 org.apache.commons.logging;version="[1.1.1, 2.0.0)"

The preceding example specifies that Bundlor should version the com.springsource.* packages at [2.5.4.A, 3.0.0) and the org.apache.commons.logging package at [1.1.1, 2.0.0) in the generated manifest file. This works just fine for many use cases, but sometimes the use of literal versions in this manner can be restrictive.

In order to make the manifest template more dynamic and useful, you can specify that Bundlor automatically expand the package version into a version range using an expansion pattern of your choosing. The pattern uses as a base a property placeholder that you define (as described in Section 5.3, “Specifying property placeholders”) and set to a valid OSGI version number. Then, based on the expansion pattern you specify, Bundlor generates a version range using the 4 parts of an OSGI version: major, minor, micro, and qualifier.

The way to tell Bundlor to automatically expand a package import version is to specify the property placeholder to the right of the version directive of the package in the Import-Template header, and then within the property placeholder, specify the pattern for both sides of the version range. The following manifest template snippet shows how to use this feature; the example is described in detail after the table.

Import-Template: 
 com.springsource.kernel.*;version="${com.springsource.kernel:[=.=.=.=, +1.0.0)}",
 org.apache.commons.logging.*;version="${org.apache.commons.logging:[=.=.=.=, =.=.+1)}"

The following table lists the symbols you can use in the expansion pattern.

Based on the descriptions of the symbols, we can now understand how the examples above work. First assume that you have set the property ${com.springsource.kernel} to the value 1.2.0. Based on the expansion pattern, Bundlor sets the version range of the imported com.springsource.kernel.* packages to [1.2.0, 2.0.0). The pattern in this case first specifies that the beginning of the version range stay exactly the same as the value of the property. The pattern then specifies that at the end of the version range, the major part of the version should be one integer larger than what the property is originally set to (1); the pattern then specifies that the minor and micro segments of the version both be set to 0.

Similarly, assume that you set the ${org.apache.commons.logging} property to 1.4.0. Bundlor generates a version range of [1.4.0, 1.4.1). Again, the beginning of the range is exactly the same as the property value. The pattern specifies that, in the end of the range, only the micro segment of the version increase by one; the major and minor segments stay the same.

Version-Patterns:
 apache;pattern="[=.=.=.=, +1.0.0)",
 hibernate;pattern="[=.=.=.=, =.=.+1)"

Import-Template:
 org.apache.commons.codec.*;version="${org.apache.commons.codec:apache}",
 org.apache.commons.logging.*;version="${org.apache.commons.logging:apache}",
 org.hibernate.*;version="${org.hibernate:hibernate}"
 org.myorg.*;version="${org.myorg:(=.=.=.=, =.+1.0.=]}"

The following shows a simple example of a Bundlor manifest template file, with a description after the sample.

Bundle-ManifestVersion: 2
Bundle-SymbolicName: org.springframework.binding
Bundle-Name: ${bundle.name}
Bundle-Vendor: SpringSource
Import-Package: 
 ognl;version="[2.6.9, 3.0.0)";resolution:=optional,
 org.jboss.el;version="[2.0.0, 3.0.0)";resolution:=optional
Import-Template: 
 org.springframework.*;version="[2.5.4.A, 3.0.0)",
 org.apache.commons.logging;version="[1.1.1, 2.0.0)",
 javax.el;version="[2.1.0, 3.0.0)";resolution:=optional,
 ognl;version="[2.6.9, 3.0.0)";resolution:=optional,
 org.jboss.el;version="[2.0.0, 3.0.0)";resolution:=optional
		

The headers marked in bold are required in all manifest templates unless the jar already contains a manifest with those headers.

An OSGi profile defines the packages that a particular OSGI runtime (such as dm Server) exports from the system bundle and the packages that it delegates to the boot class loader. An OSGI profile isn't an actual file; rather, it is two properties that are well known to an OSGi runtime. However, when you pass these properties to Bundlor, you pass them as a file, as described in the next section. The properties that make up an OSGI profile are as follows.

If you are using dm Server as your OSGI runtime, see the file DM_SERVER_HOME/lib/java6-server.profile for its OSGI profile, where DM_SERVER_HOME refers to the main installation directory of dm Server. If you are using another OSGI runtime, such as Equinox, then see their documentation for their OSGI profile.

For additional information about the syntax of the values of these properties, see sections 3.8.3 and 3.8.5 of the OSGI specification.

The first step in using OSGI profiles with Bundlor is to create a file that contains a textual representation of the two properties that make up an OSGI profile: org.osgi.framework.system.packages and org.osgi.framework.bootdelegation. What you include in this file is up to you, but typically you start with the OSGI profile of the OSGI runtime you are using, and then customize it to fit your environment.

If you are using dm Server as your OSGI runtime, you can start by copying the section of the file $DM_SERVER_HOME/lib/java6-server.profile that refers to the two properties and pasting it into your text file. If you are using another runtime, consult their documentation.

The following snippet shows a partial OSGI profile for dm Server; for clarity only a few packages are shown. The example shows the format in which you should create your own OSGI profile file.

org.osgi.framework.system.packages = \
 javax.accessibility,\
 javax.activation,\
 javax.activation;version="1.1.0",\
 javax.activity,\
 javax.annotation,\
...

org.osgi.framework.bootdelegation = \
 com_cenqua_clover,\
 com.cenqua.*,\
 com.yourkit.*,\
...

Once you've created your OSGI profile file, the method of passing it to Bundlor depends on the front end you are using to generate a manifest. For detailed information about using the various front ends, see Chapter 4, Usage.

Bundlor scans any Java class it can find in the artifact created by the underlying build system. This means that if a build process has custom behavior (i.e. weaving with AspectJ or jarjaring), Bundlor will be able to see and analyze the changes made by that process as long as the changes are in the artifact created by the build system.

There are a number of places in a Java class that another Java type can be referenced from. Bundlor detects these references and adds manifest requirements for them.

Bundlor scans for Spring context configuration files. If it detects this file type, it scans the file for a number of values that contain class names.

Bundlor scans for Blueprint Service configuration files. If it detects this file type, it scans the file for a number of values that contain class names.

Bundlor scans for the Servlet web.xml file located in the WEB-INF directory. If it detects this file, it scans the file for a number of values that contain class names.

Bundlor scans for JAR files located anywhere in the bundle. If it detects this file, it runs the entire set of analyzers against it. The imports and exports of the JAR file are added to the outer bundle's manifest and the JAR file is placed on the outer bundle's Bundle-Classpath.

Bundlor scans for the JPA persistence.xml files located in the META-INF directory. If it detects this file it scans the file for a number of values that contain class names.

Bundlor scans for any file that ends with a .hbm extension. If it detects one of these files it scans the file for a number of attributes that can contain class names. If the class name is unqualified (i.e. has no '.' in it), the classname is prepended with the hibernate-mapping tags' package attribute. Many of the attributes that can contain class names can also contain Hibernate keywords corresponding to Hibernate-known types. When these are detected, no manifest requirements are added.

Bundlor scans for the JSP files. If it detects this file, it scans the file for a number of values that contain class names.

Bundlor scans for Log4J configuration files. If it detects this file type, it scans the file for a number of values that contain class names.

Bundlor scans for any static resource and exports that package.

Bundlor checks that all entries in the Import-Package header have a sensible version range declared. This ensures that there are no version ranges that are reversed ([2, 1)), and no version ranges that are exclusive ([1, 1]).

Bundlor checks that the manifest does not import any package that it exports. This behavior is usually indicative of a package split between two bundles.

Bundlor checks that the manifest does not contain headers indicating that it is from a signed JAR. Running Bundlor against a signed JAR will render that JAR invalid as the manifest will have changed from the when it was signed.

Bundlor checks that all entries in the Import-Package header have a version declared.

Bundlor checks that all entries in the Export-Package header have a version declared.

Bundlor checks that the manifest contains a Bundle-SymbolicName header.

Bundlor checks that the manifest contains a Bundle-ManifestVersion header with a value of 2.