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:
- without any processing instructions;
- by specifying wrapping instructions file;
- 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:
| Instruction | Value |
|---|---|
| Import-Package | *;resolution:=optional |
| Export-Package | all packages from the wrapped jar |
| Bundle-SymbolicName | made up out of the wrapped jar url where all characters that are not in [a-zA-Z_0-9-] are replaced with "_" |
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.
| Option key | Description |
|---|---|
| org.ops4j.pax.url.wrap.certicateCheck | optional; true/false if the SSL certificate check should be done while accesing the wrapped jar url and wrapping instructions url. Default false. |
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
