Pax Web extends OSGi Http Service with the following according to latest developments of Servlet specs (see also Pax Web Extender if you would like to deploy a WAR file):
In order to make use of this extensions you will have to look for a WebContainer instead of HttpService as in:
bundleContext.getServiceReference(org.ops4j.pax.web.service.WebContainer.getClass().getName());
public interface WebContainer
This Web Container allows bundles to dynamically:
- set context parameters for a Http Context
- register and unregister servlets with multiple url mappings (including wild card '*' support)
- register and unregister event listeners, for better control over the life cycle of ServletContext, HttpSession and ServletRequest;
- register and unregister filters into the URI namespace of Http Service (including wild card '*' support)
- register and unregister error pages
- register and unregister welcome files
- register and unregister JSP support
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.
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)
|
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.
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)
|
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.
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)
|
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 "/"
|
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
|
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 |
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
|
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) |
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) |
