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
All Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description default <T extends PaxWebContainerView>
Tadapt(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 defaultHttpContext
as defined in originalHttpService.createDefaultHttpContext()
, but allowing to specify a name.MultiBundleWebContainerContext
createDefaultSharedHttpContext()
Creates a default implementation of aMultiBundleWebContainerContext
with default behavior andshared
name.MultiBundleWebContainerContext
createDefaultSharedHttpContext(String contextId)
Creates a default implementation of aMultiBundleWebContainerContext
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 locationvoid
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(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
registerJspConfigPropertyGroup(javax.servlet.descriptor.JspPropertyGroupDescriptor descriptor, org.osgi.service.http.HttpContext httpContext)
Adds JSP configuration to given context usingJspPropertyGroupDescriptor
.void
registerJspConfigTagLibs(String tagLibLocation, String tagLibUri, org.osgi.service.http.HttpContext httpContext)
Adds mapping of taglib 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
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 {@link} instead of {@link }. void
registerLoginConfig(String authMethod, String realmName, String formLoginPage, String formErrorPage, org.osgi.service.http.HttpContext httpContext)
Registers<login-config>
configuration into the selected contextvoid
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 andmultipart configuration
.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, org.osgi.service.http.HttpContext httpContext)
Register a servlet using class instead of an instance and with URL mappings instead of alias.void
registerServlet(String alias, javax.servlet.Servlet servlet, Dictionary<?,?> initParams, Integer loadOnStartup, Boolean asyncSupported, org.osgi.service.http.HttpContext httpContext)
Registers a servlet as inHttpService.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 fromweb.xml
) async supported (<servlet>/<async-supported>
element fromweb.xml
)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[] urlPatterns, Dictionary<String,String> initParams, org.osgi.service.http.HttpContext httpContext)
Registers a servlet as inHttpService.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 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 andmultipart configuration
.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, org.osgi.service.http.HttpContext httpContext)
Registers a servlet as inHttpService.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
registerServletContainerInitializer(javax.servlet.ServletContainerInitializer initializer, Class<?>[] classes, org.osgi.service.http.HttpContext httpContext)
RegisterServletContainerInitializer
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(String domain, String name, Boolean httpOnly, Boolean secure, String path, Integer maxAge, org.osgi.service.http.HttpContext httpContext)
Set session configuration.void
setSessionCookieConfig(javax.servlet.SessionCookieConfig config, 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(String filterName)
Unregisters a previously registered servlet filter by its name.void
unregisterFilter(javax.servlet.Filter filter)
Unregisters a previously registered servlet filter.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 {@link} in web.xml
.void
unregisterLoginConfig(org.osgi.service.http.HttpContext httpContext)
Clears login configuration for given contextvoid
unregisterServlet(String servletName)
Unregister a previously registered servlet by its name.void
unregisterServlet(javax.servlet.Servlet servlet)
Unregisters a previously registered servlet.void
unregisterServletContainerInitializer(javax.servlet.ServletContainerInitializer initializer, org.osgi.service.http.HttpContext httpContext)
Unregister aServletContainerInitializer
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).
-
-
-
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 originalHttpService.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 passingHttpContext
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 referenceServletContextHelper
instances - legacy (Pax Web specific)
httpContext.id=name
service registration property
httpContext.id
property. User can register aHttpContext
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 theHttpContext
as service.- Returns:
HttpContext
- standard (Whiteboard)
-
createDefaultSharedHttpContext
MultiBundleWebContainerContext createDefaultSharedHttpContext()
Creates a default implementation of a
MultiBundleWebContainerContext
with default behavior andshared
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 aMultiBundleWebContainerContext
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 fromweb.xml
) - async supported (
<servlet>/<async-supported>
element fromweb.xml
)
- Parameters:
alias
- name in the URI namespace at which the servlet is registered (single, exact URI mapping)servlet
- the servlet object to registerinitParams
- initialization arguments for the servlet ornull
if there are none.loadOnStartup
-asyncSupported
-httpContext
-HttpContext
to use for registered servlet. Ifnull
, default will be created.- Throws:
org.osgi.service.http.NamespaceException
- if the registration fails because the alias is already in use.javax.servlet.ServletException
- load on startup (
-
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 registerurlPatterns
- url patterns for servlet mappinginitParams
- initialization arguments for the servlet ornull
if there are none.httpContext
-HttpContext
to use for registered servlet. Ifnull
, 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 registerurlPatterns
- url patterns for servlet mappinginitParams
- initialization arguments for the servlet ornull
if there are none.loadOnStartup
-asyncSupported
-httpContext
-HttpContext
to use for registered servlet. Ifnull
, 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 registerservletName
- name of the servlet. If not specified, fully qualified name of servlet class will be usedurlPatterns
- url patterns for servlet mappinginitParams
- initialization arguments for the servlet ornull
if there are none.httpContext
-HttpContext
to use for registered servlet. Ifnull
, 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 registerservletName
- name of the servlet. If not specified, fully qualified name of servlet class will be usedurlPatterns
- url patterns for servlet mappinginitParams
- initialization arguments for the servlet ornull
if there are none.loadOnStartup
-asyncSupported
-httpContext
-HttpContext
to use for registered servlet. Ifnull
, 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 andmultipart configuration
.- Parameters:
servlet
- the servlet object to registerservletName
- name of the servlet. If not specified, fully qualified name of servlet class will be usedurlPatterns
- url patterns for servlet mappinginitParams
- initialization arguments for the servlet ornull
if there are none.loadOnStartup
-asyncSupported
-multiPartConfig
-httpContext
-HttpContext
to use for registered servlet. Ifnull
, 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 registerurlPatterns
- url patterns for servlet mappinginitParams
- initialization arguments for the servlet ornull
if there are none.httpContext
-HttpContext
to use for registered servlet. Ifnull
, 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 registerurlPatterns
- url patterns for servlet mappinginitParams
- initialization arguments for the servlet ornull
if there are none.loadOnStartup
-asyncSupported
-httpContext
-HttpContext
to use for registered servlet. Ifnull
, 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 andmultipart configuration
.- Parameters:
servletClass
- the servlet class to instantiate and registerurlPatterns
- url patterns for servlet mappinginitParams
- initialization arguments for the servlet ornull
if there are none.loadOnStartup
-asyncSupported
-multiPartConfig
-httpContext
-HttpContext
to use for registered servlet. Ifnull
, 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 registerurlPatterns
- url patterns for filter mappingservletNames
- servlet names for filter mappinginitParams
- initialization arguments for the filter ornull
if there are none.httpContext
-HttpContext
to use for registered filter. Ifnull
, 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 registerfilterName
-urlPatterns
- url patterns for filter mappingservletNames
- servlet names for filter mappinginitParams
- initialization arguments for the filter ornull
if there are none.asyncSupported
-httpContext
-HttpContext
to use for registered filter. Ifnull
, 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 registerurlPatterns
- url patterns for filter mappingservletNames
- servlet names for filter mappinginitParams
- initialization arguments for the filter ornull
if there are none.httpContext
-HttpContext
to use for registered filter. Ifnull
, 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 registerfilterName
-urlPatterns
- url patterns for filter mappingservletNames
- servlet names for filter mappinginitParams
- initialization arguments for the filter ornull
if there are none.asyncSupported
-httpContext
-HttpContext
to use for registered filter. Ifnull
, 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
- 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
orindex.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 forwardedhttpContext
- 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 whenHttpService
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 (or4xx
or5xx
)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 codehttpContext
- 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 usedinitParams
- an array of initialization parameters passed directly to Jasper servlet. These parameters can override the defaults and global configuration fromorg.ops4j.pax.web
PIDhttpContext
- 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 {@link} instead of {@link }. When Tomcat parses
web.xml
and finds such<servlet>
,org.apache.catalina.startup.ContextConfig#convertJsp()
sets the servlet class toorg.apache.jasper.servlet.JspServlet
and the<jsp-file>
is used as its init parameterjspFile
.- 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) fromweb.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 withfile:
orjar:
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 duringServletContainerInitializer.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) fromweb.xml
- but only those used in Pax Web 8. For full configuration, checkregisterJspConfigPropertyGroup(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 usingJspPropertyGroupDescriptor
.- 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 {@link} in web.xml
.- Parameters:
jspFile
-httpContext
-
-
registerServletContainerInitializer
void registerServletContainerInitializer(javax.servlet.ServletContainerInitializer initializer, Class<?>[] classes, org.osgi.service.http.HttpContext httpContext)
RegisterServletContainerInitializer
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 aServletContainerInitializer
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 contexthttpContext
- 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 inServletContainerInitializer
s.- Parameters:
params
- context parameters for the servlet context corresponding to specified http contexthttpContext
- 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 aClass
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. Whileweb.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 totrue
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
-
-
-