org.ops4j.pax.web.service

Interface WebContainer

All Superinterfaces:

org.osgi.service.http.HttpService

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

This interface extends HttpService defined in OSGi CMPN R7, chapter 102 "Http Service specification".

In addition to basic registration methods from HttpService, here we can register all remaining web components defined in Java Servlet Specification 4:

• servlets (using more options)
• filters
• JSPs (as specialization of servlet)
• error pages
• welcome files
• login configurations
• security constraints
• servlet container initializers
• web sockets

All registration methods allow passing an instance of HttpContext from original Http Service specification to indicate particular context (ServletContext from Servlet API) where given web component should be registered. This means that this web container represents entire Java HTTP/Servlet container which organizes web elements (like servlets) in contexts or simply web applications.

Note that all "unregister" methods do not specify a context (this behavior is derived from original HttpContext), so if this service was used to register two servlets under the same alias and for two different contexts, HttpService.unregister(String) MUST unregister both registrations.

Since Pax Web 8, methods different than registerXXX()/unregisterXXX() are moved to other interfaces.

Since:

0.5.2

Author:

Alin Dreghiciu

Method Summary

Modifier and Type	Method and Description
default <T extends PaxWebContainerView> T	adapt(Class<T> type) Extension method to provide specialized view of a container to perform different tasks than registration of web elements/components.
org.osgi.service.http.HttpContext	createDefaultHttpContext(String contextId) Creates a default HttpContext as defined in original HttpService.createDefaultHttpContext(), but allowing to specify a name.
MultiBundleWebContainerContext	createDefaultSharedHttpContext() Creates a default implementation of a MultiBundleWebContainerContext with default behavior and shared name.
MultiBundleWebContainerContext	createDefaultSharedHttpContext(String contextId) Creates a default implementation of a MultiBundleWebContainerContext with default behavior and given name.
void	registerConstraintMapping(String constraintName, String httpMethod, String url, String dataConstraint, boolean authentication, List<String> roles, org.osgi.service.http.HttpContext httpContext) Not recommended way to register single security constraint for target context.
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	registerErrorPages(String[] errors, String location, org.osgi.service.http.HttpContext httpContext) Register multiple error pages to be associated with given location
void	registerEventListener(EventListener listener, org.osgi.service.http.HttpContext httpContext) Registers an event listener.
void	registerFilter(Class<? extends javax.servlet.Filter> filterClass, String[] urlPatterns, String[] servletNames, Dictionary<String,String> initParams, org.osgi.service.http.HttpContext httpContext) Registers a filter by class name, with filter URL mappings and/or servlet names to map the filter to.
void	registerFilter(Class<? extends javax.servlet.Filter> filterClass, String filterName, String[] urlPatterns, String[] servletNames, Dictionary<String,String> initParams, Boolean asyncSupported, org.osgi.service.http.HttpContext httpContext) Registers a filter by class name, with filter URL mappings, servlet names to map the filter to and async-support flag.
void	registerFilter(javax.servlet.Filter filter, String[] urlPatterns, String[] servletNames, Dictionary<String,String> initParams, org.osgi.service.http.HttpContext httpContext) Registers a filter with filter URL mappings and/or servlet names to map the filter to.
void	registerFilter(javax.servlet.Filter filter, String filterName, String[] urlPatterns, String[] servletNames, Dictionary<String,String> initParams, Boolean asyncSupported, org.osgi.service.http.HttpContext httpContext) Registers a filter with filter URL mappings, servlet names to map the filter to and async-support flag.
void	registerJspConfigPropertyGroup(javax.servlet.descriptor.JspPropertyGroupDescriptor descriptor, org.osgi.service.http.HttpContext httpContext) Adds JSP configuration to given context using JspPropertyGroupDescriptor.
void	registerJspConfigPropertyGroup(List<String> includeCodas, List<String> includePreludes, List<String> urlPatterns, Boolean elIgnored, Boolean scriptingInvalid, Boolean isXml, org.osgi.service.http.HttpContext httpContext) Adds JSP configuration to given context.
void	registerJspConfigTagLibs(Collection<javax.servlet.descriptor.TaglibDescriptor> tagLibs, org.osgi.service.http.HttpContext httpContext) Adds multiple URI - location mappings for TLDs.
void	registerJspConfigTagLibs(String tagLibLocation, String tagLibUri, org.osgi.service.http.HttpContext httpContext) Adds mapping of taglib to given context.
void	registerJsps(String[] urlPatterns, Dictionary<String,String> initParams, org.osgi.service.http.HttpContext httpContext) Enable JSP support by configuring target runtime specific JSP servlet (which is Jasper in all the cases).
void	registerJspServlet(String jspFile, String[] urlPatterns, Dictionary<String,String> initParams, org.osgi.service.http.HttpContext httpContext) >@code web.xml} allows registration of a <servlet> with instead of .
void	registerLoginConfig(String authMethod, String realmName, String formLoginPage, String formErrorPage, org.osgi.service.http.HttpContext httpContext) Registers <login-config> configuration into the selected context
void	registerServlet(Class<? extends javax.servlet.Servlet> servletClass, String[] urlPatterns, Dictionary<String,String> initParams, org.osgi.service.http.HttpContext httpContext) Register a servlet using class instead of an instance and with URL mappings instead of alias.
void	registerServlet(Class<? extends javax.servlet.Servlet> servletClass, String[] urlPatterns, Dictionary<String,String> initParams, Integer loadOnStartup, Boolean asyncSupported, org.osgi.service.http.HttpContext httpContext) Register a servlet using class instead of an instance and with URL mappings instead of alias and with load-on-startup and async-support parameters.
void	registerServlet(Class<? extends javax.servlet.Servlet> servletClass, String[] urlPatterns, Dictionary<String,String> initParams, Integer loadOnStartup, Boolean asyncSupported, javax.servlet.MultipartConfigElement multiPartConfig, org.osgi.service.http.HttpContext httpContext) Register a servlet using class instead of an instance and with URL mappings instead of alias and with load-on-startup, async-support parameters and multipart configuration.
void	registerServlet(javax.servlet.Servlet servlet, String[] urlPatterns, Dictionary<String,String> initParams, org.osgi.service.http.HttpContext httpContext) Registers a servlet as in HttpService.registerServlet(java.lang.String, javax.servlet.Servlet, java.util.Dictionary<?, ?>, org.osgi.service.http.HttpContext) but with servlet URL mappings (see Servlet API specification, chapter 12.2, "Specification of Mappings") instead of single alias.
void	registerServlet(javax.servlet.Servlet servlet, String[] urlPatterns, Dictionary<String,String> initParams, Integer loadOnStartup, Boolean asyncSupported, org.osgi.service.http.HttpContext httpContext) Registers a servlet with servlet URL mappings, load-on-startup and async-support parameters.
void	registerServlet(javax.servlet.Servlet servlet, String servletName, String[] urlPatterns, Dictionary<String,String> initParams, org.osgi.service.http.HttpContext httpContext) Registers a servlet as in HttpService.registerServlet(java.lang.String, javax.servlet.Servlet, java.util.Dictionary<?, ?>, org.osgi.service.http.HttpContext) but with servlet name and URL mappings (see Servlet API specification, chapter 12.2, "Specification of Mappings") instead of single alias.
void	registerServlet(javax.servlet.Servlet servlet, String servletName, String[] urlPatterns, Dictionary<String,String> initParams, Integer loadOnStartup, Boolean asyncSupported, org.osgi.service.http.HttpContext httpContext) Registers a servlet with servlet name, URL mappings, load-on-startup and async-support parameters.
void	registerServlet(javax.servlet.Servlet servlet, String servletName, String[] urlPatterns, Dictionary<String,String> initParams, Integer loadOnStartup, Boolean asyncSupported, javax.servlet.MultipartConfigElement multiPartConfig, org.osgi.service.http.HttpContext httpContext) Registers a servlet with servlet name, URL mappings, load-on-startup, async-support parameters and multipart configuration.
void	registerServlet(String alias, javax.servlet.Servlet servlet, Dictionary<?,?> initParams, Integer loadOnStartup, Boolean asyncSupported, org.osgi.service.http.HttpContext httpContext) Registers a servlet as in HttpService.registerServlet(java.lang.String, javax.servlet.Servlet, java.util.Dictionary<?, ?>, org.osgi.service.http.HttpContext) with two additional parameters: load on startup (<servlet>/<load-on-startup> element from web.xml) async supported (<servlet>/<async-supported> element from web.xml)
void	registerServletContainerInitializer(javax.servlet.ServletContainerInitializer initializer, Class<?>[] classes, org.osgi.service.http.HttpContext httpContext) Register ServletContainerInitializer into a context.
void	registerWebSocket(Object webSocket, org.osgi.service.http.HttpContext httpContext) Registers a WebSocket endpoint annotated with @javax.websocket.server.ServerEndpoint.
void	registerWelcomeFiles(String[] welcomeFiles, boolean redirect, org.osgi.service.http.HttpContext httpContext) Registers an ordered list of partial URIs that conform to welcome pages definition from chapter 10.10 of Servlet 4 specification.
void	setContextParams(Dictionary<String,Object> params, org.osgi.service.http.HttpContext httpContext) Sets context paramaters to be used in the servlet context corresponding to specified http context.
void	setSessionCookieConfig(javax.servlet.SessionCookieConfig config, org.osgi.service.http.HttpContext httpContext) Set session configuration.
void	setSessionCookieConfig(String domain, String name, Boolean httpOnly, Boolean secure, String path, Integer maxAge, org.osgi.service.http.HttpContext httpContext) Set session configuration.
void	setSessionTimeout(Integer minutes, org.osgi.service.http.HttpContext httpContext) Sets the session timeout of the servlet context corresponding to specified http context.
void	unregisterConstraintMapping(org.osgi.service.http.HttpContext httpContext) Removes all security constraints from given context - for compatibility with Pax Web 7.
void	unregisterErrorPage(String error, org.osgi.service.http.HttpContext httpContext) Unregisters a previously registered error page - it'll be removed from a set of error pages associated with some mapping location.
void	unregisterErrorPages(String[] errors, org.osgi.service.http.HttpContext httpContext) Unregisters multiple error pages associated with some mapping location.
void	unregisterEventListener(EventListener listener) Unregisters a previously registered listener.
void	unregisterFilter(javax.servlet.Filter filter) Unregisters a previously registered servlet filter.
void	unregisterFilter(String filterName) Unregisters a previously registered servlet filter by its name.
void	unregisterFilters(Class<? extends javax.servlet.Filter> filterClass) Unregisters a previously registered servlet filters with given class.
void	unregisterJsps(org.osgi.service.http.HttpContext httpContext) Unregisters JSP servlet from given context - the only possible servlet regardless of the related mappings.
void	unregisterJspServlet(String jspFile, org.osgi.service.http.HttpContext httpContext) Unregisters a servlet that's using in web.xml.
void	unregisterLoginConfig(org.osgi.service.http.HttpContext httpContext) Clears login configuration for given context
void	unregisterServlet(javax.servlet.Servlet servlet) Unregisters a previously registered servlet.
void	unregisterServlet(String servletName) Unregister a previously registered servlet by its name.
void	unregisterServletContainerInitializer(javax.servlet.ServletContainerInitializer initializer, org.osgi.service.http.HttpContext httpContext) Unregister a ServletContainerInitializer from a context.
void	unregisterServlets(Class<? extends javax.servlet.Servlet> servletClass) Unregisters all previously registered servlets with given class.
void	unregisterWebSocket(Object webSocket, org.osgi.service.http.HttpContext httpContext) Unregisters a previously registered WebSocket endpoint annotated with @javax.websocket.server.ServerEndpoint
void	unregisterWelcomeFiles(String[] welcomeFiles, org.osgi.service.http.HttpContext httpContext) Unregisters previously registered welcome files (whether redirected or not).

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

