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

Interface WebAppWebContainerView

All Superinterfaces:

org.ops4j.pax.web.service.views.PaxWebContainerView

public interface WebAppWebContainerView
extends org.ops4j.pax.web.service.views.PaxWebContainerView

This interface should be used by pax-web-extender-war, so the manipulation of different web elements and contexts happens as if all of them belonged to single web application.

Internally, the same methods of Pax Web WebContainer are used, but additionally we can arrange the operations within a kind of transaction. This is desired and expected if all the web elements belong to single WAR (WAB) and also because some kind of validation was already performed when WAB's web.xml (and possibly web fragments and annotated elements) was parsed. Also all the elements really belong to single ServletContext and share single context path.

As with traditional Servlet containers, each WAR (in OSGi: WAB) maps 1:1 to unique servlet context identified by context path. In Whiteboard scenario, many bundles may contribute to a single context (path) by registering servlets, filters, etc. In WAR/WAB scenario, we have to remember about few things:

• When a WAR/WAB is configured, its associated context path doesn't have to be be free. When it's taken by another WAB, new WAB has to be put in failed state, awaiting uninstallation of the previous WAB. When the context is taken using HttpService/Whiteboard, the WAB's context should be treated with highest and indisputable priority, so the Whiteboard/HttpService elements are only used (whether registered before or after the WAB) to alter the WAB.
• After the deployment starts and before it finishes, the context (while not ready yet) has to be marked as unavailable, so no Whiteboard service tries to register any web elements there. This is to keep validation simple - web elements have to be valid only within a scope of single context.
• After the deployment finishes, it should be treated as normal Whiteboard/HttpService context, so we can alter the context by registering (for example) a Whiteboard filter into WAR/WAB context
• If a WAR/WAB's deployment is attempted and associated context (path) is not free, we have to put such WAR/WAB into a kind of pending state, because the conflicting context (path) may at some point be unregistered. This is already implemented for Whiteboard/HttpService scenario, so we need to adjust the mechanism for WARs/WABs as well. However, 128.3.2 "Starting the Web Application Bundle" says simply that "If the Context Path value is already in use by another Web Application, then the Web Application must not be deployed, and the deployment fails. [...] If the prior Web Application with the same Context Path is undeployed later, this Web Application should be considered as a candidate. As mentioned above, only another WAB taking the context may cause the WAB failure.

Before Pax Web 8 there were special begin() and end() methods in WebContainer interface which are now implemented as transactional batches.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	WebAppWebContainerView.AllocationStatus

Method Summary

Modifier and Type	Method and Description
WebAppWebContainerView.AllocationStatus	allocateContext(org.osgi.framework.Bundle wab, String contextPath) Before a WAB can be deployed, we have to check if the target context is available.
Configuration	getConfiguration() Returns Configuration object related to current container
OsgiContextModel	getOsgiContext(org.osgi.framework.Bundle wab, String contextPath) After allocateContext(Bundle, String) has returned true, we can use this method to get the OsgiContextModel created by Pax Web Runtime for our WAB.
ServletContextModel	getServletContext(org.osgi.framework.Bundle wab, String contextPath) After allocateContext(Bundle, String) has returned true, we can use this method to get ServletContextModel for our WAB.
void	registerReportViewPlugin(ReportViewPlugin plugin) Register additional ReportViewPlugin
void	releaseContext(org.osgi.framework.Bundle wab, String contextPath) After a WAB is undeployed, the context path used by this bundle is again free for registration by Whiteboard or HttpService.
void	sendBatch(Batch batch) Pax Web Extender WAR assembles a "web application" using many different sources (web.xml, fragments, annotations, ...).
void	unregisterReportViewPlugin(ReportViewPlugin plugin) Unregister previously registered ReportViewPlugin

Method Detail

allocateContext

WebAppWebContainerView.AllocationStatus allocateContext(org.osgi.framework.Bundle wab,
                                                        String contextPath)

Before a WAB can be deployed, we have to check if the target context is available. If it's not, the WAB will be put into "awaiting free context" state.

Parameters:

wab -

contextPath -

Returns:

getServletContext

ServletContextModel getServletContext(org.osgi.framework.Bundle wab,
                                      String contextPath)

After allocateContext(Bundle, String) has returned true, we can use this method to get ServletContextModel for our WAB.

Parameters:

wab -

contextPath -

Returns:

getOsgiContext

OsgiContextModel getOsgiContext(org.osgi.framework.Bundle wab,
                                String contextPath)

After allocateContext(Bundle, String) has returned true, we can use this method to get the OsgiContextModel created by Pax Web Runtime for our WAB. The same instance should be returned until releaseContext(Bundle, String) is called.

Parameters:

wab -

contextPath -

Returns:

releaseContext

void releaseContext(org.osgi.framework.Bundle wab,
                    String contextPath)

After a WAB is undeployed, the context path used by this bundle is again free for registration by Whiteboard or HttpService.

Parameters:

wab -

contextPath -

sendBatch

void sendBatch(Batch batch)

Pax Web Extender WAR assembles a "web application" using many different sources (web.xml, fragments, annotations, ...). Eventually this method should be used to pass the model with all the servlets, SCIs, filters, listeners, ... to the runtime, so it's send then to actual HTTP runtime.

Parameters:

batch -

registerReportViewPlugin

void registerReportViewPlugin(ReportViewPlugin plugin)

Register additional ReportViewPlugin

Parameters:

plugin -

unregisterReportViewPlugin

void unregisterReportViewPlugin(ReportViewPlugin plugin)

Unregister previously registered ReportViewPlugin

Parameters:

plugin -

getConfiguration

Configuration getConfiguration()

Returns Configuration object related to current container

Returns: