A.4. Wrap URL Handler

Overview

If you need to reference a JAR file that is not already packaged as a bundle, you can use the Wrap URL handler to convert it dynamically. The implementation of the Wrap URL handler is based on Peter Krien's open source Bnd utility.

Syntax

A Wrap URL has the following syntax:
wrap:locationURL[,instructionsURL][$instructions]
The locationURL can be any URL that locates a JAR (where the referenced JAR is not formatted as a bundle). The optional instructionsURL references a Bnd properties file that specifies how the bundle conversion is performed. The optional instructions is an ampersand, &, delimited list of Bnd properties that specify how the bundle conversion is performed.

Default instructions

In most cases, the default Bnd instructions are adequate for wrapping an API JAR file. By default, Wrap adds manifest headers to the JAR's META-INF/Manifest.mf file as shown in Table A.1, “Default Instructions for Wrapping a JAR”.

Table A.1. Default Instructions for Wrapping a JAR

Manifest HeaderDefault Value
Import-Package*;resolution:=optional
Export-PackageAll packages from the wrapped JAR.
Bundle-SymbolicNameThe name of the JAR file, where any characters not in the set [a-zA-Z0-9_-] are replaced by underscore, _.

Examples

The following Wrap URL locates version 1.1 of the commons-logging JAR in a Maven repository and converts it to an OSGi bundle using the default Bnd properties:
wrap:mvn:commons-logging/commons-logging/1.1
The following Wrap URL uses the Bnd properties from the file, E:\Data\Examples\commons-logging-1.1.bnd:
wrap:mvn:commons-logging/commons-logging/1.1,file:E:/Data/Examples/commons-logging-1.1.bnd
The following Wrap URL specifies the Bundle-SymbolicName property and the Bundle-Version property explicitly:
wrap:mvn:commons-logging/commons-logging/1.1$Bundle-SymbolicName=apache-comm-log&Bundle-Version=1.1
If the preceding URL is used as a command-line argument, it might be necessary to escape the dollar sign, \$, to prevent it from being processed by the command line, as follows:
wrap:mvn:commons-logging/commons-logging/1.1\$Bundle-SymbolicName=apache-comm-log&Bundle-Version=1.1

Reference

For more details about the wrap URL handler, see the following references: