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/22 20:42:20 UTC
[2/8] isis git commit: ISIS-1258: updating docs.
ISIS-1258: updating docs.
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/3aabf7f5
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/3aabf7f5
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/3aabf7f5
Branch: refs/heads/master
Commit: 3aabf7f53024db0f5443ad52715cfb7836e32255
Parents: a43967b
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Sun Nov 22 19:12:27 2015 +0000
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Sun Nov 22 19:12:27 2015 +0000
----------------------------------------------------------------------
.../asciidoc/guides/_cg_isis-maven-plugin.adoc | 231 +---------
.../guides/_cg_isis-maven-plugin_validate.adoc | 241 ++++++++++
.../guides/_cg_isis-maven-plugin_xsd.adoc | 321 +++++++++++++
.../guides/_ug_more-advanced_view-models.adoc | 447 +------------------
.../_ug_more-advanced_view-models_jaxb.adoc | 240 ++++++++++
...-advanced_view-models_programming-model.adoc | 87 ++++
..._ug_more-advanced_view-models_use-cases.adoc | 142 ++++++
.../guides/_ug_restfulobjects-viewer.adoc | 2 -
8 files changed, 1057 insertions(+), 654 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/3aabf7f5/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin.adoc
index 9eba2fd..0aee53b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin.adoc
@@ -5,25 +5,33 @@
:_imagesdir: images/
:toc: right
+The Apache Isis Maven plugin defines two goals:
-The Apache Isis programming model requires that a number of naming conventions are followed.
+* `validate` +
++
+Use to verify at build time that the metamodel of an application is valid. This runs the `MetaModelValidator` that is also run when the application is started up.
-For example, the validator will detect any orphaned supporting methods (eg `hideXxx()`) if the corresponding property or action has been renamed or deleted but the supporting method was not also updated. Another example is that a class cannot have a title specified both using `title()` method and also using `@Title` annotation.
+* `xsd` +
++
+Uses the xref:rg.adoc#_rg_services-api_manpage-JaxbService[`JaxbService`] to generate XSD schemas from any JAXB-annotated view models/DTOs. +
++
+This is instead of and preferable to using the JAXB link:https://jaxb.java.net/2.2.4/docs/schemagen.html[schemagen] tool, because it uses the framework's support (via xref:rg.adoc#_rg_annotations_manpage-XmlJavaValueType[`@XmlJavaValueType`]) to translate any references to domain objects into ``OidDto``s (as defined by the Apache Isis xref:rg.adoc#_rg_schema-common[common schema]).
-When running the application these are enforced by the `MetaModelValidator` component that detects these errors, failing fast.
+The `validate` goal is by default bound to the `test` phase of your application's `dom` sub-module, whereas the `xsd` goal defaults to the `generate-resources` phase of a completely separate `canonical` submodule. An example can be found in the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] example app.
-The purpose of the `isis-maven-plugin` is to enforce these naming conventions at build time, typically enforced by way of a continuous integration server.
-[NOTE]
-====
-The instructions given here relate to `1.10.0`. The plugin was also released for `1.9.0`, but with a slightly different configuration; see the final section for differences.
-====
+Both goals require an xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[`AppManifest`] to point the plugin at, so that
+it knows how to bootstrap an Isis runtime. This is discussed below, followed by sections on configuring the two goals.
-== `dom` project
-To start with, we need an xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[`AppManifest`] to point the plugin at so that it knows which services and entities are to be validated.
+== `AppManifest`
+
+As noted in the introduction, both goals require an xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[`AppManifest`]
+to point the plugin at, so that it knows how to bootstrap an Isis runtime.
+
+This can be extremely minimal. For example, the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp]'s
+manifest is:
-This can be extremely minimal. For example, the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp]'s manifest is:
[source,java]
----
@@ -54,207 +62,14 @@ where `DomainAppDomainModule` simply identifies the package for the manifest to
[source,java]
----
package domainapp.dom;
-public final class DomainAppDomainModule {
-}
-----
-
-Next, update the `pom.xml` (in your project's `dom` module):
-
-[source,xml]
-----
-<profile>
- <id>isis-validate</id>
- <activation>
- <property>
- <name>isis-validate</name> <!--1-->
- </property>
- </activation>
- <build>
- <plugins>
- <plugin>
- <groupId>org.apache.isis.tool</groupId>
- <artifactId>isis-maven-plugin</artifactId>
- <version>${isis.version}</version> <!--2-->
- <configuration>
- <appManifest>domainapp.dom.DomainAppDomManifest</appManifest> <!--3-->
- </configuration>
- <dependencies>
- <dependency>
- <groupId>${project.groupId}</groupId>
- <artifactId>simpleapp-dom</artifactId> <!--4-->
- <version>${project.version}</version>
- </dependency>
- <!-- workaround to avoid conflict with plexus-default -->
- <dependency>
- <groupId>com.google.guava</groupId>
- <artifactId>guava</artifactId>
- <version>16.0.1</version>
- </dependency>
- </dependencies>
- <executions>
- <execution>
- <phase>test</phase>
- <goals>
- <goal>validate</goal> <!--5-->
- </goals>
- </execution>
- </executions>
- </plugin>
- </plugins>
- </build>
-</profile>
-----
-<1> the profile can be activated using `-Disis-validate`
-<2> set to `1.10.0` (or any later version)
-<3> the manifest discussed previously; adjust as required
-<4> the `dom` module for the project; adjust as required
-<5> binds the plugin's `validate` goal to the Maven `test` lifecycle phase (ie the goal will be called when `mvn test` is run).
-
-
-
-
-== To run
-
-The plugin is activated by enabling the profile and invoking the `test` phase:
-
-[source,bash]
+public final class DomainAppDomainModule { }
----
-mvn test -Disis-validate
-----
-
-This will run any tests, and then also - because the plugin is activated by the `isis-validate` property and bound to the `test` phase, will run the plugin's `validate` goal.
-
-
-
-
-== Example of failure
-
-In the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp] application the `SimpleObject` defines an `updateName` action. This has a supporting method:
-[source,java]
-----
-public SimpleObject updateName( ... ) { ... }
-public String default0UpdateName() { ... }
-----
-
-We can introduce an error by misspelling the supporting method, for example:
+As you'll see below, the configuration for the two goals both refer to this app manifest.
-[source,java]
-----
-public String default0XUpdateName() { ... }
-----
-Running `mvn -Disis-valdate test` then generates this output:
-
-
-[source,bash]
-----
-[error]
-[error]
-[error]
-[error] domainapp.dom.simple.SimpleObject#default0XUpdateName: has prefix default, is probably a supporting method for a property, collection or action. If the method is intended to be an action, then rename and use @ActionLayout(named="...") or ignore completely using @Programmatic
-[error]
-[error]
-[error]
-[INFO] ------------------------------------------------------------------------
-[INFO] Reactor Summary:
-[INFO]
-[INFO] Simple App ......................................... SUCCESS [ 0.087 s]
-[INFO] Simple App DOM ..................................... FAILURE [ 4.182 s]
-[INFO] Simple App Fixtures ................................ SKIPPED
-[INFO] Simple App Application ............................. SKIPPED
-[INFO] Simple App Integration Tests ....................... SKIPPED
-[INFO] Simple App Webapp .................................. SKIPPED
-[INFO] ------------------------------------------------------------------------
-[INFO] BUILD FAILURE
-[INFO] ------------------------------------------------------------------------
-[INFO] ...
-[ERROR] Failed to execute goal org.apache.isis.tool:isis-maven-plugin:1.11.0-SNAPSHOT:validate (default) on project simpleapp-dom: 1 problems found. -> [Help 1]
-----
-
-If one were to attempt to run the application, the same error would appear in the log files on startup (and the application would not boot).
-
-
-
-
-== Custom validation rules
-
-It is also possible to customize the validation, explained xref:ug.adoc#_ug_extending_programming-model_custom-validator[here]. For example, you could enforce project-specific conventions by implementing a custom `MetaModelValidator`, and registering using a configuration property.
-
-To support this using `AppManifest`s, override its `getConfigurationProperties()` method:
-
-[source,ini]
-----
-public class DomainAppDomManifest implements AppManifest {
- ...
- public Map<String, String> getConfigurationProperties() {
- final Map<String, String> map = Maps.newTreeMap();
- map.put("isis.reflector.validator","com.mycompany.myapp.MyMetaModelValidator");
- return map;
- }
-}
-----
-
-
-== 1.9.0 version
-
-The `1.9.0` version of the plugin requires slightly different configuratoin. Rather than using an `AppManifest`, instead the configuration directory containing `isis.properties` is specified:
-
-[source,xml]
-----
-<profile>
- <id>isis-validate</id>
- <activation>
- <activeByDefault>false</activeByDefault> <!--1-->
- </activation>
- <build>
- <plugins>
- <plugin>
- <groupId>org.apache.isis.tool</groupId>
- <artifactId>isis-maven-plugin</artifactId>
- <version>1.9.0-SNAPSHOT</version>
- <configuration>
- <isisConfigDir>../webapp/src/main/webapp/WEB-INF</isisConfigDir> <!--2-->
- </configuration>
- <dependencies>
- <dependency>
- <groupId>org.apache.isis.example.application</groupId>
- <artifactId>simpleapp-dom</artifactId>
- <version>1.9.0-SNAPSHOT</version>
- </dependency>
- <!-- workaround to avoid conflict with plexus-default -->
- <dependency>
- <groupId>com.google.guava</groupId>
- <artifactId>guava</artifactId>
- <version>16.0.1</version>
- </dependency>
- </dependencies>
- <executions>
- <execution>
- <phase>test</phase>
- <goals>
- <goal>validate</goal>
- </goals>
- </execution>
- </executions>
- </plugin>
- </plugins>
- </build>
-</profile>
-----
-<1> activated using the `-P` profile flag rather than a `-D` system property
-<2> specify the `isisConfigDir` directory (containing the `isis.properties` file).
-
-To use the `1.9.0` version, use:
-
-[source,bash]
-----
-mvn -P isis-validate test
-----
-[NOTE]
-====
-Note that the `isisConfigDir` property was removed in `1.10.0`; only the `AppManifest` approach is supported.
-====
+include::_cg_isis-maven-plugin_validate.adoc[leveloffset=+1]
+include::_cg_isis-maven-plugin_xsd.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/3aabf7f5/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin_validate.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin_validate.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin_validate.adoc
new file mode 100644
index 0000000..7d2709e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin_validate.adoc
@@ -0,0 +1,241 @@
+[[_cg_isis-maven-plugin_validate]]
+= `validate` goal
+: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/
+:toc: right
+
+
+The Apache Isis programming model requires that a number of naming conventions are followed.
+
+For example, the validator will detect any orphaned supporting methods (eg `hideXxx()`) if the corresponding property
+or action has been renamed or deleted but the supporting method was not also updated. Another example is that a class
+cannot have a title specified both using `title()` method and also using `@Title` annotation.
+
+When running the application these are enforced by the `MetaModelValidator` component that detects these errors, failing fast.
+
+The purpose of the `validate` goal of the `isis-maven-plugin` is to enforce these naming conventions at build time,
+typically enforced by way of a continuous integration server.
+
+The `validate` goal defines a single property:
+
+* `appManifest` - fully qualified class name for the app manifest used to bootstrap the application (see discussion above)
+
+The sections below explain how to configure the plugin within an app.
+
+[NOTE]
+====
+The instructions given here relate to `1.10.0`. This goal was also released for `1.9.0`, but with a slightly
+different configuration; see the final section for differences.
+====
+
+
+== `dom` submodule
+
+Update the `pom.xml` (in your project's `dom` module):
+
+[source,xml]
+----
+<profile>
+ <id>isis-validate</id>
+ <activation>
+ <property>
+ <name>!skip.isis-validate</name> <!--1-->
+ </property>
+ </activation>
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.isis.tool</groupId>
+ <artifactId>isis-maven-plugin</artifactId>
+ <version>${isis.version}</version> <!--2-->
+ <configuration>
+ <appManifest>domainapp.dom.DomainAppDomManifest</appManifest> <!--3-->
+ </configuration>
+ <dependencies>
+ <dependency>
+ <groupId>${project.groupId}</groupId>
+ <artifactId>simpleapp-dom</artifactId> <!--4-->
+ <version>${project.version}</version>
+ </dependency>
+ <!-- workaround to avoid conflict with plexus-default -->
+ <dependency>
+ <groupId>com.google.guava</groupId>
+ <artifactId>guava</artifactId>
+ <version>16.0.1</version>
+ </dependency>
+ </dependencies>
+ <executions>
+ <execution>
+ <phase>test</phase>
+ <goals>
+ <goal>validate</goal> <!--5-->
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+</profile>
+----
+<1> the profile is active by default, though can be disabled using `-Dskip.isis-validate`
+<2> set to `1.10.0` (or any later version)
+<3> the manifest discussed previously; adjust as required
+<4> the `dom` module for the project; adjust as required
+<5> binds the plugin's `validate` goal to the Maven `test` lifecycle phase (ie the goal will be called when `mvn test` is run).
+
+
+
+
+== To run
+
+The plugin is activated by default, so is run simply using:
+
+[source,bash]
+----
+mvn test
+----
+
+This will run any tests, and then also - because the plugin is activated by the `isis-validate` property and bound to the `test` phase, will run the plugin's `validate` goal.
+
+
+If for any reason you want to disable the validation, use:
+
+[source,bash]
+----
+mvn test -Dskip.isis-validate
+----
+
+
+
+== Example of failure
+
+In the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp] application the `SimpleObject` defines an `updateName` action. This has a supporting method:
+
+
+[source,java]
+----
+public SimpleObject updateName( ... ) { ... }
+public String default0UpdateName() { ... }
+----
+
+We can introduce an error by misspelling the supporting method, for example:
+
+[source,java]
+----
+public String default0XUpdateName() { ... }
+----
+
+Running `mvn test` then generates this output:
+
+
+[source,bash]
+----
+[error]
+[error]
+[error]
+[error] domainapp.dom.simple.SimpleObject#default0XUpdateName: has prefix default, is probably a supporting method for a property, collection or action. If the method is intended to be an action, then rename and use @ActionLayout(named="...") or ignore completely using @Programmatic
+[error]
+[error]
+[error]
+[INFO] ------------------------------------------------------------------------
+[INFO] Reactor Summary:
+[INFO]
+[INFO] Simple App ......................................... SUCCESS [ 0.087 s]
+[INFO] Simple App DOM ..................................... FAILURE [ 4.182 s]
+[INFO] Simple App Fixtures ................................ SKIPPED
+[INFO] Simple App Application ............................. SKIPPED
+[INFO] Simple App Integration Tests ....................... SKIPPED
+[INFO] Simple App Webapp .................................. SKIPPED
+[INFO] ------------------------------------------------------------------------
+[INFO] BUILD FAILURE
+[INFO] ------------------------------------------------------------------------
+[INFO] ...
+[ERROR] Failed to execute goal org.apache.isis.tool:isis-maven-plugin:1.11.0-SNAPSHOT:validate (default) on project simpleapp-dom: 1 problems found. -> [Help 1]
+----
+
+If one were to attempt to run the application, the same error would appear in the log files on startup (and the application would not boot).
+
+
+
+
+== Custom validation rules
+
+It is also possible to customize the validation, explained xref:ug.adoc#_ug_extending_programming-model_custom-validator[here]. For example, you could enforce project-specific conventions by implementing a custom `MetaModelValidator`, and registering using a configuration property.
+
+To support this using `AppManifest`s, override its `getConfigurationProperties()` method:
+
+[source,ini]
+----
+public class DomainAppDomManifest implements AppManifest {
+ ...
+ public Map<String, String> getConfigurationProperties() {
+ final Map<String, String> map = Maps.newTreeMap();
+ map.put("isis.reflector.validator","com.mycompany.myapp.MyMetaModelValidator");
+ return map;
+ }
+}
+----
+
+
+== 1.9.0 version
+
+The `1.9.0` version of the plugin requires slightly different configuratoin. Rather than using an `AppManifest`, instead the configuration directory containing `isis.properties` is specified:
+
+[source,xml]
+----
+<profile>
+ <id>isis-validate</id>
+ <activation>
+ <activeByDefault>false</activeByDefault> <!--1-->
+ </activation>
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.isis.tool</groupId>
+ <artifactId>isis-maven-plugin</artifactId>
+ <version>1.9.0-SNAPSHOT</version>
+ <configuration>
+ <isisConfigDir>../webapp/src/main/webapp/WEB-INF</isisConfigDir> <!--2-->
+ </configuration>
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.isis.example.application</groupId>
+ <artifactId>simpleapp-dom</artifactId>
+ <version>1.9.0-SNAPSHOT</version>
+ </dependency>
+ <!-- workaround to avoid conflict with plexus-default -->
+ <dependency>
+ <groupId>com.google.guava</groupId>
+ <artifactId>guava</artifactId>
+ <version>16.0.1</version>
+ </dependency>
+ </dependencies>
+ <executions>
+ <execution>
+ <phase>test</phase>
+ <goals>
+ <goal>validate</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+</profile>
+----
+<1> activated using the `-P` profile flag rather than a `-D` system property
+<2> specify the `isisConfigDir` directory (containing the `isis.properties` file).
+
+To use the `1.9.0` version, use:
+
+[source,bash]
+----
+mvn -P isis-validate test
+----
+
+[NOTE]
+====
+Note that the `isisConfigDir` property was removed in `1.10.0`; only the `AppManifest` approach is supported.
+====
+
http://git-wip-us.apache.org/repos/asf/isis/blob/3aabf7f5/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin_xsd.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin_xsd.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin_xsd.adoc
new file mode 100644
index 0000000..1e52c08
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin_xsd.adoc
@@ -0,0 +1,321 @@
+[[_cg_isis-maven-plugin_xsd]]
+= `xsd` goal (`1.11.0-SNAPSHOT`)
+: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/
+:toc: right
+
+
+The `xsd` goal of the `isis-maven-plugin` uses the xref:rg.adoc#_rg_services-api_manpage-JaxbService[`JaxbService`] to
+generate XSD schemas from any JAXB-annotated xref:ug.adoc#_ug_more-advanced_view-models[view model/DTOs].
+
+This is instead of and preferable to using the JAXB link:https://jaxb.java.net/2.2.4/docs/schemagen.html[schemagen]
+tool, because it uses the framework's support (via
+xref:rg.adoc#_rg_annotations_manpage-XmlJavaValueType[`@XmlJavaValueType`]) to translate any references to domain
+objects into ``OidDto``s (as defined by the Apache Isis xref:rg.adoc#_rg_schema-common[common schema]).
+
+The `xsd` goal defines the following properties:
+
+* `appManifest` - fully qualified class name for the app manifest used to bootstrap the application (see discussion above)
+
+* `jaxbClasses` - a list of xref:rg.adoc#_ug_more-advanced_view-models_jaxb[JAXB-annotated view model] classes;
+
+* `output` - (optional) subdirectory under the `target` directory to generate the XSDs +
++
+Defaults to `generated-resources/isis-xsd`
+
+* `separate` - (optional) whether to create separate directories for each JAXB-class. +
++
+Defaults to `false`. Most DTO classes will reference one another or the xref:rg.adoc#_rg_schema-common[common schema]. Normally it's fine to merge all these XSDs together. This property, if set, results in each a separate directory for each generation of its XSD or XSDs.
+
+The sections below explain in more detail how to configure the plugin.
+
+As a convenience to potential Java subscribers, the XSDs generated from the view models can then in turn be generated
+into DTOs. The original view models and these DTOs are similar but not identical: the view models can only be used
+within the Isis application (they may reference underlying domain entities) whereas the DTO classes generated from the
+XSDs can be used standalone, eg by a Java subscriber running on an ESB such as Apache Camel.
+
+
+
+
+[[_cg_isis-maven-plugin_xsd]]
+== `xsd` submodule
+
+We recommend creating a new submodule that will perform the following build steps:
+
+* run the `xsd` goal (in the `generate-resources` phase) to generate the XSDs from the specified view model/DTOs
+
+* use the link:http://maven.apache.org/plugins/maven-assembly-plugin/[maven-assembly-plugin] to bundle the
+ generated XSD files into a zip file.
+
+* use the `xjc-gen` to generate corresponding DTO classes from the XSDs. +
++
+These are _not_ the same as the original view models; they are provided as a convenience for subscribers to marshall XML documents into Java classes, but running as a standalone process (not part of the Isis app)
+
+
+For example, here is the `pom.xml` file for the (non-ASF)
+http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] example app's `todoapp-xsd` submodule.
+
+First, the usual boilerplate:
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+
+ <parent>
+ <groupId>org.isisaddons.app</groupId>
+ <artifactId>todoapp</artifactId>
+ <version>1.11.0-SNAPSHOT</version>
+ </parent>
+
+ <artifactId>todoapp-xsd</artifactId>
+ <name>Isis Addons ToDoApp XSD</name>
+
+ <dependencies>
+ <dependency>
+ <groupId>${project.groupId}</groupId>
+ <artifactId>todoapp-app</artifactId> <!--1-->
+ </dependency>
+ </dependencies>
+
+ <profiles>
+ <profile>
+ <id>isis-xsd</id> <!--2-->
+ ...
+ </profile>
+ <profile>
+ <id>xjc</id> <!--3-->
+ ...
+ </profile>
+ </profiles>
+</project>
+----
+<1> depends on the rest of the application's modules
+<2> XSD generation, to run the `xsd` goal and then assemble into a zip file; within a profile for modularity
+<3> XJC generation, to run the `xjc` to generate Java DTO classes from XSDs; within a profile for modularity
+
+
+
+=== XSD profile
+
+The `isis-xsd` profile runs the `xsd` goal of the `isis-maven-plugin`; these are then zipped up by the assembly plugin:
+
+[source,xml]
+----
+<profile>
+ <id>isis-xsd</id>
+ <activation>
+ <property>
+ <name>!skip.isis-xsd</name> <!--1-->
+ </property>
+ </activation>
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.isis.tool</groupId>
+ <artifactId>isis-maven-plugin</artifactId>
+ <version>${isis.version}</version>
+ <configuration>
+ <appManifest>todoapp.dom.ToDoAppDomManifest</appManifest> <!--2-->
+ <jaxbClasses> <!--3-->
+ <jaxbClass>todoapp.app.viewmodels.todoitem.v1_0.ToDoItemDto</jaxbClass>
+ <jaxbClass>todoapp.app.viewmodels.todoitem.v1_1.ToDoItemDto</jaxbClass>
+ </jaxbClasses>
+ </configuration>
+ <dependencies>
+ <dependency>
+ <groupId>${project.groupId}</groupId>
+ <artifactId>todoapp-dom</artifactId>
+ <version>${project.version}</version>
+ </dependency>
+ <dependency> <!--4-->
+ <groupId>com.google.guava</groupId>
+ <artifactId>guava</artifactId>
+ <version>16.0.1</version>
+ </dependency>
+ </dependencies>
+ <executions>
+ <execution>
+ <phase>generate-sources</phase> <!--5-->
+ <goals>
+ <goal>xsd</goal> <!--6-->
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ <plugin>
+ <artifactId>maven-assembly-plugin</artifactId> <!--7-->
+ <version>2.5.3</version>
+ <configuration>
+ <descriptor>src/assembly/dep.xml</descriptor> <!--8-->
+ </configuration>
+ <executions>
+ <execution>
+ <id>create-archive</id>
+ <phase>package</phase>
+ <goals>
+ <goal>single</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+</profile>
+----
+<1> enabled _unless_ `skip.isis-xsd` property specified
+<2> specify the app manifest to bootstrap the Isis runtime within the maven plugin
+<3> enumerate all JAXB-annotated view models
+<4> workaround to avoid conflict with plexus-default
+<5> by default is bound to `generate-resources`, but bind instead to `generate-sources` if also running the `xjc` profile: the XSD are an input to `xjc`, but it is bound by default to `generate-sources` and the `generate-sources` phase runs before the `generate-resources`.
+<6> run the `xsd` goal
+<7> define the assembly plugin
+<8> assembles the XSD schemas into a zip file, as defined by the `dep.xml` file (see below).
+
+ The `dep.xml` file, referenced by the `assembly` plugin, is defined as:
+
+[source,xml]
+----
+<assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2
+ http://maven.apache.org/xsd/assembly-1.1.2.xsd">
+ <id>xsd</id>
+ <formats>
+ <format>zip</format>
+ </formats>
+ <fileSets>
+ <fileSet>
+ <directory>${project.build.directory}/generated-resources/isis-xsd</directory> <!--1-->
+ <outputDirectory>/</outputDirectory>
+ </fileSet>
+ </fileSets>
+</assembly>
+----
+<1> the location that the `xsd` goal writes to.
+
+
+
+=== XJC profile
+
+The `xjc` profile reads the XSD generated by the `xsd` goal, and from it generates Java DTOs. Note that this isn't
+round-tripping: the original view model is only for use within the Isis app, whereas the DTO generated from the XSDs
+is for use in a standalone context, eg in a Java subscriber on an event bus.
+
+The `xjc` profile is defined as:
+
+[source,xml]
+----
+<profile>
+ <id>xjc</id>
+ <activation>
+ <property>
+ <name>!skip.xjc</name> <!--1-->
+ </property>
+ </activation>
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.jvnet.jaxb2.maven2</groupId>
+ <artifactId>maven-jaxb2-plugin</artifactId>
+ <version>0.12.3</version>
+ <executions>
+ <execution>
+ <id>xjc-generate</id>
+ <phase>generate-sources</phase>
+ <goals>
+ <goal>generate</goal>
+ </goals>
+ </execution>
+ </executions>
+ <configuration>
+ <removeOldOutput>true</removeOldOutput>
+ <schemaDirectory> <!--2-->
+ target/generated-resources/isis-xsd/viewmodels.app.todoapp/todoitem
+ </schemaDirectory>
+ <schemaIncludes> <!--3-->
+ <schemaInclude>v1_0/todoitem.xsd</schemaInclude>
+ <schemaInclude>v1_1/todoitem.xsd</schemaInclude>
+ </schemaIncludes>
+ <catalog>src/main/resources/catalog.xml</catalog> <!--4-->
+ </configuration>
+ </plugin>
+ <plugin>
+ <groupId>org.codehaus.mojo</groupId>
+ <artifactId>build-helper-maven-plugin</artifactId> <!--5-->
+ <version>1.9.1</version>
+ <executions>
+ <execution>
+ <id>add-source</id>
+ <phase>generate-sources</phase>
+ <goals>
+ <goal>add-source</goal>
+ </goals>
+ <configuration>
+ <sources>
+ <source>target/generated-sources/xjc</source> <!--6-->
+ </sources>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+</profile>
+----
+<1> enabled _unless_ `skip.xjc` property specified
+<2> specifies the directory that the XSD schemas were generated to by the `isis-maven-plugin`
+<3> specify each of the XSDs to be processed
+<4> catalog file indicates the location of the referenced link:_rg_schema-common[common schema] XSDs.
+<5> the `build-helper-maven-plugin` adds the Java source generated by the `xjc` plugin so that it can be compiled and
+packaged as any other code
+<6> the location that the `xjc` plugin generates its source code.
+
+
+The referenced `catalog.xml` file instructs the `xjc` plugin how to resolve referenced schema locations. Only a
+reference for the Apache Isis link:_rg_schema-common[common schema] is likely to be needed:
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE catalog
+ PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN"
+ "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">
+<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
+ <public publicId="http://isis.apache.org/schema/common"
+ uri="http://isis.apache.org/schema/common/common.xsd"/> <!--1-->
+</catalog>
+----
+<1> resolve the common schema from the Apache Isis website
+
+
+== To run
+
+The plugin is activated by default, so is run simply using:
+
+[source,bash]
+----
+mvn package
+----
+
+This will generate the XSDs, the DTOs from the XSDs, and package up the XSDs into a ZIP file and the generated DTO
+class files into a regular JAR package.
+
+
+If for any reason you want to disable the generation of the DTOs, use:
+
+[source,bash]
+----
+mvn test -Dskip.xjc
+----
+
+If you want to disable the generation of both the XSDs and the DTOs, use:
+
+[source,bash]
+----
+mvn test -Dskip.xjc -Dskip.isis-xsd
+----
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/3aabf7f5/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_view-models.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_view-models.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_view-models.adoc
index 2f84f8d..97d13ee 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_view-models.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_view-models.adoc
@@ -12,449 +12,8 @@ This opens up a number of more advanced use cases.
In this topic we'll explore those use cases, and learn the programming model and conventions to use view models in your application.
+include::_ug_more-advanced_view-models_use-cases.adoc[leveloffset=+1]
+include::_ug_more-advanced_view-models_programming-model.adoc[leveloffset=+1]
+include::_ug_more-advanced_view-models_jaxb.adoc[leveloffset=+1]
-[[_ug_more-advanced_view-models_use-cases]]
-== Use Cases
-
-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
-needs to integrate with other systems, or if the application needs to support reasonably complex business processes, then you may need to look beyond just domain entities. This section explores these use cases.
-
-=== Externally-managed entities
-
-Sometimes the entities that make up your application are persisted not in the local JDO/DataNucleus database
-but reside in some other system, for example accessible only through a SOAP web service. Logically that data
-might still be considered a domain entity and we might want to associate behaviour with it, however it cannot be
-modelled as a domain entity if only because JDO/DataNucleus doesn't know about the entity nor how to retrieve or
-update it.
-
-There are a couple of ways around this: we could either replicate the data somehow from the external system into the
- Isis-managed database (in which case it is once again just another domain entity), or we could set up a stub/proxy for
- the externally managed entity. This proxy would hold the reference to the externally-managed domain entity (eg an
- external id), as well as the "smarts" to know how to interact with that entity (by making SOAP web service calls etc).
-
-The stub/proxy is a type of view model: a view - if you like - onto the domain entity managed by the external system.
-
-[NOTE]
-====
-DataNucleus does in fact define its own link:http://www.datanucleus.org/documentation/extensions/store_manager.html[Store Manager] extension point, so an alternative architecture would be to implement this interface such that DataNucleus
-could make the calls to the external system; these externally-persisted domain entities would therefore be modelled as regular `@PersistenceCapable` entities after all. For entities not persisted externally the implementation would delegate down to the default RDBMS-specific `StoreManager` provided by DataNucleus itself.
-
-An implementation that supported only reading from an external entity ought to be comparatively straight-forward, but
-implementing one that also supported updating external entities would need to carefully consider error conditions if the
-external system is unavailable; distributed transactions are most likely difficult/impossible to implement (and not
-desirable in any case).
-====
-
-
-=== In-memory entities
-
-As a variation on the above, sometimes there are domain objects that are, conceptually at least entities, but whose
-state is not actually persisted anywhere, merely held in-memory (eg in a hash).
-
-A simple example might be read-only configuration data that is read from a config file (eg log4j appender
-definitions) but thereafter is presented in the UI just like any other entity.
-
-
-=== Application-layer view models
-
-Domain entities (whether locally persisted using JDO/DataNucleus or managed externally) are the bread-and-butter of Apache Isis applications: the focus after all, should be on the business domain concepts and ensuring that they are
-solid. Generally those domain entities will make sense to the business domain experts: they form the _ubiquitous language_ of the domain. These domain entities are part of the domain layer.
-
-That said, it may not always be practical to expect end-users of the application to interact solely with those domain
-entities. For example, it may be useful to show a dashboard of the most significant data in the system to a user,
-often pulling in and aggregating information from multiple points of the app. Obtaining this information by hand (by
- querying the respective services/repositories) would be tedious and slow; far better to have a dashboard do the job for
- the end user.
-
-A dashboard object is a model of the most relevant state to the end-user, in other words it is (quite literally) a view
- model. It is not a persisted entity, instead it belongs to the application layer.
-
-A view model need not merely aggregate data; it could also provide actions of its own. Most likely these actions will
-be queries and will always ultimately just delegate down to the appropriate domain-layer service/repository. But in
-some cases such view model actions might also modify state of underlying domain entities.
-
-Another common use for view models is to help co-ordinate complex business processes; for example to perform a
-quarterly invoicing run, or to upload annual interest rates from an Excel spreadsheet. In these cases the view model
-might have some state of its own, but in most cases that state does not need to be persisted per se.
-
-.Desire Lines
-****
-One way to think of application view models is as modelling the "desire line": the commonly-trod path
-that end-users must follow to get from point A to point B as quickly as possible.
-
-To explain: there are link:http://ask.metafilter.com/62599/Where-the-sidewalk-ends[documented]
-link:https://sivers.org/walkways[examples]
-link:http://www.softpanorama.org/People/Wall/larry_wall_articles_and_interviews.shtml[that] architects of university
-campus will only add in paths some while after the campus buildings are complete: let the pedestrians figure out the
-routes they want to take. The name we like best for this idea is "desire lines", though it has also been called
-a "desire path", "paving the path" or "paving the sidewalk".
-
-What that means is you should add view models _after_ having built up the domain layer, rather than before. These view
-models pave that commonly-trod path, automating the steps that the end-user would otherwise have to do by hand.
-
-It takes a little practice though, because even when building the domain layer "first", you should still bear in mind
-what the use cases are that those domain entities are trying to support. You certainly _shouldn't_ try to build out a
-domain layer that could support every conceivable use case before starting to think about view models.
-
-Instead, you should iterate. Identify the use case/story/end-user objective that you will deliver value to the
-business. Then build out the minimum domain entities to support that use case (refining the xref:ug.adoc#_ug_core-concepts_philosophy_domain-driven-design_ubiquitous-language[ubiquitous language] as you
-go). Then, identify if there any view models that could be introduced which would simplify the end-user interactions
-with the system (perhaps automating several related use cases together).
-****
-
-=== DTOs (`1.11.0-SNAPSHOT`)
-
-DTOs (data transfer objects) are simple classes that (according to link:https://en.wikipedia.org/wiki/Data_transfer_object[wikipedia]) "carries data between processes".
-
-If those two processes are parts of the same overall application (the same team builds and deploys both server and
-client) then there's generally no need to define a DTO; just access the entities using Apache Isis'
-xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer].
-
-On the other hand, if the client consuming the DTO is a different application -- by which we mean developed/deployed by
-a different (possible third-party) team -- then the DTOs act as a formal contract between the provider and the consumer.
-In such cases, exposing domain entities over xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects] would be
-"A Bad Thing"(TM) because the consumer would in effect have access to implementation details that could then not be
-easily changed by the producer.
-
-Instead, a view model can be defined to act as a DTO. To put this formal contract onto a solid footing, this view
-model can (as of `1.11.0-SNAPSHOT`) simply be defined as a JAXB-annotated entity; this allows the consumer to obtain
-the DTO in XML format along with a corresponding XSD schema describing the structure of that XML. These XML
-representations can be surfaced by the xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer] (by implementing
-the xref:rg.adoc#_rg_services-spi_manpage-ContentMappingService[`ContentMappingService`]); the XSD can be obtained
-using the xref:rg.adoc#_rg_services-api_manpage-JaxbService[`JaxbService`]. Using the formalism of XML also allows
-DTOs to be carefully and properly versioned using XML namespaces.
-
-[TIP]
-====
-If the view model DTO implements the xref:rg.adoc#_rg_classes_mixins_Dto[`Dto`] marker interface, then the framework
-will also provide the ability to download the XML or its XSD directly from the UI.
-====
-
-In case it's not clear, these DTOs are still usable as "regular" view models; they will render in the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] just like any other. Indeed (as the xref:ug.adoc#_ug_more-advanced_view-models_programming-model[programming model] section below makes clear), these
-JAXB-annotated view models are in many regards the most powerful of all the view model alternatives.
-
-
-=== ESB Subscribers
-
-One important variation of the DTO use case concerns subscribers on an enterprise event bus such as
-link:http://camel.apache.org[Apache Camel(TM)] and similar.
-
-A xref:rg.adoc#_rg_services-spi_manpage-PublishingService[`PublishingService`] implementation (eg that provided by
-(non-ASF) http://github.com/isisaddons/isis-module-publishmq[Isis addons' publishmq] module) can publish XML events
-onto a message queue, typically representing action invocations within the originating Isis application. The ESB
-(Apache Camel) then dispatches this event to all interested subscribers. These subscribers represent external systems
-in the enterprise, managed by other teams, and so act as the third-party consumers of the data.
-
-Rather than try to anticipate their requirements and push the data that these subscribers might need into the original
-XML event (a hopeless task), DTO objects can be defined to allow these consumers to call back to the publishing Isis
-application to obtain the data they need.
-
-
-[[_ug_more-advanced_view-models_programming-model]]
-== Programming Model
-
-So much for the theory; how should view models be implemented? Fundamentally all view models' state is serialized into
-a string memento; this memento is then held by the client (browser) in the form of a URL. As you might imagine, this
-URL can become quite long, but Apache Isis offers a mechanism (the xref:rg.adoc#_rg_services-spi_manpage-UrlEncodingService[`UrlEncodingService`]) if it exceeds the maximum length for a URL
-(2083 characters). Also, of course, this string memento must only contain characters that it is valid for use within
-a URL.
-
-While the underlying technique is the same irrespective of use case, the programming model provides various ways of
-defining a view model so that the original intent is not lost. They are:
-
-.View model programming model
-[cols="1a,4a,2a", options="header"]
-|===
-
-| Use case
-| Code
-| Description
-
-
-| External entity
-|[source,java]
-----
-@DomainObject(nature=Nature.EXTERNAL_ENTITY)
-public class CustomerRecordOnSAP { ... }
-----
-|Annotated with xref:rg.adoc#_rg_annotations_manpage-DomainObject_nature[`@DomainObject#nature()`] and a nature of `EXTERNAL_ENTITY`, with memento derived automatically from the properties of the domain object. Collections are ignored, as are any properties annotated as xref:rg.adoc#_rg_annotations_manpage-Property_notPersisted[not persisted].
-
-| In-memory entity
-|[source,java]
-----
-@DomainObject(nature=Nature.INMEMORY_ENTITY)
-public class Log4JAppender { ... }
-----
-|As preceding, but using a nature of `INMEMORY_ENTITY`.
-
-|Application view model
-|[source,java]
-----
-@DomainObject(nature=Nature.VIEW_MODEL)
-public class Dashboard { ... }
-----
-|As preceding, but using a nature of `VIEW_MODEL`.
-
-|Application view model
-|
-[source,java]
-----
-@ViewModel
-public class Dashboard { ... }
-----
-
-|Annotated with xref:rg.adoc#_rg_annotations_manpage-ViewModel[`@ViewModel`] annotation (effectively just an alias)' memento is as preceding: from "persisted" properties, collections ignored
-
-|Application view model
-|
-[source,java]
-----
-public class ExcelUploadManager implements ViewModel {
- public String viewModelMemento() { ... }
- public void viewModelInit(String memento) { ... }
-}
-|Implement xref:rg.adoc#_rg_classes_super_manpage-ViewModel[`ViewModel`] interface. The memento is as defined by the
-interface's methods: the programmer has full control (but also full responsibility) for the string memento.
-
-|DTO (`1.11.0-SNAPSHOT`)
-|
-[source,java]
-----
-@XmlRootElement("customer")
-public class CustomerDto { ... }
-----
-|Annotate using JAXB xref:rg.adoc#_rg_annotations_manpage-XmlRootElement[`@XmlRootElement`] annotation. Memento
-derived automatically by serializing the XML graph as implied by the JAXB annotations. Note that (unlike `@ViewModel`
-et al) this state _can_ include collections.
-|===
-
-JAXB-annotated DTOs are discussed in more detail immediately xref:rg.adoc#_ug_more-advanced_view-models_jaxb[below].
-
-
-[[_ug_more-advanced_view-models_jaxb]]
-== JAXB-annotated DTOs (`1.11.0-SNAPSHOT`)
-
-This section provides some recommended practices if using JAXB and `@XmlRootElement` to define domain models. The
-examples are taken from the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp].
-
-=== Use packages to version DTOs
-
-The whole point of using DTOs (in Apache Isis, at least) is to define a formal contact between two interoperating but
-independent applications. Since the only thing we can predicate about the future with any certainty is that it one or
-both of these applications will change, we should version DTOs from the get-go.
-
-With XML every element may be defined as belonging to a particular namespace; in JAXB this translates to Java packages.
-We therefore should place each DTO within its own package, and that package should include a version identifier.
-
-For example, the http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] defines this DTO (as a versioned
-representation of its underlying `ToDoItem` entity):
-
-[source,java]
-----
-@XmlRootElement(name = "toDoItemDto") // <1>
-@XmlType(
- namespace = "http://viewmodels.app.todoapp/v1/todoitem", // <2>
- propOrder = { // <3>
- "description",
- "category",
- "subcategory",
- "cost"
- }
-)
-@DomainObjectLayout(
- titleUiEvent = TitleUiEvent.Doop.class // <4>
-)
-public class ToDoItemDto implements Dto {
- @XmlElement(required = true)
- @Getter @Setter // <5>
- protected String description;
-
- @XmlElement(required = true)
- @Getter @Setter
- protected String category;
-
- @Getter @Setter
- protected String subcategory;
-
- @Getter @Setter
- protected BigDecimal cost;
-}
-----
-<1> identifies this class as a view model and defines the root element for JAXB serialization
-<2> specify the XML schema namespace to which this element type belongs
-<3> all properties in the class must be listed; (they can be ignored using `@XmlTransient`)
-<4> demonstrating use of UI events for a subscriber to provide the DTO's title; see xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_titleUiEvent[`@DomainObjectLayout#titleUiEvent()`].
-<5> optional; JAXB metadata can specify such attributes as required/optional
-
-
-For the package in which the DTO class resides, we define a corresponding namespace. This goes in `package-info.java`:
-
-[source,java]
-----
-@javax.xml.bind.annotation.XmlSchema(
- namespace = "http://viewmodels.app.todoapp/v1/todoitem", // <1>
- xmlns = {
- @javax.xml.bind.annotation.XmlNs(
- namespaceURI = "http://isis.apache.org/schema/common", // <2>
- prefix = "common"
- )
- },
- elementFormDefault = javax.xml.bind.annotation.XmlNsForm.QUALIFIED
-)
-package todoapp.app.viewmodels.todoitem.v1_0; // <3>
-----
-<1> the namespace URI. There is no requirement for this to correspond to a physical URL, but it should be unique (this
-usually implies the usage of a company domain name)
-<2> define an alias for all of other Java types used within the DTO class. It's recommended that the Apache Isis xref:rg.adoc#_rg_schema-common[common schema] is always be defined; any references to persistent entities will resultin usage
-of this schema.
-<3> the package in which the DTO resides.
-
-Note how both the XML namespace and package are broadly equivalent to each other; in particular note that they both
-also include a version "v1".
-
-
-
-=== Versioning
-
-Versioning DTOs enables us to make changes without breaking existing consumers of the data. We can distinguish two
-types of changes:
-
-* backwardly compatible changes
-* breaking changes.
-
-Following link:http://semver.org[semantic versioning] approach, we suggest using `v1_0`, `v1_1`, `v1_2` etc as the
-package version for a sequence of backwardly compatible changes, then bump up to `v2_0` for a breaking change.
-
-Backwardly compatible changes can generally (always?) be modelled using class inheritance. Thus, `v1_1.ToDoItemDto`
-is a subclass of `v1_0.ToDoItemDto`. This makes sense too: OO inheritance means "is-substitutable-for", so what is
-true in an OO context is true when processing XML documents.
-
-On the other hand, breaking changes probably (always?) imply that the next version of the DTO does not use inheritance.
-Thus `v2_0.ToDoItemDto` might share many of the same properties as the `v1_1.ToDoItemDto`, but any reuse would be
-copy-n-paste rather than through inheritance.
-
-To see this in practice, here's (the outline of) v1.1 of `ToDoItemDto`:
-
-[source,java]
-----
-package todoapp.app.viewmodels.todoitem.v1_1;
-...
-@XmlRootElement(name = "toDoItemDto")
-@XmlType(
- namespace = "http://viewmodels.app.todoapp/v1_1/todoitem",
- propOrder = {
- "toDoItem",
- "similarItems"
- }
-)
-public class ToDoItemDto extends todoapp.app.viewmodels.todoitem.v1_0.ToDoItemDto {
- ...
-}
-----
-
-
-The corresponding `package-info.java` is similar to that for `v1_0`, though note how it also defines a namespace prefix
-for `v1_0`:
-
-[source,java]
-----
-@javax.xml.bind.annotation.XmlSchema(
- namespace = "http://viewmodels.app.todoapp/v1_1/todoitem",
- xmlns = {
- @javax.xml.bind.annotation.XmlNs(
- namespaceURI = "http://isis.apache.org/schema/common",
- prefix = "common"
- ),
- @javax.xml.bind.annotation.XmlNs(
- namespaceURI = "http://viewmodels.app.todoapp/v1_0/todoitem",
- prefix = "todoitem-v1_0"
- ),
- @javax.xml.bind.annotation.XmlNs(
- namespaceURI = "http://viewmodels.app.todoapp/v1_1/todoitem",
- prefix = "todoitem-v1_1"
- )
- },
- elementFormDefault = javax.xml.bind.annotation.XmlNsForm.QUALIFIED
-)
-package todoapp.app.viewmodels.todoitem.v1_1;
-----
-
-
-
-=== Referencing Domain Entities
-
-It's quite common for view models to be "backed by" (be projections of) some underlying domain entity. The
-`ToDoItemDto` we've been using as the example in this section is an example: there is an underlying `ToDoItem` entity.
-
-It wouldn't make sense to serialize out the state of a persistent entity: the point of a DTO is to act as a facade
-on top of the entity so that the implementation details (of the entity's structure) don't leak out to the consumer.
-However, the identity of the underlying entity can be well defined; Apache Isis defines the
-xref:rg.adoc#_rg_schema-common[Common schema] which defines the `<oid-dto>` element (and corresponding `OidDto` class):
-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`].
-
-There is only one requirement to make this work: every referenced domain entity must be annotated with
-xref:rg.adoc#_rg_annotations_manpage-XmlJavaTypeAdapter[`@XmlJavaTypeAdapter`], specifying the framework-provided
-`PersistentEntityAdapter.class`. This class is similar to the `BookmarkService`: it knows how to create an `OidDto`
-from an object reference.
-
-Thus, in our view model we can legitimately write:
-
-[source,java]
-----
-package todoapp.app.viewmodels.todoitem.v1_1;
-...
-public class ToDoItemDto extends todoapp.app.viewmodels.todoitem.v1_0.ToDoItemDto {
- ...
- @Getter @Setter
- protected ToDoItem toDoItem;
-}
-----
-
-All we need to do is remember to add that `@XmlJavaTypeAdapter` annotation to the referenced entity:
-
-[source,java]
-----
-@XmlJavaTypeAdapter(PersistentEntityAdapter.class)
-public class ToDoItem ... {
- ...
-}
-----
-
-
-
-=== Collections
-
-It's also possible for a DTO to hold collections of objects. These can be of any type, either simple properties, or
-references to other objects.
-
-The only bit of boilerplate that is required is the `@XmlElementWrapper` annotation. This instructs JAXB to create
-an XML element (based on the field name) to contain each of the elements. (If this is omitted then the contents of
-the collection are at the same level as the properties; almost certainly not what is required).
-
-For example, the v1.1 of the `ToDoItemDto` could also contain:
-
-[source,java]
-----
-package todoapp.app.viewmodels.todoitem.v1_1;
-...
-public class ToDoItemDto extends todoapp.app.viewmodels.todoitem.v1_0.ToDoItemDto {
- ...
- @XmlElementWrapper
- @XmlElement(name = "todoItem")
- @Getter @Setter
- protected List<ToDoItem> similarItems = Lists.newArrayList();
-}
-----
-
-
-There's nothing to prevent a JAXB DTO from containing rich graphs of data, parent containing children containing
-children. Be aware though that all of this state will become the DTO's memento, ultimately converted into a URL-safe
-form, by way of the xref:rg.adoc#_rg_services-spi_manpage-UrlEncodingService[`UrlEncodingService`].
-
-There are limits to the lengths of URLs, however. Therefore the DTO should not include state that can easily be
-derived from other information. If the URL does exceed limits, then provide a custom implementation of `UrlEncodingService`
-to handle the memento string in some other fashion (eg substituting it with a GUID, with the memento cached somehow
-on the server).
http://git-wip-us.apache.org/repos/asf/isis/blob/3aabf7f5/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_view-models_jaxb.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_view-models_jaxb.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_view-models_jaxb.adoc
new file mode 100644
index 0000000..9e9d606
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_view-models_jaxb.adoc
@@ -0,0 +1,240 @@
+[[_ug_more-advanced_view-models_jaxb]]
+= JAXB-annotated DTOs (`1.11.0-SNAPSHOT`)
+: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 provides some recommended practices if using JAXB and `@XmlRootElement` to define domain models. The
+examples are taken from the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp].
+
+
+
+[[_ug_more-advanced_view-models_jaxb_using-packages-to-version]]
+== Use packages to version DTOs
+
+The whole point of using DTOs (in Apache Isis, at least) is to define a formal contact between two interoperating but
+independent applications. Since the only thing we can predicate about the future with any certainty is that it one or
+both of these applications will change, we should version DTOs from the get-go.
+
+With XML every element may be defined as belonging to a particular namespace; in JAXB this translates to Java packages.
+We therefore should place each DTO within its own package, and that package should include a version identifier.
+
+For example, the http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] defines this DTO (as a versioned
+representation of its underlying `ToDoItem` entity):
+
+[source,java]
+----
+@XmlRootElement(name = "toDoItemDto") // <1>
+@XmlType(
+ propOrder = { // <2>
+ "description",
+ "category",
+ "subcategory",
+ "cost"
+ }
+)
+@DomainObjectLayout(
+ titleUiEvent = TitleUiEvent.Doop.class // <3>
+)
+public class ToDoItemDto implements Dto {
+ @XmlElement(required = true)
+ @Getter @Setter // <4>
+ protected String description;
+
+ @XmlElement(required = true)
+ @Getter @Setter
+ protected String category;
+
+ @Getter @Setter
+ protected String subcategory;
+
+ @Getter @Setter
+ protected BigDecimal cost;
+}
+----
+<1> identifies this class as a view model and defines the root element for JAXB serialization
+<2> all properties in the class must be listed; (they can be ignored using `@XmlTransient`)
+<3> demonstrating use of UI events for a subscriber to provide the DTO's title; see xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_titleUiEvent[`@DomainObjectLayout#titleUiEvent()`].
+<4> optional; JAXB metadata can specify such attributes as required/optional
+
+
+For the package in which the DTO class resides, we define a corresponding namespace. This goes in `package-info.java`:
+
+[source,java]
+----
+@javax.xml.bind.annotation.XmlSchema(
+ namespace = "http://viewmodels.app.todoapp/todoitem/v1_0/todoitem.xsd", // <1>
+ elementFormDefault = javax.xml.bind.annotation.XmlNsForm.QUALIFIED
+)
+package todoapp.app.viewmodels.todoitem.v1_0; // <2>
+----
+<1> the namespace URI, used by the DTO residing in this package. There is no requirement for this to correspond to a physical URL, but it should be unique (this
+usually implies the usage of a company domain name).
+<2> the package in which the DTO resides.
+
+Note how both the XML namespace and package are broadly equivalent to each other; in particular note that they both
+also include a version "v1_0".
+
+
+
+
+[[_ug_more-advanced_view-models_jaxb_semantic-versioning]]
+== Semantic Versioning
+
+Versioning DTOs enables us to make changes without breaking existing consumers of the data. We can distinguish two
+types of changes:
+
+* backwardly compatible changes
+* breaking changes.
+
+Following link:http://semver.org[semantic versioning] approach, we suggest using `v1_0`, `v1_1`, `v1_2` etc as the
+package version for a sequence of backwardly compatible changes, then bump up to `v2_0` for a breaking change.
+
+Backwardly compatible changes can generally (always?) be modelled using class inheritance. Thus, `v1_1.ToDoItemDto`
+is a subclass of `v1_0.ToDoItemDto`. This makes sense too: OO inheritance means "is-substitutable-for", so what is
+true in an OO context is true when processing XML documents.
+
+On the other hand, breaking changes probably (always?) imply that the next version of the DTO does not use inheritance.
+Thus `v2_0.ToDoItemDto` might share many of the same properties as the `v1_1.ToDoItemDto`, but any reuse would be
+copy-n-paste rather than through inheritance.
+
+To see this in practice, here's (the outline of) v1.1 of `ToDoItemDto`:
+
+[source,java]
+----
+package todoapp.app.viewmodels.todoitem.v1_1;
+...
+@XmlRootElement(name = "toDoItemDto")
+@XmlType(
+ propOrder = {
+ "toDoItem",
+ "similarItems"
+ }
+)
+public class ToDoItemDto extends todoapp.app.viewmodels.todoitem.v1_0.ToDoItemDto {
+ ...
+}
+----
+
+
+The corresponding `package-info.java` is similar to that for `v1_0`, though note how it also defines a namespace prefix
+for `v1_0`:
+
+[source,java]
+----
+@javax.xml.bind.annotation.XmlSchema(
+ namespace = "http://viewmodels.app.todoapp/todoitem/v1_1/todoitem.xsd", // <1>
+ xmlns = {
+ @javax.xml.bind.annotation.XmlNs( // <2>
+ namespaceURI = "http://isis.apache.org/schema/common",
+ prefix = "common"
+ ),
+ @javax.xml.bind.annotation.XmlNs(
+ namespaceURI = "http://viewmodels.app.todoapp/todoitem/v1_0/todoitem.xsd",
+ prefix = "todoitem-v1_0"
+ )
+ },
+ elementFormDefault = javax.xml.bind.annotation.XmlNsForm.QUALIFIED
+)
+package todoapp.app.viewmodels.todoitem.v1_1;
+----
+<1> namespace URI for DTO in this class.
+<2> aliases for any other namespaces referenced.
+
+
+
+[[_ug_more-advanced_view-models_jaxb_referencing-domain-entities]]
+== Referencing Domain Entities
+
+It's quite common for view models to be "backed by" (be projections of) some underlying domain entity. The
+`ToDoItemDto` we've been using as the example in this section is an example: there is an underlying `ToDoItem` entity.
+
+It wouldn't make sense to serialize out the state of a persistent entity: the point of a DTO is to act as a facade
+on top of the entity so that the implementation details (of the entity's structure) don't leak out to the consumer.
+However, the identity of the underlying entity can be well defined; Apache Isis defines the
+xref:rg.adoc#_rg_schema-common[Common schema] which defines the `<oid-dto>` element (and corresponding `OidDto` class):
+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`].
+
+There is only one requirement to make this work: every referenced domain entity must be annotated with
+xref:rg.adoc#_rg_annotations_manpage-XmlJavaTypeAdapter[`@XmlJavaTypeAdapter`], specifying the framework-provided
+`PersistentEntityAdapter.class`. This class is similar to the `BookmarkService`: it knows how to create an `OidDto`
+from an object reference.
+
+Thus, in our view model we can legitimately write:
+
+[source,java]
+----
+package todoapp.app.viewmodels.todoitem.v1_1;
+...
+public class ToDoItemDto extends todoapp.app.viewmodels.todoitem.v1_0.ToDoItemDto {
+ ...
+ @Getter @Setter
+ protected ToDoItem toDoItem;
+}
+----
+
+All we need to do is remember to add that `@XmlJavaTypeAdapter` annotation to the referenced entity:
+
+[source,java]
+----
+@XmlJavaTypeAdapter(PersistentEntityAdapter.class)
+public class ToDoItem ... {
+ ...
+}
+----
+
+
+
+[[_ug_more-advanced_view-models_jaxb_collections]]
+== Collections
+
+It's also possible for a DTO to hold collections of objects. These can be of any type, either simple properties, or
+references to other objects.
+
+The only bit of boilerplate that is required is the `@XmlElementWrapper` annotation. This instructs JAXB to create
+an XML element (based on the field name) to contain each of the elements. (If this is omitted then the contents of
+the collection are at the same level as the properties; almost certainly not what is required).
+
+For example, the v1.1 of the `ToDoItemDto` could also contain:
+
+[source,java]
+----
+package todoapp.app.viewmodels.todoitem.v1_1;
+...
+public class ToDoItemDto extends todoapp.app.viewmodels.todoitem.v1_0.ToDoItemDto {
+ ...
+ @XmlElementWrapper
+ @XmlElement(name = "todoItem")
+ @Getter @Setter
+ protected List<ToDoItem> similarItems = Lists.newArrayList();
+}
+----
+
+
+There's nothing to prevent a JAXB DTO from containing rich graphs of data, parent containing children containing
+children. Be aware though that all of this state will become the DTO's memento, ultimately converted into a URL-safe
+form, by way of the xref:rg.adoc#_rg_services-spi_manpage-UrlEncodingService[`UrlEncodingService`].
+
+There are limits to the lengths of URLs, however. Therefore the DTO should not include state that can easily be
+derived from other information. If the URL does exceed limits, then provide a custom implementation of `UrlEncodingService`
+to handle the memento string in some other fashion (eg substituting it with a GUID, with the memento cached somehow
+on the server).
+
+
+
+
+
+== Generating XSDs and DTOs
+
+The xref:cg.adoc#_cg_isis-maven-plugin[Apache Isis maven plugin] provides the xref:cg.adoc#_cg_isis-maven-plugin_xsd[xsd] goal that allows the XSDs to be generated from any JAXB-annotated view models.
+These use the xref:rg.adoc#_rg_services-api_manpage-JaxbService[`JaxbService`] to generate the schemas; using the
+standard `schemagen` command line will not correctly interpret any references to domain entities as OIDs.
+
+The documentation for the `xsd` goal also explains how to generate DTO classes from the generated XSDs. Note that these
+DTOs are not the same as the JAXB view models; they can be used outside of an Isis application, for example in a
+standalone subscriber running on an enterprise service bus such as Apache Camel.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/3aabf7f5/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_view-models_programming-model.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_view-models_programming-model.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_view-models_programming-model.adoc
new file mode 100644
index 0000000..015a597
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_view-models_programming-model.adoc
@@ -0,0 +1,87 @@
+[[_ug_more-advanced_view-models_programming-model]]
+= Programming Model
+: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/
+
+
+
+So much for the theory; how should view models be implemented? Fundamentally all view models' state is serialized into
+a string memento; this memento is then held by the client (browser) in the form of a URL. As you might imagine, this
+URL can become quite long, but Apache Isis offers a mechanism (the xref:rg.adoc#_rg_services-spi_manpage-UrlEncodingService[`UrlEncodingService`]) if it exceeds the maximum length for a URL
+(2083 characters). Also, of course, this string memento must only contain characters that it is valid for use within
+a URL.
+
+While the underlying technique is the same irrespective of use case, the programming model provides various ways of
+defining a view model so that the original intent is not lost. They are:
+
+.View model programming model
+[cols="1a,4a,2a", options="header"]
+|===
+
+| Use case
+| Code
+| Description
+
+
+| External entity
+|[source,java]
+----
+@DomainObject(nature=Nature.EXTERNAL_ENTITY)
+public class CustomerRecordOnSAP { ... }
+----
+|Annotated with xref:rg.adoc#_rg_annotations_manpage-DomainObject_nature[`@DomainObject#nature()`] and a nature of `EXTERNAL_ENTITY`, with memento derived automatically from the properties of the domain object. Collections are ignored, as are any properties annotated as xref:rg.adoc#_rg_annotations_manpage-Property_notPersisted[not persisted].
+
+| In-memory entity
+|[source,java]
+----
+@DomainObject(nature=Nature.INMEMORY_ENTITY)
+public class Log4JAppender { ... }
+----
+|As preceding, but using a nature of `INMEMORY_ENTITY`.
+
+|Application view model
+|[source,java]
+----
+@DomainObject(nature=Nature.VIEW_MODEL)
+public class Dashboard { ... }
+----
+|As preceding, but using a nature of `VIEW_MODEL`.
+
+|Application view model
+|
+[source,java]
+----
+@ViewModel
+public class Dashboard { ... }
+----
+
+|Annotated with xref:rg.adoc#_rg_annotations_manpage-ViewModel[`@ViewModel`] annotation (effectively just an alias)' memento is as preceding: from "persisted" properties, collections ignored
+
+|Application view model
+|
+[source,java]
+----
+public class ExcelUploadManager implements ViewModel {
+ public String viewModelMemento() { ... }
+ public void viewModelInit(String memento) { ... }
+}
+|Implement xref:rg.adoc#_rg_classes_super_manpage-ViewModel[`ViewModel`] interface. The memento is as defined by the
+interface's methods: the programmer has full control (but also full responsibility) for the string memento.
+
+|DTO (`1.11.0-SNAPSHOT`)
+|
+[source,java]
+----
+@XmlRootElement("customer")
+public class CustomerDto { ... }
+----
+|Annotate using JAXB xref:rg.adoc#_rg_annotations_manpage-XmlRootElement[`@XmlRootElement`] annotation. Memento
+derived automatically by serializing the XML graph as implied by the JAXB annotations. Note that (unlike `@ViewModel`
+et al) this state _can_ include collections.
+|===
+
+JAXB-annotated DTOs are discussed in more detail immediately xref:rg.adoc#_ug_more-advanced_view-models_jaxb[below].
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/3aabf7f5/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_view-models_use-cases.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_view-models_use-cases.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_view-models_use-cases.adoc
new file mode 100644
index 0000000..d56e2c4
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_view-models_use-cases.adoc
@@ -0,0 +1,142 @@
+[[_ug_more-advanced_view-models_use-cases]]
+= Use Cases
+: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/
+
+
+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
+needs to integrate with other systems, or if the application needs to support reasonably complex business processes, then you may need to look beyond just domain entities. This section explores these use cases.
+
+== Externally-managed entities
+
+Sometimes the entities that make up your application are persisted not in the local JDO/DataNucleus database
+but reside in some other system, for example accessible only through a SOAP web service. Logically that data
+might still be considered a domain entity and we might want to associate behaviour with it, however it cannot be
+modelled as a domain entity if only because JDO/DataNucleus doesn't know about the entity nor how to retrieve or
+update it.
+
+There are a couple of ways around this: we could either replicate the data somehow from the external system into the
+ Isis-managed database (in which case it is once again just another domain entity), or we could set up a stub/proxy for
+ the externally managed entity. This proxy would hold the reference to the externally-managed domain entity (eg an
+ external id), as well as the "smarts" to know how to interact with that entity (by making SOAP web service calls etc).
+
+The stub/proxy is a type of view model: a view - if you like - onto the domain entity managed by the external system.
+
+[NOTE]
+====
+DataNucleus does in fact define its own link:http://www.datanucleus.org/documentation/extensions/store_manager.html[Store Manager] extension point, so an alternative architecture would be to implement this interface such that DataNucleus
+could make the calls to the external system; these externally-persisted domain entities would therefore be modelled as regular `@PersistenceCapable` entities after all. For entities not persisted externally the implementation would delegate down to the default RDBMS-specific `StoreManager` provided by DataNucleus itself.
+
+An implementation that supported only reading from an external entity ought to be comparatively straight-forward, but
+implementing one that also supported updating external entities would need to carefully consider error conditions if the
+external system is unavailable; distributed transactions are most likely difficult/impossible to implement (and not
+desirable in any case).
+====
+
+
+== In-memory entities
+
+As a variation on the above, sometimes there are domain objects that are, conceptually at least entities, but whose
+state is not actually persisted anywhere, merely held in-memory (eg in a hash).
+
+A simple example might be read-only configuration data that is read from a config file (eg log4j appender
+definitions) but thereafter is presented in the UI just like any other entity.
+
+
+== Application-layer view models
+
+Domain entities (whether locally persisted using JDO/DataNucleus or managed externally) are the bread-and-butter of Apache Isis applications: the focus after all, should be on the business domain concepts and ensuring that they are
+solid. Generally those domain entities will make sense to the business domain experts: they form the _ubiquitous language_ of the domain. These domain entities are part of the domain layer.
+
+That said, it may not always be practical to expect end-users of the application to interact solely with those domain
+entities. For example, it may be useful to show a dashboard of the most significant data in the system to a user,
+often pulling in and aggregating information from multiple points of the app. Obtaining this information by hand (by
+ querying the respective services/repositories) would be tedious and slow; far better to have a dashboard do the job for
+ the end user.
+
+A dashboard object is a model of the most relevant state to the end-user, in other words it is (quite literally) a view
+ model. It is not a persisted entity, instead it belongs to the application layer.
+
+A view model need not merely aggregate data; it could also provide actions of its own. Most likely these actions will
+be queries and will always ultimately just delegate down to the appropriate domain-layer service/repository. But in
+some cases such view model actions might also modify state of underlying domain entities.
+
+Another common use for view models is to help co-ordinate complex business processes; for example to perform a
+quarterly invoicing run, or to upload annual interest rates from an Excel spreadsheet. In these cases the view model
+might have some state of its own, but in most cases that state does not need to be persisted per se.
+
+.Desire Lines
+****
+One way to think of application view models is as modelling the "desire line": the commonly-trod path
+that end-users must follow to get from point A to point B as quickly as possible.
+
+To explain: there are link:http://ask.metafilter.com/62599/Where-the-sidewalk-ends[documented]
+link:https://sivers.org/walkways[examples]
+link:http://www.softpanorama.org/People/Wall/larry_wall_articles_and_interviews.shtml[that] architects of university
+campus will only add in paths some while after the campus buildings are complete: let the pedestrians figure out the
+routes they want to take. The name we like best for this idea is "desire lines", though it has also been called
+a "desire path", "paving the path" or "paving the sidewalk".
+
+What that means is you should add view models _after_ having built up the domain layer, rather than before. These view
+models pave that commonly-trod path, automating the steps that the end-user would otherwise have to do by hand.
+
+It takes a little practice though, because even when building the domain layer "first", you should still bear in mind
+what the use cases are that those domain entities are trying to support. You certainly _shouldn't_ try to build out a
+domain layer that could support every conceivable use case before starting to think about view models.
+
+Instead, you should iterate. Identify the use case/story/end-user objective that you will deliver value to the
+business. Then build out the minimum domain entities to support that use case (refining the xref:ug.adoc#_ug_core-concepts_philosophy_domain-driven-design_ubiquitous-language[ubiquitous language] as you
+go). Then, identify if there any view models that could be introduced which would simplify the end-user interactions
+with the system (perhaps automating several related use cases together).
+****
+
+== DTOs (`1.11.0-SNAPSHOT`)
+
+DTOs (data transfer objects) are simple classes that (according to link:https://en.wikipedia.org/wiki/Data_transfer_object[wikipedia]) "carries data between processes".
+
+If those two processes are parts of the same overall application (the same team builds and deploys both server and
+client) then there's generally no need to define a DTO; just access the entities using Apache Isis'
+xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer].
+
+On the other hand, if the client consuming the DTO is a different application -- by which we mean developed/deployed by
+a different (possible third-party) team -- then the DTOs act as a formal contract between the provider and the consumer.
+In such cases, exposing domain entities over xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects] would be
+"A Bad Thing"(TM) because the consumer would in effect have access to implementation details that could then not be
+easily changed by the producer.
+
+Instead, a view model can be defined to act as a DTO. To put this formal contract onto a solid footing, this view
+model can (as of `1.11.0-SNAPSHOT`) simply be defined as a JAXB-annotated entity; this allows the consumer to obtain
+the DTO in XML format along with a corresponding XSD schema describing the structure of that XML. These XML
+representations can be surfaced by the xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer] (by implementing
+the xref:rg.adoc#_rg_services-spi_manpage-ContentMappingService[`ContentMappingService`]); the XSD can be obtained
+using the xref:rg.adoc#_rg_services-api_manpage-JaxbService[`JaxbService`]. Using the formalism of XML also allows
+DTOs to be carefully and properly versioned using XML namespaces.
+
+[TIP]
+====
+If the view model DTO implements the xref:rg.adoc#_rg_classes_mixins_Dto[`Dto`] marker interface, then the framework
+will also provide the ability to download the XML or its XSD directly from the UI.
+====
+
+In case it's not clear, these DTOs are still usable as "regular" view models; they will render in the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] just like any other. Indeed (as the xref:ug.adoc#_ug_more-advanced_view-models_programming-model[programming model] section below makes clear), these
+JAXB-annotated view models are in many regards the most powerful of all the view model alternatives.
+
+
+== ESB Subscribers
+
+One important variation of the DTO use case concerns subscribers on an enterprise event bus such as
+link:http://camel.apache.org[Apache Camel(TM)] and similar.
+
+A xref:rg.adoc#_rg_services-spi_manpage-PublishingService[`PublishingService`] implementation (eg that provided by
+(non-ASF) http://github.com/isisaddons/isis-module-publishmq[Isis addons' publishmq] module) can publish XML events
+onto a message queue, typically representing action invocations within the originating Isis application. The ESB
+(Apache Camel) then dispatches this event to all interested subscribers. These subscribers represent external systems
+in the enterprise, managed by other teams, and so act as the third-party consumers of the data.
+
+Rather than try to anticipate their requirements and push the data that these subscribers might need into the original
+XML event (a hopeless task), DTO objects can be defined to allow these consumers to call back to the publishing Isis
+application to obtain the data they need.
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/3aabf7f5/adocs/documentation/src/main/asciidoc/guides/_ug_restfulobjects-viewer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_restfulobjects-viewer.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_restfulobjects-viewer.adoc
index 256a6cd..7682aa8 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_restfulobjects-viewer.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_restfulobjects-viewer.adoc
@@ -11,9 +11,7 @@ The Restful Objects viewer also provides a number of proprietary extensions.
include::_ug_restfulobjects-viewer_features.adoc[leveloffset=+1]
-
include::_ug_restfulobjects-viewer_configuration-properties.adoc[leveloffset=+1]
-
include::_ug_restfulobjects-viewer_hints-and-tips.adoc[leveloffset=+1]