Configuring a Bundle Plug-in

Overview

A bundle plug-in requires very little information to function. All of the required properties have default settings to generate a valid OSGi bundle.

While you can create a valid bundle using just the default values, you will likely want to modify some of the values. You can specify most of the properties inside the plug-in's instructions element.

Configuration properties

Some of the commonly used configuration properties are:

Setting a bundle's symbolic name

By default, the bundle plug-in sets the value for the Bundle-SymbolicName property to groupId+ "." +artifactId, with the following exceptions:

If groupId has only one section (no dots), the first package name with classes is returned.
For example, if the groupId is commons-logging:commons-logging, the bundle's symbolic name is org.apache.commons.logging.
If artifactId is equal to the last section of groupId, then groupId is used.
For example, if the POM specifies the group ID and artifact ID as org.apache.maven:maven, the bundle's symbolic name is org.apache.maven.
If artifactId starts with the last section of groupId, that portion is removed.
For example, if the POM specifies the group ID and artifact ID as org.apache.maven:maven-core, the bundle's symbolic name is org.apache.maven.core.

To specify your own value for the bundle's symbolic name, add a Bundle-SymbolicName child in the plug-in's instructions element, as shown in Example A.2.

Example A.2. Setting a Bundle's Symbolic Name

<plugin>
  <groupId>org.apache.felix</groupId>
  <artifactId>maven-bundle-plugin</artifactId>
  <configuration>
   <instructions>
     <Bundle-SymbolicName>${pom.artifactId}</Bundle-SymbolicName>
     ...
    </instructions>
  </configuration> 
</plugin>

Setting a bundle's name

By default, a bundle's name is set to ${pom.name}.

To specify your own value for the bundle's name, add a Bundle-Name child to the plug-in's instructions element, as shown in Example A.3.

Example A.3. Setting a Bundle's Name

<plugin>
  <groupId>org.apache.felix</groupId>
  <artifactId>maven-bundle-plugin</artifactId>
  <configuration>
   <instructions>
     <Bundle-Name>JoeFred</Bundle-Name>
     ...
    </instructions>
  </configuration> 
</plugin>

Setting a bundle's version

By default, a bundle's version is set to ${pom.version}. Any dashes (-) are replaced with dots (.).

To specify your own value for the bundle's version, add a Bundle-Version child to the plug-in's instructions element, as shown in Example A.4.

Example A.4. Setting a Bundle's Version

<plugin>
  <groupId>org.apache.felix</groupId>
  <artifactId>maven-bundle-plugin</artifactId>
  <configuration>
   <instructions>
     <Bundle-Version>1.0.3.1</Bundle-Version>
     ...
    </instructions>
  </configuration> 
</plugin>

By default, the OSGi manifest's Export-Package list is populated by all of the packages in your project's class path that match the pattern Bundle-SymbolicName.*. These packages are also included in the bundle.

	Important
	If you use a `Private-Package` element in your plug-in configuration and do not specify a list of packages to export, the default behavior is to assume that no packages are exported. Only the packages listed in the `Private-Package` element are included in the bundle and none of them are exported.

The default behavior can result in very large packages as well as exporting packages that should be kept private. To change the list of exported packages you can add a Export-Package child to the plug-in's instructions element.

The Export-Package element specifies a list of packages that are to be included in the bundle and be exported. The package names can be specified using the * wildcard. For example, the entry com.fuse.demo.*, includes all packages on the project's classpath that start with com.fuse.demo.

You can specify packages to be excluded be prefixing the entry with !. For example, the entry, !com.fuse.demo.private, excludes the package com.fuse.demo.private.

When attempting to exclude packages, the order of entries in the list is important. The list is processed in order from the start and subsequent contradicting entries are ignored.

For example, to include all packages starting with com.fuse.demo except the package com.fuse.demo.private, list the packages in the following way:

!com.fuse.demo.private,com.fuse.demo.*

However, if you list the packages as:

com.fuse.demo.*,!com.fuse.demo.private

Then com.fuse.demo.private is included in the bundle because it matches the first pattern.

Specifying private packages

By default, all packages included in a bundle are exported. You can include packages in the bundle without exporting them. To specify a list of packages to be included in a bundle, but not exported, add a Private-Package child to the plug-in's instructions element.

The Private-Package element works similarly to the Export-Package element. You specify a list of packages to be included in the bundle. The bundle plug-in uses the list to find all classes on the project's classpath to be included in the bundle. These packages are packaged in the bundle, but not exported.

	Important
	If a package matches an entry in both the `Private-Package` element and the `Export-Package` element, the `Export-Package` element takes precedent. The package is added to the bundle and exported.

Example A.5 shows the configuration for including a private package in a bundle

Example A.5. Including a Private Package in a Bundle

<plugin>
  <groupId>org.apache.felix</groupId>
  <artifactId>maven-bundle-plugin</artifactId>
  <configuration>
   <instructions>
     <Private-Package>org.apache.cxf.wsdlFirst.impl</Private-Package>
     ...
    </instructions>
  </configuration> 
</plugin>

Specifying imported packages

By default, the bundle plug-in populates the OSGi manifest's Import-Package property with a list of all the packages referred to by the contents of the bundle and not included in the bundle.

While the default behavior is typically sufficient for most projects, you might find instances where you want to import packages that are not automatically added to the list. The default behavior can also result in unwanted packages being imported.

To specify a list of packages to be imported by the bundle, add a Import-Package child to the plug-in's instructions element. The syntax for the package list is the same as for both the Export-Package and Private-Package elements.

	Important
	When you use the `Import-Package` element, the plug-in does not automatically scan the bundle's contents to determine if there are any required imports. To ensure that the contents of the bundle are scanned, you must place `*` as the last entry in the package list.

Example A.6 shows the configuration for including a private package in a bundle

Example A.6. Specifying the Packages Imported by a Bundle

<plugin>
  <groupId>org.apache.felix</groupId>
  <artifactId>maven-bundle-plugin</artifactId>
  <configuration>
   <instructions>
     <Import-Package>javax.jws,
         javax.wsdl,
         org.apache.cxf.bus,
         org.apache.cxf.bus.spring,
         org.apache.cxf.bus.resource,
         org.apache.cxf.configuration.spring,
         org.apache.cxf.resource,
         org.springframework.beans.factory.config,
         *
     </Import-Package>
     ...
   </instructions>
  </configuration> 
</plugin>

More information

For more information on configuring a bundle plug-in, see: