Pax Web 4.4.0

OSGi R4 Http Service and Web Applications (OSGi Enterprise Release chapter 128) implementation using Jetty 9.2.19.v20160908 or Tomcat 8.0.14.

Pax Web extends OSGi Http Service with better servlet support, filters, listeners, error pages and JSPs and some others in order to meet the latest versions of Servlet specs. Pax Web facilitates an easy installation of WAR bundles as well as discovery of web elements published as OSGi services. All of this beside the, standard, programmatic registration as detailed in the HTTP Service specs.

1. Supported Technology

Right now following Technologies are supported by Pax Web:

1.1. Pax Web 4.1.0:

Latest stable release is 4.0.0, this is for the next SNAPSHOT version

Servlet 3.1
JSP 2.3
JSF 2.2
Jetty 9.2.x
Tomcat 8.0.x (still experimental, but better supported)
support of CDI (through Pax-CDI)
support of only Servlet 3.0 annotated Servlets in JAR
support of only Servlet 3.0 annotated Servlets with Whiteboard extender
support of Websockets JSR 356 (Jetty Only)
Web-Fragments

1.2. Pax Web 4.0.x:

Latest stable release is 4.0.0

Servlet 3.0
JSP 2.0
JSF 2.1
Jetty 9.0.x
Tomcat 7.x (still experimental, but better supported)
support of CDI (through Pax-CDI)
support of only Servlet 3.0 annotated Servlets in JAR
Web-Fragments

1.3. Pax Web 3.x:

Latest stable release is 3.1.1

Servlet 3.0
JSP 1.1.2
JSF 2.1
Jetty 8.x
Tomcat 7.x (still experimental)
support of CDI (through Pax-CDI)
support of only Servlet 3.0 annotated Servlets in JAR

1.4. Versions already at end of life

Following versions are already at end of life.

1.4.1. Pax Web 2.x:

Servlet 3.0
JSP 1.1.2
JSF 2.1
Jetty 8.x
support of application binding to a virtual host (Http-Connector) for WABs

1.4.2. Pax Web 1.x:

Servlet 2.5
JSP 1.1.2
JSF 1.2
Jetty 7.x

2. User Guide

The following guides details different aspects of using Pax Web from the user perspective, where user means somebody that uses Pax Web.

2.1. Configuration

Pax Web can be configured using Configuration Admin or via framework/system properties.

While looking for a configuration property, Pax Web will first use the property configured via Configuration Admin. If the property is not set (present), it will look for a framework/system property with the same name. In the end, if the property is still not present it will use a default value (when applicable).

For cases that requires advanced Jetty configuration read Advanced Jetty Configuration page.

2.1.1. Configuration via OSGi Configuration Admin Service

Pax Web can be configured via Configuration Admin Service (if available) and it supports all properties listed above.
The PID used for configuration is "org.ops4j.pax.web".

2.1.2. Configuration via OSGi framework/system properties properties

Pax Web can be configured via osgi environment properties and it supports all properties from above. Note that according to OSGi specs if a framework property is not set then the framework must fallback to using standard Java System properties (set via vm -D option).

2.1.3. Basic Configuration

The following is a list with basic configuration properties that can be used to customize Pax Web.

org.osgi.service.http.port

This property specifies the port used for servlets and resources accessible via HTTP. Default value for this property is 8080.
You can specify a value of 0 (zero), if you wish to allow Pax Web to automatically determine a free port to use for HTTP access.

org.osgi.service.http.port.secure

This property specifies the port used for servlets and resources accessible via HTTPS. Default value for this property is 8443.
You can specify a value of 0 (zero), if you wish to allow Pax Web to automatically determine a free port to use for HTTPS access.

org.osgi.service.http.enabled

This property specifies if the HTTP is enabled. If “true” the support for HTTP access will be enabled. If “false” the support for HTTP access will be disabled. Default value is “true”.

org.osgi.service.http.secure.enabled

This property specifies if the HTTPS is enabled. If “true” the support for HTTPS access will be enables. If “false” the support for HTTPS access will be disabled. Default value is “false”.

org.osgi.service.http.useNIO

This property specifies if the connections established use the nio classes from java. If “true” connections are established using NIO, if “false” connections are established the standard way.

javax.servlet.context.tempdir

A temporary directory that can be accessed via the servlet context attribute with the same name. If not set a default temporary directory wil be created and used.

org.ops4j.pax.web.session.timeout

The number of minutes after which an inactive session will timeout.

org.ops4j.pax.web.listening.addresses

This property specifies the comma separated list of addresses used to provide servlets and resources via HTTP
(e.g. localhost or localhost,10.0.0.1). Host names or IP addresses can be used. Default value is “0.0.0.0”.

Session cookie name.
From Jetty documentation:
Defaults to JSESSIONID.

org.ops4j.pax.web.session.url

Session URL.
From Jetty documentation:
Defaults to jsessionid. If set to null or “none” no URL rewriting will be done

org.ops4j.pax.web.worker.name

Sets worker name for use with Apache mod_proxy_balancer sticky sessions.
See: http://docs.codehaus.org/display/JETTY/Configuring+mod_proxy
Defaults to null.

org.ops4j.pax.web.config.file

Configures where to look for an external configuration file for the underlying web container (e.g. Jetty).

org.ops4j.pax.web.log.ncsa.format

Sets the format for logging access logs

org.ops4j.pax.web.log.ncsa.format = /yyyy_mm_dd.request.log

org.ops4j.pax.web.log.ncsa.retainDays

org.ops4j.pax.web.log.ncsa.retainDays = 90

org.ops4j.pax.web.log.ncsa.append

org.ops4j.pax.web.log.ncsa.append = true/false

org.ops4j.pax.web.log.ncsa.extended

org.ops4j.pax.web.log.ncsa.extended = true/false

org.ops4j.pax.web.log.ncsa.LogTimeZone

org.ops4j.pax.web.log.ncsa.LogTimeZone= GMT

2.1.4. Advanced Jetty Configuration

To configure advanced features of Jetty you may use jetty xml style configuration files. To make Pax Web aware of your Jety configuration files you will have to use fragments. Be aware that fragment bundles are not yet fully supported on all OSGi implementations!

As an example, it’s shown enabling JMX in Jetty.

OSGi-Bundle Fragment way

To customize Jetty used by Pax Web Service follow instructions: Create a bundle fragment for Pax Web Service bundle for example:

Manifest-Version: 1.0
Fragment-Host: org.ops4j.pax.web.pax-web-jetty-bundle (1)
Bundle-Version: 0.1
Bundle-Name: My Jetty config
Bundle-ManifestVersion: 2
Bundle-SymbolicName: my.jetty_config

1	the required line in the manifest.

