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
.
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 |
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) |
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 |
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) |
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) |
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
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
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.
|
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 );
|
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
-
(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.