Package 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

      All Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method 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​(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 using JspPropertyGroupDescriptor.
      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 context
      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​(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 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 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 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 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​(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 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 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​(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 context
      void 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 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

      • 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 {@link } instead of {@link }.

        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 {@link } 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 -