If the version you are using is the non bundled version of jetty bundle you should use org.ops4j.pax.web.pax-web-jetty instead of org.ops4j.pax.web.pax-web-jetty-bundle as value of Fragment-Host.

Put jetty.xml in root directory of fragment. For example, take a look at a simple example fragment bundle from Pax Web that will add an additional connector on port 8383.

https://github.com/ops4j/org.ops4j.pax.web/tree/master/samples/jetty-config-fragment/src/main/resources/jetty.xml

Add fragment to your start configuration If you have logging at DEBUG level enabled, when you start, you should see in logs something like this:

DEBUG  pax.web.service.internal.JettyServerImpl  - starting JettyServerImpl{}
DEBUG  pax.web.service.internal.JettyServerImpl  - configure using bundleresource://100/jetty.xml

Note that the url “bundleresource://100/jetty.xml” from above is just an example as the url is framework specific

Using external jetty.xml file

Sometimes it’s needed to have a much more easier way of configuring the underlying Jetty server. An external located jetty.xml file can be used for configuring the jetty server. This can be activated by setting the following property for Pax Web

org.ops4j.pax.web.config.file=<FILE-IN-FILESYSTEM>

For more details on how to configure the Jetty Server take a look at the official jetty.xml configuring page.

Adding specialized ContextHandlers

If you want to add specialized ContextHandlers to the jetty server you have to be careful not to break the way Pax Web works. So Instead of defining a new Collection of Handlers in the jetty.xml you need to add your specialized ContextHandler to the existing Collection.

Here is an example where the jetty Default Servlet is used to server static content from the file system.

  <Get name="handler">
    <Call name="addHandler">
      <Arg>
        <New class="org.eclipse.jetty.servlet.ServletContextHandler">
          <Set name="contextPath">/app</Set>
          <Set name="resourceBase">/path/to/your/share</Set>
          <Call name="addServlet">
            <Arg>org.eclipse.jetty.servlet.DefaultServlet</Arg>
            <Arg>/</Arg>
          </Call>
        </New>
      </Arg>
    </Call>
  </Get>

Using Handler and Connectors as Services

The Following described way of working is only valid starting with version - 4.1.0

All possible Handler or Connector configurations to Jetty through the jetty.xml file can now be registered as Services. With this it’s possible to register the previously made sample of specialized ContextHandler as service.

ContextHandler ctxtHandler = new ContextHandler();
ctxtHandler.setContextPath("/static-content");
ResourceHandler resourceHandler = new ResourceHandler();
resourceHandler.setResourceBase("target");
resourceHandler.setDirectoriesListed(true);
ctxtHandler.setHandler(resourceHandler);

ServiceRegistration<Handler> registerService = bundleContext.registerService(Handler.class, ctxtHandler, null);

2.1.5. SSL Configuration

Pax Web supports SSL (https) via Jetty built in SSL support. To get used with Jetty support you may read How to configure SSL in Jetty and skip step 4 from that page, as the configuration part must be done in Pax Web specific way.

To enable SSL support you must set the following properties:

org.osgi.service.http.secure.enabled to true
org.ops4j.pax.web.ssl.keystore to the path to the keystore to be used. If not set the default path ${user.home}/.keystore is used.
org.ops4j.pax.web.ssl.password to the password used for keystore integrity check. The value can be in plain text or obfuscated ( starting with OBF: ) as described in step 4 of jetty docummentation
org.ops4j.pax.web.ssl.keypassword to the password used for keystore. The value can be in plain text or obfuscated ( starting with OBF: ) as described in step 4 of jetty docummentation

You may also set the following:

org.osgi.service.http.port.secure to change the port. Default is 8443.

The following is a list with SSL related configuration properties that can be used to customize Pax Web SSL support.

org.ops4j.pax.web.ssl.keystore

Path to the keystore file. See ops4j:SSL Configuration for details.

org.ops4j.pax.web.ssl.keystore.type

This property specifies the keystore type. Defaults to JKS.

org.ops4j.pax.web.ssl.password

Password used for keystore integrity check.

org.ops4j.pax.web.ssl.keypassword

Password used for keystore.

org.ops4j.pax.web.ssl.clientauthwanted

This property specifies, if certificate-based client authentication at the server is “wanted”.

org.ops4j.pax.web.ssl.clientauthneeded

This property specifies, if certificate-based client authentication at the server is “required”.

2.1.6. JSP Configuration

The following is a list with extra configuration properties for JSP compilation, these can be used to customize Pax Web. If not specified otherwise, the property is available since Pax Web - 1.0.0.
These properties are send to the underlying JSP servlet Container see

The default configuration used can be seen via the MetaTypeService or in the metatype.xml of the runtime bundle.

org.ops4j.pax.web.jsp.scratch.dir

This property defines the Directory where servlets are generated.

org.ops4j.pax.web.jsp.check.interval

Interval in seconds between background recompile checks. Only relevant if org.ops4j.pax.web.jsp.development=false.

org.ops4j.pax.web.jsp.debug.info

Include debugging info in class file.

org.ops4j.pax.web.jsp.development

If true, recompilation checks are made on each request.

org.ops4j.pax.web.jsp.enable.pooling

Determines whether tag handler pooling is enabled.

org.ops4j.pax.web.jsp.ie.classid

Classid used for InternetExplorer

org.ops4j.pax.web.jsp.java.encoding

Pass through the encoding to use for the compilation.

org.ops4j.pax.web.jsp.keep.generated

Do you want to keep the generated Java files around?

org.ops4j.pax.web.jsp.log.verbosity.level

Log verbosity level used.

org.ops4j.pax.web.jsp.mapped.file

Support for mapped Files. Generates a servlet that has a print statement per line of the jsp file.

org.ops4j.pax.web.jsp.tagpool.max.size

Maximum size for tags in pool.

org.ops4j.pax.web.jsp.precompilation

If JSPs should be precompiled (see for more details here)

Since Pax Web - 2.0.0

2.2. Http Service Extensions

Pax Web extends OSGi Http Service in order to align OSGi web support with latest developments of Servlet specs.

In order to make use of this extensions you will have to get hold of a WebContainer service instead of HttpService as in:

bundleContext.getServiceReference( "org.ops4j.pax.web.service.WebContainer" );

Having an WebContainer service instance you will be able to dynamically:

set context parameters for a Http Context
register and unregister servlets with multiple url mappings (including wild card ‘*’ support)
register and unregister filters into the URI namespace of Http Service (including wild card ‘*’ support)
register and unregister event listeners, for better control over the life cycle of ServletContext, HttpSession and ServletRequest;
register and unregister error pages
register and unregister welcome files
enable and disable JSP support

Accessing the BundleContext

The BundleContext is exposed as attribute of the ServletContext:

