The package dependencies for the clients of this specification are listed in the following table.

JSP is optional for the Web Runtime.

The Web Application Specification is composed of a number of cooperating parts, which are implemented by a Web Container. A Web Container consists of:

WABs are standard OSGi bundles with additional headers in the manifest that serve as deployment instructions to the Web Extender. WABs can also contain the Java EE defined web.xml descriptor in the WEB-INF/ directory. When the Web Extender detects that a WAB is ready the Web Extender deploys the WAB to the Web Runtime using information contained in the web.xml descriptor and the appropriate manifest headers. The Bundle Context of the WAB is made available as a Servlet Context attribute. From that point, the Web Runtime will use the information in the WAB to serve content to any requests. Both dynamic as well as static content can be provided.

The Web URL Handler allows the deployment of an unmodified WAR as a WAB into the OSGi framework. This Web URL Handler provides a URL stream handler with the webbundle: scheme. Installing a WAR with this scheme allows the Web URL Handler to interpose itself as a filter on the input stream of the contents of the WAR, transforming the contents of the WAR into a WAB. The Web URL Handler rewrites the manifest by adding necessary headers to turn the WAR into a valid WAB. Additional headers can be added to the manifest that serve as instructions to the Web Extender.

After a WAB has been deployed to the Web Runtime, the Web Application can interact with the OSGi framework via the provided Bundle Context. The Servlet Context associated with this WAB follows the same life cycle as the WAB. That is, when the underlying Web Application Bundle is started, the Web Application is deployed to the Web Runtime. When the underlying Web Application Bundle is stopped because of a failure or other reason, the Web Application is undeployed from the Web Run-time.

A WAB is differentiated from non Web Application bundles through the specification of the additional manifest header:

Web-ContextPath ::= path

The Web-ContextPath header specifies the value of the Context Path of the Web Application. All web accessible content of the Web Application is available on the web server relative to this Context Path. For example, if the context path is /sales, then the URL would be something like: http://www.acme.com/sales. The Context Path must always begin with a solidus ('/' \u002F).

The Web Extender must not recognize a bundle as a Web Application unless the Web-ContextPath header is present in its manifest and the header value is a valid path for the bundle.

A WAB can optionally contain a web.xml resource to specify additional configuration. This web.xml must be found with the Bundle findEntries method at the path:

 WEB-INF/web.xml

The findEntries method includes fragments, allowing the web.xml to be provided by a fragment. The Web Extender must fully support a web.xml descriptor that specifies Servlets, Filters, or Listeners whose classes are required by the WAB.

A WAB's Web Application must be deployed while the WAB is ready. Deployed means that the Web Application is available for web requests. Once deployed, a WAB can serve its web content on the given Context Path. Ready is when the WAB:

The Web Extender should ensure that serving static content from the WAB does not activate the WAB when it has a lazy activation policy.

To deploy the WAB, the Web Extender must initiate the deploying of the Web Application into a Web Runtime. This is outlined in the following steps:

If at any moment before the org/osgi/service/web/DEPLOYED event is published the deployment of the WAB fails, then the WAB deployment fails, see Failure.

Any validation failures must prevent the Web Application from being accessible via HTTP, and must result in a org/osgi/service/web/FAILED event being posted. See Events. The situation after the failure must be as if the WAB was never deployed.

To help management agents with tracking the state of Web Applications, the Web Extender must register the Servlet Context of the WAB as a service, using the Bundle Context of the WAB. The Servlet Context service must be registered with the service properties listed in the following table.

A deployed WAB provides content on requests from the web. For certain access paths, this can serve content from the resources of the web application: this is called static content. A Web Runtime must use the Servlet Context resource access methods to service static content, the resource loading strategy for these methods is based on the findEntries method, see Resource Lookup. For confidentiality reasons, a Web Runtime must not return any static content for paths that start with one of the following prefixes:

WEB-INF/
OSGI-INF/
META-INF/
OSGI-OPT/

These protected directories are intended to shield code content used for dynamic content generation from accidentally being served over the web, which is a potential attack route. In the servlet specification, the WEB-INF/ directory in the WAR is protected in such a way. However, this protection is not complete. A dependent JAR can actually be placed outside the WEB-INF directory that can then be served as static content. The same is true for a WAB. Though the protected directories must never be served over the web, there are no other checks required to verify that no content can be served that is also available from the Bundle class path.

It is the responsibility of the author of the WAB to ensure that confidential information remains confidential by placing it in one of the protected directories. WAB bundles should be constructed in such a way that they do not accidentally expose code or confidential information. The simplest way to achieve this is to follow the WAR model where code is placed in the WEB-INF/classes directory and this directory is placed on the Bundle's class path as the first entry. For example:

Bundle-ClassPath: WEB-INF/classes, WEB-INF/lib/acme.jar

Dynamic content is content that uses code to generate the content, for example a servlet. This code must be loaded from the bundle with the Bundle loadClass method, following all the Bundle class path rules.

