You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2015/12/03 19:15:43 UTC
[25/51] [abbrv] isis git commit: ISIS-1234: moved headless-access
into the advanced techniques chapter (within ugbtb.adoc). Also moved web-xml
from rg.adoc to ugbtb.adoc
ISIS-1234: moved headless-access into the advanced techniques chapter (within ugbtb.adoc). Also moved web-xml from rg.adoc to ugbtb.adoc
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/f4f26316
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/f4f26316
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/f4f26316
Branch: refs/heads/master
Commit: f4f263164f3ff3e37df7eafb22aa5398ee49ec3e
Parents: b103f76
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Thu Dec 3 16:56:41 2015 +0000
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Dec 3 16:56:41 2015 +0000
----------------------------------------------------------------------
.../guides/_rg_runtime_deployment-types.adoc | 2 +-
.../_rg_runtime_specifying-components.adoc | 2 +-
.../src/main/asciidoc/guides/_rg_web-xml.adoc | 473 -------------------
.../asciidoc/guides/_rgant-Action_command.adoc | 4 +-
.../_rgsvc-spi_BackgroundCommandService.adoc | 2 +-
.../asciidoc/guides/_ugbtb_headless-access.adoc | 27 --
...less-access_AbstractIsisSessionTemplate.adoc | 40 --
...dless-access_BackgroundCommandExecution.adoc | 45 --
.../asciidoc/guides/_ugbtb_more-advanced.adoc | 1 +
.../_ugbtb_more-advanced_headless-access.adoc | 27 ++
...less-access_AbstractIsisSessionTemplate.adoc | 40 ++
...dless-access_BackgroundCommandExecution.adoc | 45 ++
.../main/asciidoc/guides/_ugbtb_web-xml.adoc | 473 +++++++++++++++++++
.../guides/_ugsec_usage-by-isis-viewers.adoc | 2 +-
.../src/main/asciidoc/guides/rg.adoc | 1 -
.../src/main/asciidoc/guides/ugbtb.adoc | 2 +-
16 files changed, 593 insertions(+), 593 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/f4f26316/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_deployment-types.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_deployment-types.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_deployment-types.adoc
index 650f457..a8ce098 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_deployment-types.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_deployment-types.adoc
@@ -66,7 +66,7 @@ Wicket's mechanism for specifying the "configuration" is to use a context parame
Most Apache Isis applications will consist of at least the xref:ugvw.adoc#[Wicket viewer] and optionally the xref:ugvro.adoc#[RestfulObjects viewer]. When both viewers are deployed in the same app, then the bootstrapping is performed by Wicket, and so the deployment type is configured as described in the previous section.
-In some cases though you may be using Apache Isis to provide a REST API only, that is, you won't have deployed the Wicket viewer. In these cases your app will be bootstrapped using Apache Isis' xref:rg.adoc#_rg_web-xml_servlet-context-listeners[ `IsisWebAppBootstrapper`].
+In some cases though you may be using Apache Isis to provide a REST API only, that is, you won't have deployed the Wicket viewer. In these cases your app will be bootstrapped using Apache Isis' xref:ugbtb.adoc#_ugbtb_web-xml_servlet-context-listeners[ `IsisWebAppBootstrapper`].
In this case the deployment type is specified through an Apache Isis-specific context parameter, called `isis.deploymentType`:
http://git-wip-us.apache.org/repos/asf/isis/blob/f4f26316/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_specifying-components.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_specifying-components.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_specifying-components.adoc
index e8f5531..2049ab2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_specifying-components.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_specifying-components.adoc
@@ -96,7 +96,7 @@ If the `AppManifest` is _not_ being used then there are number of other configur
== Viewer Configuration
-Viewers are specified by way of the filters and servlets in the xref:rg.adoc#_rg_web-xml[`web.xml`] file; these are not bootstrapped by the framework, rather it is the other way around. However, we can also hint to the framework as to which viewers are in use by way of a context parameter:
+Viewers are specified by way of the filters and servlets in the xref:ugbtb.adoc#_ugbtb_web-xml[`web.xml`] file; these are not bootstrapped by the framework, rather it is the other way around. However, we can also hint to the framework as to which viewers are in use by way of a context parameter:
[source,xml]
----
http://git-wip-us.apache.org/repos/asf/isis/blob/f4f26316/adocs/documentation/src/main/asciidoc/guides/_rg_web-xml.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_web-xml.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_web-xml.adoc
deleted file mode 100644
index 8490cd2..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_web-xml.adoc
+++ /dev/null
@@ -1,473 +0,0 @@
-[[_rg_web-xml]]
-= `web.xml`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-Apache Isis provides two different viewers, the xref:ugvw.adoc#[Wicket viewer] and the xref:ugvro.adoc#[RestfulObjects viewer]. You can deploy both of these concurrently, or deploy just the Wicket viewer, or deploy just the Restful Objects viewer. The configuration in `web.xml` varies accordingly, both in terms of the servlet context listeners, filters and servlets.
-
-If you are using Apache Isis' integration with Apache Shiro (for security) then this also needs configuring in `web.xml`. See the xref:ugsec.adoc#_ugsec_configuring-isis-to-use-shiro[security chapter] for full details on this topic.
-
-The servlets and filters are mapped to three main pipelines:
-
-* `/wicket` - the Wicket viewer UI
-* `/restful` - the Restful Objects resources (REST API)
-* other paths, also static resources (such as `.png`, `.css`)
-
-With the following key:
-
-image::{_imagesdir}runtime/web-xml/key.png[width="800px",link="{_imagesdir}runtime/web-xml/key.png"]
-
-the diagram below shows the components to be configured if deploying both the Wicket viewer and Restful Objects viewer:
-
-image::{_imagesdir}runtime/web-xml/wicket-and-ro.png[width="800px",link="{_imagesdir}runtime/web-xml/wicket-and-ro.png"]
-
-Here the Wicket viewer is responsible for the main bootstrapping of Apache Isis itself, in other words the shared (global) metadata; this is done by the `IsisWicketApplication` class (extending the `WicketApplication` Wicket API). This class is also responsible for Apache Isis' own session and transaction management.
-
-The Restful Objects viewer - being a JAX-RS application implemented using the RestEasy framework - requires the `RestEasyBootstrapper` servlet context listener. It is this context listener that also sets up the `RestfulObjectsApplication`, which is then delegated to by the RestEasy `HttpServletDispatcher`. This pipeline uses the `IsisSessionFilter` and `IsisTransactionFilterForRestfulObjects` to perform the session and transaction management before it hits the RestEasy servlet.
-
-If only the Wicket viewer is deployed, then the diagram is more or less the same: the RestEasy servlet, context listener and supporting filters are simply removed:
-
-image::{_imagesdir}runtime/web-xml/wicket-only.png[width="800px",link="{_imagesdir}runtime/web-xml/wicket-only.png"]
-
-Finally, if only the Restful Objects viewer is deployed, then things change a little more subtly. Here, the Wicket filter is no longer needed. In its place, though the `IsisWebAppBootstrapper` context listener is required: this is responsible for seting up the shared (global) metadata.
-
-image::{_imagesdir}runtime/web-xml/ro-only.png[width="800px",link="{_imagesdir}runtime/web-xml/ro-only.png"]
-
-The following sections detail these various listeners, filters and servlets in more detail.
-
-
-
-[[_rg_web-xml_servlet-context-listeners]]
-== Servlet Context Listeners
-
-Servlet context listeners are used to perform initialization on application startup. Both Shiro (if configured as the security mechanism) and RestEasy (for the Restful Objects viewer) require their own context listener. In addition, if the Wicket viewer is _not_ being used, then additional Apache Isis-specific listener is required for bootstrapping of the Apache Isis framework itself.
-
-
-=== `EnvironmentLoaderListener` (Shiro)
-
-Bootstrap listener to startup and shutdown the web application's Shiro `WebEnvironment` at startup and shutdown respectively.
-
-Its definition is:
-
-[source,xml]
-----
-<listener>
- <listener-class>org.apache.shiro.web.env.EnvironmentLoaderListener</listener-class>
-</listener>
-----
-
-
-
-=== `IsisWebAppBootstrapper`
-
-The `IsisWebAppBootstrapper` servlet context listener bootstraps the shared (global) metadata for the Apache Isis framework. This listener is not required (indeed must not be configured) if the Wicket viewer is in use.
-
-Its definition is:
-
-[source,xml]
-----
-<listener>
- <listener-class>org.apache.isis.core.webapp.IsisWebAppBootstrapper</listener-class>
-</listener>
-----
-
-Its context parameters are:
-
-[source,xml]
-----
-<context-param>
- <param-name>deploymentType</param-name>
- <param-value>SERVER_PROTOTYPE</param-value>
-</context-param>
-<context-param>
- <param-name>isis.viewers</param-name>
- <param-value>restfulobjects</param-value>
-</context-param>
-----
-
-
-=== `ResteasyBootstrap` (RestEasy)
-
-The `ResteasyBootstrap` servlet context listener initializes the RestEasy runtime, specifying that classes (namely, those specified in Isis' `RestfulObjectsApplication`) to be exposed as REST resources. It is required if the Restful Objects viewer is to be deployed.
-
-Its definition is:
-
-[source,xml]
-----
-<listener>
- <listener-class>org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap</listener-class>
-</listener>
-----
-
-There are two relevant context parameters:
-
-[source,xml]
-----
-<context-param>
- <param-name>javax.ws.rs.Application</param-name> <!--1-->
- <param-value>org.apache.isis.viewer.restfulobjects.server.RestfulObjectsApplication</param-value>
-</context-param>
-<context-param>
- <param-name>resteasy.servlet.mapping.prefix</param-name>
- <param-value>/restful/</param-value> <!--2-->
-</context-param>
-----
-<1> used by RestEasy to determine the JAX-RS resources and other related configuration
-<2> should correspond to the filter mapping of the `HttpServletDispatcher` servlet
-
-
-
-[[_rg_web-xml_servlets]]
-== Servlets
-
-Servlets process HTTP requests and return corresponding responses.
-
-
-=== `HttpServletDispatcher` (RestEasy)
-
-This servlet is provided by the RestEasy framework, and does the dispatching to the resources defined by Apache Isis' `RestfulObjectsApplication` (see above).
-
-Its definition is:
-
-[source,xml]
-----
-<servlet>
- <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
- <servlet-class>org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher</servlet-class>
-</servlet>
-----
-
-Its mapping is:
-
-[source,xml]
-----
-<servlet-mapping>
- <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
- <url-pattern>/restful/*</url-pattern>
-</servlet-mapping>
-----
-
-
-=== `ResourceServlet`
-
-The `ResourceServlet` loads and services static content either from the filesystem or from the classpath, each with an appropriate mime type.
-
-Static content here means request paths ending in `.js`, `.css`, `.html`, `.png`, `.jpg`, `.jpeg` and `gif`.
-
-
-Its definition is:
-
-[source,xml]
-----
-<servlet>
- <servlet-name>Resource</servlet-name>
- <servlet-class>org.apache.isis.core.webapp.content.ResourceServlet</servlet-class>
-</servlet>
-----
-
-Its mapping is:
-
-[source,xml]
-----
-<servlet-mapping>
- <servlet-name>Resource</servlet-name>
- <url-pattern>*.css</url-pattern>
-</servlet-mapping>
-<servlet-mapping>
- <servlet-name>Resource</servlet-name>
- <url-pattern>*.png</url-pattern>
-</servlet-mapping>
-<servlet-mapping>
- <servlet-name>Resource</servlet-name>
- <url-pattern>*.jpg</url-pattern>
-</servlet-mapping>
-<servlet-mapping>
- <servlet-name>Resource</servlet-name>
- <url-pattern>*.gif</url-pattern>
-</servlet-mapping>
-<servlet-mapping>
- <servlet-name>Resource</servlet-name>
- <url-pattern>*.js</url-pattern>
-</servlet-mapping>
-<servlet-mapping>
- <servlet-name>Resource</servlet-name>
- <url-pattern>*.html</url-pattern>
-</servlet-mapping>
-<servlet-mapping>
- <servlet-name>Resource</servlet-name>
- <url-pattern>*.swf</url-pattern>
-</servlet-mapping>
-----
-
-
-
-
-[[_rg_web-xml_filters]]
-== Filters
-
-The order in which filters appear in `web.xml` matters: first to last they define a pipeline. This is shown in the
-above diagrams, and the subsections also list the in the same order that they should appear in your `web.xml`.
-
-
-=== `ShiroFilter` (Shiro)
-
-Shiro filter that sets up a Shiro security manager for the request, obtained from the Shiro `WebEnvironment` set up
-by the Shiro `EnvironmentLoaderListener` (discussed above).
-
-Its definition is:
-
-[source,xml]
-----
-<filter>
- <filter-name>ShiroFilter</filter-name>
- <filter-class>org.apache.shiro.web.servlet.ShiroFilter</filter-class>
-</filter>
-----
-
-Its mapping is:
-
-[source,xml]
-----
-<filter-mapping>
- <filter-name>ShiroFilter</filter-name>
- <url-pattern>/*</url-pattern>
-</filter-mapping>
-----
-
-
-=== `IsisLogOnExceptionFilter`
-
-The `IsisLogOnExceptionFilter` filter simply logs the URL of any request that causes an exception to be thrown, then
-re-propagates the exception. The use case is simply to ensure that all exceptions are logged (against the
-`IsisLogOnExceptionFilter` slf4j appender).
-
-Its definition is:
-
-[source,xml]
-----
-<filter>
- <filter-name>IsisLogOnExceptionFilter</filter-name>
- <filter-class>org.apache.isis.core.webapp.diagnostics.IsisLogOnExceptionFilter</filter-class>
-</filter>
-----
-
-
-Its mapping is:
-
-[source,xml]
-----
-<filter-mapping>
- <filter-name>IsisLogOnExceptionFilter</filter-name>
- <url-pattern>/wicket/*</url-pattern>
-</filter-mapping>
-<filter-mapping>
- <filter-name>IsisLogOnExceptionFilter</filter-name>
- <url-pattern>/restful/*</url-pattern>
-</filter-mapping>
-----
-
-
-
-=== `ResourceCachingFilter`
-
-The `ResourceCachingFilter` adds HTTP cache headers to specified resources, based on their pattern.
-
-Its definition is:
-
-[source,xml]
-----
-<filter>
- <filter-name>ResourceCachingFilter</filter-name>
- <filter-class>org.apache.isis.core.webapp.content.ResourceCachingFilter</filter-class>
- <init-param>
- <param-name>CacheTime</param-name> <!--1-->
- <param-value>86400</param-value>
- </init-param>
-</filter>
-----
-<1> cache time, in seconds
-
-Its mapping is:
-
-[source,xml]
-----
-<filter-mapping>
- <filter-name>ResourceCachingFilter</filter-name>
- <url-pattern>*.js</url-pattern>
-</filter-mapping>
-<filter-mapping>
- <filter-name>ResourceCachingFilter</filter-name>
- <url-pattern>*.css</url-pattern>
-</filter-mapping>
-<filter-mapping>
- <filter-name>ResourceCachingFilter</filter-name>
- <url-pattern>*.png</url-pattern>
-</filter-mapping>
-<filter-mapping>
- <filter-name>ResourceCachingFilter</filter-name>
- <url-pattern>*.jpg</url-pattern>
-</filter-mapping>
-<filter-mapping>
- <filter-name>ResourceCachingFilter</filter-name>
- <url-pattern>*.gif</url-pattern>
-</filter-mapping>
-<filter-mapping>
- <filter-name>ResourceCachingFilter</filter-name>
- <url-pattern>*.html</url-pattern>
-</filter-mapping>
-<filter-mapping>
- <filter-name>ResourceCachingFilter</filter-name>
- <url-pattern>*.swf</url-pattern>
-</filter-mapping>
-----
-
-
-=== `WicketFilter`
-
-The `WicketFilter` is responsible for initiating the handling of Wicket requests.
-
-Its definition is:
-
-[source,xml]
-----
-<filter>
- <filter-name>WicketFilter</filter-name>
- <filter-class>org.apache.wicket.protocol.http.WicketFilter</filter-class>
- <init-param>
- <param-name>applicationClassName</param-name> <!--1-->
- <param-value>domainapp.webapp.SimpleApplication</param-value>
- </init-param>
-</filter>
-----
-<1> specify the application (subclass of `IsisWicketApplication`) to use
-
-Its mapping is:
-
-[source,xml]
-----
-<filter-mapping>
- <filter-name>WicketFilter</filter-name>
- <url-pattern>/wicket/*</url-pattern>
-</filter-mapping>
-----
-
-This filter reads one context parameter:
-[source,xml]
-----
-<context-param>
- <param-name>configuration</param-name>
- <param-value>deployment</param-value> <!--1-->
-</context-param>
-----
-<1> alternatively set to "development"; see xref:rg.adoc#_rg_runtime_deployment-types[deployment types] for further discussion.
-
-
-=== `IsisSessionFilter`
-
-The `IsisSessionFilter` is responsible for the (persistence) session management; in effect a wrapper around DataNucleus' `PersistenceManager` object. It is only required for the Restful Objects viewer.
-
-[source,xml]
-----
-<filter>
- <filter-name>IsisSessionFilterForRestfulObjects</filter-name>
- <filter-class>org.apache.isis.core.webapp.IsisSessionFilter</filter-class>
- <init-param>
- <param-name>authenticationSessionStrategy</param-name> <!--1-->
- <param-value>
- org.apache.isis.viewer.restfulobjects.server.authentication.AuthenticationSessionStrategyBasicAuth
- </param-value>
- </init-param>
- <init-param>
- <param-name>whenNoSession</param-name> <!--2-->
- <param-value>basicAuthChallenge</param-value>
- </init-param>
- <!--
- <init-param>
- <param-name>restricted</param-name> <!--3-->
- <param-value>...</param-value>
- </init-param>
- <init-param>
- <param-name>redirectToOnException</param-name> <!--4-->
- <param-value>...</param-value>
- </init-param>
- -->
-</filter>
-----
-<1> pluggable strategy for determining what the authentication session (credentials) are of the request
-<2> what the servlet should do if no existing session was found; typically a 401, or can issue a Basic Auth challenge
-<3> List of paths that are allowed through even if not authenticated. The servlets mapped to these paths are expected to be able to deal with there being no session. Typically they will be logon pages.
-<4> where to redirect to if an exception occurs.
-
-
-This filter should be mapped to the `servlet-name` for the RestEasy `HttpServletDispatcher`; for example:
-
-[source,xml]
-----
-<filter-mapping>
- <filter-name>IsisSessionFilterForRestfulObjects</filter-name>
- <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
-</filter-mapping>
-----
-
-
-
-
-=== `IsisTransactionFilterForRestfulObjects`
-
-The `IsisTransactionFilterForRestfulObjects` filter simply ensures that a transaction is in progress for all
-calls routed to the xref:ugvro.adoc#[RestfulObjects viewer].
-
-Its definition is:
-
-[source,xml]
-----
-<filter>
- <filter-name>IsisTransactionFilterForRestfulObjects</filter-name>
- <filter-class>org.apache.isis.viewer.restfulobjects.server.webapp.IsisTransactionFilterForRestfulObjects</filter-class>
-</filter>
-----
-
-This filter should be mapped to the `servlet-name` for the RestEasy `HttpServletDispatcher`; for example:
-
-[source,xml]
-----
-<filter-mapping>
- <filter-name>IsisTransactionFilterForRestfulObjects</filter-name>
- <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
-</filter-mapping>
-----
-
-
-
-[[_rg_web-xml_context-parameters]]
-== Configuration Files
-
-However Apache Isis is bootstrapped (using the `IsisWicketApplication` or using `IsisWebAppBootstrapper`), it will
-read a number of configuration files, such as `isis.properties`.
-
-By default these are read from `WEB-INF` directory. This can be overriden using the `isis.config.dir` context parameter:
-
-[source,xml]
-----
-<context-param>
- <param-name>isis.config.dir</param-name>
- <param-value>location of your config directory if fixed</param-value>
-</context-param>
-----
-
-Another context parameter, `isis.viewres` specifies which additional configuration files to search for (over and above
-the default ones of `isis.properties` et al):
-
-[source,xml]
-----
-<context-param>
- <param-name>isis.viewers</param-name>
- <param-value>wicket,restfulobjects</param-value>
-</context-param>
-----
-
-For example, this will cause `viewer_wicket.properties` and `viewer_restfulobjects.properties` to also be loaded.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/f4f26316/adocs/documentation/src/main/asciidoc/guides/_rgant-Action_command.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-Action_command.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-Action_command.adoc
index 6e47d22..7c7cb3a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-Action_command.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-Action_command.adoc
@@ -23,7 +23,7 @@ By default, actions are invoked in directly in the thread of the invocation. I
[NOTE]
====
-If background ``Command``s are used, then an external scheduler, using xref:ugbtb.adoc#_ugbtb_headless-access_BackgroundCommandExecution[headless access], must also be configured.
+If background ``Command``s are used, then an external scheduler, using xref:ugbtb.adoc#_ugbtb_more-advanced_headless-access_BackgroundCommandExecution[headless access], must also be configured.
====
@@ -112,7 +112,7 @@ will prevent the parent `Command` object from being persisted, _even if_ a child
For persisted commands, the `commandExecuteIn()` attribute determines whether the `Command` should be executed in the foreground (the default) or executed in the background.
-Background execution means that the command is not executed immediately, but is available for a configured xref:rgsvc.adoc#_rgsvc-spi_BackgroundCommandService[`BackgroundCommandService`] to execute, eg by way of an in-memory scheduler such as Quartz. See xref:ugbtb.adoc#_ugbtb_headless-access_BackgroundCommandExecution[here] for further information on this topic.
+Background execution means that the command is not executed immediately, but is available for a configured xref:rgsvc.adoc#_rgsvc-spi_BackgroundCommandService[`BackgroundCommandService`] to execute, eg by way of an in-memory scheduler such as Quartz. See xref:ugbtb.adoc#_ugbtb_more-advanced_headless-access_BackgroundCommandExecution[here] for further information on this topic.
For example:
http://git-wip-us.apache.org/repos/asf/isis/blob/f4f26316/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_BackgroundCommandService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_BackgroundCommandService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_BackgroundCommandService.adoc
index 7701409..7bfed67 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_BackgroundCommandService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_BackgroundCommandService.adoc
@@ -55,7 +55,7 @@ public class ActionInvocationMemento {
== "Internal" SPI
-The `BackgroundCommandExecution` (in isis-core) is an abstract template class for xref:ugbtb.adoc#_ugbtb_headless-access_AbstractIsisSessionTemplate[headless access], that defines an abstract hook method to obtain background `Command`s to be executed:
+The `BackgroundCommandExecution` (in isis-core) is an abstract template class for xref:ugbtb.adoc#_ugbtb_more-advanced_headless-access_AbstractIsisSessionTemplate[headless access], that defines an abstract hook method to obtain background `Command`s to be executed:
[source,java]
----
http://git-wip-us.apache.org/repos/asf/isis/blob/f4f26316/adocs/documentation/src/main/asciidoc/guides/_ugbtb_headless-access.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_headless-access.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_headless-access.adoc
deleted file mode 100644
index b6b2ecc..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_headless-access.adoc
+++ /dev/null
@@ -1,27 +0,0 @@
-[[_ugbtb_headless-access]]
-= Headless access
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-This chapter tackles the topic of enabling access to an Isis application directly, or at least, not through either the xref:ugvw.adoc#[Wicket] or xref:ugvro.adoc#[Restful] viewers.
-
-There are several main use-cases:
-
-* enabling background execution, eg of a thread managed by Quartz scheduler and running within the webapp
-
-* integration from other systems, eg for a subscriber on a pub/sub mechanism such as Camel, pushing changes through an Apache Isis domain model.
-
-* leveraging an Isis application within a batch process
-
-Note that the calling thread runs in the same process space as the Apache Isis domain object model (must be physically linked to the JAR files containing the domain classes). For use cases where the calling thread runs in some other process space (eg migrating data from a legacy system), then the xref:ugvro.adoc#[Restful Objects viewer] is usually the way to go.
-
-The API described in this chapter is reasonably low-level, allowing code to interact very directly with the Apache Isis metamodel and runtime. Such callers should be considered trusted: they do not (by default) honour any business rules eg implicit in the Isis annotations or hide/disable/validate methods. However the xref:rgsvc.adoc#_rgsvc-api_WrapperFactory[`WrapperFactory`] service could be used to enforce such business rules if required.
-
-
-
-include::_ugbtb_headless-access_AbstractIsisSessionTemplate.adoc[leveloffset=+1]
-include::_ugbtb_headless-access_BackgroundCommandExecution.adoc[leveloffset=+1]
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/f4f26316/adocs/documentation/src/main/asciidoc/guides/_ugbtb_headless-access_AbstractIsisSessionTemplate.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_headless-access_AbstractIsisSessionTemplate.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_headless-access_AbstractIsisSessionTemplate.adoc
deleted file mode 100644
index 14e0e36..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_headless-access_AbstractIsisSessionTemplate.adoc
+++ /dev/null
@@ -1,40 +0,0 @@
-[[_ugbtb_headless-access_AbstractIsisSessionTemplate]]
-= AbstractIsisSessionTemplate
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-The `AbstractIsisSessionTemplate` class (whose name is inspired by the Spring framework's naming convention for similar classes that query http://docs.spring.io/spring/docs/2.5.x/reference/jdbc.html#jdbc-JdbcTemplate[JDBC], http://docs.spring.io/spring/docs/2.5.x/reference/jms.html#jms-jmstemplate[JMS], http://docs.spring.io/spring/docs/2.5.x/reference/orm.html#orm-jpa-template[JPA] etc.) provides the mechanism to open up a 'session' within the Apache Isis framework, in order to resolve and interact with entities.
-
-The class itself is intended to be subclassed:
-
-[source,java]
-----
-public abstract class AbstractIsisSessionTemplate {
-
- public void execute(final AuthenticationSession authSession, final Object context) { ... } //<1>
- protected abstract void doExecute(Object context); // <2>
-
- protected ObjectAdapter adapterFor(final Object targetObject) { ... }
- protected ObjectAdapter adapterFor(final RootOid rootOid) { ... }
-
- protected PersistenceSession getPersistenceSession() { ... }
- protected IsisTransactionManager getTransactionManager() { ... }
- protected AdapterManager getAdapterManager() { ... }
-}
-----
-<1> `execute(...)` sets up the `IsisSession` and delegates to ...
-<2> `doExecute(...)`, the mandatory hook method for subclasses to implement.
-The passed object represents passes a context from the caller (eg the scheduler, cron job, JMS etc) that instantiated and executed the class.
-
-The `protected` methods expose key internal APIs within Apache Isis, for the subclass to use as necessary.
-
-
-[TIP]
-====
-One notable feature of `AbstractIsisSessionTemplate` is that it will automatically inject any domain services into itself. Thus, it is relatively easy for the subclass to "reach into" the domain, through injected repository services.
-====
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/f4f26316/adocs/documentation/src/main/asciidoc/guides/_ugbtb_headless-access_BackgroundCommandExecution.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_headless-access_BackgroundCommandExecution.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_headless-access_BackgroundCommandExecution.adoc
deleted file mode 100644
index aff468f..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_headless-access_BackgroundCommandExecution.adoc
+++ /dev/null
@@ -1,45 +0,0 @@
-[[_ugbtb_headless-access_BackgroundCommandExecution]]
-= BackgroundCommandExecution
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `BackgroundCommandExecution` class (a subclass of xref:ugbtb.adoc#_ugbtb_headless-access_AbstractIsisSessionTemplate[AbstractIsisSessionTemplate]) is intended to simplify the execution of background ``Command``s persisted by way of the xref:rgsvc.adoc#_rgsvc-spi_CommandService[`CommandService`] and the xref:rgsvc.adoc#_rgsvc-spi_BackgroundCommandService[`BackgroundCommandService`].
-
-Its signature is:
-
-[source,java]
-----
-public abstract class BackgroundCommandExecution extends AbstractIsisSessionTemplate {
- protected void doExecute(Object context) { ... }
- protected abstract List<? extends Command> findBackgroundCommandsToExecute(); // <1>
-}
-----
-<1> `findBackgroundCommandsToExecute()` is a mandatory hook method for subclasses to implement.
-
-This allows for different implementations of the `CommandService` and `BackgroundCommandService` to persist to wherever.
-
-The diagram below (http://yuml.me/edit/363b335f[yuml.me/363b335f]) shows the dependencies between these various classes:
-
-.Inheritance Hierarchy for `BackgroundCommandExecution`
-image::{_imagesdir}headless-access/BackgroundCommandExecution.png[width="400px"]
-
-
-
-
-
-
-
-== Background Execution
-
-The `BackgroundCommandExecutionFromBackgroundCommandServiceJdo` is a concrete subclass of `BackgroundCommandExecution` (see the xref:rgsvc.adoc#_rgsvc-api_BackgroundService[`BackgroundCommandService`]), the intended use being for the class to be instantiated regularly (eg every 10 seconds) by a scheduler such as http://quartz-scheduler.org[Quartz]) to poll for ``Command``s to be executed, and then execute them.
-
-This implementation queries for ``Command``s persisted by the link:http://www.isisaddons.org/isis-module-command[Isis addons Command Module]'s implementations of xref:rgsvc.adoc#_rgsvc-spi_CommandService[`CommandService`] and xref:rgsvc.adoc#_rgsvc-spi_BackgroundCommandService[`BackgroundCommandService`] using the `BackgroundCommandServiceJdoRepository`.
-
-The diagram below (link:http://yuml.me/edit/25343da1[yuml.me/25343da1]) shows the inheritance hierarchy for this class:
-
-.Inheritance Hierarchy for `BackgroundCommandExecutionFromBackgroundCommandServiceJdo`
-image::{_imagesdir}headless-access/BackgroundCommandExecutionFromBackgroundCommandServiceJdo.png[width="500px"]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/f4f26316/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced.adoc
index a31c039..051c8d6 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced.adoc
@@ -18,6 +18,7 @@ include::_ugbtb_more-advanced_i18n.adoc[leveloffset=+1]
include::_ugbtb_more-advanced_multi-tenancy.adoc[leveloffset=+1]
include::_ugbtb_more-advanced_persisted-title.adoc[leveloffset=+1]
include::_ugbtb_more-advanced_replacing-default-service-implementations.adoc[leveloffset=+1]include::_ugbtb_more-advanced_tips-n-tricks.adoc[leveloffset=+1]
+include::_ugbtb_more-advanced_headless-access.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/f4f26316/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_headless-access.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_headless-access.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_headless-access.adoc
new file mode 100644
index 0000000..9369935
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_headless-access.adoc
@@ -0,0 +1,27 @@
+[[_ugbtb_more-advanced_headless-access]]
+= Headless access
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+This section tackles the topic of enabling access to an Isis application directly, or at least, not through either the xref:ugvw.adoc#[Wicket] or xref:ugvro.adoc#[Restful] viewers.
+
+There are several main use-cases:
+
+* enabling background execution, eg of a thread managed by Quartz scheduler and running within the webapp
+
+* integration from other systems, eg for a subscriber on a pub/sub mechanism such as Camel, pushing changes through an Apache Isis domain model.
+
+* leveraging an Isis application within a batch process
+
+Note that the calling thread runs in the same process space as the Apache Isis domain object model (must be physically linked to the JAR files containing the domain classes). For use cases where the calling thread runs in some other process space (eg migrating data from a legacy system), then the xref:ugvro.adoc#[Restful Objects viewer] is usually the way to go.
+
+The API described in this chapter is reasonably low-level, allowing code to interact very directly with the Apache Isis metamodel and runtime. Such callers should be considered trusted: they do not (by default) honour any business rules eg implicit in the Isis annotations or hide/disable/validate methods. However the xref:rgsvc.adoc#_rgsvc-api_WrapperFactory[`WrapperFactory`] service could be used to enforce such business rules if required.
+
+
+
+include::_ugbtb_more-advanced_headless-access_AbstractIsisSessionTemplate.adoc[leveloffset=+1]
+include::_ugbtb_more-advanced_headless-access_BackgroundCommandExecution.adoc[leveloffset=+1]
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/f4f26316/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_headless-access_AbstractIsisSessionTemplate.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_headless-access_AbstractIsisSessionTemplate.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_headless-access_AbstractIsisSessionTemplate.adoc
new file mode 100644
index 0000000..a0dcc5a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_headless-access_AbstractIsisSessionTemplate.adoc
@@ -0,0 +1,40 @@
+[[_ugbtb_more-advanced_headless-access_AbstractIsisSessionTemplate]]
+= AbstractIsisSessionTemplate
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+The `AbstractIsisSessionTemplate` class (whose name is inspired by the Spring framework's naming convention for similar classes that query http://docs.spring.io/spring/docs/2.5.x/reference/jdbc.html#jdbc-JdbcTemplate[JDBC], http://docs.spring.io/spring/docs/2.5.x/reference/jms.html#jms-jmstemplate[JMS], http://docs.spring.io/spring/docs/2.5.x/reference/orm.html#orm-jpa-template[JPA] etc.) provides the mechanism to open up a 'session' within the Apache Isis framework, in order to resolve and interact with entities.
+
+The class itself is intended to be subclassed:
+
+[source,java]
+----
+public abstract class AbstractIsisSessionTemplate {
+
+ public void execute(final AuthenticationSession authSession, final Object context) { ... } //<1>
+ protected abstract void doExecute(Object context); // <2>
+
+ protected ObjectAdapter adapterFor(final Object targetObject) { ... }
+ protected ObjectAdapter adapterFor(final RootOid rootOid) { ... }
+
+ protected PersistenceSession getPersistenceSession() { ... }
+ protected IsisTransactionManager getTransactionManager() { ... }
+ protected AdapterManager getAdapterManager() { ... }
+}
+----
+<1> `execute(...)` sets up the `IsisSession` and delegates to ...
+<2> `doExecute(...)`, the mandatory hook method for subclasses to implement.
+The passed object represents passes a context from the caller (eg the scheduler, cron job, JMS etc) that instantiated and executed the class.
+
+The `protected` methods expose key internal APIs within Apache Isis, for the subclass to use as necessary.
+
+
+[TIP]
+====
+One notable feature of `AbstractIsisSessionTemplate` is that it will automatically inject any domain services into itself. Thus, it is relatively easy for the subclass to "reach into" the domain, through injected repository services.
+====
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/f4f26316/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_headless-access_BackgroundCommandExecution.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_headless-access_BackgroundCommandExecution.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_headless-access_BackgroundCommandExecution.adoc
new file mode 100644
index 0000000..c2ab8d1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_headless-access_BackgroundCommandExecution.adoc
@@ -0,0 +1,45 @@
+[[_ugbtb_more-advanced_headless-access_BackgroundCommandExecution]]
+= BackgroundCommandExecution
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The `BackgroundCommandExecution` class (a subclass of xref:ugbtb.adoc#_ugbtb_more-advanced_headless-access_AbstractIsisSessionTemplate[AbstractIsisSessionTemplate]) is intended to simplify the execution of background ``Command``s persisted by way of the xref:rgsvc.adoc#_rgsvc-spi_CommandService[`CommandService`] and the xref:rgsvc.adoc#_rgsvc-spi_BackgroundCommandService[`BackgroundCommandService`].
+
+Its signature is:
+
+[source,java]
+----
+public abstract class BackgroundCommandExecution extends AbstractIsisSessionTemplate {
+ protected void doExecute(Object context) { ... }
+ protected abstract List<? extends Command> findBackgroundCommandsToExecute(); // <1>
+}
+----
+<1> `findBackgroundCommandsToExecute()` is a mandatory hook method for subclasses to implement.
+
+This allows for different implementations of the `CommandService` and `BackgroundCommandService` to persist to wherever.
+
+The diagram below (http://yuml.me/edit/363b335f[yuml.me/363b335f]) shows the dependencies between these various classes:
+
+.Inheritance Hierarchy for `BackgroundCommandExecution`
+image::{_imagesdir}headless-access/BackgroundCommandExecution.png[width="400px"]
+
+
+
+
+
+
+
+== Background Execution
+
+The `BackgroundCommandExecutionFromBackgroundCommandServiceJdo` is a concrete subclass of `BackgroundCommandExecution` (see the xref:rgsvc.adoc#_rgsvc-api_BackgroundService[`BackgroundCommandService`]), the intended use being for the class to be instantiated regularly (eg every 10 seconds) by a scheduler such as http://quartz-scheduler.org[Quartz]) to poll for ``Command``s to be executed, and then execute them.
+
+This implementation queries for ``Command``s persisted by the link:http://www.isisaddons.org/isis-module-command[Isis addons Command Module]'s implementations of xref:rgsvc.adoc#_rgsvc-spi_CommandService[`CommandService`] and xref:rgsvc.adoc#_rgsvc-spi_BackgroundCommandService[`BackgroundCommandService`] using the `BackgroundCommandServiceJdoRepository`.
+
+The diagram below (link:http://yuml.me/edit/25343da1[yuml.me/25343da1]) shows the inheritance hierarchy for this class:
+
+.Inheritance Hierarchy for `BackgroundCommandExecutionFromBackgroundCommandServiceJdo`
+image::{_imagesdir}headless-access/BackgroundCommandExecutionFromBackgroundCommandServiceJdo.png[width="500px"]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/f4f26316/adocs/documentation/src/main/asciidoc/guides/_ugbtb_web-xml.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_web-xml.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_web-xml.adoc
new file mode 100644
index 0000000..1dc3a24
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_web-xml.adoc
@@ -0,0 +1,473 @@
+[[_ugbtb_web-xml]]
+= `web.xml`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+Apache Isis provides two different viewers, the xref:ugvw.adoc#[Wicket viewer] and the xref:ugvro.adoc#[RestfulObjects viewer]. You can deploy both of these concurrently, or deploy just the Wicket viewer, or deploy just the Restful Objects viewer. The configuration in `web.xml` varies accordingly, both in terms of the servlet context listeners, filters and servlets.
+
+If you are using Apache Isis' integration with Apache Shiro (for security) then this also needs configuring in `web.xml`. See the xref:ugsec.adoc#_ugsec_configuring-isis-to-use-shiro[security chapter] for full details on this topic.
+
+The servlets and filters are mapped to three main pipelines:
+
+* `/wicket` - the Wicket viewer UI
+* `/restful` - the Restful Objects resources (REST API)
+* other paths, also static resources (such as `.png`, `.css`)
+
+With the following key:
+
+image::{_imagesdir}runtime/web-xml/key.png[width="800px",link="{_imagesdir}runtime/web-xml/key.png"]
+
+the diagram below shows the components to be configured if deploying both the Wicket viewer and Restful Objects viewer:
+
+image::{_imagesdir}runtime/web-xml/wicket-and-ro.png[width="800px",link="{_imagesdir}runtime/web-xml/wicket-and-ro.png"]
+
+Here the Wicket viewer is responsible for the main bootstrapping of Apache Isis itself, in other words the shared (global) metadata; this is done by the `IsisWicketApplication` class (extending the `WicketApplication` Wicket API). This class is also responsible for Apache Isis' own session and transaction management.
+
+The Restful Objects viewer - being a JAX-RS application implemented using the RestEasy framework - requires the `RestEasyBootstrapper` servlet context listener. It is this context listener that also sets up the `RestfulObjectsApplication`, which is then delegated to by the RestEasy `HttpServletDispatcher`. This pipeline uses the `IsisSessionFilter` and `IsisTransactionFilterForRestfulObjects` to perform the session and transaction management before it hits the RestEasy servlet.
+
+If only the Wicket viewer is deployed, then the diagram is more or less the same: the RestEasy servlet, context listener and supporting filters are simply removed:
+
+image::{_imagesdir}runtime/web-xml/wicket-only.png[width="800px",link="{_imagesdir}runtime/web-xml/wicket-only.png"]
+
+Finally, if only the Restful Objects viewer is deployed, then things change a little more subtly. Here, the Wicket filter is no longer needed. In its place, though the `IsisWebAppBootstrapper` context listener is required: this is responsible for seting up the shared (global) metadata.
+
+image::{_imagesdir}runtime/web-xml/ro-only.png[width="800px",link="{_imagesdir}runtime/web-xml/ro-only.png"]
+
+The following sections detail these various listeners, filters and servlets in more detail.
+
+
+
+[[_ugbtb_web-xml_servlet-context-listeners]]
+== Servlet Context Listeners
+
+Servlet context listeners are used to perform initialization on application startup. Both Shiro (if configured as the security mechanism) and RestEasy (for the Restful Objects viewer) require their own context listener. In addition, if the Wicket viewer is _not_ being used, then additional Apache Isis-specific listener is required for bootstrapping of the Apache Isis framework itself.
+
+
+=== `EnvironmentLoaderListener` (Shiro)
+
+Bootstrap listener to startup and shutdown the web application's Shiro `WebEnvironment` at startup and shutdown respectively.
+
+Its definition is:
+
+[source,xml]
+----
+<listener>
+ <listener-class>org.apache.shiro.web.env.EnvironmentLoaderListener</listener-class>
+</listener>
+----
+
+
+
+=== `IsisWebAppBootstrapper`
+
+The `IsisWebAppBootstrapper` servlet context listener bootstraps the shared (global) metadata for the Apache Isis framework. This listener is not required (indeed must not be configured) if the Wicket viewer is in use.
+
+Its definition is:
+
+[source,xml]
+----
+<listener>
+ <listener-class>org.apache.isis.core.webapp.IsisWebAppBootstrapper</listener-class>
+</listener>
+----
+
+Its context parameters are:
+
+[source,xml]
+----
+<context-param>
+ <param-name>deploymentType</param-name>
+ <param-value>SERVER_PROTOTYPE</param-value>
+</context-param>
+<context-param>
+ <param-name>isis.viewers</param-name>
+ <param-value>restfulobjects</param-value>
+</context-param>
+----
+
+
+=== `ResteasyBootstrap` (RestEasy)
+
+The `ResteasyBootstrap` servlet context listener initializes the RestEasy runtime, specifying that classes (namely, those specified in Isis' `RestfulObjectsApplication`) to be exposed as REST resources. It is required if the Restful Objects viewer is to be deployed.
+
+Its definition is:
+
+[source,xml]
+----
+<listener>
+ <listener-class>org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap</listener-class>
+</listener>
+----
+
+There are two relevant context parameters:
+
+[source,xml]
+----
+<context-param>
+ <param-name>javax.ws.rs.Application</param-name> <!--1-->
+ <param-value>org.apache.isis.viewer.restfulobjects.server.RestfulObjectsApplication</param-value>
+</context-param>
+<context-param>
+ <param-name>resteasy.servlet.mapping.prefix</param-name>
+ <param-value>/restful/</param-value> <!--2-->
+</context-param>
+----
+<1> used by RestEasy to determine the JAX-RS resources and other related configuration
+<2> should correspond to the filter mapping of the `HttpServletDispatcher` servlet
+
+
+
+[[_ugbtb_web-xml_servlets]]
+== Servlets
+
+Servlets process HTTP requests and return corresponding responses.
+
+
+=== `HttpServletDispatcher` (RestEasy)
+
+This servlet is provided by the RestEasy framework, and does the dispatching to the resources defined by Apache Isis' `RestfulObjectsApplication` (see above).
+
+Its definition is:
+
+[source,xml]
+----
+<servlet>
+ <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
+ <servlet-class>org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher</servlet-class>
+</servlet>
+----
+
+Its mapping is:
+
+[source,xml]
+----
+<servlet-mapping>
+ <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
+ <url-pattern>/restful/*</url-pattern>
+</servlet-mapping>
+----
+
+
+=== `ResourceServlet`
+
+The `ResourceServlet` loads and services static content either from the filesystem or from the classpath, each with an appropriate mime type.
+
+Static content here means request paths ending in `.js`, `.css`, `.html`, `.png`, `.jpg`, `.jpeg` and `gif`.
+
+
+Its definition is:
+
+[source,xml]
+----
+<servlet>
+ <servlet-name>Resource</servlet-name>
+ <servlet-class>org.apache.isis.core.webapp.content.ResourceServlet</servlet-class>
+</servlet>
+----
+
+Its mapping is:
+
+[source,xml]
+----
+<servlet-mapping>
+ <servlet-name>Resource</servlet-name>
+ <url-pattern>*.css</url-pattern>
+</servlet-mapping>
+<servlet-mapping>
+ <servlet-name>Resource</servlet-name>
+ <url-pattern>*.png</url-pattern>
+</servlet-mapping>
+<servlet-mapping>
+ <servlet-name>Resource</servlet-name>
+ <url-pattern>*.jpg</url-pattern>
+</servlet-mapping>
+<servlet-mapping>
+ <servlet-name>Resource</servlet-name>
+ <url-pattern>*.gif</url-pattern>
+</servlet-mapping>
+<servlet-mapping>
+ <servlet-name>Resource</servlet-name>
+ <url-pattern>*.js</url-pattern>
+</servlet-mapping>
+<servlet-mapping>
+ <servlet-name>Resource</servlet-name>
+ <url-pattern>*.html</url-pattern>
+</servlet-mapping>
+<servlet-mapping>
+ <servlet-name>Resource</servlet-name>
+ <url-pattern>*.swf</url-pattern>
+</servlet-mapping>
+----
+
+
+
+
+[[_ugbtb_web-xml_filters]]
+== Filters
+
+The order in which filters appear in `web.xml` matters: first to last they define a pipeline. This is shown in the
+above diagrams, and the subsections also list the in the same order that they should appear in your `web.xml`.
+
+
+=== `ShiroFilter` (Shiro)
+
+Shiro filter that sets up a Shiro security manager for the request, obtained from the Shiro `WebEnvironment` set up
+by the Shiro `EnvironmentLoaderListener` (discussed above).
+
+Its definition is:
+
+[source,xml]
+----
+<filter>
+ <filter-name>ShiroFilter</filter-name>
+ <filter-class>org.apache.shiro.web.servlet.ShiroFilter</filter-class>
+</filter>
+----
+
+Its mapping is:
+
+[source,xml]
+----
+<filter-mapping>
+ <filter-name>ShiroFilter</filter-name>
+ <url-pattern>/*</url-pattern>
+</filter-mapping>
+----
+
+
+=== `IsisLogOnExceptionFilter`
+
+The `IsisLogOnExceptionFilter` filter simply logs the URL of any request that causes an exception to be thrown, then
+re-propagates the exception. The use case is simply to ensure that all exceptions are logged (against the
+`IsisLogOnExceptionFilter` slf4j appender).
+
+Its definition is:
+
+[source,xml]
+----
+<filter>
+ <filter-name>IsisLogOnExceptionFilter</filter-name>
+ <filter-class>org.apache.isis.core.webapp.diagnostics.IsisLogOnExceptionFilter</filter-class>
+</filter>
+----
+
+
+Its mapping is:
+
+[source,xml]
+----
+<filter-mapping>
+ <filter-name>IsisLogOnExceptionFilter</filter-name>
+ <url-pattern>/wicket/*</url-pattern>
+</filter-mapping>
+<filter-mapping>
+ <filter-name>IsisLogOnExceptionFilter</filter-name>
+ <url-pattern>/restful/*</url-pattern>
+</filter-mapping>
+----
+
+
+
+=== `ResourceCachingFilter`
+
+The `ResourceCachingFilter` adds HTTP cache headers to specified resources, based on their pattern.
+
+Its definition is:
+
+[source,xml]
+----
+<filter>
+ <filter-name>ResourceCachingFilter</filter-name>
+ <filter-class>org.apache.isis.core.webapp.content.ResourceCachingFilter</filter-class>
+ <init-param>
+ <param-name>CacheTime</param-name> <!--1-->
+ <param-value>86400</param-value>
+ </init-param>
+</filter>
+----
+<1> cache time, in seconds
+
+Its mapping is:
+
+[source,xml]
+----
+<filter-mapping>
+ <filter-name>ResourceCachingFilter</filter-name>
+ <url-pattern>*.js</url-pattern>
+</filter-mapping>
+<filter-mapping>
+ <filter-name>ResourceCachingFilter</filter-name>
+ <url-pattern>*.css</url-pattern>
+</filter-mapping>
+<filter-mapping>
+ <filter-name>ResourceCachingFilter</filter-name>
+ <url-pattern>*.png</url-pattern>
+</filter-mapping>
+<filter-mapping>
+ <filter-name>ResourceCachingFilter</filter-name>
+ <url-pattern>*.jpg</url-pattern>
+</filter-mapping>
+<filter-mapping>
+ <filter-name>ResourceCachingFilter</filter-name>
+ <url-pattern>*.gif</url-pattern>
+</filter-mapping>
+<filter-mapping>
+ <filter-name>ResourceCachingFilter</filter-name>
+ <url-pattern>*.html</url-pattern>
+</filter-mapping>
+<filter-mapping>
+ <filter-name>ResourceCachingFilter</filter-name>
+ <url-pattern>*.swf</url-pattern>
+</filter-mapping>
+----
+
+
+=== `WicketFilter`
+
+The `WicketFilter` is responsible for initiating the handling of Wicket requests.
+
+Its definition is:
+
+[source,xml]
+----
+<filter>
+ <filter-name>WicketFilter</filter-name>
+ <filter-class>org.apache.wicket.protocol.http.WicketFilter</filter-class>
+ <init-param>
+ <param-name>applicationClassName</param-name> <!--1-->
+ <param-value>domainapp.webapp.SimpleApplication</param-value>
+ </init-param>
+</filter>
+----
+<1> specify the application (subclass of `IsisWicketApplication`) to use
+
+Its mapping is:
+
+[source,xml]
+----
+<filter-mapping>
+ <filter-name>WicketFilter</filter-name>
+ <url-pattern>/wicket/*</url-pattern>
+</filter-mapping>
+----
+
+This filter reads one context parameter:
+[source,xml]
+----
+<context-param>
+ <param-name>configuration</param-name>
+ <param-value>deployment</param-value> <!--1-->
+</context-param>
+----
+<1> alternatively set to "development"; see xref:rg.adoc#_rg_runtime_deployment-types[deployment types] for further discussion.
+
+
+=== `IsisSessionFilter`
+
+The `IsisSessionFilter` is responsible for the (persistence) session management; in effect a wrapper around DataNucleus' `PersistenceManager` object. It is only required for the Restful Objects viewer.
+
+[source,xml]
+----
+<filter>
+ <filter-name>IsisSessionFilterForRestfulObjects</filter-name>
+ <filter-class>org.apache.isis.core.webapp.IsisSessionFilter</filter-class>
+ <init-param>
+ <param-name>authenticationSessionStrategy</param-name> <!--1-->
+ <param-value>
+ org.apache.isis.viewer.restfulobjects.server.authentication.AuthenticationSessionStrategyBasicAuth
+ </param-value>
+ </init-param>
+ <init-param>
+ <param-name>whenNoSession</param-name> <!--2-->
+ <param-value>basicAuthChallenge</param-value>
+ </init-param>
+ <!--
+ <init-param>
+ <param-name>restricted</param-name> <!--3-->
+ <param-value>...</param-value>
+ </init-param>
+ <init-param>
+ <param-name>redirectToOnException</param-name> <!--4-->
+ <param-value>...</param-value>
+ </init-param>
+ -->
+</filter>
+----
+<1> pluggable strategy for determining what the authentication session (credentials) are of the request
+<2> what the servlet should do if no existing session was found; typically a 401, or can issue a Basic Auth challenge
+<3> List of paths that are allowed through even if not authenticated. The servlets mapped to these paths are expected to be able to deal with there being no session. Typically they will be logon pages.
+<4> where to redirect to if an exception occurs.
+
+
+This filter should be mapped to the `servlet-name` for the RestEasy `HttpServletDispatcher`; for example:
+
+[source,xml]
+----
+<filter-mapping>
+ <filter-name>IsisSessionFilterForRestfulObjects</filter-name>
+ <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
+</filter-mapping>
+----
+
+
+
+
+=== `IsisTransactionFilterForRestfulObjects`
+
+The `IsisTransactionFilterForRestfulObjects` filter simply ensures that a transaction is in progress for all
+calls routed to the xref:ugvro.adoc#[RestfulObjects viewer].
+
+Its definition is:
+
+[source,xml]
+----
+<filter>
+ <filter-name>IsisTransactionFilterForRestfulObjects</filter-name>
+ <filter-class>org.apache.isis.viewer.restfulobjects.server.webapp.IsisTransactionFilterForRestfulObjects</filter-class>
+</filter>
+----
+
+This filter should be mapped to the `servlet-name` for the RestEasy `HttpServletDispatcher`; for example:
+
+[source,xml]
+----
+<filter-mapping>
+ <filter-name>IsisTransactionFilterForRestfulObjects</filter-name>
+ <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
+</filter-mapping>
+----
+
+
+
+[[_ugbtb_web-xml_context-parameters]]
+== Configuration Files
+
+However Apache Isis is bootstrapped (using the `IsisWicketApplication` or using `IsisWebAppBootstrapper`), it will
+read a number of configuration files, such as `isis.properties`.
+
+By default these are read from `WEB-INF` directory. This can be overriden using the `isis.config.dir` context parameter:
+
+[source,xml]
+----
+<context-param>
+ <param-name>isis.config.dir</param-name>
+ <param-value>location of your config directory if fixed</param-value>
+</context-param>
+----
+
+Another context parameter, `isis.viewres` specifies which additional configuration files to search for (over and above
+the default ones of `isis.properties` et al):
+
+[source,xml]
+----
+<context-param>
+ <param-name>isis.viewers</param-name>
+ <param-value>wicket,restfulobjects</param-value>
+</context-param>
+----
+
+For example, this will cause `viewer_wicket.properties` and `viewer_restfulobjects.properties` to also be loaded.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/f4f26316/adocs/documentation/src/main/asciidoc/guides/_ugsec_usage-by-isis-viewers.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugsec_usage-by-isis-viewers.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugsec_usage-by-isis-viewers.adoc
index 4676ce6..bd4fd66 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugsec_usage-by-isis-viewers.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugsec_usage-by-isis-viewers.adoc
@@ -49,7 +49,7 @@ Similarly, for those object members that _are_ visible, the viewer also checks i
=== User-registration
-As well as providing a sign-in screen, the Wicket viewer also provides the ability for xref:_user_registration[users to self-register]. By and large this operates outside of Apache Isis' security mechanisms; indeed the various pages (sign-up, sign-up verification, password reset) are all rendered _without_ there being any current user session. These pages all "reach inside" Apache Isis framework using a mechanism similar to xref:ugbtb.adoc#_ugbtb_headless-access[Headless access] in order to actually do their stuff.
+As well as providing a sign-in screen, the Wicket viewer also provides the ability for xref:_user_registration[users to self-register]. By and large this operates outside of Apache Isis' security mechanisms; indeed the various pages (sign-up, sign-up verification, password reset) are all rendered _without_ there being any current user session. These pages all "reach inside" Apache Isis framework using a mechanism similar to xref:ugbtb.adoc#_ugbtb_more-advanced_headless-access[Headless access] in order to actually do their stuff.
[TIP]
====
http://git-wip-us.apache.org/repos/asf/isis/blob/f4f26316/adocs/documentation/src/main/asciidoc/guides/rg.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rg.adoc b/adocs/documentation/src/main/asciidoc/guides/rg.adoc
index e6199b5..05b304e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rg.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rg.adoc
@@ -23,4 +23,3 @@ include::_rg_methods.adoc[leveloffset=+1]
include::_rg_classes.adoc[leveloffset=+1]
include::_rg_runtime.adoc[leveloffset=+1]
include::_rg_schema.adoc[leveloffset=+1]
-include::_rg_web-xml.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/f4f26316/adocs/documentation/src/main/asciidoc/guides/ugbtb.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb.adoc
index d4281c4..7201821 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb.adoc
@@ -29,5 +29,5 @@ This users' guide is _not_ intended as a reference manual; for that see the *xre
include::_ugbtb_more-advanced.adoc[leveloffset=+1]
include::_ugbtb_programming-model.adoc[leveloffset=+1]
include::_ugbtb_deployment.adoc[leveloffset=+1]
-include::_ugbtb_headless-access.adoc[leveloffset=+1]
+include::_ugbtb_web-xml.adoc[leveloffset=+1]