createDefaultHttpContext, registerResources, registerServlet, unregister

Method Detail

adapt

default <T extends PaxWebContainerView> T adapt(Class<T> type)

Extension method to provide specialized view of a container to perform different tasks than registration of web elements/components.

And even if that may sound weird, this method may be used internally by passing internal Pax Web interfaces. This way, pax-http-extender-whiteboard may use specialized registration methods for Whiteboard Service specific tasks (like batch registration of servlets to multiple contexts).

Type Parameters:

T -

Parameters:

type - another interface defined in pax-web-api for container manipulation/configuration.

Returns:

createDefaultHttpContext

org.osgi.service.http.HttpContext createDefaultHttpContext(String contextId)

Creates a default HttpContext as defined in original HttpService.createDefaultHttpContext(), but allowing to specify a name. Default means default behaviour (security, resource access) and not the fact that it's global (or shared) context.

This allows single bundle (working on bundle-scoped HttpService) to register web elements into same context without passing HttpContext around.

Of course such HttpContext can later be registered as OSGi service and referenced later using:

• standard (Whiteboard) osgi.http.whiteboard.context.select=(osgi.http.whiteboard.context.name=name) service registration property even if this property is designed to reference ServletContextHelper instances
• legacy (Pax Web specific) httpContext.id=name service registration property

Legacy Pax Web Whiteboard implementation handles contexts registered with httpContext.id property. User can register a HttpContext with such property and then register a servlet (or filter, or ...) with the same property to associate it with given context.

HttpContext retrieved this way can't be used between bundles and is not registered automatically as OSGi service.

In OSGi CMPN Whiteboard implementation there's no special API to create instances of ServletContextHelper instances.

Parameters:

contextId - the ID of the context which is used while registering the HttpContext as service.

Returns:

HttpContext

createDefaultSharedHttpContext

MultiBundleWebContainerContext createDefaultSharedHttpContext()

Creates a default implementation of a MultiBundleWebContainerContext with default behavior and shared name. Each call creates new instance and may be registered as OSGi service and referenced later by different bundles.

Returns:

MultiBundleWebContainerContext

createDefaultSharedHttpContext

MultiBundleWebContainerContext createDefaultSharedHttpContext(String contextId)

Creates a default implementation of a MultiBundleWebContainerContext with default behavior and given name.

Parameters:

contextId -

Returns:

registerServlet

void registerServlet(String alias,
                     javax.servlet.Servlet servlet,
                     Dictionary<?,?> initParams,
                     Integer loadOnStartup,
                     Boolean asyncSupported,
                     org.osgi.service.http.HttpContext httpContext)
              throws javax.servlet.ServletException,
                     org.osgi.service.http.NamespaceException