BundleContext ctx = (BundleContext) servletContext.getAttribute(
                                WebContainerConstants.BUNDLE_CONTEXT_ATTRIBUTE);

2.2.1. Servlets

Register servlet by URL pattern

public void registerServlet( Servlet servlet, String[] urlPatterns, Dictionary initParams, HttpContext httpContext ) throws ServletException
Registers a servlet.

servlet	The servlet object to register
urlPatterns	An array of url patterns this servlet maps to. Cannot be null.
initParams	Initialization arguments for the servlet or null if there are none. This argument is used by the servlet’s ServletConfig object.
httpContext	The HttpContext object for the registered servlet, or null if a default HttpContext is to be created and used
Throws	ServletException — if given servlet object has already been registered
Throws	IllegalArgumentException — in the following situations: servlet is null urlPatterns is null or empty

servlet

The servlet object to register

urlPatterns

An array of url patterns this servlet maps to. Cannot be null.

initParams

Initialization arguments for the servlet or null if there are none. This argument is used by the servlet’s ServletConfig object.

httpContext

The HttpContext object for the registered servlet, or null if a default HttpContext is to be created and used

Throws

ServletException — if given servlet object has already been registered

Throws

IllegalArgumentException — in the following situations: servlet is null urlPatterns is null or empty

To give a name to the registered servlet you can add an element named *servlet-name* to initParams and as value the servlet name.

starting with 1.1.4 it’s possible to filter init parameters. As shown in WebExperience it’s now possible to configure the init.parameters for the servlets and filters with the prefix init.
For background info take a look at here

Unregister a servlet

public void unregisterServlet( Servlet servlet )
Unregisters a previously registered servlet.

servlet	The servlet to be unregistered
Throws	IllegalArgumentException — if: servlet is null the servlet is unknown to Web Container (never registered or unregistered before)

servlet

The servlet to be unregistered

Throws

IllegalArgumentException — if: servlet is null the servlet is unknown to Web Container (never registered or unregistered before)

2.2.2. Filters

Register filters

public void registerFilter( Filter filter, String[] urlPatterns, String[] servletNames, Dictionary initParams, HttpContext httpContext )
Registers a servlet filter.

filter	The flter to register
urlPatterns	An array of url patterns this filter maps to. Can be null.
servletNames	An array of servlets names this filter maps to. Can be null.
initParams	Initialization arguments for the servlet or null if there are none. This argument is used by the filter’s FilterConfig object.
httpContext	the http context this filter is for. If null a default http context will be used.
Throws	IllegalArgumentException — if: filter is null both urlPatterns and servletNames are null or empty

filter

The flter to register

urlPatterns

An array of url patterns this filter maps to. Can be null.

servletNames

An array of servlets names this filter maps to. Can be null.

initParams

Initialization arguments for the servlet or null if there are none. This argument is used by the filter’s FilterConfig object.

httpContext

the http context this filter is for. If null a default http context will be used.

Throws

IllegalArgumentException — if: filter is null both urlPatterns and servletNames are null or empty

To give a name to the registered servlet you can add an element named filter-name to initParams and as value the filter name.

starting with Pax Web 1.1.4 it’s possible to filter init parameters. As shown in WebExperience it’s now possible to configure the init.parameters for the servlets and filters with the prefix init.
For background info take a look at here

Unregister filters

public void unregisterFilter( Filter filter )
Unregisters a previously registered servlet filter.

filter	The servlet filter to be unregistered
Throws	IllegalArgumentException — if: filter is null the filter is unknown to Web Container (never registered or unregistered before)

filter

The servlet filter to be unregistered

Throws

IllegalArgumentException — if: filter is null the filter is unknown to Web Container (never registered or unregistered before)

2.2.3. Listeners

Register event listeners

public void registerEventListener( EventListener listener, HttpContext httpContext )

Registers an event listener. Depending on the listener type, the listener will be notified on different life cycle events. The following listeners are supported: HttpSessionActivationListener, HttpSessionAttributeListener, HttpSessionBindingListener, HttpSessionListener, ServletContextListener, ServletContextAttributeListener, ServletRequestListener, ServletRequestAttributeListener.
Check out Servlet specification for details on what type of event the registered listener will be notified.

Unregister event listeners

public void unregisterEventListener( EventListener listener )

Unregisters a previously registered listener.

listener	The event listener to be unregistered
Throws	IllegalArgumentException — if: listener is null the listener is unknown to the http service (never registered or unregistered before)

listener

The event listener to be unregistered

Throws

IllegalArgumentException — if: listener is null the listener is unknown to the http service (never registered or unregistered before)

2.2.4. Error Pages

Register error pages

public void registerErrorPage( String error, String location, HttpContext httpContext )

Registers an error page to customize the response sent back to the web client in case that an exception or error propagates back to the web container, or the servlet/filter calls sendError() on the response object for a specific status code.
Read Servlet specs for details related to error pages.

error

A fully qualified Exception class name or an error status code. Cannot be null.

location

The request path that will fill the response page. The location must start with an “/”. Cannot be null.

httpContext

The http context this error page is for. If null a default http context will be used.

Throws

IllegalArgumentException — if: error is null or empty location is null location does not start with a slash “/”

Unregister error pages

public void unregisterErrorPage( String error, HttpContext httpContext )

Unregisters a previous registered error page.

error

A fully qualified Exception class name or an error status code to be unregistered. Cannot be null.

httpContext

The http context from which the error page should be unregistered. Cannot be null.

Throws

IllegalArgumentException — if: error is null or empty error page was not registered before httpContext is null

2.2.5. Welcome Files

Register welcome files

public void registerWelcomeFiles( String[] welcomeFiles, boolean redirect, HttpContext httpContext )

Registers an ordered list of partial URIs. The purpose of this mechanism is to allow the deployer to specify an ordered list of partial URIs for the container to use for appending to URIs when there is a request for a URI that corresponds to a directory entry in the WAR not mapped to a Web component. Read Servlet specs for details related to welcome files.

welcomeFiles

An array of welcome files paths. Paths must not start or end with “/”.

redirect

True if the client should be rediected to welcome file or false if forwarded.

httpContext

The http context these welcome files is for. If null a default http context will be used.

Throws

IllegalArgumentException — if: welcome files is null or empty entries in array are null or empty entries in array start or end with “/”

Throws

IllegalStateException — if welcome files are already registered

Unregister welcome files

public void unregisterWelcomeFiles( HttpContext httpContext )

Unregisters previous registered welcome files.

httpContext

The http context from which the welcome files should be unregistered. Cannot be null.

Throws

IllegalArgumentException — if: no welcome files were registered before httpContext is null

2.2.6. JSP

Pax Web has support for Java Server Pages (JSP) via using Tomcat Jasper 2

