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/11/19 23:42:47 UTC
[6/6] isis git commit: ISIS-1250: more docs
ISIS-1250: more docs
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/4bf7ee1a
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/4bf7ee1a
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/4bf7ee1a
Branch: refs/heads/master
Commit: 4bf7ee1a46be874329101f7030bd992eea2cce76
Parents: d409a71
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Thu Nov 19 22:41:59 2015 +0000
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Nov 19 22:41:59 2015 +0000
----------------------------------------------------------------------
.../main/asciidoc/guides/_rg_schema-aim.adoc | 65 +++++++++++-----
.../main/asciidoc/guides/_rg_schema-common.adoc | 79 +++++++++-----------
...ilities-ActionInvocationMementoDtoUtils.adoc | 47 ------------
.../asciidoc/guides/_rg_schema-utilities.adoc | 18 -----
.../src/main/asciidoc/guides/_rg_schema.adoc | 1 -
..._services-spi_manpage-PublishingService.adoc | 2 +-
.../src/main/asciidoc/guides/_rg_web-xml.adoc | 59 +++++++++------
.../_ug_core-concepts_building-blocks.adoc | 2 +-
.../utils/ActionInvocationMementoDtoUtils.java | 2 +-
9 files changed, 123 insertions(+), 152 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/4bf7ee1a/adocs/documentation/src/main/asciidoc/guides/_rg_schema-aim.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_schema-aim.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_schema-aim.adoc
index 5a3c528..e9903da 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_schema-aim.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_schema-aim.adoc
@@ -5,42 +5,47 @@
:_imagesdir: images/
-NOTE: TODO
+The "aim" schema defines the serialized form (or memento) of an action invocation.
+Action invocations are captured (in memory rather than in serialized form) when the end-user invokes the action
+"through" the UI, by way of the xref:rg.adoc#_rg_services-api_manpage-CommandContext[CommandContext] service. Using the
+`ActionInvocationMementoDtoUtils` utility class, a service can instantiate `ActionInvocationMementoDto` which can then
+be serialized to/from using the same `ActionInvocationMementoDtoUtils` class.
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
-<xs:schema targetNamespace="http://isis.apache.org/schema/aim"
+<xs:schema targetNamespace="http://isis.apache.org/schema/aim" <!--1-->
elementFormDefault="qualified"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns="http://isis.apache.org/schema/aim"
xmlns:common="http://isis.apache.org/schema/common">
- <xs:import namespace="http://isis.apache.org/schema/common" schemaLocation="http://isis.apache.org/schema/common/common-1.0.xsd"/>
+ <xs:import namespace="http://isis.apache.org/schema/common" <!--2-->
+ schemaLocation="http://isis.apache.org/schema/common/common-1.0.xsd"/>
- <xs:element name="actionInvocationMementoDto">
+ <xs:element name="actionInvocationMementoDto"> <!--3-->
<xs:complexType>
<xs:sequence>
<xs:element name="metadata">
<xs:complexType>
<xs:sequence>
- <xs:element name="transactionId" type="xs:string"/>
- <xs:element name="sequence" type="xs:int"/>
- <xs:element name="timestamp" type="xs:dateTime"/>
- <xs:element name="target" type="common:oidDto"/>
- <xs:element name="targetClass" type="xs:string"/>
- <xs:element name="targetAction" type="xs:string"/>
- <xs:element name="actionIdentifier" type="xs:string"/>
- <xs:element name="user" type="xs:string"/>
- <xs:element name="title" type="xs:string"/>
+ <xs:element name="transactionId" type="xs:string"/> <!--4-->
+ <xs:element name="sequence" type="xs:int"/> <!--5-->
+ <xs:element name="timestamp" type="xs:dateTime"/> <!--6-->
+ <xs:element name="target" type="common:oidDto"/> <!--7-->
+ <xs:element name="targetClass" type="xs:string"/> <!--8-->
+ <xs:element name="targetAction" type="xs:string"/> <!--9-->
+ <xs:element name="actionIdentifier" type="xs:string"/> <!--10-->
+ <xs:element name="user" type="xs:string"/> <!--11-->
+ <xs:element name="title" type="xs:string"/> <!--12-->
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="payload">
<xs:complexType>
<xs:sequence>
- <xs:element name="parameters">
+ <xs:element name="parameters"> <!--13-->
<xs:complexType>
<xs:sequence maxOccurs="unbounded">
<xs:element name="param" type="paramDto"/>
@@ -48,7 +53,8 @@ NOTE: TODO
<xs:attribute name="num" use="required" type="xs:int"/>
</xs:complexType>
</xs:element>
- <xs:element name="return" type="common:valueDto" minOccurs="0" maxOccurs="1"/>
+ <xs:element name="return" type="common:valueDto" <!--14-->
+ minOccurs="0" maxOccurs="1"/>
</xs:sequence>
</xs:complexType>
</xs:element>
@@ -56,13 +62,36 @@ NOTE: TODO
</xs:complexType>
</xs:element>
- <xs:complexType name="paramDto">
+ <xs:complexType name="paramDto"> <!--15-->
<xs:sequence>
- <xs:element name="value" type="common:valueDto"/>
+ <xs:element name="value" type="common:valueDto"/> <!--16-->
</xs:sequence>
- <xs:attribute name="parameterName" use="required" type="xs:string"/>
+ <xs:attribute name="parameterName" use="required" type="xs:string"/> <!--17-->
<xs:attribute name="parameterType" use="required" type="common:valueType"/>
<xs:attribute name="null" use="optional" type="xs:boolean"/>
</xs:complexType>
</xs:schema>
----
+<1> the aim schema has a namespace URI of "http://isis.apache.org/schema/aim". Although URIs are not the same as URLs, you will find that the schemas are also downloadable from this location.
+<2> reuses the xref:rg.adoc#_rg_schema-common[common] schema
+<3> definition of the `actionInvocationMementoDto` complex type. This consists of metadata (the transaction identifier, the target object, the initiating user) and the payload (the action parameter/arguments, the return value if known).
+<4> the unique transaction Id (a guid) allocated by the framework for each and every transaction
+<5> a sequence number within the transaction. It is possible for there to be more than one action invocation to be
+<6> when the action was invoked
+<7> target object, as an OID (using `oidDto` from the xref:rg.adoc#_rg_schema-common[common] schema)
+<8> fully qualified class name of the target object, for information only
+<9> name of the action, for information only
+<10> Javadoc style unique identifier for the action.
+<11> User that invoked the action
+<12> title of the target object, for information only
+<13> Collection of parameter/arguments, defined in terms of the `paramDto` complex type (discussed just below)
+<14> The return value of the action, if known (and not void)
+<15> The `paramDto` defines both an action parameter and its corresponding argument values
+<16> The value of the parameter, in other words an argument value
+<17> Metadata about the parameter itself: its name, type, optionality.
+
+[NOTE]
+====
+As of `1.11.0` this schema is not used directly by the framework; in particular `Command#setMemento(...)` sets a similar
+but less formal XML structure. This may change in the future.
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/4bf7ee1a/adocs/documentation/src/main/asciidoc/guides/_rg_schema-common.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_schema-common.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_schema-common.adoc
index aedf188..2582fa4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_schema-common.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_schema-common.adoc
@@ -6,8 +6,6 @@
-== `oidDto`
-
The main purpose of the common schema is to define the `oidDto` complex type: the object's type and its identifier.
This is basically a formal XML equivalent to the `Bookmark` object obtained from the
xref:rg.adoc#_rg_services-api_manpage-BookmarkService[`BookmarkService`].
@@ -17,22 +15,22 @@ a given Apache Isis application. With it, we have the ability to lookup any arb
examples can be found xref:ug.adoc#_ug_core-concepts_building-blocks_oid[here].
-
-
[source,xml]
----
<xs:schema targetNamespace="http://isis.apache.org/schema/common" <!--1-->
elementFormDefault="qualified"
xmlns="http://isis.apache.org/schema/common"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
+
<xs:complexType name="oidDto"> <!--2-->
<xs:sequence>
- <xs:element name="objectType" type="xs:string"/>
- <xs:element name="objectIdentifier" type="xs:string"/>
+ <xs:element name="objectType" type="xs:string"/> <!--3-->
+ <xs:element name="objectIdentifier" type="xs:string"/> <!--4-->
</xs:sequence>
<xs:attribute name="objectState" type="bookmarkObjectState" default="persistent"/>
</xs:complexType>
- <xs:simpleType name="bookmarkObjectState">
+
+ <xs:simpleType name="bookmarkObjectState"> <!--5-->
<xs:restriction base="xs:string">
<xs:enumeration value="persistent"/>
<xs:enumeration value="transient"/>
@@ -42,12 +40,31 @@ examples can be found xref:ug.adoc#_ug_core-concepts_building-blocks_oid[here].
...
</xs:schema>
----
+<1> the common schema has a namespace URI of "http://isis.apache.org/schema/common". Although URIs are not the same as URLs, you will find that the schemas are also downloadable from this location.
+<2> the `oidDto` complex type defines the unique identifier for any domain object: its type, and an identifier. The `objectState` attribute is of type `bookmarkObjectState` and will typically be "transient" or "viewModel"
+<3> the object type, corresponding to either the
+xref:rg.adoc#_rg_annotations_manpage-DomainObject_objectType[`@DomainObject#objectType()`] attribute, or to the (JDO)
+xref:rg.adoc#_rg_annotations_manpage-PersistenceCapable[`@PersistenceCapable`] annotation (`schema` and/or `table`
+attributes), or to the (JDO) xref:rg.adoc#_rg_annotations_manpage-Discriminator[`@Discriminator`] annotation. If none
+is specified, then the fully
+qualified class name will be used.
+<4> the object identifier (aka primary key), converted to string form.
+<5> the `bookmarkObjectState` enumerates the possible persistence states of the referenced object. Although "transient" is shown,
+in practice the only types of objects will be "persistent" (entities) or "viewModel".
+
+The `oidDto` complex type is used in two specific places by the framework:
-This
+* first, as a means of serializing JAXB view model/DTOs (annotated with
+xref:rg.adoc#_rg_annotations_manpage-XmlRootElement[`@XmlRootElement`]), that reference domain entities. +
++
+These references are serialized instead into OIDs
-== `valueDto` and `valueType`
+* second, as references to the target of action invocations, as described by the
+xref:rg.adoc#_rg_schema-aim[action invocation memento] schema. +
++
+They are also used to represent references to any action arguments that take domain object entities.
-The common schema defines two further types: the `valueDto` complex type and the `valueType` simple type:
+The common schema also defines two further types: the `valueDto` complex type and the `valueType` simple type:
[source,xml]
----
@@ -56,48 +73,23 @@ The common schema defines two further types: the `valueDto` complex type and the
xmlns="http://isis.apache.org/schema/common"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
...
- <xs:complexType name="valueDto"> <!--1-->
+ <xs:complexType name="valueDto"> <!--1-->
<xs:choice minOccurs="0" maxOccurs="1">
<xs:element name="string" type="xs:string"/>
<xs:element name="byte" type="xs:byte"/>
<xs:element name="short" type="xs:short"/>
- <xs:element name="int" type="xs:int"/>
- <xs:element name="long" type="xs:long"/>
- <xs:element name="float" type="xs:float"/>
- <xs:element name="double" type="xs:double"/>
- <xs:element name="boolean" type="xs:boolean"/>
- <xs:element name="char" type="xs:string"/>
- <xs:element name="bigDecimal" type="xs:decimal"/>
- <xs:element name="bigInteger" type="xs:integer"/>
- <xs:element name="dateTime" type="xs:dateTime"/>
- <xs:element name="localDate" type="xs:date"/>
- <xs:element name="localDateTime" type="xs:dateTime"/>
+ ...
<xs:element name="localTime" type="xs:time"/>
<xs:element name="reference" type="oidDto"/>
</xs:choice>
</xs:complexType>
- <xs:simpleType name="valueType"> <!--2-->
+
+ <xs:simpleType name="valueType"> <!--2-->
<xs:restriction base="xs:string">
<xs:enumeration value="string"/>
<xs:enumeration value="byte"/>
<xs:enumeration value="short"/>
- <xs:enumeration value="int"/>
- <xs:enumeration value="long"/>
- <xs:enumeration value="float"/>
- <xs:enumeration value="double"/>
- <xs:enumeration value="boolean"/>
- <xs:enumeration value="char"/>
- <xs:enumeration value="bigInteger"/>
- <xs:enumeration value="bigDecimal"/>
- <xs:enumeration value="javaUtilDate"/>
- <xs:enumeration value="javaSqlDate"/>
- <xs:enumeration value="javaSqlTime"/>
- <xs:enumeration value="javaSqlTimestamp"/>
- <xs:enumeration value="jodaDateTime"/>
- <xs:enumeration value="jodaLocalDate"/>
- <xs:enumeration value="jodaLocalTime"/>
- <xs:enumeration value="jodaLocalDateTime"/>
- <xs:enumeration value="isisApplibBlob"/>
+ ...
<xs:enumeration value="isisApplibClob"/>
<xs:enumeration value="reference"/>
</xs:restriction>
@@ -105,6 +97,7 @@ The common schema defines two further types: the `valueDto` complex type and the
</xs:schema>
----
-These two definitions are just building blocks, both used within the xref:rg.adoc#_rg_schema-aim[Action Invocation Memento]
-schema. The first, `valueDto` is intended to hold any valid value, eg of an argument to an action. The second,
-`valueType`, enumerates the different types of vales, eg of a formal parameter to an action.
+These two type definitions are just building blocks, also used within the
+xref:rg.adoc#_rg_schema-aim[action iInvocation memento] schema. The first, `valueDto` is intended to hold any valid
+value, eg of an argument to an action. The second, `valueType`, enumerates the different types of vales, eg of a
+formal parameter to an action.
http://git-wip-us.apache.org/repos/asf/isis/blob/4bf7ee1a/adocs/documentation/src/main/asciidoc/guides/_rg_schema-utilities-ActionInvocationMementoDtoUtils.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_schema-utilities-ActionInvocationMementoDtoUtils.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_schema-utilities-ActionInvocationMementoDtoUtils.adoc
deleted file mode 100644
index a9d2609..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_schema-utilities-ActionInvocationMementoDtoUtils.adoc
+++ /dev/null
@@ -1,47 +0,0 @@
-[[_rg_schema-utilities-ActionInvocationMementoDtoUtils]]
-= `ActionInvocationMementoDtoUtils`
-: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/
-
-
-NOTE: TODO
-
-`ActionInvocationMementoDtoUtils`
-
-
-[source,java]
-----
-public class ActionInvocationMementoDtoUtils {
- public static ActionInvocationMementoDto newDto() { ... } // <1>
- public static void setMetadata( ... ) { ... }
- public static boolean addArgValue( ... ) { ... }
- public static void addArgReference( ... ) { ... }
- public static boolean addReturnValue( ... ) { ... }
- public static void addReturnReference( ... ) { ... }
-
- public static int getNumberOfParameters(final ActionInvocationMementoDto aim) { ... } // <2>
- public static List<ParamDto> getParameters(final ActionInvocationMementoDto aim) { ... }
- public static List<String> getParameterNames(final ActionInvocationMementoDto aim) { ... }
- public static List<ValueType> getParameterTypes(final ActionInvocationMementoDto aim) { ... }
- public static ParamDto getParameter(final ActionInvocationMementoDto aim, final int paramNum) { ... } // <3>
- public static ValueDto getParameterValue(final ActionInvocationMementoDto aim, final int paramNum) { ... }
- public static String getParameterName(final ActionInvocationMementoDto aim, final int paramNum) { ... }
- public static ValueType getParameterType(final ActionInvocationMementoDto aim, final int paramNum) { ... }
- public static boolean isNull(final ActionInvocationMementoDto aim, int paramNum) { ... }
-
- public static <T> T getArg(final ActionInvocationMementoDto aim, int paramNum, Class<T> cls) { ... } // <3>
-
- public static ActionInvocationMementoDto fromXml(Reader reader) { ... } // <4>
- public static ActionInvocationMementoDto fromXml(
- final Class<?> contextClass,
- final String resourceName,
- final Charset charset) throws IOException { ... }
- public static String toXml(final ActionInvocationMementoDto aim) { ... }
- public static void toXml(final ActionInvocationMementoDto aim, final Writer writer) { ... }
-}
-----
-<1> not API; for the Apache Isis framework itself to create and initialize DTOs representing action invocations
-<2> API, obtaining metadata about the action invocation
-<3> API, obtaining the argument value for a particular parameter of the action invocation
-<4> marshall the DTO to/from XML
http://git-wip-us.apache.org/repos/asf/isis/blob/4bf7ee1a/adocs/documentation/src/main/asciidoc/guides/_rg_schema-utilities.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_schema-utilities.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_schema-utilities.adoc
deleted file mode 100644
index d5130e1..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_schema-utilities.adoc
+++ /dev/null
@@ -1,18 +0,0 @@
-[[_rg_schema-utilities]]
-= Utilities
-: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/
-
-
-NOTE: TODO
-
-In addition to defining the schemas themselves, Apache Isis also provides some simple helper classes, under the
-`org.apache.isis.schema.utils` package.
-
-
-include::_rg_schema-utilities-ActionInvocationMementoDtoUtils.adoc[leveloffset=+1]
-
-
-
-PersistentEntityAdapter.class
http://git-wip-us.apache.org/repos/asf/isis/blob/4bf7ee1a/adocs/documentation/src/main/asciidoc/guides/_rg_schema.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_schema.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_schema.adoc
index c05e127..b7e97ee 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_schema.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_schema.adoc
@@ -22,4 +22,3 @@ The sections below discuss these schemas in more detail.
include::_rg_schema-common.adoc[leveloffset=+1]
include::_rg_schema-aim.adoc[leveloffset=+1]
-include::_rg_schema-utilities.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/4bf7ee1a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-PublishingService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-PublishingService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-PublishingService.adoc
index 2af475b..a46a39e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-PublishingService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-PublishingService.adoc
@@ -67,7 +67,7 @@ The (non-ASF) http://github.com/isisaddons/isis-module-publishmq[Isis addons' pu
implementation (`org.isisaddons.module.publismq.dom.servicespi.PublishingServiceUsingActiveMq`) that publishes each
action invocation as an event on an link:http://activemq.apache.org[ActiveMQ] message queue. These are converted into
a canonical XML form (the xref:rg.adoc#_rg_schema-aim[ActionInvocationMemento] schema) using the
-xref:rg.adoc#_rg_schema-utilities-ActionInvocationMementoDtoUtils[`ActionInvocationMementoDtoUtils`] class; the idea
+`ActionInvocationMementoDtoUtils` class; the idea
being that subscribers on the ActiveMQ message queue can then query back for further information, for example using
the xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer].
http://git-wip-us.apache.org/repos/asf/isis/blob/4bf7ee1a/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
index b32535a..70b1b40 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_web-xml.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_web-xml.adoc
@@ -153,7 +153,10 @@ Its mapping is:
=== `ResourceServlet`
-NOTE: WIP
+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:
@@ -205,11 +208,14 @@ Its mapping is:
[[_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`.
+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
+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:
@@ -234,7 +240,9 @@ Its mapping is:
=== `IsisLogOnExceptionFilter`
-NOTE: WIP
+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:
@@ -265,7 +273,7 @@ Its mapping is:
=== `ResourceCachingFilter`
-NOTE: WIP
+The `ResourceCachingFilter` adds HTTP cache headers to specified resources, based on their pattern.
Its definition is:
@@ -319,8 +327,7 @@ Its mapping is:
=== `WicketFilter`
-NOTE: WIP
-
+The `WicketFilter` is responsible for initiating the handling of Wicket requests.
Its definition is:
@@ -410,7 +417,8 @@ This filter should be mapped to the `servlet-name` for the RestEasy `HttpServlet
=== `IsisTransactionFilterForRestfulObjects`
-NOTE: WIP
+The `IsisTransactionFilterForRestfulObjects` filter simply ensures that a transaction is in progress for all
+calls routed to the xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer].
Its definition is:
@@ -437,22 +445,29 @@ This filter should be mapped to the `servlet-name` for the RestEasy `HttpServlet
[[_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`.
+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.
+By default these are read from `WEB-INF` directory. This can be overriden using the `isis.config.dir` context parameter:
- <context-param>
- <param-name>isis.config.dir</param-name>
- <param-value>location of your config directory if fixed</param-value>
- </context-param>
- -->
+[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):
- <!--
- determines which additional configuration files to search for
- -->
- <context-param>
- <param-name>isis.viewers</param-name>
- <param-value>wicket,restfulobjects</param-value>
- </context-param>
+[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/4bf7ee1a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_building-blocks.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_building-blocks.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_building-blocks.adoc
index 90e0977..e6163d0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_building-blocks.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_building-blocks.adoc
@@ -208,7 +208,7 @@ in Apache Isis, and do _not_ correspond to actions even though they have public
-== Domain Entities vs View Models
+== Entities vs View Models
When developing an Apache Isis application you will most likely start off with the persistent domain entities:
`Customer`, `Order`, `Product`, and so on. For some applications this may well suffice. However, if the application
http://git-wip-us.apache.org/repos/asf/isis/blob/4bf7ee1a/core/schema/src/main/java/org/apache/isis/schema/utils/ActionInvocationMementoDtoUtils.java
----------------------------------------------------------------------
diff --git a/core/schema/src/main/java/org/apache/isis/schema/utils/ActionInvocationMementoDtoUtils.java b/core/schema/src/main/java/org/apache/isis/schema/utils/ActionInvocationMementoDtoUtils.java
index 1314b75..30128b2 100644
--- a/core/schema/src/main/java/org/apache/isis/schema/utils/ActionInvocationMementoDtoUtils.java
+++ b/core/schema/src/main/java/org/apache/isis/schema/utils/ActionInvocationMementoDtoUtils.java
@@ -62,7 +62,7 @@ import org.apache.isis.schema.utils.jaxbadapters.JodaLocalDateTimeXMLGregorianCa
import org.apache.isis.schema.utils.jaxbadapters.JodaLocalDateXMLGregorianCalendarAdapter;
import org.apache.isis.schema.utils.jaxbadapters.JodaLocalTimeXMLGregorianCalendarAdapter;
-public class ActionInvocationMementoDtoUtils {
+public final class ActionInvocationMementoDtoUtils {
//region > static
private static final Function<ParamDto, String> PARAM_DTO_TO_NAME = new Function<ParamDto, String>() {