Wrap Protocol

Pax URL Wrap is an OSGi URL handler that can process your legacy jar at runtime and transform it into an OSGi bundle.

Why

Imagine this. You have a bundle that requires a set of existing jars in order to work. As for example Apache Commons Lang. What you could do? Look first on Apache Felix Commons to find out if is not already wrapped and use that jar. But what if is not there or the version you are looking for is not there? What if is your own jar? Of course you could wrap it yourself but wouldn't be easier that you could just use an url wrap it? That's why this handler was made.

Overview

By using the wrap protocol you can wrap an existing jar as an OSGi bundle. The wrapping process can be done in different ways:

1. without any processing instructions;
2. by specifying wrapping instructions file;
3. by encoding the instructions in the url

It uses Peter's Kriens bnd tool for carrying out the actual wrapping process.

Syntax ( see #examples )

wrap-uri := "wrap:" wrapped-jar-uri [ "," wrapping-instr-uri ] [ "$" wrapping-instructions ]
wrapped-jar-uri := < rfc2396 uri > ; uri of the jar file to be wrapped
wrapping-instr-uri := < rfc2396 uri > ; uri of a java properties file that contains wrapping instructions
wrapping-instr-list := wrapping-instr / wrapping-instr "&" wrapping-instr-list
wrapping-instr := instr-name "=" instr-value
instr-name := < bnd instruction name > ;see bnd tool for details
instr-value := < bnd instruction value > ;see bnd tool for details

Default instructions

The following instructions are mandatory for wrapping a jar as an OSGi bundle, so if not found in the wrapping file or wrapping instructions a default value will be used as follows:

Configuration

The service can be configured in two ways: via configuration admin if available and via framework/system properties where the configuration via config admin has priority.

Examples

Wraps apache commons logging version 1.1 found on working directory using #default instructions:

wrap:file:commons-logging-1.1.jar

Wraps apache commons logging version 1.1 found by using mvn: protocol using #default instructions:

wrap:mvn:commons-logging/commons-logging/1.1

Wraps apache commons logging version 1.1 found by using mvn: protocol using #default instructions:

wrap:http://repo1.maven.org/maven2/commons-logging/commons-logging/1.1/commons-logging-1.1.jar

Wraps apache commons logging version 1.1 found by using mvn: protocol using instructions from commons-logging-1.1.bnd from local directory:

wrap:mvn:commons-logging/commons-logging/1.1,file:commons-logging-1.1.bnd

Wraps apache commons logging version 1.1 found by using mvn: protocol using instructions Bundle-SymbolicName=JCL and Bundle-Version=1.1:

wrap:mvn:commons-logging/commons-logging/1.1$Bundle-SymbolicName=JCL&Bundle-Version=1.1

Wraps apache commons logging version 1.1 found by using mvn: protocol using instructions from commons-logging-1.1.bnd from local directory and instructions Bundle-SymbolicName=JCL and Bundle-Version=1.1:

wrap:mvn:commons-logging/commons-logging/1.1,file:commons-logging-1.1.bnd$Bundle-SymbolicName=JCL&Bundle-Version=1.1

Wraps infinispan version 5.2.6.final found by using mvn: protocol using instructions the existing manifest and merging those with some fixed informations about Import-Package and Export-Package:

wrap:mvn:org.infinispan/infinispan-core/5.2.6.Final$overwrite=merge&Import-Package=sun.misc;net.jcip.annotations;resolution:=optional,org.jgroups.*;version="[3.2,4)",org.jboss.logging;version="[3.1,4)",*&Export-Package=org.infinispan.*;-noimport:=true

NOTE: Beware that you may need to escape the $ character which precedes the instruction list if you are using a shell. That is, precede the dollar sign with a backslash: \$. Otherwise, your instruction may be interpreted as a variable name and consequently the shell will attempt to resolve it.