OSGi R5 Http Service and Web Applications implementation using Undertow.

1. Introduction

Pax Web 5.x is a servlet container for OSGi web applications. The 5.x release line is currently experimental and significantly different from the stable 3.x and 4.x release lines.

For a stable OSGi servlet container, please take a look at Pax Web 4.x.

Pax Web 5.x explores some new technologies, and at the same time narrows its scope compared to the stable releases, with the ultimate goal of merging the 4.x and 5.x release lines, once the new features of Pax Web 5 have stabilized.

1.1. Functional Goals

  • Implement Web Applications Specification 1.0 (OSGi Enterprise 5, Section 128).

  • Implement Http Service Specification 1.2 (OSGi Enterprise 5, Section 102).

  • Support additional features of Servlet 3.1 Specification.

  • Support JSF, CDI and JSP in Web Application Bundles.

  • Support JSF and JSP libraries in separate bundles.

  • Support Equinox and Felix (OSGi 5.0.0 or higher).

  • Provide Karaf Features (for Apache Karaf 3.0.1 or higher).

  • Java EE 7 API compatibility.

1.2. Design Goals

  • Integrate (an OSGified version of) the Undertow servlet container.

  • Integrate the JSF 2.2 reference implementation (Mojarra 2.2.8 or higher).

  • Simplify OSGi service dependency tracking based on Declarative Services (including DS annotations).

  • Simplify the interaction with Pax CDI.

1.3. Non-Goals for the short term

  • Support for Jetty or Tomcat (but still provide a SPI for other web containers)

  • API compatibility with Pax Web ⇐ 4.x.

1.4. Long Term Goal

  • Merge with the master branch so that a future Pax Web release will support Jetty, Tomcat and Undertow

2. User Guide

This guide explains the usage of Pax Web for developers wishing to build their own OSGi-enabled web applications. The reader is expected to be familiar with the OSGi and Servlet specifications.

2.1. Getting Started

Pax Web can run on any OSGi framework. For OSGi novices, it may be easier to work with Apache Karaf, an OSGi runtime environment including a powerful shell and advanced provisioning and configuration methods.

OSGi experts may prefer to directly work with Pax Web bundles and their dependencies on a standalone OSGi framework implementation.

Both approaches are possible - Pax Web does not depend on Karaf.

2.1.1. Getting started on Apache Karaf


Apache Karaf is a convenient environment for getting started with Pax Web, thanks to Pax Web Karaf features which let you install Pax Web and its dependencies with a few simple commands.

First of all, download and install a distribution of Apache Karaf 3.0.1 or higher. Unpack the distribution and run


to start Karaf. Wait for the Karaf shell prompt to appear.

Then enter the following commands

karaf@root()> feature:repo-add mvn:org.ops4j.pax.web/pax-web-features/5.0.0/xml/features
karaf@root()> feature:install pax-web-undertow

replacing the version 5.0.0 of Pax Web by the version you are actually using. Listing the installed bundles by entering

karaf@root()> la

you should see the following output:

 78 | Active   |  30 | 1.3.2                 | Apache Felix EventAdmin
 79 | Active   |  30 | 1.0.10                | Apache Felix Metatype Service
 80 | Active   |  30 | 1.8.2                 | Apache Felix Declarative Services
 81 | Active   |  30 | 3.0.1                 | Apache Karaf :: SCR :: Shell Commands
 82 | Active   |  40 | 3.1.0                 | Java Servlet API
 83 | Active   |  40 | 1.2                   | javax.annotation API
 84 | Active   |  40 | 3.1.4.GA              | JBoss Logging 3
 85 | Active   |  40 |              | OPS4J Pax Tipi - undertow-core
 86 | Active   |  40 |              | OPS4J Pax Tipi - undertow-servlet
 87 | Active   |  40 |               | OPS4J Pax Tipi - xnio-api
 88 | Active   |  40 |               | OPS4J Pax Tipi - xnio-nio
 89 | Active   |  40 | 5.0.2                 | ASM all classes with debug info
 90 | Active   |  40 | 3.18.0                | Apache XBean OSGI Bundle Utilities
 91 | Active   |  40 | 3.18.0                | Apache XBean :: Classpath Resource Finder
 92 | Active   |  40 |    | osgi.cmpn
 93 | Active   |  40 | 1.4.0                 | OPS4J Base - Service Provider Access
 94 | Active   |  40 | 1.4.0                 | OPS4J Base - IO
 95 | Active   |  40 | 0.0.2                 | Apache Felix JAAS Support
 96 | Active   |  40 | 5.0.0.SNAPSHOT        | OPS4J Pax Web - Service Provider Interface
 97 | Active   |  40 | 5.0.0.SNAPSHOT        | OPS4J Pax Web - Web Bundle Extender
 98 | Active   |  40 | 5.0.0.SNAPSHOT        | OPS4J Pax Web - Undertow Adapter
 99 | Active   |  40 | 5.0.0.SNAPSHOT        | OPS4J Pax Web - Deployment Descriptor Model