Unlike a WAR, a WAB is not constrained to package classes and code resources in the WEB-INF/classes directory or dependent JARs in WEB-INF/lib/ only. These entries can be packaged in any way that's valid for an OSGi bundle as long as such directories and JARs are part of bundle class path as set with the Bundle-ClassPath header and any attached fragments. JARs that are specified in the Bundle-ClassPath header are treated like JARs in the WEB-INF/lib/ directory of the Servlet specification. Similarly, any directory that is part of the Bundle-ClassPath header is treated like WEB-INF/classes directory of the Servlet specification.

Like WARs, code content that is placed outside the protected directories can be served up to clients as static content.

This example consists of a WAB with the following contents:

acme.jar:
    Bundle-ClassPath: WEB-INF/classes, LIB/bar.jar
    Web-ContextPath: /acme

    WEB-INF/lib/foo.jar
    LIB/bar.jar
    index.html
    favicon.ico

The content of the embedded JARs foo.jar and bar.jar is:

foo.jar:                bar.jar:
    META-INF/foo.tld        META-INF/bar.tld
    foo/FooTag.class        bar/BarTag.class

Assuming there are no special rules in place then the following lists specifies the result of a number of web requests for static content:

/acme/index.html            acme.wab:index.html
/acme/favicon.ico           acme.wab:favicon.ico
/acme/WEB-INF/lib/foo.jar   not found because protecteddirectory
/acme/LIB/bar.jar           acme.wab:LIB/bar.jar  (code, but not protected)

In this example, the tag classes in bar.jar must be found (if JSP is supported) but the tag classes in foo.jar must not because foo.jar is not part of the bundle class path.

A web application is stopped by stopping the corresponding WAB. In response to a WAB STOPPING event, the Web Extender must undeploy the corresponding Web Application from the Servlet Container and clean up any resources. This undeploying must occur synchronously with the WAB's stopping event. This will involve the following steps:

Any failure during undeploying should be logged but must not stop the cleaning up of resources and notification of (other) listeners as well as handling any collisions.

A web application can be uninstalled by uninstalling the corresponding WAB. The WAB will be uninstalled from the OSGi framework.

When the Web Extender is stopped all deployed WABs are undeployed as described in Stopping the Web Application Bundle. Although the WAB is undeployed it remains in the ACTIVE state. When the Web Extender leaves the STOPPING state all WABs will have been undeployed.

The Web URL Handler's scheme is defined to be:

scheme     ::= 'webbundle:' embedded '?' web-params
embedded   ::= <embedded URL according to RFC 1738>
web-params ::= ( web-param ( '&' web-param )* )?
web-param  ::= <key> '=' <value>

The web-param <key> and <value> as well as the <embedded url> must follow [6] Uniform Resource Locators, RFC 1738 for their escaping and character set rules.A Web URL must further follow all the rules of a URL. Whitespaces are not allowed between terms.

An example for a webbundle: URL:

webbundle:http://www.acme.com:8021/sales.war?Web-ContextPath=/sales

Any URL scheme understood by the framework can be embedded, such as an http:, or file: URL. Some forms of embedded URL also contain URL query parameters and this must be supported. The embedded URL most be encoded as a standard URL. That is, the control characters like colon (':' \u003A), solidus ('/' \u002F), percent ('%' \u0025), and ampersand ('&' \u0026) must not be encoded. Thus the value returned from the getPath method may contain a query part. Any implementation must take care to preserve both the query parameters for the embedded URL, and for the complete webbundle: URL. A question mark must always follow the embedded URL to simplify this processing. The following example shows an HTTP URL with some query parameters:

webbundle:http://www.acme.com/sales?id=123?Bundle-SymbolicName=com.example&
                                             Web-ContextPath=/

The URL object for a webbundle: URL must return the following values for the given methods:

For the following example:

webbundle:http://acme.com/repo?war=example.war?Web-ContextPath=/sales

The aforementioned methods must return:

All the parameters in the webbundle: URL are optional except for the Web-ContextPath parameter. The parameter names are case insensitive, but their values must be treated as case sensitive. Table 128.3 describes the parameters that must be supported by any webbundle: URL Stream handler. A Web URL Handler is allowed to support additional parameters.

The Web URL Handler can set or modify the Web-ContextPath of a WAB if the input source is already a bundle. It must be considered as a bundle when any of the OSGi defined headers listed in Table 128.3 is present in the bundle.

For WAB Modification, the Web URL Handler must only support the Web-ContextPath parameter and it must not modify any existing headers other than the Web-ContextPath. Any other parameter given must result in a Bundle Exception.

The Web URL Handler is designed to support the transparent deployment of Java EE Web ARchives (WAR). Such WARs are ignorant of the requirements of the underlying OSGi framework that hosts the Web Runtime. These WARs are not proper OSGi bundles because they do not contain the necessary metadata in the manifest. For example, a WAR without a Bundle-ManifestVersion, Import-Package, and other headers cannot operate in an OSGi framework.

The Web URL Handler implementation copies the contents of the embedded URL to the output and rewrites the manifest headers based on the given parameters. The result must be a WAB.

Any parameters specified must be treated as manifest headers for the web. The following manifest headers must be set to the following values if not specified:

