Package org.opendaylight.aaa.web

Interface WebContext

public interface WebContext
Web Context with URL prefix. AKA Web App or Servlet context.

Its WebContext.Builder allows programmatic web component registration (as opposed to declarative e.g. via web.xml, OSGi HTTP Whiteboard blueprint integration, CXF BP etc.)

This is preferable because:

  • using code instead of hiding class names in XML enables tools such as e.g. BND (in the maven-bundle-plugin) to correctly figure dependencies e.g. for OSGi Import-Package headers;
  • explicit passing of web components instances, instead of providing class names in XML files and letting a web container create the new instances using the default constructor, solves a pesky dependency injection (DI) related problem which typically leads to weird hoops in code through static etc. that can be avoided using this;
  • tests can more easily programmatically instantiate web components.

This, not surprisingly, looks somewhat like a Servlet (3.x+) ServletContext, which also allows programmatic dynamic registration e.g. via ServletRegistration; however in practice direct use of that API has been found to be problematic under OSGi, because it is intended for JSE and does not easily appear to permit dynamic registration at any time (only during Servlet container initialization time by ServletContainerInitializer), and is generally less clear to use than this simple API which intentionally maps directly to what one would have declared in a web.xml file. This API is also slightly more focused and drops a number of concepts that API has which we do not want to support here (including e.g. security, roles, multipart etc.)

It also looks somewhat similar to the OSGi HttpService, but we want to avoid any org.osgi dependency (both API and impl) here, and that API is also less clear (and uses an ancient (!) Dictionary in its method signature), and -most importantly- simply does not support Filters and Listeners, only Servlets. The Pax Web API does extend the base OSGi API and adds supports for Filters, Listeners and context parameters, but is still OSGi specific, whereas this offers a much simpler standalone API without OSGi dependency. (The Pax Web API also has confusing signatures in its registerFilter() methods, where one can easily confuse which String[] is the urlPatterns; which we had initially done accidentally; and left AAA broken.)

This is immutable, with a Builder, because contrary to a declarative approach in a file such as web.xml, the registration order very much matters (e.g. an context parameter added after a Servlet registration would not be seen by that Servlet; or a Filter added to protect a Servlet might not yet be active for an instant if the registerServlet is before the registerFilter). Therefore, this API enforces atomicity and lets clients first register everything on the Builder, and only then use WebServer.registerWebContext(WebContext).

Author:
Michael Vorburger.ch

  • Method Details

    • name

      @NonNull String name()
      Get the descriptive name of this context.
      Returns:
      A descriptive name.

    • contextPath

      @NonNull String contextPath()
      Get path which will be used as URL prefix to all registered servlets and filters. Guaranteed to be non-empty
      Returns:
      String path
      See Also:
      • "Java Servlet Specification Version 3.1, Section 3.5 Request Path Elements"

    • supportsSessions

      boolean supportsSessions()
      Get flag value whether this context supports web sessions.
      Returns:
      boolean flag value

    • servlets

      @NonNull List<ServletDetails> servlets()
      Get list of servlets.
      Returns:
      List list of ServletDetails

    • filters

      @NonNull List<FilterDetails> filters()
      Get list of filters.
      Returns:
      List list of FilterDetails

    • listeners

      @NonNull List<javax.servlet.ServletContextListener> listeners()
      Get list of servlet context listeners.
      Returns:
      List list of ServletContextListener

    • resources

      @NonNull List<ResourceDetails> resources()
      Get lis of resources (e.g. html files) that can be accessed via the URI namespace.
      Returns:
      List list of ResourceDetails

    • contextParams

      @NonNull Map<String,String> contextParams()
      Get map of context params.

      These are the ServletContexts initial parameters; contrary to individual ServletDetails.initParams() and FilterDetails.initParams(). While a ServletContext accepts any Object as a parameter, that is not accepted in all implementations. Most notably OSGi HTTP Whiteboard specification allows only String values, hence we are enforcing that.

      Returns:
      Map context parameters map

    • builder

      static @NonNull WebContext.Builder builder()
      Create builder for WebContext.
      Returns:
      WebContext.Builder builder instance