100 | Active   |  40 | 5.0.0.SNAPSHOT        | OPS4J Pax Web - JAAS Authentication Support

Pax Web is now listening on the default port 8080. Opening a web browser on http://localhost:8080, you should see an empty page.

The pax-web-undertow feature contains a minimal configuration of Pax Web with the Undertow Servlet Container, not including any support for JSP, JSF or CDI.

The latter are supported by additional Karaf features

  • pax-web-jsp

  • jsf-mojarra

  • pax-web-undertow-cdi-1.2-weld

Deploying Web Bundles

You can install any web application bundle (WAB) using the Karaf console:

karaf@root()> bundle:install mvn:org.ops4j.pax.web.samples/pax-web-sample-static/5.0.0
Bundle ID: 106
karaf@root()> start 106

After starting the bundle, you can open http://localhost:8080/sample-static in your web browser. The context path of the web application is determined by the Web-ContextPath manifest header of the web bundle.

After installing the pax-web-deployer bundle or the pax-web-war feature, you can deploy a bundle via the file system, by simply copying it to $KARAF_HOME/deploy.

Deploying plain old WARs

Once you have installed the pax-web-war feature via

karaf@root()> feature:install pax-web-war

file system deployment via $KARAF_HOME/deploy even works for ordinary web archives, lacking the OSGi manifest headers.

A suitable OSGi manifest is generated on the fly by the Pax URL war: protocol handler.

You can also use this special URL protocol to deploy plain old WARs from the Karaf shell:

karaf@root()> install war:mvn:org.ops4j.pax.web.samples/pax-web-sample-war/5.0.0/war?Web-ContextPath=/sample-war
Bundle ID: 107
karaf@root()> start 107
Changing the configuration

Pax Web can be configured using the OSGi Configuration Admin service. In Karaf, changing the configuration is as easy as creating or editing a file named org.ops4j.pax.web.undertow.cfg in the $KARAF_HOME/etc directory.

For example, to change the HTTP port used by Pax Web, create or edit the following property in this file:

org.osgi.service.http.port = 9876

See the Configuration section for more details on configuration properties.

2.1.2. Getting started on plain OSGi

If you plan to work with Pax Web on a stand-alone OSGi framework, you will require a number of bundle dependencies, in addition to Pax Web’s own bundles.

Even when not using Karaf, looking at Pax Web’s feature repository file may be the easiest way to find the required dependencies. Alternatively, you can take a look at Pax Web’s integration tests as a starting point for your own setup.

For file system deployments and file-based configuration, you should include the Apache Felix File Install bundle.

2.2. Configuration

2.2.1. Overview

Pax Web can be configured using configuration properties provided by the OSGi Configuration Admin service, as OSGi framework properties or as Java system properties.

There are two levels of configuration: per server and per deployment.

Per deployment configuration is only supported via Configuration Admin.

2.2.2. Server-level Configuration Properties

Property key Default value Meaning


Comma-separated list of virtual host names<hostname>.aliases

Comma-separated list of aliases for a virtual host



SSL Keystore format


Password for the keystore



Access log format



Is the access log enabled?



Is the HTTP protocol enabled?



HTTP port


HTTPS port


Is the HTTPS protocol enabled?

While looking for a configuration property, Pax Web will first use the property configured via Configuration Admin. If the property is not found, it will look for a framework property with the same name, falling back to a system property of the same name. If no property is defined, a default value is applied as indicated above.

The PID used for Configuration Admin is org.ops4j.pax.web.undertow.

2.2.3. Deployment-level Configuration Properties

Pax Web supports deployment-level configuration via Configuration Admin, letting the user override the context path or assign the deployment to a given virtual host.

This mechanism is based on a factory configuration with PID org.ops4j.pax.web.deployment.

For each deployment, Pax Web applies a configuration of this PID where the property bundle.symbolicName matches the bundle symbolic name of the deployment or generates a default configuration from the bundle manifest.

The following properties are supported:

Property key Default value Meaning


Value of Bundle-SymbolicName manifest header

Used to assign a configuration to a given bundle


Value of Web-ContextPath manifest header

Overrides the web context path for the given deployment.

Name of virtual host for this deployment. The host must be configured at server level.

2.3. Special Features

2.3.1. General Information

The OSGi Web Applications Specification 1.0 is based on Servlet 2.5, whereas the current Java EE 7 umbrella specification includes Servlet 3.1.

Pax Web aims at filling the gap by supporting a subset of additional Java EE 7 features from the Servlet, JSP, JSF and CDI specifications. Features not mentioned explicitly in this section are not currently covered by integration tests and may or may not work.