Why

Quoted from Java Server Pages home page:

JavaServer Pages (JSP) technology provides a simplified, fast way to create dynamic web content. JSP technology enables rapid development of web-based applications that are server- and platform-independent.

How does it work

First of all you must have your JSPs (not mandatory but useful). Then you have to let Pax Web know that you have jsps by calling the registerJsps() method on WebContainer.
At runtime you have to also deploy the jsp support bundle org.ops4j.pax.web.jsp (see installation instructions bellow) together with Pax Web.
You can find an example of the example page.

Tag Libs

In order to get your custom tag libs working your TLD files will have to be reachable in your bundle in “special” places:

all tld files in any jar referenced by your Bundle-ClassPath manifest entry
all tld files in WEB-INF directory or sub-directory of WEB-INF in your bundle jar

Imported packages are being searched too as of 1.1.2 and 2.0.0. See PAXWEB-86 and PAXWEB-130. PAX Web JSP’s only scans the META-INF/ directory within each imported (Import-Package) or required bundle (Require-Bundle), thus mimicking Jasper’s behaviour when searching JAR files for TLDs.

Enable JSP support

public void registerJsps( String[] urlPatterns, HttpContext httpContext )

Enables jsp support. For more details take a look here.

urlPatterns

An array of url patterns this jsp support maps to. If null, a default “*.jsp” will be used

httpContext

The http context for which the jsp support should be enabled. If null a default http context will be used.

Throws

UnsupportedOperationException — If jsp support is not available (optional org.ops4j.pax.web.jsp package is not resolved)

Disable JSP support

public void unregisterJsps( HttpContext httpContext )

Disable jsp support.

httpContext

The http context for which the jsp support should be disabled

Throws

IllegalArgumentException — If http context is null.

Throws

UnsupportedOperationException — If jsp support is not available (optional org.ops4j.pax.web.jsp package is not resolved)

2.3. Examples

This page is out of Date and needs rework

Pax Web includes a set of examples that demonstrates its usage. These can be found at the github samples

2.3.1. Http Service usage

This example shows you how to register a servlet and resources using the standard Http Service. Source code can be found at the samples on GitHub.
Once the example is started (see below) you can point your web browser to http://localhost:8080/helloworld/hs.

You can simply start the example by using Pax Runner using one of the two methods below:

Download the provision file

Download https://github.com/ops4j/org.ops4j.pax.web/tree/master/samples/provision/src/main/resources/sample-helloworld-hs.bundles to an arbitrary location
Start Pax Runner from the directory you have downloaded the provision file:
```
pax-run sample-helloworld-hs.bundles
```

Direct

pax-run scan-file:jar:mvn:org.ops4j.pax.web.samples/provision!/sample-helloworld-hs.bundles

2.3.2. Extended http service

This example shows you how to register servlets, resources, filters, listeners and error pages using the extended Http Service, WebContainer. Source code can be found in GitHub.
Once the example is started (see bellow) you can point your web browser to

http://localhost:8080/helloworld/wc — to see the result of servlet invocation being wrapped by a filter (see example source for details). In this case the filter is applied based on an url pattern.
http://localhost:8080/helloworld/wc/sn/ — to see the result of servlet invocation being wrapped by a filter (see example source for details). In this case the filter is applied based on a servlet name.
To see that a different filter was applied you can check out the page title for each of the above urls. * http://localhost:8080/helloworld/wc/error/create?type=java.lang.IllegalArgumentException — to see how the error page will be triggered when a servlet throws an exception. The exception to be thrown is specified by the type parameter. The error page will display all servlet request attributes related to an exception page as specified by Servlet spec.
http://localhost:8080/helloworld/wc/a.page.that.not.exist — to see how the error page will be triggered based on the error type (404 in this case — page not found).

