War Protocol

Pax URL War is an OSGi URL handler that automates war deployment. To do that war url handler will transform a war file by adding the necessary manifest headers based on a set of processing instructions or default assumptions.

Why

Imagine this. You have a standard war file that you want to deploy into an OSGi framework. For this to work it needs extra OSGi manifest headers and you do not want to preprocess the war file before deployment, and you are wondering why can't this process be done automatically. Well, it can. See bellow.

Syntax ( see #examples )

war-uri := war-uri-auto | war-uri-ref
war-uri-auto := "war:" | "webbundle:" < rfc2396 uri > ; uri of the war file
war-uri-ref := "warref:" < rfc2396 uri > ; uri of a java properties file that contains custom war instructions

So, when you want to make a bundle out of your war using default instructions you will have to use the "war:" or "webbundle:" protocol and provide a url for the war file, and when you want to use custom instructions you have to use the "warref:" protocol and provide a url for the instructions file to use. Whatever of the two protocols you use, the handler will take the specified war file, scan the WEB-INF/lib directory for all the jars in order to create the Bundle-ClassPath instruction and toegether wth the default or provided instructions will use the BND tool to generate the OSGi bundle.

Instructions file syntax

The instructions file is a standard java properties that contains properties to be used while transforming the war into an OSGi compatible bundle. See Peter Kriens BND Tool for details about instructions. Beside those you have/can use the following wrap protocol specific instructions:

Mandatory properties

• WAR-URL — < rfc2396 uri >; url of the war file to be transformed

Optional properties

Any property that you specify will be added into the transformed war manifest file (META-INF/MANIFEST.MF) (see some useful properties). Some of the properties will have a special meaning as can be seen bellow:

• Bundle-SymbolicName — If not specified the bundle symbolic name will be generate out of War-URI where all characters that are one of [a-zA-Z_0-9-\.] are replaced with "."
• Webapp-Context — no default value (War Extender will use Bundle-SymbolicName as default)
• Bundle-ClassPath — you can provide any class path entries you need and the following entries will be added automatically:
  • .
  • WEB-INF/classes
  • all jars from WEB-INF/lib directory

Default instructions

By default the following will be used:

• import all packages that:
  • start with javax;
  • start with org.org.xml
  • start with org.w3c
• no packages will be exported
• WAR-URL (see above) will be the provided url ( everything after "warref:" )
• Default instructions (see above) will be used

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

Create an OSGi compliant war file (bundle) using default instructions downloaded using http protocol:

war:http://repo1.maven.org/maven2/org/apache/wicket/wicket-examples/1.3.0/wicket-examples-1.3.0.war

Create an OSGi compliant war file (bundle) using default instructions downloaded using mvn protocol:

war:mvn:org.apache.wicket/wicket-examples/1.3.0/war

Create an OSGi compliant war file (bundle) using specific instructions downloaded using mvn protocol:

warref:jar:mvn:org.ops4j.pax.web-extender.samples/provision!/wicket-examples-1.3.0.bnd

Specify the webapp context in the URL:

war:mvn:org.apache.wicket/wicket-examples/1.3.0/war?Webapp-Context=wicket