Registers a servlet as in HttpService.registerServlet(java.lang.String, javax.servlet.Servlet, java.util.Dictionary<?, ?>, org.osgi.service.http.HttpContext) with two additional parameters:

• load on startup (<servlet>/<load-on-startup> element from web.xml)
• async supported (<servlet>/<async-supported> element from web.xml)

Parameters:

alias - name in the URI namespace at which the servlet is registered (single, exact URI mapping)

servlet - the servlet object to register

initParams - initialization arguments for the servlet or null if there are none.

loadOnStartup -

asyncSupported -

httpContext - HttpContext to use for registered servlet. If null, default will be created.

Throws:

org.osgi.service.http.NamespaceException - if the registration fails because the alias is already in use.

javax.servlet.ServletException

registerServlet

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

Registers a servlet as in HttpService.registerServlet(java.lang.String, javax.servlet.Servlet, java.util.Dictionary<?, ?>, org.osgi.service.http.HttpContext) but with servlet URL mappings (see Servlet API specification, chapter 12.2, "Specification of Mappings") instead of single alias.

Parameters:

servlet - the servlet object to register

urlPatterns - url patterns for servlet mapping

initParams - initialization arguments for the servlet or null if there are none.

httpContext - HttpContext to use for registered servlet. If null, default will be created.

Throws:

javax.servlet.ServletException

registerServlet

void registerServlet(javax.servlet.Servlet servlet,
                     String[] urlPatterns,
                     Dictionary<String,String> initParams,
                     Integer loadOnStartup,
                     Boolean asyncSupported,
                     org.osgi.service.http.HttpContext httpContext)
              throws javax.servlet.ServletException

Registers a servlet with servlet URL mappings, load-on-startup and async-support parameters.

Parameters:

servlet - the servlet object to register

urlPatterns - url patterns for servlet mapping

initParams - initialization arguments for the servlet or null if there are none.

loadOnStartup -

asyncSupported -

httpContext - HttpContext to use for registered servlet. If null, default will be created.

Throws:

javax.servlet.ServletException

registerServlet

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

Registers a servlet as in HttpService.registerServlet(java.lang.String, javax.servlet.Servlet, java.util.Dictionary<?, ?>, org.osgi.service.http.HttpContext) but with servlet name and URL mappings (see Servlet API specification, chapter 12.2, "Specification of Mappings") instead of single alias.

Parameters:

servlet - the servlet object to register

servletName - name of the servlet. If not specified, fully qualified name of servlet class will be used

urlPatterns - url patterns for servlet mapping

initParams - initialization arguments for the servlet or null if there are none.

httpContext - HttpContext to use for registered servlet. If null, default will be created.

Throws:

javax.servlet.ServletException

registerServlet

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

Registers a servlet with servlet name, URL mappings, load-on-startup and async-support parameters.

Parameters:

servlet - the servlet object to register

servletName - name of the servlet. If not specified, fully qualified name of servlet class will be used

urlPatterns - url patterns for servlet mapping

initParams - initialization arguments for the servlet or null if there are none.

loadOnStartup -

asyncSupported -

httpContext - HttpContext to use for registered servlet. If null, default will be created.

Throws:

javax.servlet.ServletException

registerServlet

void registerServlet(javax.servlet.Servlet servlet,
                     String servletName,
                     String[] urlPatterns,
                     Dictionary<String,String> initParams,
                     Integer loadOnStartup,
                     Boolean asyncSupported,
                     javax.servlet.MultipartConfigElement multiPartConfig,
                     org.osgi.service.http.HttpContext httpContext)
              throws javax.servlet.ServletException

