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

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)

Filters

Register filters

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

filter The filter 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)

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)

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

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

JSP

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

Why

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)