2.3.2. Servlet 3.0+ Capabilities

  • Servlet container initializers are supported, but the @HandlesTypes annotation is currently ignored.

  • Annotation scanning is supported. Pax Web will discover classes annotated with @WebServlet, @WebFilter and @WebListener contained in a web bundle.

2.3.3. Java Server Pages (JSP)

Java Server Pages are supported by the optional pax-web-jsp bundle which depends on the Jasper component from the Apache Tomcat project and on the Eclipse Java Compiler (ECJ).

Working with Karaf, you can install the pax-web-jsp Karaf feature to enable JSP support with all required dependencies.

In order to use tag libraries from other bundles, your web bundles must be wired to the required tag library bundles, e.g. by Require-Bundle.

2.3.4. Java Server Faces (JSF)

Pax Web supports the JSF 2.2 reference implementation Mojarra by means of the optional Karaf feature jsf-mojarra. JSF is also supported in stand-alone OSGi mode, if you take care to manually install the required dependencies listed in the Karaf feature.

Note that the Mojarra feature (or more precisely, the JSTL implementation) requires a number of additional system packages which need to be appended to the org.osgi.framework.system.packages.extra property.

When using Karaf, edit etc/ as follows:

org.osgi.framework.system.packages.extra= \, \, \, \, \, \, \
 org.apache.karaf.branding, \
 org.apache.html.dom; version="2.11.0", \

In order to use JSF components from other bundles, your web bundles must be wired to the required component bundles, e.g. by Require-Bundle. See the included sample pax-web-sample-primefaces and the corresponding integration test PrimeFacesTest.

2.3.5. Contexts and Dependency Injection (CDI)

Pax Web also supports CDI 1.1 and 1.2 by integrating Pax CDI. CDI and JSF support do not depend on each other, but can be used in combination.

At the moment, Weld is the only CDI implementation supporting CDI 1.1 or higher. Pax Web provides the following optional Karaf features including Weld 2.1.x for CDI 1.1 or Weld 2.2.x for CDI 1.2:

  • pax-web-undertow-cdi-1.1-weld

  • pax-web-undertow-cdi-1.2-weld

Again, CDI support does not require Karaf. Stand-alone OSGi users should simply derive the list of required bundles from the feature definition and install them manually.

2.4. Http Service Extensions

Pax Web 5.x does not include any of the OSGi Http Service extensions provided by Pax Web 4.x.

These are expected to be superseded by the new Http Whiteboard specification published with the OSGi Enterprise 6 draft.

3. Developer Guide

This guide explains the design and the development process of Pax Web.

It is aimed at developers wishing to understand the internals of Pax Web or to contribute to the code base.

3.1. Source

3.1.1. Checkout source code

You can check out the source code of Pax Web and switch to the 5.x branch by using the following commands:

git clone git://
cd org.ops4j.pax.web
git checkout undertow

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 browser to

3.2. Build

This chapter explains 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 IDEs will support Maven.

To build Pax Web follow these steps:

  • Download and install Apache Maven

  • Check out the latest source from the OPS4J Pax Web GitHub 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

This section describes the individual bundles and other artifacts provided by Pax Web 5.x.

3.3.1. pax-web-deployer

This artifact is an optional bundle which supports file system deployment of traditional WARs without an OSGi manifest. This feature is based on Apache Felix File Install and the Pax URL WAR protocol handler (more specifically, the webbundle: protocol).

3.3.2. pax-web-descriptor

pax-web-descriptor contains a JAXB model of the web.xml deployment descriptor generated from the corresponding XML schema. This model is used at run-time to unmarshal deployment descriptors and to transport deployment metadata between Pax Web bundles.

3.3.3. pax-web-extender

This artifact implements the OSGi extender pattern for web application bundles. In general, an OSGi extender listens to bundle events and adds functionality to some of the observed bundles.

The pax-web-extender monitors web application bundles, identified by the Web-ContextPath manifest header, parses their deployment metadata and deploys them to the servlet container.

3.3.4. pax-web-features

This artifact contains feature definitions to provision Pax Web in Apache Karaf 3.0.0 or higher.

3.3.5. pax-web-jaas

This artifact contains some helper classes to implement JAAS based login configurations for web applications.

3.3.6. pax-web-jsp

This artifact contains JSP support based on Jasper and some other modules of Apache Tomcat 8.x. It is an optional component that will be used by the runtime if present. If you do not use JSPs in your project, you can leave out this artifact from your setup.

3.3.7. pax-web-spi

This artifact contains some model classes and interfaces to be implemented for a specific servlet container adapter. This service provider interface (SPI) currently has just one implementation in pax-web-undertow.

3.3.8. pax-web-undertow

This artifact implements the pax-web-spi service provider interface based on Undertow. It does not include Undertow, so you will have to provision Undertow separately.

Note that the official Undertow artifacts and their XNIO dependencies currently do not include OSGi headers in their manifests.

For this reason, OPS4J provides OSGified versions of these artifacts in the Pax Tipi project.