Registers a servlet with servlet name, URL mappings, load-on-startup, async-support parameters and multipart configuration.

Parameters:

servlet - the servlet object to register

servletName - name of the servlet. If not specified, fully qualified name of servlet class will be used

urlPatterns - url patterns for servlet mapping

initParams - initialization arguments for the servlet or null if there are none.

loadOnStartup -

asyncSupported -

multiPartConfig -

httpContext - HttpContext to use for registered servlet. If null, default will be created.

Throws:

javax.servlet.ServletException

registerServlet

void registerServlet(Class<? extends javax.servlet.Servlet> servletClass,
                     String[] urlPatterns,
                     Dictionary<String,String> initParams,
                     org.osgi.service.http.HttpContext httpContext)
              throws javax.servlet.ServletException

Register a servlet using class instead of an instance and with URL mappings instead of alias.

Parameters:

servletClass - the servlet class to instantiate and register

urlPatterns - url patterns for servlet mapping

initParams - initialization arguments for the servlet or null if there are none.

httpContext - HttpContext to use for registered servlet. If null, default will be created.

Throws:

javax.servlet.ServletException

registerServlet

void registerServlet(Class<? extends javax.servlet.Servlet> servletClass,
                     String[] urlPatterns,
                     Dictionary<String,String> initParams,
                     Integer loadOnStartup,
                     Boolean asyncSupported,
                     org.osgi.service.http.HttpContext httpContext)
              throws javax.servlet.ServletException

Register a servlet using class instead of an instance and with URL mappings instead of alias and with load-on-startup and async-support parameters.

Parameters:

servletClass - the servlet class to instantiate and register

urlPatterns - url patterns for servlet mapping

initParams - initialization arguments for the servlet or null if there are none.

loadOnStartup -

asyncSupported -

httpContext - HttpContext to use for registered servlet. If null, default will be created.

Throws:

javax.servlet.ServletException

registerServlet

void registerServlet(Class<? extends javax.servlet.Servlet> servletClass,
                     String[] urlPatterns,
                     Dictionary<String,String> initParams,
                     Integer loadOnStartup,
                     Boolean asyncSupported,
                     javax.servlet.MultipartConfigElement multiPartConfig,
                     org.osgi.service.http.HttpContext httpContext)
              throws javax.servlet.ServletException

Register a servlet using class instead of an instance and with URL mappings instead of alias and with load-on-startup, async-support parameters and multipart configuration.

Parameters:

servletClass - the servlet class to instantiate and register

urlPatterns - url patterns for servlet mapping

initParams - initialization arguments for the servlet or null if there are none.

loadOnStartup -

asyncSupported -

multiPartConfig -

httpContext - HttpContext to use for registered servlet. If null, default will be created.

Throws:

javax.servlet.ServletException

unregisterServlet

void unregisterServlet(javax.servlet.Servlet servlet)

Unregisters a previously registered servlet. If the same instance was registered in more contexts, it'll be removed from all of them.

Parameters:

servlet - the servlet to be unregistered

unregisterServlet

void unregisterServlet(String servletName)

Unregister a previously registered servlet by its name. If more servlets were registered using the same name, all of them will be unregistered.

Parameters:

servletName - the servlet identified by it's name.

unregisterServlets

void unregisterServlets(Class<? extends javax.servlet.Servlet> servletClass)

Unregisters all previously registered servlets with given class. If more servlets were registered with the same class, all of them will be unregistered.

Parameters:

servletClass - the servlet class to be unregistered

registerFilter

void registerFilter(javax.servlet.Filter filter,
                    String[] urlPatterns,
                    String[] servletNames,
                    Dictionary<String,String> initParams,
                    org.osgi.service.http.HttpContext httpContext)
             throws javax.servlet.ServletException

Registers a filter with filter URL mappings and/or servlet names to map the filter to.

Parameters:

filter - the filter object to register

urlPatterns - url patterns for filter mapping

servletNames - servlet names for filter mapping

initParams - initialization arguments for the filter or null if there are none.

httpContext - HttpContext to use for registered filter. If null, default will be created.

Throws:

javax.servlet.ServletException

registerFilter

void registerFilter(javax.servlet.Filter filter,
                    String filterName,
                    String[] urlPatterns,
                    String[] servletNames,
                    Dictionary<String,String> initParams,
                    Boolean asyncSupported,
                    org.osgi.service.http.HttpContext httpContext)
             throws javax.servlet.ServletException

Registers a filter with filter URL mappings, servlet names to map the filter to and async-support flag.

Parameters:

filter - the filter object to register

filterName -