The Web URL Handler is responsible for managing the import dependencies of the WAR. Implementations are free to handle the import dependencies in an implementation defined way. They can augment the Import-Package header with byte-code analysis information, add a fixed set of clauses, and/or use the DynamicImport-Package header as last resort.

Any other manifest headers defined as a parameter or WAR manifest header not described in this section must be copied to the WAB manifest by the Web URL Handler. Such an header must not be modified.

When a signed WAR file is installed using the Web URL Handler, then the manifest rewriting process invalidates the signatures in the bundle. The OSGi specification requires fully signed bundles for security reasons, security resources in partially signed bundles are ignored.

If the use of the signing metadata is required, the WAR must be converted to a WAB during development and then signed. In this case, the Web URL Handler cannot be used. If the Web URL Handler is presented with a signed WAR, the manifest name sections that contain the resource's check sums must be stripped out by the URL stream handler. Any signer files ( *.SF and their corresponding DSA/RSA signature files) must also be removed.

In order to properly integrate in an OSGi environment, a Web Application can access the OSGi service registry for publishing its services, accessing services provided by other bundles, and listening to bundle and service events to track the life cycle of these artifacts. This requires access to the Bundle Context of the WAB.

The Web Extender must make the Bundle Context of the corresponding WAB available to the Web Application via the Servlet Context osgi-bundlecontext attribute. A Servlet can obtain a Bundle Context as follows:

BundleContext ctxt = (BundleContext) 
    servletContext.getAttribute("osgi-bundlecontext");

Web Applications sometimes need to inter-operate with services provided by other component models, such as a Declarative Services or Blueprint. Per the Servlet specification, the Servlet Container owns the life cycle of a Servlet; the life cycle of the Servlet must be subordinate to the life cycle of the Servlet Context, which is only dependent on the life cycle of the WAB. Interactions between different bundles are facilitated by the OSGi service registry. This interaction can be managed in several ways:

Per this specification, it is not possible to make the Servlet life cycle dependent on the availability of specific services. Any synchronization and service dependency management must therefore be done by the Web Application itself.

The getResource and getResourceAsStream methods of the ServletContext interface are used to access resources in the web application. For a WAB, these resources must be found according to the findEntries method, this method includes fragments. For the getResource and getResourceAsStream method, if multiple resources are found, then the first one must be used.

Since the getResource and getResourceAsStream methods do not support wildcards while the findEntries method does it is necessary to escape the wildcard asterisk ('*' \u002A) with prefixing it with a reverse solidus ('\' \u005C). This implies that a reverse solidus must be escaped with an extra reverse solidus. For example, the path foo\bar* must be escaped to foo\\bar\*.

The getResourcePaths method must map to the Bundle getEntryPaths method, its return type is a Set and can not handle multiples. However, the paths from the getEntryPaths method are relative while the methods of the getResourcePaths must be absolute.

For example, assume the following manifest for a bundle:

Bundle-ClassPath: localized, WEB-INF
...

This WAB has an attached fragment acme-de.jar with the following content:

META-INF/MANIFEST.MF
localized/logo.png

The getResource method for localized/logo.png uses the findEntries method to find a resource in the directory /localized and the resource logo.png. Assuming the host bundle has no localized/ directory, the Web Runtime must serve the logo.png resource from the acme-de.jar.

The Web Application web.xml descriptor can specify the metadata-complete attribute on the web-app element. This attribute defines whether the web.xml descriptor is complete, or whether the classes in the bundle should be examined for deployment annotations. If the metadata-complete attribute is set to true, the Web Runtime must ignore any servlet annotations present in the class files of the Web Application. Otherwise, if the metadata-complete attribute is not specified, or is set to false, the container should process the class files of the Web Application for annotations, if supported.

A WAB can make use of the annotations defined by [7] JSR 250 Common Annotations for the Java Platform if supported by the Web Extender. Such a WAB must import the packages the annotations are contained in. A Web Extender that does not support the use of JSR 250 annotations must not process a WAB that imports the annotations package.

Java Server Pages (JSP) is a rendering technology for template based web page construction. This specification supports [4] JSP 2.1 specification if available with the Web Runtime. The servlet element in a web.xml descriptor is used to describe both types of Web Components. JSP components are defined implicitly in the web.xml descriptor through the use of an implicit .jsp extension mapping, or explicitly through the use of a jsp-group element.

A Web Runtime compiles a JSP page into a Servlet, either during the deployment phase, or at the time of request processing, and dispatches the request to an instance of such a dynamically created class. Often times, the compilation task is delegated to a separate JSP compiler that will be responsible for identifying the necessary tag libraries, and generating the corresponding Servlet. The container then proceeds to load the dynamically generated class, creates an instance and dispatches the servlet request to that instance.

Supporting in-line compilation of a JSP inside a bundle will require that the Web Runtime maintains a private area where it can store such compiled classes. The Web Runtime can leverage its private bundle storage area. The Web Runtime can construct a special class loader to load generated JSP classes such that classes from the bundle class path are visible to newly compiled JSP classes.

The JSP specification does not describe how JSP pages are dynamically compiled or reloaded. Various Web Runtime implementations handle the aspects in proprietary ways. This specification does not bring forward any explicit requirements for supporting dynamic aspects of JSP pages.