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
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 | 126.96.36.199 | OPS4J Pax Tipi - undertow-core 86 | Active | 40 | 188.8.131.52 | OPS4J Pax Tipi - undertow-servlet 87 | Active | 40 | 184.108.40.206 | OPS4J Pax Tipi - xnio-api 88 | Active | 40 | 220.127.116.11 | 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 | 18.104.22.168305092017 | 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
you should see an empty page.
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
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
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
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.
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
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?
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
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
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|
Used to assign a configuration to a given bundle
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
@HandlesTypesannotation is currently ignored.
Annotation scanning is supported. Pax Web will discover classes annotated with
@WebListenercontained 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
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
When using Karaf, edit
etc/config.properties as follows:
org.osgi.framework.system.packages.extra= \ com.sun.org.apache.xalan.internal.res, \ com.sun.org.apache.xml.internal.utils, \ com.sun.org.apache.xml.internal.utils, \ com.sun.org.apache.xpath.internal, \ com.sun.org.apache.xpath.internal.jaxp, \ com.sun.org.apache.xpath.internal.objects, \ 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
and the corresponding integration test
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:
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.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://github.com/ops4j/org.ops4j.pax.web.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
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:
This section describes the individual bundles and other artifacts provided by Pax Web 5.x.
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
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.
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.
pax-web-extender monitors web application bundles, identified by the
header, parses their deployment metadata and deploys them to the servlet container.
This artifact contains feature definitions to provision Pax Web in Apache Karaf 3.0.0 or higher.
This artifact contains some helper classes to implement JAAS based login configurations for web applications.
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.
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
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.