urlPatterns - url patterns for filter mapping

servletNames - servlet names for filter mapping

initParams - initialization arguments for the filter or null if there are none.

asyncSupported -

httpContext - HttpContext to use for registered filter. If null, default will be created.

Throws:

javax.servlet.ServletException

registerFilter

void registerFilter(Class<? extends javax.servlet.Filter> filterClass,
                    String[] urlPatterns,
                    String[] servletNames,
                    Dictionary<String,String> initParams,
                    org.osgi.service.http.HttpContext httpContext)
             throws javax.servlet.ServletException

Registers a filter by class name, with filter URL mappings and/or servlet names to map the filter to.

Parameters:

filterClass - the filter class to register

urlPatterns - url patterns for filter mapping

servletNames - servlet names for filter mapping

initParams - initialization arguments for the filter or null if there are none.

httpContext - HttpContext to use for registered filter. If null, default will be created.

Throws:

javax.servlet.ServletException

registerFilter

void registerFilter(Class<? extends javax.servlet.Filter> filterClass,
                    String filterName,
                    String[] urlPatterns,
                    String[] servletNames,
                    Dictionary<String,String> initParams,
                    Boolean asyncSupported,
                    org.osgi.service.http.HttpContext httpContext)
             throws javax.servlet.ServletException

Registers a filter by class name, with filter URL mappings, servlet names to map the filter to and async-support flag.

Parameters:

filterClass - the filter class to register

filterName -

urlPatterns - url patterns for filter mapping

servletNames - servlet names for filter mapping

initParams - initialization arguments for the filter or null if there are none.

asyncSupported -

httpContext - HttpContext to use for registered filter. If null, default will be created.

Throws:

javax.servlet.ServletException

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

unregisterFilter

void unregisterFilter(String filterName)

Unregisters a previously registered servlet filter by its name. If more filters were registered using the same name, all of them will be unregistered.

Parameters:

filterName - the servlet filter name to be unregistered

Throws:

IllegalArgumentException - if the filter is unknown to the http service

unregisterFilters

void unregisterFilters(Class<? extends javax.servlet.Filter> filterClass)

Unregisters a previously registered servlet filters with given class. If more filters were registered with the same class, all of them will be unregistered.

Parameters:

filterClass - the servlet filter to be unregistered, found by the Filter class

Throws:

IllegalArgumentException - if the filter is unknown to the http service

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

registerWelcomeFiles

void registerWelcomeFiles(String[] welcomeFiles,
                          boolean redirect,
                          org.osgi.service.http.HttpContext httpContext)

Registers an ordered list of partial URIs that conform to welcome pages definition from chapter 10.10 of Servlet 4 specification. They're mainly used to return "something" when sending requests for directories, but a welcome file may also map to actual web component (a servlet) which is usually the case with welcome file like index.do or index.xhtml (from JSF).

Welcome files are cumulative - they're added to single set of welcome files specified for given context.

Welcome files are strictly connected with resource servlets and without actual resources they're useless. Welcome files are also registered per context and affect all the resource servlets registered into (in association with) given context.

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.

unregisterWelcomeFiles

void unregisterWelcomeFiles(String[] welcomeFiles,
                            org.osgi.service.http.HttpContext httpContext)

Unregisters previously registered welcome files (whether redirected or not). This method should really only remove the passed welcome files, so it may be confusing, as there's no way to register two sets of distinct sets of welcome files. Each registered, single welcome file is simply added to a list of welcome files available for given context.

To make management easier, passing empty set of welcome files to this method will unregister all available welcome files (for given context).

Also, differently than with servlets, filters and listeners, unregistration method requires passing original HttpContext, because array of Strings is not enough to identify proper model. In normal scenario, if exactly the same (element-wise, not reference wise) array of welcome files is passed, we can properly clean up the models, but if user registers 3 welcome files, but unregisters only one, it's not possible to clean up the state - it'll be cleaned when HttpService is destroyed.

Parameters:

welcomeFiles -

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

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.

This method was created before Pax Web implemented OSGi CMPN Whiteboard specification, where error pages are always registered in association with concrete Servlet instance that will be used to handle the errors, while the mapping location location of this servlet is not important. Here, registering error page(s) should be made after registering actual servlet for given mapping.

The mapping location should be fixed prefix absolute location (i.e., no wildcard) and registered error code (or FQCN of an exception) is added to a collection (set) of error pages mapped to given location.

Single error pages can't be associated with multiple locations. However in Whiteboard scenario, where service ranking is available, it is possible to shadow one mapping with another having higher service ranking.

Parameters:

