org.ops4j.pax.web.service
Interface WebContainer

All Superinterfaces:

org.osgi.service.http.HttpService

public interface WebContainer
extends org.osgi.service.http.HttpService

WebContainer allows bundles to dynamically:
* 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

Since:

0.5.2

Author:

Alin Dreghiciu

Method Summary

SharedWebContainerContext	getDefaultSharedHttpContext()
void	registerErrorPage(String error, String location, org.osgi.service.http.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.
void	registerEventListener(EventListener listener, org.osgi.service.http.HttpContext httpContext) Registers an event listener.
void	registerFilter(javax.servlet.Filter filter, String[] urlPatterns, String[] servletNames, Dictionary initparams, org.osgi.service.http.HttpContext httpContext) Registers a servlet filter.
void	registerJsps(String[] urlPatterns, org.osgi.service.http.HttpContext httpContext) Enable jsp support.
void	registerServlet(javax.servlet.Servlet servlet, String[] urlPatterns, Dictionary initParams, org.osgi.service.http.HttpContext httpContext) Registers a servlet.
void	registerServlet(javax.servlet.Servlet servlet, String servletName, String[] urlPatterns, Dictionary initParams, org.osgi.service.http.HttpContext httpContext) Registers a named servlet. A named servlet can then be referenced by name while registering a filter.
void	registerWelcomeFiles(String[] welcomeFiles, boolean redirect, org.osgi.service.http.HttpContext httpContext) Registers an ordered list of partial URIs.
void	setContextParam(Dictionary params, org.osgi.service.http.HttpContext httpContext) Sets context paramaters to be used in the servlet context corresponding to specified http context.
void	setSessionTimeout(Integer minutes, org.osgi.service.http.HttpContext httpContext) Sets the session timeout of the servlet context corresponding to specified http context.
void	unregisterErrorPage(String error, org.osgi.service.http.HttpContext httpContext) Unregisters a previous registered error page.
void	unregisterEventListener(EventListener listener) Unregisters a previously registered listener.
void	unregisterFilter(javax.servlet.Filter filter) Unregisters a previously registered servlet filter.
void	unregisterJsps(org.osgi.service.http.HttpContext httpContext) Unregister jsps and disable jsp support.
void	unregisterServlet(javax.servlet.Servlet servlet) Unregisters a previously registered servlet.
void	unregisterWelcomeFiles(org.osgi.service.http.HttpContext httpContext) Unregisters previous registered welcome files.

Methods inherited from interface org.osgi.service.http.HttpService

createDefaultHttpContext, registerResources, registerServlet, unregister

Method Detail

registerServlet

void registerServlet(javax.servlet.Servlet servlet,
                     String[] urlPatterns,
                     Dictionary initParams,
                     org.osgi.service.http.HttpContext httpContext)
                     throws javax.servlet.ServletException

Registers a servlet.

Parameters:

servlet - a servlet. Cannot be null.

urlPatterns - url patterns this servlet maps to

initParams - initialization arguments for the servlet or null if there are none. This argument is used by the servlet�s ServletConfig object.

httpContext - the http context this servlet is for. If null a default http context will be used.

Throws:

IllegalArgumentException - if servlet is null, urlPattern is null or empty, or urlPattern is invalid

javax.servlet.ServletException - if servlet was already registered

registerServlet

void registerServlet(javax.servlet.Servlet servlet,
                     String servletName,
                     String[] urlPatterns,
                     Dictionary initParams,
                     org.osgi.service.http.HttpContext httpContext)
                     throws javax.servlet.ServletException

Registers a named servlet.
A named servlet can then be referenced by name while registering a filter.

Parameters:

servlet - a servlet. Cannot be null.

servletName - servlet name. If null, acts as for the registration method that does not take a servlet name

urlPatterns - url patterns this servlet maps to

initParams - initialization arguments for the servlet or null if there are none. This argument is used by the servlet�s ServletConfig object.

httpContext - the http context this servlet is for. If null a default http context will be used.

Throws:

IllegalArgumentException - if servlet is null, urlPattern is null or empty, or urlPattern is invalid

javax.servlet.ServletException - if servlet was already registered

unregisterServlet

void unregisterServlet(javax.servlet.Servlet servlet)

Unregisters a previously registered servlet.

Parameters:

servlet - the servlet to be unregistered

Throws:

IllegalArgumentException - if the servlet is null

registerEventListener

void registerEventListener(EventListener listener,
                           org.osgi.service.http.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.

Parameters:

listener - an event listener to be registered. If null an IllegalArgumentException is thrown.

httpContext - the http context this listener is for. If null a default http context will be used.

unregisterEventListener

void unregisterEventListener(EventListener listener)

Unregisters a previously registered listener.

Parameters:

listener - the event listener to be unregistered.

Throws:

IllegalArgumentException - if the listener is unknown to the http service (never registered or unregistered before) or the listener is null

registerFilter

void registerFilter(javax.servlet.Filter filter,
                    String[] urlPatterns,
                    String[] servletNames,
                    Dictionary initparams,
                    org.osgi.service.http.HttpContext httpContext)

Registers a servlet filter.

Parameters:

filter - a servlet filter. If null an IllegalArgumentException is thrown.

urlPatterns - url patterns this filter maps to

servletNames - servlet names this filter maps to

initparams - initialization arguments for the filter or null if there are none. This argument is used by the filters�s FilterConfig object.

httpContext - the http context this filter is for. If null a default http context will be used.

unregisterFilter

void unregisterFilter(javax.servlet.Filter filter)

Unregisters a previously registered servlet filter.

Parameters:

filter - the servlet filter to be unregistered

Throws:

IllegalArgumentException - if the filter is unknown to the http service (never registered or unregistered before) or the filter is null

setContextParam

void setContextParam(Dictionary params,
                     org.osgi.service.http.HttpContext httpContext)

Sets context paramaters to be used in the servlet context corresponding to specified http context. This method must be used before any register method that uses the specified http context, otherwise an IllegalStateException will be thrown.

Parameters:

params - context parameters for the servlet context corresponding to specified http context

httpContext - http context. Cannot be null.

Throws:

IllegalArgumentException - if http context is null

IllegalStateException - if the call is made after the http context was already used into a registration

setSessionTimeout

void setSessionTimeout(Integer minutes,
                       org.osgi.service.http.HttpContext httpContext)

Sets the session timeout of the servlet context corresponding to specified http context. This method must be used before any register method that uses the specified http context, otherwise an IllegalStateException will be thrown.

Parameters:

minutes - session timeout of the servlet context corresponding to specified http context

httpContext - http context. Cannot be null.

Throws:

IllegalArgumentException - if http context is null

IllegalStateException - if the call is made after the http context was already used into a registration

registerJsps

void registerJsps(String[] urlPatterns,
                  org.osgi.service.http.HttpContext httpContext)

Enable jsp support.

Parameters:

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 optional org.ops4j.pax.web.jsp package is not resolved

Since:

0.3.0, January 07, 2007

unregisterJsps

void unregisterJsps(org.osgi.service.http.HttpContext httpContext)

Unregister jsps and disable jsp support.

Parameters:

httpContext - the http context for which the jsp support should be disabled

Throws:

IllegalArgumentException - if http context is null or jsp support was not enabled for the http context

UnsupportedOperationException - if optional org.ops4j.pax.web.jsp package is not resolved

Since:

0.3.0, January 07, 2007

registerErrorPage

void registerErrorPage(String error,
                       String location,
                       org.osgi.service.http.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.

Parameters:

error - a fully qualified Exception class name or an error status code

location - the request path that will fill the response page. The location must start with an "/"

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 "/"

Since:

0.3.0, January 12, 2007

unregisterErrorPage

void unregisterErrorPage(String error,
                         org.osgi.service.http.HttpContext httpContext)

Unregisters a previous registered error page.

Parameters:

error - a fully qualified Exception class name or an error status code

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

Since:

0.3.0, January 12, 2007

registerWelcomeFiles

void registerWelcomeFiles(String[] welcomeFiles,
                          boolean redirect,
                          org.osgi.service.http.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

Parameters:

welcomeFiles - an array of welcome files paths. Paths must not start or end with "/"

redirect - true if the client should be redirected to welcome file or false if forwarded

httpContext - the http context this error page is for. If null a default http context will be used.

Throws:

IllegalArgumentException - if: welcome files param is null or empty entries in array are null or empty entries in array start or end with "/"

IllegalStateException - if welcome files are already registered

Since:

0.3.0, January 16, 2007

unregisterWelcomeFiles

void unregisterWelcomeFiles(org.osgi.service.http.HttpContext httpContext)

Unregisters previous registered welcome files.

Parameters:

httpContext - the http context from which the welcome files should be unregistered. Cannot be null.

Throws:

IllegalArgumentException - if httpContext is null

Since:

0.3.0, January 16, 2007

getDefaultSharedHttpContext

SharedWebContainerContext getDefaultSharedHttpContext()