Package org.ops4j.pax.web.service.spi.model

SPI model hierarchy contains classes to internally represent all the information required during registration (adding to running server) of web components (servlets, filters, welcome files, error pages, security constraints, ...).

See: Description

Interface Summary

Interface	Description
ModelRegistrationTask<T>	A task that can be passed to ServerModel#run(ModelRegistrationTask) to ensure running it in single threaded "configuration/registration" event loop.

Class Summary

Class	Description
ContextKey
ContextMetadataModel	Some meta information about the "context", attached to OsgiContextModel, but only in the target runtime.
Identity	Auto generated id.
OsgiContextModel	This class represents OSGi-specific HttpContext/ServletContextHelper and points to single, server-specific ServletContext and (at model level) to single ServletContextModel.
ServerModel	Holds web elements in a global context accross all services (all bundles using the Http Service).
ServiceModel	Service Model is kept at HttpService level, which is bundle-scoped in Pax Web (though Http Service specification doesn't mention the scope of Http Service).
ServletContextModel	This class is 1:1 representation of server-specific ServletContext and is unaware of OSGi-related representation of a context (like HttpContext and ServletContextHelper).

Exception Summary

Exception	Description
ModelRegistrationException	Special RuntimeException to handle checked exceptions thrown from ModelRegistrationTask that can be run in CompletableFuture.

Package org.ops4j.pax.web.service.spi.model Description

SPI model hierarchy contains classes to internally represent all the information required during registration (adding to running server) of web components (servlets, filters, welcome files, error pages, security constraints, ...). Such hierarchy is completely unaware of request mapping and it should be treated purely as static database of registrations.

This package containing classes that try to hold server independent model of components, though it's modelled after actual capabilities of Jetty, Tomcat and Undertow.

In Tomcat, we have these concepts:

• Server (org.apache.catalina.core.StandardServer) is entire Catalina instance to run one or more services.
• Service (org.apache.catalina.core.StandardService) groups one or more connectors that share a single container (engine).
• Connector (org.apache.catalina.connector.Connector) works inside a service and receives a request translating it into logical invocation
• Engine (org.apache.catalina.core.StandardEngine) resides as single container inside a service. It's main purpose is to hold virtual hosts (one of them is default).
• Virtual host (org.apache.catalina.core.StandardHost) processes requests according to Host HTTP header or non-matched requests if acting as default virtual host for an engine. For Tomcat purpose, a virtual host has dedicated app base.
• Context (org.apache.catalina.core.StandardContext) represents ServletContext or in other words, entire web application. The most important thing is that it uses single, unique context path.

Tomcat uses quite straightforward processing: connector - virtual host - context - servlet. In standard conf/server.xml it's not easy to use single context in several virtual hosts, but it's possible to use such configuration in embedded mode.

In Jetty, we have these concepts:

• Server contains connectors which translates a network request into handler invocation.
• Connector handles specific protocol and works inside server.
• Handler is generic interface to handle HTTP request after it's been parsed/processed by connector. Even a server is a handler and everything depends on which delegate was set inside the server itself.
• Handler collection is a special handler recommended to set as delegate inside a server. Each handler from the collection is called until one of them marks request as "handled".
• Context (org.eclipse.jetty.server.handler.ContextHandler and subclasses) represents
ServletContext (or in other words, entire web application) and is unique wrt context path. Standalone Jetty (in etc/jetty.xml and Pax Web itself) choose to use handler collection containing context handlers.
• Virtual host is not a special handler - it's part of handling request inside context handler. Such handler rejests requests (doesn't mark it as "handled") if virtual host test fails.

Jetty allows special syntax where virtual host name (or pattern) is followed by @connectorName allowing to filter request based on connector through which the request had arrived.

In Undertow, we have these concepts:

• Server (io.undertow.Undertow) contains listeners and single, default handler where user may choose many handlers from rich hierarchy.
• Listeners receives a request and calls single handler inside a server.
• Virtual host is just one of the handlers (io.undertow.server.handlers.NameVirtualHostHandler) and doesn't have to be set in a server.
• Context, which matches ServletContext has context path and represents entire web application (or WAR deployment), allowing to register servlets, filters, etc.

Undertow doesn't do special context mapping and uses io.undertow.server.handlers.PathHandler to do it. found prefix is set using io.undertow.server.HttpServerExchange#setResolvedPath().

Now, the above, server-specific concepts have to be mapped into Pax Web and OSGi specifications (both "102 Http Service" and "140 Whiteboard Service". The mapping starts ... in the middle with a concept of a context.

There are two contexts depending on OSGi CMPN specification considered:

• HttpContext ("102 Http Service")
• ServletContextHelper ("140 Whiteboard Service")

However, these contexts are not mapped 1:1 with single ServletContext representing a web application as seen by actual server implementation. The above are used by some other servlet context which is mapped 1:1 with original one (according to OSGi CMPN R7). But there's still additional ServletContext actually visible by servlets/filters/etc. depending on the HttpContext or ServletContextHelper with which the servlet/filter/etc. was registered to preserve bundle-affinity.

First, original, server-specific ServletContext, identified uniquely by context path is created everytime a HttpContext or ServletContextHelper is tracked from service registry, with specified context path. Such context is represented by ServletContextModel and is agnostic wrt any bundle. When more HttpContext/ServletContextHelper services are registered for a given context path, there's no conflict - simply more OSGi-specific contexts point to server-specific context.

Then, registered servlet/filter/etc. is associated with some OSGi-specific context using context name (osgi.http.whiteboard.context.name or httpContext.id) and when there are more OSGi-specific contexts (even if pointing to different server-specific contexts), service ranking is used to resolve the conflict. Such OSGi-specific context is represented by OsgiContextModel.

Additionally, what servlets, filters see is yet another ServletContext with proper delegation to relevant class loader. Such context has no representation in the model.

When servlet (or filter, or ...) is registered, it is registered with one (or more!) contexts and when actual server implementation is asked to register such element the registration has to be done for all actual ServletContext instances.

There's a requirement, that ServletContextHelper instances have to be available in OSGi registry (including the default one registered by Whiteboard implementation itself). It is not a case with Http Service and HttpContext.