error - a fully qualified Exception class name or an error status code (or 4xx or 5xx)

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.

Since:

0.3.0, January 12, 2007

registerErrorPages

void registerErrorPages(String[] errors,
                        String location,
                        org.osgi.service.http.HttpContext httpContext)

Register multiple error pages to be associated with given location

Parameters:

errors -

location -

httpContext -

unregisterErrorPage

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

Unregisters a previously registered error page - it'll be removed from a set of error pages associated with some mapping location.

Also, differently than with servlets, filters and listeners, unregistration method requires passing original HttpContext, because array of Strings is not enough to identify proper model.

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.

Since:

0.3.0, January 12, 2007

unregisterErrorPages

void unregisterErrorPages(String[] errors,
                          org.osgi.service.http.HttpContext httpContext)

Unregisters multiple error pages associated with some mapping location.

Parameters:

errors -

httpContext -

registerJsps

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

Enable JSP support by configuring target runtime specific JSP servlet (which is Jasper in all the cases). JSP servlet will be available under selected URL patterns which should be compliant to patterns specified in Servlet API specification, chapter 12.2 "Specification of Mappings".

Even if I can imagine registration of different JSP servlets with different init parameters, mapped to different URL patterns, for now Pax Web 8 will just handle single JSP servlet per context (service ranking rules still apply!).

Parameters:

urlPatterns - an array of url patterns this jsp support maps to. If null, a default *.jsp will be used

initParams - an array of initialization parameters passed directly to Jasper servlet. These parameters can override the defaults and global configuration from org.ops4j.pax.web PID

httpContext - the http context for which the jsp support should be enabled. If null a default http context will be used.

Since:

0.3.0, January 07, 2007

registerJspServlet

void registerJspServlet(String jspFile,
                        String[] urlPatterns,
                        Dictionary<String,String> initParams,
                        org.osgi.service.http.HttpContext httpContext)

>@code web.xml} allows registration of a <servlet> with instead of .

When Tomcat parses web.xml and finds such <servlet>, org.apache.catalina.startup.ContextConfig#convertJsp() sets the servlet class to org.apache.jasper.servlet.JspServlet and the <jsp-file> is used as its init parameter jspFile.

Parameters:

jspFile -

urlPatterns -

initParams -

httpContext -

registerJspConfigTagLibs

void registerJspConfigTagLibs(String tagLibLocation,
                              String tagLibUri,
                              org.osgi.service.http.HttpContext httpContext)

Adds mapping of taglib to given context. The taglib matches <jsp-config>/<taglib> element(s) from web.xml.

The location should be resolvable according to "JSP.7.3.2 TLD resource path" and "JSP.7.3.6.1 Computing TLD Locations" chapters of JSR 245 JSP specification, which generally means that protocol-less URIs are resolved against /WEB-INF/ directory. In Pax Web, if the location is absolute URI with file: or jar: schemes, we check for its existence (but not TLD copliance). If the location is relative or protocol-less URI, an attempt to resolve it will be made only during ServletContainerInitializer.onStartup(java.util.Set<java.lang.Class<?>>, javax.servlet.ServletContext) of the JSP SCI.

Parameters:

tagLibLocation -

tagLibUri -

httpContext -

registerJspConfigTagLibs

void registerJspConfigTagLibs(Collection<javax.servlet.descriptor.TaglibDescriptor> tagLibs,
                              org.osgi.service.http.HttpContext httpContext)

Adds multiple URI - location mappings for TLDs.

Parameters:

tagLibs -

httpContext -

registerJspConfigPropertyGroup

void registerJspConfigPropertyGroup(List<String> includeCodas,
                                    List<String> includePreludes,
                                    List<String> urlPatterns,
                                    Boolean elIgnored,
                                    Boolean scriptingInvalid,
                                    Boolean isXml,
                                    org.osgi.service.http.HttpContext httpContext)

Adds JSP configuration to given context. The configuration matches <jsp-config></jsp-property-group> element(s) from web.xml - but only those used in Pax Web 8. For full configuration, check registerJspConfigPropertyGroup(JspPropertyGroupDescriptor, HttpContext).

Parameters:

includeCodas - <jsp-property-group>/<include-coda>

includePreludes - <jsp-property-group>/<include-prelude>

urlPatterns - <jsp-property-group>/<url-pattern>

elIgnored - <jsp-property-group>/<el-ignored>

scriptingInvalid - <jsp-property-group>/<scripting-invalid>

isXml - <jsp-property-group>/<is-xml>

httpContext -

registerJspConfigPropertyGroup

