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/07/09 18:29:37 UTC
[8/9] isis git commit: ISIS-1133: documentation relating to web.xml.
ISIS-1133: documentation relating to web.xml.
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/eabc1686
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/eabc1686
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/eabc1686
Branch: refs/heads/master
Commit: eabc1686fe648878fd1c5ebf3304333557dbceb3
Parents: a4989fd
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Thu Jul 9 13:47:37 2015 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Jul 9 13:47:37 2015 +0100
----------------------------------------------------------------------
.../guides/_rg_runtime_deployment-types.adoc | 2 +-
.../asciidoc/guides/_rg_runtime_web-xml.adoc | 444 ++++++++++++++++++-
.../guides/images/runtime/web-xml/key.png | Bin 0 -> 3195 bytes
.../guides/images/runtime/web-xml/parts.pptx | Bin 0 -> 72386 bytes
.../guides/images/runtime/web-xml/ro-only.png | Bin 0 -> 17937 bytes
.../images/runtime/web-xml/wicket-and-ro.png | Bin 0 -> 32723 bytes
.../images/runtime/web-xml/wicket-only.png | Bin 0 -> 16617 bytes
.../webapp/src/main/webapp/WEB-INF/web.xml | 2 +-
8 files changed, 434 insertions(+), 14 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/eabc1686/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 04c1363..f3aeb76 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:ug.adoc#_ug_wicket-viewer[Wicket viewer] and optionally the xref:ug.adoc#_ug_restfulobjects-viewer[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_runtime_web-xml_servlet-context-listener[ `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:rg.adoc#_rg_runtime_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/eabc1686/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_web-xml.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_web-xml.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_web-xml.adoc
index 72204d5..4d7cee4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_web-xml.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_web-xml.adoc
@@ -6,38 +6,458 @@
-NOTE: TODO
+Apache Isis provides two different viewers, the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] and the xref:ug.adoc#_ug_restfulobjects-viewer[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:ug.adoc#_ug_security_configuring-isis-to-use-shiro[security chapter] for full details on this topic.
-== Init Params
+The servlets and filters are mapped to three main pipelines:
-`<isis.viewers>`
+* `/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"]
-[[_rg_runtime_web-xml_servlet-context-listener]]
-== Servlet Context Listener
+the diagram below shows the components to be configured if deploying both the Wicket viewer and Restful Objects viewer:
-NOTE: TODO
+image::{_imagesdir}runtime/web-xml/wicket-and-ro.png[width="800px",link="{_imagesdir}runtime/web-xml/wicket-and-ro.png"]
-`IsisWebAppBootstrapper`
+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:
-== Filters
+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_runtime_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)
+
+NOTE: WIP
+
+definition:
+
+[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.
+
+NOTE: WIP
+
+definition:
+
+[source,xml]
+----
+<listener>
+ <listener-class>org.apache.isis.core.webapp.IsisWebAppBootstrapper</listener-class>
+</listener>
+----
+
+context parameters:
+
+[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.
-NOTE: TODO
+NOTE: WIP
+definition:
+[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_runtime_web-xml_servlets]]
== Servlets
-NOTE: TODO
+NOTE: WIP
+
+
+=== `HttpServletDispatcher` (RestEasy)
+
+NOTE: WIP
+
+
+definition:
+
+[source,xml]
+----
+<servlet>
+ <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
+ <servlet-class>org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher</servlet-class>
+</servlet>
+----
+
+mapping:
+
+[source,xml]
+----
+<servlet-mapping>
+ <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
+ <url-pattern>/restful/*</url-pattern>
+</servlet-mapping>
+----
+
+
+=== `ResourceServlet`
+
+NOTE: WIP
+
+definition
+
+[source,xml]
+----
+<servlet>
+ <servlet-name>Resource</servlet-name>
+ <servlet-class>org.apache.isis.core.webapp.content.ResourceServlet</servlet-class>
+</servlet>
+----
+
+mapping:
+
+[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_runtime_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)
+
+NOTE: WIP
+
+definition:
+
+[source,xml]
+----
+<filter>
+ <filter-name>ShiroFilter</filter-name>
+ <filter-class>org.apache.shiro.web.servlet.ShiroFilter</filter-class>
+</filter>
+----
+
+mapping:
+
+[source,xml]
+----
+<filter-mapping>
+ <filter-name>ShiroFilter</filter-name>
+ <url-pattern>/*</url-pattern>
+</filter-mapping>
+----
+
+
+=== `IsisLogOnExceptionFilter`
+
+NOTE: WIP
+
+definition:
+
+[source,xml]
+----
+<filter>
+ <filter-name>IsisLogOnExceptionFilter</filter-name>
+ <filter-class>org.apache.isis.core.webapp.diagnostics.IsisLogOnExceptionFilter</filter-class>
+</filter>
+----
+
+
+mapping:
+
+[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`
+
+NOTE: WIP
+
+definition:
+
+[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
+
+mapping:
+
+[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`
+
+NOTE: WIP
+
+
+definition:
+
+[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
+
+mapping:
+
+[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`
+
+NOTE: WIP
+
+definition:
+
+[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_runtime_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.
+ <context-param>
+ <param-name>isis.config.dir</param-name>
+ <param-value>location of your config directory if fixed</param-value>
+ </context-param>
+ -->
-== Running RO Viewer only
+ <!--
+ determines which additional configuration files to search for
+ -->
+ <context-param>
+ <param-name>isis.viewers</param-name>
+ <param-value>wicket,restfulobjects</param-value>
+ </context-param>
-NOTE: TODO
http://git-wip-us.apache.org/repos/asf/isis/blob/eabc1686/adocs/documentation/src/main/asciidoc/guides/images/runtime/web-xml/key.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/runtime/web-xml/key.png b/adocs/documentation/src/main/asciidoc/guides/images/runtime/web-xml/key.png
new file mode 100644
index 0000000..b6f6ae9
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/runtime/web-xml/key.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/eabc1686/adocs/documentation/src/main/asciidoc/guides/images/runtime/web-xml/parts.pptx
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/runtime/web-xml/parts.pptx b/adocs/documentation/src/main/asciidoc/guides/images/runtime/web-xml/parts.pptx
new file mode 100644
index 0000000..59c1eeb
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/runtime/web-xml/parts.pptx differ
http://git-wip-us.apache.org/repos/asf/isis/blob/eabc1686/adocs/documentation/src/main/asciidoc/guides/images/runtime/web-xml/ro-only.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/runtime/web-xml/ro-only.png b/adocs/documentation/src/main/asciidoc/guides/images/runtime/web-xml/ro-only.png
new file mode 100644
index 0000000..c96135c
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/runtime/web-xml/ro-only.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/eabc1686/adocs/documentation/src/main/asciidoc/guides/images/runtime/web-xml/wicket-and-ro.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/runtime/web-xml/wicket-and-ro.png b/adocs/documentation/src/main/asciidoc/guides/images/runtime/web-xml/wicket-and-ro.png
new file mode 100644
index 0000000..b8a2d05
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/runtime/web-xml/wicket-and-ro.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/eabc1686/adocs/documentation/src/main/asciidoc/guides/images/runtime/web-xml/wicket-only.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/runtime/web-xml/wicket-only.png b/adocs/documentation/src/main/asciidoc/guides/images/runtime/web-xml/wicket-only.png
new file mode 100644
index 0000000..46070ce
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/runtime/web-xml/wicket-only.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/eabc1686/example/application/simpleapp/webapp/src/main/webapp/WEB-INF/web.xml
----------------------------------------------------------------------
diff --git a/example/application/simpleapp/webapp/src/main/webapp/WEB-INF/web.xml b/example/application/simpleapp/webapp/src/main/webapp/WEB-INF/web.xml
index bb6098f..4de67d5 100644
--- a/example/application/simpleapp/webapp/src/main/webapp/WEB-INF/web.xml
+++ b/example/application/simpleapp/webapp/src/main/webapp/WEB-INF/web.xml
@@ -212,7 +212,7 @@
<context-param>
<param-name>deploymentType</param-name>
- <param-value>SERVER_EXPLORATION</param-value>
+ <param-value>SERVER_PROTOTYPE</param-value>
</context-param>
<context-param>