To verify that the listener (a ServletRequestListener is working you can repeat the request and check out the bottom of the page that displays a counter for the request made to the server.

You can simply start the example by using Pax Runner using one of the two methods below:

Download the provision file

Download https://github.com/ops4j/org.ops4j.pax.web/tree/master/samples/provision/src/main/resources/sample-helloworld-wc.bundles to an arbitrary location
Start Pax Runner from the directory you have downloaded the provision file:
```
pax-run sample-helloworld-wc.bundles
```

Direct

pax-run scan-file:jar:mvn:org.ops4j.pax.web.samples/provision!/sample-helloworld-wc.bundles

2.3.3. JSP support

This example shows you how to register jsps using the extended Http Service, WebContainer. Source code can be found in SVN.
Once the example is started (see bellow) you can point your web browser to

http://localhost:8080/helloworld/jsp/helloworld.jsp — to see the result of invoking a jsp.
http://localhost:8080/helloworld/jsp/helloworld-tld.jsp/ — to see the result of invoking a jsp that uses taglibs.

You can simply start the example by using Pax Runner using one of the two methods below:

Download the provision file

Download https://github.com/ops4j/org.ops4j.pax.web/tree/master/samples/provision/src/main/resources/sample-helloworld-jsp.bundles to an arbitrary location
Start Pax Runner from the directory you have downloaded the provision file:
```
pax-run sample-helloworld-jsp.bundles
```

Direct

pax-run scan-file:jar:mvn:org.ops4j.pax.web.samples/provision!/sample-deptstore.bundles

2.4. WAR Extender

Pax Web Extender WAR is an extender bundle that makes possible to deploy WAR files into OSGi.

2.4.1. How does it work

First you should have a war file compliant with Servlet specs. As the war file will have to be deployed as a bundle the war file must have the necessary OSGi manifest headers (take a look what is required and how you can easily add them). Once you have this preconditions you just have to deploy your bundle in your preferred OSGi framework. Of course, what you need more is that pax web extender war bundle to be installed together with an http service (preferred Pax Web).

2.4.2. Detailed way of working

Once installed the war extender will watch over the bundles that get started / stopped.
Once your war bundle gets deployed and started, the war extender will parse your web.xml and registers all elements with http service. If the http service is Pax Web then most likely that you will get a fully working web application. If the http service is a standard one some of the elements will not be registered as standard http service only supports servlets and resources.
Once your war bundle gets stopped all the prior registered elements will be unregistered.

2.4.3. Benefits

with no/minimum modifications to your war you can deploy it into an osgi framework
you do not depend on any OSGi api
you do not have to keep track of http service availability
you do not have to register/unregister your servlets/resources/filters/listeners
easy to use

2.4.4. WAR Extender Examples

This page is outdated!

WAR Extender includes a set of examples that demonstrates its usage. While running the examples bellow under Felix, version ⇐ 1.0.1 you may get will logging enabled quite a lot of error messages. You can ignore them as Felix logs a FrameworkEvent.ERROR every time it cannot find a class, fact that clashes with Spring way of searching for BeanInfo classes. This issue is resolved in the upcoming version on Felix.

Wicket Examples

Wicket provides an example war file that includes various examples related to Wicket
To deploy the wicket examples war (that is available in maven central repo) you just have to deploy to your preferred OSGi framework the following bundles:

Pax Web version >= 0.3.1
Pax Web Extender - War version >= 0.3.0
JSP API — required by Wicket Examples (you need an OSGi version of it)
Wicket Examples war repackaged as bundle (OSGi manifest headers added)
(optional) Pax Logging — if you want to see also the log output

Alternatively you can easy do the deployment using Pax Runner:

pax-run scan-file:jar:mvn:org.ops4j.pax.web-extender.samples/provision!/wicket-examples-1.3.0-wrap.bundles

The wicket-examples-1.3.0-wrap.bundles file above is a simple text file that lists all the bundles to be installed.

Once you have everything running point your browser to http://localhost:8080/wicket.examples/index.html. Notice that re-packaging of Wicket Examples War may take a while as the war file has about 9Mb (depending on your connection speed - file is downloaded from maven central repository). Anyhow, this is done just first time you run the example and it helps if you already have the war file in your local maven repository.

You can start it up even simpler by using the new war: protocol handler (you need Pax Runner version >= 0.6.0):

pax-run war:mvn:org.apache.wicket/wicket-examples/1.3.0/war --profiles=war

As you will see the war: protocol handler will do all that is necessary to directly deploy a war file. Note that in this case the context name will be generated automatically, so you should use http://localhost:8080/mvn_org.apache.wicket_wicket-examples_1.3.0_war/index.html to access the application (upcoming version 0.2.0 of war protocol will permit context name setup).

Spring PetClinic

Spring provides an example application named PetClinic. The Petclinic sample application is designed to show how the Spring application frameworks can be used to build simple, but powerful database-oriented enterprise applications.
To deploy the PetClinic war you will have first to build it by yourself (Spring PetClinic is not available in a maven repository and anyhow it needs some small changes):

Follow the build instructions provided by Spring

Before building the war file you have to change petclinic-servlet.xml as follows. You have to do this change not because of Pax Web but because the <context:component-scan …/> does not work in an OSGi environment (Spring DM guys are working on that).

Edit petclinic-servlet.xml

Replace line

<context:component-scan base-package="org.springframework.samples.petclinic.web">

with

<context:annotation-config/>
<bean class="org.springframework.samples.petclinic.web.ClinicController"/>
<bean class="org.springframework.samples.petclinic.web.AddOwnerForm"/>
<bean class="org.springframework.samples.petclinic.web.AddPetForm"/>
<bean class="org.springframework.samples.petclinic.web.AddVisitForm"/>
<bean class="org.springframework.samples.petclinic.web.EditOwnerForm"/>
<bean class="org.springframework.samples.petclinic.web.EditPetForm"/>
<bean class="org.springframework.samples.petclinic.web.FindOwnersForm"/>

Save the file and build Spring PetClinic according to instructions

Start the PetClinic database (not required but otherwise you cannot use the whole application)

Then deploy to your preferred OSGi framework the following bundles:

Pax Web version >= 0.3.1
JSP version >= 0.3.1
Pax Web Extender - War version >= 0.3.0
PetClinic war repackaged as bundle (OSGi manifest headers added)
(optional) Pax Logging — if you want to see also the log output

Alternatively you can easy do the deployment using Pax Runner (you must start Pax Runner from PetClinic’s dist directory so it can find the war file):

pax-run scan-file:jar:mvn:org.ops4j.pax.web-extender.samples/provision!/spring-petclinic-2.5-wrap.bundles

The spring-petclinic-2.5-wrap.bundles file above is a simple text file that lists all the bundles to be installed.

Once you have everything running point your browser to http://localhost:8080/petclinic/index.jsp. Notice that re-packaging of Spring PetClinic war file may take a while as the war file has about 15Mb. Anyhow, this is done just first time you run the example.

Note also then when running under Felix version before 1.0.3 you will see quite a lot of stack traces displayed on the screen (if you have logging enabled). Just ignore them as they are only log messages from Felix shown when a class cannot be found and Spring tries to load classes related to bean support, classes that do not exist. This (error messages) are all gone if you use Felix >= 1.0.3.

You can start it up even simpler by using the new war: protocol handler (you need Pax Runner version >= 0.6.0):

pax-run war:file:petclinic.war --profiles=war mvn:org.ops4j.pax.web/pax-web-jsp

As you will see the war: protocol handler will do all that is necessary to directly deploy a war file. Spring PetClinic makes use of JSP so the command line provision also Pax Web JSP Support. Note that in this case the context name will be generated automatically, so you should use http://localhost:8080/file_petclinic.war/ to access the application (upcoming version 0.2.0 of war protocol will permit context name setup).

Using the above mentioned methods involves that Spring Petclinic WAR file is processed first by war: url protocol handler in order to make it a bundle. As the WAR file is particularly large it requires “extensive” resources to process in terms of memory, so you may encounter java.lang.StackOverflowError or java.lang.OutOfMemoryError depending on your execution platform (Windows/*nix) as they differ in “defaults”. To avoid this problems you will have to set some extra start up parameters for JVM, such as:

java.lang.StackOverflowError: \{-Xss`, as for example -Xss=512k
java.lang.OutOfMemoryError: -Xmx, as for example -Xmx256m

It may be that the example values are too much or too less for your case so feel free to experiment.
In order to set this options you have to do the following (example uses both settings but you may only need one of them):

Windows:

set JAVA_OPTS=-Xss512k -Xmx256m
pax-run ...

*nix

export JAVA_OPTS=-Xss512k -Xmx256m
pax-run ...

2.4.5. OSGi-fy your WAR

This page explains what it takes to make a standard war file deployable into OSGi. For detailed information read OSGi Service Platform Core Specification section 3.2 — Module Layer — Bundles. The pages specified bellow refers to Release 4, Version 4.1 April 2007.

The quickest way is for your project to use Maven and utilize Maven Bundle Plugin to generate OSGi manifest for your WAR project. See: Getting the benefits of maven-bundle-plugin in other project types

If you opt for a lower level way, read on…

First of all the war has to be a valid OSGi bundle. As minimum the war file must contain the following manifest headers in META-INF/MANIFEST.MF:

Bundle-ManifestVersion: 2 — This header defines that the bundle follows the rules of R4 specification.
Bundle-SymbolicName — This header specifies a unique, non-localizable name for this bundle. This name should be based on the reverse domain name convention. See Bundle-SymbolicName on page 35.
(optional) Bundle-Version — This header specifies the version of this bundle. The default value is 0.0.0. See Version on page 28.
(optional) Bundle-Name — This header defines a readable name for this bundle. This should be a short, human-readable name that can contain spaces.
(optional) Bundle-Vendor — This header contains a human-readable description of the bundle vendor.
(optional) Bundle-Copyright — This header contains the copyright specification for this bundle.
(optional) Webapp-Context — servlet context path. If not specified Bundle-SymbolicName will be used. Note that this header is a War extender specific header not an OSGi header. Deprecated since 1.0.0 use
(optional) Web-ContextPath — servlet context path, as specified in the OSGi spec. If not specified Bundle-SymbolicName will be used. Note this is a official OSGi header.

If you have this header, will suffice to deploy the war into OSGi. But this is not enough to have it working in most of the situations as OSGi has a very strict class loading policy. So next, you will have to specify how the classes you need in runtime will be found via the following headers:

Bundle-ClassPath — This header defines a comma-separated list of JAR file path names or directories (inside the bundle) containing classes and resources. The period (’.’) specifies the root directory of the bundle’s JAR. The period is also the default. See Bundle Class Path on page 49.
Import-Package — This header declares the imported packages for this bundle. See Import-Package Header on page 36.
(not recommended) Require-Bundle — This header specifies the required exports from another bundle. See Require-Bundle on page 65.

Most likely the above headers will have to have the following values:

Bundle-ClassPath :
- WEB_INF/classes — this will find any class / file in WEB-INF/classes
- lib/<dependency>.jar — you should have an entry for each jar you have in your lib directory, where <dependency> is the name of jar
  So, as an example the header can look like:

Bundle-ClassPath: WEB-INF/classes,lib/commons-logging.jar,lib/spring.jar * Import-Package : should contain any package that your web application depends on but is not included into one of your dependencies that you listed in the Bundle-ClassPath header. Usually a war will not include J2EE apis: javax.servlet - servlet api javax.servlet.http - servlet api
So, as an example the header can look like:
Import-Package: javax.servlet,javax.servlet.http

Now you are ready to deploy your war. If you still get class loading exceptions then is most likely that you did not include all the jars you need in the Bundle-ClassPath or Import-Package.

Preprocess

If you find this process hard to grasp or if you cannot change the manifest of your war or maybe you simple want to automate it take a look at how you can automate it in a static or dynamic way. You may also use War Protocol.

2.4.6. Supported Web Elements

The following is a list showing what elements are supported in both standard http service and Pax Web. If the list bellow does not contain the descriptior element you are looking for it means that is not (yet) supported.

*context name* : name of the context (known as context path)
- Pax Web
- Standard Http Service : servlets/resources will be deployed into the root path (‘`’')
*context params* : <context-param> element in web.xml
- Pax Web
- Standard Http Service
*session timeout* : <session-config> / <session-timeout> element in web.xml
- Pax Web (starting with version 0.4.0)
- Standard Http Service
*servlets* : <servlet> element in web.xml
- Pax Web
- Standard Http Service
*servlets init params* : <servlet><init-param> element in web.xml
- Pax Web
- Standard Http Service
*servlets mapping* : <servlet-mapping> elements in web.xml
- Pax Web
- Standard Http Service : only exact match, no wild card (“*”) support
*filters* : <filter> elements in web.xml
- Pax Web
- Standard Http Service
*filters init params* : <filter><init-param> element in web.xml
- Pax Web
- Standard Http Service
*filters mapping* : <filter-mapping> elements in web.xml; both <url-pattern> and <servlet-name>
- Pax Web
- Standard Http Service
*listeners* : <listener> element in web.xml
- Pax Web
- Standard Http Service
*error pages* : <error-page> element in web.xml
- Pax Web
- Standard Http Service
*welcome files* : <welcome-file-list> element in web.xml
- Pax Web
- Standard Http Service
*mime mappings* : <mime-mapping> elements in web.xml
- Pax Web
- Standard Http Service

2.4.7. WAR Extender FAQ

Is the order the bundles are installed / started important?

No. Http service (Pax Web), war extender or your war bundle(s) can be installed / uninstalled / started / stopped in any order. Everything will function as you expect.

What will happen if I stop / uninstall my war?

All the registered elements for the web application corresponding to the stopped war (servlet context, servlets, resources, filters, listeners) will be unregistered.

What if I restart it? Or update it?

A new web application corresponding to your war will be registered.

What happens if I stop / uninstall the http service?

All deployed web applications will be unregistered.

What if I restart it?

New web applications will be registered for all deployed wars.

What happens if I stop / uninstall the pax war extender?

All deployed web applications will be unregistered.

What if I restart it?

New web applications will be registered for all deployed wars.

I have a standard war. Can I deploy it into an OSGi framework?

Yes, OSGi-fy-your-WAR tells you how you can do that.

I do not want / can change the war. Can I still deploy it?

Yes, you can do that in a static or dynamic way.

Now that I deployed my war, how can I get a service from OSGi Service Registry?

A deployed war is as any OSGi bundle. A bundle accesses the OSGi framework’s services through the bundle’s BundleContext. To enable a web application to access its BundleContext you must develop a BundleActivator and add the Bundle-Activator manifest header. This BundleActivator should store the BundleContext in a location that is accessible by the application’s servlets, filters or listeners. You can achieve this by using a static field/method set by your BundleActivator or store it in a ServletContext attribute.

My application uses JSPs. Are them supported?

Yes, JSPs are supported via Pax Web Extensions. Take a look at how you can enable JSP support.

How can I set the servlet context path?

Pax Web War extender will use as servlet path by default the symbolic name of the bundle. If you want to change that you can set the Webapp-Context manifest attribute to the name you want. This attribute should be set into the manifest (MANIFEST.MF) of the bundle that contains the web app (same bundle as the one containing the web.xml file). For example:

Web-ContextPath: myApp

2.5. Whiteboard Extender

Pax Web Extender Whiteboard is an extender bundle that ease the pain of registering servlets, resources, filters and listeners and keeping track of Http Service availability.
Note it is not mandatory for the extender to work with Pax Web, it can work with any Http Service implementation.

2.5.1. Keeping track of Http Service availability

There are many situations that you have to handle as a bundle developer to keep track of http service availability:

The Http Service is not present
The Http Service gets started after your bundle starts
The service gets unregister during the lifetime of your servlet
A new service gets registered

Pax Web Extender handles all of this cases for you. You just have to have a servlet (smile)

2.5.2. How does it work:

Publish your web elements using one of the methods below;
Start the Pax Web Extender bundle. It does not matter if the Extender starts before or after you bundle or if is not even installed by the time your bundle starts.

2.5.3. What Extender will do:

Once it starts it will find out all published web elements;
Once a http service become available (including the moment when Extender starts) it will register all the published web elements;
If the in use http service gets unregister it will automatically unregister the (already) registered web elements;
If you register a web element as a service it will register it automatically with the http service in use (if any);
If you unregister a web element it will unregister it automatically from the http service (if was registered before);
If you stop your bundle all registered web elements are automatically unregistered

2.5.4. How does it help on servlet registration

Usually you will have to register servlets by getting an http service and registering each servlet you have with the http service.
By using the whiteboard approach you will just have to register each servlet that you expect to be published to an http service under the Servlet interface (see in jira):

Dictionary props = new Hashtable();
props.put( "alias", "/whiteboard" );
props.put("servlet-name", "My Servlet");
bundleContext.registerService( Servlet.class.getName(), new MyServlet(), props );

This is all you have to do to register a servlet. As you can see there is no necessity to lookup a http service or to track it’s availability.

Nice to know: your bundle will not have to import/depend on Http Service packages.

Registering with Servlet names becomes necessary if you want to register a Filter against it. See below.
Starting with version 4.1.x it is possible to register Annotated Servlets as services. Those annotations are interpreted in the same way as properties. This way properties may be neglected.

2.5.5. How does it help on resource registration

Usually you will have to register resources by getting an http service and registering each resource dir you have with the http service.
By using the whiteboard approach you will just have to register each resource dir that you expect to be published to an http service under the Resources class (see in jira):

import org.ops4j.pax.web.extender.whiteboard.ResourceMapping;
import org.ops4j.pax.web.extender.whiteboard.runtime.DefaultResourceMapping;
...
DefaultResourceMapping resourceMapping = new DefaultResourceMapping();
resourceMapping.setAlias( "/whiteboardresources" );
resourceMapping.setPath( "/images" );
bundleContext=bundleContext.registerService( ResourceMapping.class.getName(), resourceMapping, null );

Don’t forget to import org.ops4j.pax.web.extender.whiteboard package.

This is all you have to do to register resources. As you can see there is no necesity to lookup a http service or to track it’s availablity. The resources are served upon exact match, so listing directories in this fashion is not supported right now.

Note: your bundle must import org.ops4j.pax.web.extender.whiteboard package.

2.5.6. How does it help on filter registration

Filters can be registered against URL Patterns and/or against Servlets (identified using their names).

Dictionary props = new Hashtable();
String[] urls = {"/foo", "/protected"};
String[] servlets = {"My Servlet", "Faces Servlet"};
props.put("filter-name", "My Crazy Filter");
props.put("urlPatterns", urls);
props.put("servletNames", servlets);
bundleContext.registerService(Filter.class.getName(), new MyCrazyFilter(), props );

For URL Patterns, the pattern registered must be already mapped, either as Resource or a Servlet alias - e.g there should already be a Resource or aServlet registered to the path /foo.
For Servlet names, the names used should have been the name that has been explicitly given to the Servlet (as servlet-name), when registering.

2.5.7. How does it help on listener registration

Following specialization of java.util.EventListener are tracked by the Whiteboard-Extender:

javax.servlet.ServletContextListener
javax.servlet.ServletContextAttributeListener
javax.servlet.ServletRequestListener
javax.servlet.ServletRequestAttributeListener

2.5.8. Web elements

By web elements we mean any of http context, servlet, resources, filter, listener.

2.5.9. Whiteboard Examples

Whiteboard Extender includes a set of examples that demonstrates its usage.

The following is outdated and subject to change.

Whiteboard

The whiteboard example publishes web elements supported by whiteboard extender. To run the example you have to deploy to your preferred OSGi framework the following bundles:

Pax Web version >= 0.3.1
Whiteboard Extender version >= 0.3.0
Whiteboard example
(optional) Pax Logging — if you want to see also the log output

Alternatively you can easy do the deployment using Pax Runner:

pax-run scan-file:jar:mvn:org.ops4j.pax.web-extender.samples/provision!/sample-whiteboard.bundles

Once you have everything running point your browser to:

http://localhost:8080/whiteboard — to see a simple servlet output
http://localhost:8080/ — to see a simple servlet output mapped to root
http://localhost:8080/whiteboardresources/ops4j.png – to get a logo registered by publishing a resource
http://localhost:8080/forbidden/ — to try to access a security protected servlet
http://localhost:8080/whiteboard/filtered — to access the whiteboard filter (see above) but through a filter
on any request you can take a look in the java console to see a request filter in action

2.6. Installing using Karaf-features

Pax Web provides a set of feature-descriptors for Apache Karaf for convenient installation. To enable these features, add them in Karaf using the following command:

features:addurl mvn:org.ops4j.pax.web/pax-web-features/4.4.0/xml/features

When you type features:list now, you will see the following features available:

State         Version           Name                          Repository              Description
[uninstalled] [4.4.0] pax-jetty                     org.ops4j.pax.web-4.4.0 Provide Jetty engine support
[uninstalled] [4.4.0] pax-http                      org.ops4j.pax.web-4.4.0 Implementation of the OSGI HTTP Service
[uninstalled] [4.4.0] pax-http-whiteboard           org.ops4j.pax.web-4.4.0 Provide HTTP Whiteboard pattern support
[uninstalled] [4.4.0] pax-war                       org.ops4j.pax.web-4.4.0 Provide support of a full WebContainer

You can now install each of these features using features:install.

2.7. JSP Usage

2.7.1. Usage guidelines for working with JSPs

This page will give you some guidelines how to use the most out of pax web regarding JSPs.

First of all get to know the possible jsp configuration properties, these might help you already.

Provided packages by the JSP bundle

Following packages are exported by the JSP bundle of Pax Web:

JSP in version 1.1.2

javax.servlet.jsp; version="1.1.2"
javax.servlet.jsp.el; version="1.1.2"
javax.servlet.jsp.jstl.core; version="1.1.2"
javax.servlet.jsp.jstl.fmt; version="1.1.2"
javax.servlet.jsp.jstl.sql; version="1.1.2"
javax.servlet.jsp.jstl.tlv; version="1.1.2"

JSP in version 2.1

javax.servlet.jsp; version="2.1"
javax.servlet.jsp.el; version="2.1"
javax.servlet.jsp.jstl.core; version="2.1"
javax.servlet.jsp.jstl.fmt; version="2.1"
javax.servlet.jsp.jstl.sql; version="2.1"
javax.servlet.jsp.jstl.tlv; version="2.1"
javax.servlet.jsp.resources; version="2.1"
javax.servlet.jsp.tagext; version="2.1"

Javax el in version 2.1

javax.el;version="2.1.0"
com.sun.el;version="2.1.0.v20091210"
com.sun.el.lang;version="2.1.0.v20091210"
com.sun.el.parser;version="2.1.0.v20091210"
com.sun.el.util;version="2.1.0.v20091210"

Jasper compiler

org.apache.jasper;version="2.1.0.v20091210"
 org.apache.jasper.compiler;version="2.1.0.v20091210"
 org.apache.jasper.compiler.tagplugin;version="2.1.0.v20091210"
 org.apache.jasper.resources;version="2.1.0.v20091210"
 org.apache.jasper.runtime;version="2.1.0.v20091210"
 org.apache.jasper.security;version="2.1.0.v20091210"
 org.apache.jasper.servlet;version="2.1.0.v20091210"
 org.apache.jasper.tagplugins.jstl;version="2.1.0.v20091210"
 org.apache.jasper.util;version="2.1.0.v20091210"
 org.apache.jasper.xmlparser;version="2.1.0.v20091210"

Standard Taglibs

org.apache.taglibs.standard
org.apache.taglibs.standard.extra.spath
org.apache.taglibs.standard.functions
org.apache.taglibs.standard.lang.jstl
org.apache.taglibs.standard.lang.jstl.parser
org.apache.taglibs.standard.lang.jstl.test
org.apache.taglibs.standard.lang.jstl.test.beans
org.apache.taglibs.standard.lang.support
org.apache.taglibs.standard.resources
org.apache.taglibs.standard.tag.common.core
org.apache.taglibs.standard.tag.common.fmt
org.apache.taglibs.standard.tag.common.sql
org.apache.taglibs.standard.tag.common.xml
org.apache.taglibs.standard.tag.el.core
org.apache.taglibs.standard.tag.el.fmt
org.apache.taglibs.standard.tag.el.sql
org.apache.taglibs.standard.tag.el.xml
org.apache.taglibs.standard.tag.rt.core
org.apache.taglibs.standard.tag.rt.fmt
org.apache.taglibs.standard.tag.rt.sql
org.apache.taglibs.standard.tag.rt.xml
org.apache.taglibs.standard.tei
org.apache.taglibs.standard.tlv

Eclipse Compiler for compiling JSP pages

org.eclipse.jdt.core
org.eclipse.jdt.core.compiler
org.eclipse.jdt.core.compiler.batch
org.eclipse.jdt.internal.antadapter
org.eclipse.jdt.internal.compiler
org.eclipse.jdt.internal.compiler.apt.dispatch
org.eclipse.jdt.internal.compiler.apt.model
org.eclipse.jdt.internal.compiler.apt.util
org.eclipse.jdt.internal.compiler.ast
org.eclipse.jdt.internal.compiler.batch
org.eclipse.jdt.internal.compiler.classfmt
org.eclipse.jdt.internal.compiler.codegen
org.eclipse.jdt.internal.compiler.env
org.eclipse.jdt.internal.compiler.flow
org.eclipse.jdt.internal.compiler.impl
org.eclipse.jdt.internal.compiler.lookup
org.eclipse.jdt.internal.compiler.parser
org.eclipse.jdt.internal.compiler.parser.diagnose
org.eclipse.jdt.internal.compiler.problem
org.eclipse.jdt.internal.compiler.tool
org.eclipse.jdt.internal.compiler.util

2.7.2. How do JSPs work with Pax Web?

Standard JSPs are handled by Pax Web through a specialized Servlet that does use the Jasper compiler with a extra class loader. This class loader takes the current bundle (the war) and its containing jars into account for compiling the JSP files. Tag libs are searched within this war and it’s containing jars. With version 1.1.0 the bundles which are imported by the war are also taken into the class loader for searching the right TLD files.

2.7.3. How do JSF work with Pax Web?

Since version 1.0.2 and 1.1.0 JSF is supported by Pax Web.

Standard war files should work out of the box since Pax Url - 1.3.0 does optionally import the exported packages of Pax Web.

For Web Application Bundles - war archives with Manifest - it is required not only to import the javax.el package but also the implementation of it which is com.sun.el.*

3. Developer Guide

The following guides details different aspects of Pax Web internals and are aimed towards developers that wants to understand the inner workings of Pax Web and/or develop/maintain current code base of Pax Web and/or develop extensions in top of Pax Web.

3.1. Source

3.1.1. Checkout source code

You can checkout the source code of Pax Web by using the following command:

git clone git://github.com/ops4j/org.ops4j.pax.web.git

or you may use your IDE specific support for Git.

3.1.2. Browse source code

You can browse the source code by pointing your browse to http://github.com/ops4j/org.ops4j.pax.web.

3.2. Build

The following instructions are explaining how to build Pax Web by using Apache Maven. You may also use another means for building as for example your preferred IDE, since most IDE’s will support Maven.

To build Pax Web follow this steps:

Download and install Apache Maven
Download the latest source from OPS4J Pax Web GIT Repository
In a terminal window go the the root folder where you have downloaded the source and execute the following command:
```
mvn install
```

3.3. Artifacts

3.3.1. pax-web-api

This artifact contains Pax Web API which are the classes that are added in extension to standard HTTP Service. This is the only artifact you should depend, at compile time, if you are in need of Pax Web extensions.

3.3.2. pax-web-spi

This artifact contains the interfaces that should be implemented by a service provider wishing to provide an alternative implementation that is not Jetty based. The Jetty artifact implements this SPI in order to be used by Pax Web Runtime.

3.3.3. pax-web-runtime

This artifact is the core of Pax Web (the engine if you like so). It implements the API and will make use of an SPI, such as Jetty in order to fulfill is job.

3.3.4. pax-web-jsp

This artifact contains Pax Web JSP support based on Jasper. It is an optional component that will be used by runtime if present. If you do not use JSPs in your project you can leave this artifact out of your deployment setup.

3.3.5. pax-web-jetty

This artifact is the Jetty based implementation of SPI. This artifact does not include Jetty, so you will have to deploy Jetty along by yourself. The reason behind not including Jetty is to allow you to make your choice about the version of Jetty to be used, as for example, in case that a new version of Jetty is available and you are in need to use it.

3.3.6. pax-web-jetty-bundle

This artifact is a convenience artifact that bundles together most of the artifacts above plus a version of jetty. This in order to make your deployment easier. It includes the following: pax-web-api, pax-web-spi, pax-web-runtime, pax-web-jetty and necessary jetty bundles. Basically, if you deploy this bundle you are good to go without any additional bundles (beside the jsp or extenders that you should deploy as you need).

3.3.7. pax-web-extender-war

This artifact is the implementation of Pax Web WAR Extender and should be included in case that you want to deploy WAR files into the OSGi framework.

3.3.8. pax-web-extender-whiteboard

This artifact is the implementation of Pax Web Whiteboard Extender and should be included if you wish to publish your web elements simply by registering them as a service.