void registerJspConfigPropertyGroup(javax.servlet.descriptor.JspPropertyGroupDescriptor descriptor,
                                    org.osgi.service.http.HttpContext httpContext)

Adds JSP configuration to given context using JspPropertyGroupDescriptor.

Parameters:

descriptor -

httpContext -

Since:

Pax Web 8

unregisterJsps

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

Unregisters JSP servlet from given context - the only possible servlet regardless of the related mappings.

Parameters:

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

Since:

0.3.0, January 07, 2007

unregisterJspServlet

void unregisterJspServlet(String jspFile,
                          org.osgi.service.http.HttpContext httpContext)

Unregisters a servlet that's using in web.xml.

Parameters:

jspFile -

httpContext -

registerServletContainerInitializer

void registerServletContainerInitializer(javax.servlet.ServletContainerInitializer initializer,
                                         Class<?>[] classes,
                                         org.osgi.service.http.HttpContext httpContext)

Register ServletContainerInitializer into a context. If there are any active web elements already registered, the context must be restarted.

Parameters:

initializer -

classes -

httpContext -

unregisterServletContainerInitializer

void unregisterServletContainerInitializer(javax.servlet.ServletContainerInitializer initializer,
                                           org.osgi.service.http.HttpContext httpContext)

Unregister a ServletContainerInitializer from a context.

Parameters:

initializer -

httpContext -

setSessionTimeout

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

Sets the session timeout of the servlet context corresponding to specified http context.

Parameters:

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

httpContext - http context. Cannot be null.

setSessionCookieConfig

void setSessionCookieConfig(String domain,
                            String name,
                            Boolean httpOnly,
                            Boolean secure,
                            String path,
                            Integer maxAge,
                            org.osgi.service.http.HttpContext httpContext)

Set session configuration. THe configuration matches the elements <session-config>/<cookie-config>

Parameters:

domain -

name -

httpOnly -

secure -

path -

maxAge -

httpContext -

setSessionCookieConfig

void setSessionCookieConfig(javax.servlet.SessionCookieConfig config,
                            org.osgi.service.http.HttpContext httpContext)

Set session configuration. THe configuration matches the elements <session-config>/<cookie-config>

Parameters:

config -

httpContext -

setContextParams

void setContextParams(Dictionary<String,Object> 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 the context initialization parameters won't be taken into account (for example in ServletContainerInitializers.

Parameters:

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

httpContext - http context

registerWebSocket

void registerWebSocket(Object webSocket,
                       org.osgi.service.http.HttpContext httpContext)

Registers a WebSocket endpoint annotated with @javax.websocket.server.ServerEndpoint. The actual object passed may be both an actual instance or a Class object which will be instantiated when needed.

Parameters:

webSocket -

httpContext -

unregisterWebSocket

void unregisterWebSocket(Object webSocket,
                         org.osgi.service.http.HttpContext httpContext)

Unregisters a previously registered WebSocket endpoint annotated with @javax.websocket.server.ServerEndpoint

Parameters:

webSocket -

httpContext -

registerLoginConfig

void registerLoginConfig(String authMethod,
                         String realmName,
                         String formLoginPage,
                         String formErrorPage,
                         org.osgi.service.http.HttpContext httpContext)

Registers <login-config> configuration into the selected context

Parameters:

authMethod - <login-config>/<auth-method>

realmName - <login-config>/<realm-name>

formLoginPage - <login-config>/<form-login-config>/<form-login-page>

formErrorPage - <login-config>/<form-login-config>/<form-error-page>

httpContext -

registerConstraintMapping

void registerConstraintMapping(String constraintName,
                               String httpMethod,
                               String url,
                               String dataConstraint,
                               boolean authentication,
                               List<String> roles,
                               org.osgi.service.http.HttpContext httpContext)

Not recommended way to register single security constraint for target context. While web.xml allows multiple <security-constraint> and within single <security-constraint> multiple <security-constraint>/<web-resource-collection>, this method registers only single <security-constraint>/<web-resource-collection>

Parameters:

constraintName - <security-constraint>/<display-name>

httpMethod - single <security-constraint>/<web-resource-collection>/<http-method>

url - single <security-constraint>/<web-resource-collection>/<url-pattern>

dataConstraint - <security-constraint>/<user-data-constraint>/<transport-guarantee>

authentication - set to true if empty roles mean "deny all". false means "permit all".

roles - <security-constraint>/<auth-constraint>/<role-name>

httpContext -

unregisterLoginConfig

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

Clears login configuration for given context

Parameters:

httpContext -

unregisterConstraintMapping

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

Removes all security constraints from given context - for compatibility with Pax Web 7.

Parameters:

httpContext -