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/25 11:29:58 UTC
isis-site git commit: ISIS-1258: isis-maven-plugin xsd goal
Repository: isis-site
Updated Branches:
refs/heads/asf-site 3970c476c -> c8287a03f
ISIS-1258: isis-maven-plugin xsd goal
Project: http://git-wip-us.apache.org/repos/asf/isis-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis-site/commit/c8287a03
Tree: http://git-wip-us.apache.org/repos/asf/isis-site/tree/c8287a03
Diff: http://git-wip-us.apache.org/repos/asf/isis-site/diff/c8287a03
Branch: refs/heads/asf-site
Commit: c8287a03ff50a7922a4fffe34bc4a71b42b3c273
Parents: 3970c47
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Sun Nov 22 19:38:22 2015 +0000
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Sun Nov 22 19:38:22 2015 +0000
----------------------------------------------------------------------
content/guides/cg.html | 582 +++++++++++++++++--
content/guides/images/maven-plugin/xsd-goal.png | Bin 0 -> 46790 bytes
.../guides/images/maven-plugin/xsd-goal.pptx | Bin 0 -> 64740 bytes
content/guides/ug.html | 89 +--
4 files changed, 590 insertions(+), 81 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis-site/blob/c8287a03/content/guides/cg.html
----------------------------------------------------------------------
diff --git a/content/guides/cg.html b/content/guides/cg.html
index 8368bcd..05fb71f 100644
--- a/content/guides/cg.html
+++ b/content/guides/cg.html
@@ -1798,38 +1798,43 @@ TODO
<h2 id="_cg_isis-maven-plugin">5. Apache Isis Maven Plugin</h2>
<div class="sectionbody">
<div class="paragraph">
-<p>The Apache Isis programming model requires that a number of naming conventions are followed.</p>
+<p>The Apache Isis Maven plugin defines two goals:</p>
</div>
+<div class="ulist">
+<ul>
+<li>
+<p><code>validate</code><br></p>
<div class="paragraph">
-<p>For example, the validator will detect any orphaned supporting methods (eg <code>hideXxx()</code>) 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 <code>title()</code> method and also using <code>@Title</code> annotation.</p>
+<p>Use to verify at build time that the metamodel of an application is valid. This runs the <code>MetaModelValidator</code> that is also run when the application is started up.</p>
</div>
+</li>
+<li>
+<p><code>xsd</code><br></p>
<div class="paragraph">
-<p>When running the application these are enforced by the <code>MetaModelValidator</code> component that detects these errors, failing fast.</p>
+<p>Uses the <a href="rg.html#_rg_services-api_manpage-JaxbService"><code>JaxbService</code></a> to generate XSD schemas from any JAXB-annotated view models/DTOs.<br></p>
</div>
<div class="paragraph">
-<p>The purpose of the <code>isis-maven-plugin</code> is to enforce these naming conventions at build time, typically enforced by way of a continuous integration server.</p>
+<p>This is instead of and preferable to using the JAXB <a href="https://jaxb.java.net/2.2.4/docs/schemagen.html">schemagen</a> tool, because it uses the framework’s support (via <a href="rg.html#_rg_annotations_manpage-XmlJavaValueType"><code>@XmlJavaValueType</code></a>) to translate any references to domain objects into <code>OidDto</code>s (as defined by the Apache Isis <a href="rg.html#_rg_schema-common">common schema</a>).</p>
+</div>
+</li>
+</ul>
</div>
-<div class="admonitionblock note">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-note" title="Note"></i>
-</td>
-<td class="content">
<div class="paragraph">
-<p>The instructions given here relate to <code>1.10.0</code>. The plugin was also released for <code>1.9.0</code>, but with a slightly different configuration; see the final section for differences.</p>
+<p>The <code>validate</code> goal is by default bound to the <code>test</code> phase of your application’s <code>dom</code> sub-module, whereas the <code>xsd</code> goal defaults to the <code>generate-resources</code> phase of a completely separate <code>canonical</code> submodule. An example can be found in the (non-ASF) <a href="http://github.com/isisaddons/isis-app-todoapp">Isis addons' todoapp</a> example app.</p>
</div>
-</td>
-</tr>
-</table>
+<div class="paragraph">
+<p>Both goals require an <a href="rg.html#_rg_classes_AppManifest-bootstrapping"><code>AppManifest</code></a> 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.</p>
</div>
<div class="sect2">
-<h3 id="__code_dom_code_project">5.1. <code>dom</code> project</h3>
+<h3 id="__code_appmanifest_code">5.1. <code>AppManifest</code></h3>
<div class="paragraph">
-<p>To start with, we need an <a href="rg.html#_rg_classes_AppManifest-bootstrapping"><code>AppManifest</code></a> to point the plugin at so that it knows which services and entities are to be validated.</p>
+<p>As noted in the introduction, both goals require an <a href="rg.html#_rg_classes_AppManifest-bootstrapping"><code>AppManifest</code></a>
+to point the plugin at, so that it knows how to bootstrap an Isis runtime.</p>
</div>
<div class="paragraph">
-<p>This can be extremely minimal. For example, the <a href="ug.html#_ug_getting-started_simpleapp-archetype">SimpleApp</a>'s manifest is:</p>
+<p>This can be extremely minimal. For example, the <a href="ug.html#_ug_getting-started_simpleapp-archetype">SimpleApp</a>'s
+manifest is:</p>
</div>
<div class="listingblock">
<div class="content">
@@ -1861,12 +1866,62 @@ public <span class="type">class</span> <span class="class">DomainAppDomManifest<
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">package</span> <span class="namespace">domainapp.dom</span>;
-<span class="directive">public</span> <span class="directive">final</span> <span class="type">class</span> <span class="class">DomainAppDomainModule</span> {
-}</code></pre>
+<span class="directive">public</span> <span class="directive">final</span> <span class="type">class</span> <span class="class">DomainAppDomainModule</span> { }</code></pre>
</div>
</div>
<div class="paragraph">
-<p>Next, update the <code>pom.xml</code> (in your project’s <code>dom</code> module):</p>
+<p>As you’ll see below, the configuration for the two goals both refer to this app manifest.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_cg_isis-maven-plugin_validate">5.2. <code>validate</code> goal</h3>
+<div class="paragraph">
+<p>The Apache Isis programming model requires that a number of naming conventions are followed.</p>
+</div>
+<div class="paragraph">
+<p>For example, the validator will detect any orphaned supporting methods (eg <code>hideXxx()</code>) 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 <code>title()</code> method and also using <code>@Title</code> annotation.</p>
+</div>
+<div class="paragraph">
+<p>When running the application these are enforced by the <code>MetaModelValidator</code> component that detects these errors, failing fast.</p>
+</div>
+<div class="paragraph">
+<p>The purpose of the <code>validate</code> goal of the <code>isis-maven-plugin</code> is to enforce these naming conventions at build time,
+typically enforced by way of a continuous integration server.</p>
+</div>
+<div class="paragraph">
+<p>The <code>validate</code> goal defines a single property:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><code>appManifest</code> - fully qualified class name for the app manifest used to bootstrap the application (see discussion above)</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>The sections below explain how to configure the plugin within an app.</p>
+</div>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>The instructions given here relate to <code>1.10.0</code>. This goal was also released for <code>1.9.0</code>, but with a slightly
+different configuration; see the final section for differences.</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
+<div class="sect3">
+<h4 id="__code_dom_code_submodule">5.2.1. <code>dom</code> submodule</h4>
+<div class="paragraph">
+<p>Update the <code>pom.xml</code> (in your project’s <code>dom</code> module):</p>
</div>
<div class="listingblock">
<div class="content">
@@ -1874,7 +1929,7 @@ public <span class="type">class</span> <span class="class">DomainAppDomManifest<
<span class="tag"><id></span>isis-validate<span class="tag"></id></span>
<span class="tag"><activation></span>
<span class="tag"><property></span>
- <span class="tag"><name></span>isis-validate<span class="tag"></name></span> <i class="conum" data-value="1"></i><b>(1)</b>
+ <span class="tag"><name></span>!skip.isis-validate<span class="tag"></name></span> <i class="conum" data-value="1"></i><b>(1)</b>
<span class="tag"></property></span>
<span class="tag"></activation></span>
<span class="tag"><build></span>
@@ -1917,7 +1972,7 @@ public <span class="type">class</span> <span class="class">DomainAppDomManifest<
<table>
<tr>
<td><i class="conum" data-value="1"></i><b>1</b></td>
-<td>the profile can be activated using <code>-Disis-validate</code></td>
+<td>the profile is active by default, though can be disabled using <code>-Dskip.isis-validate</code></td>
</tr>
<tr>
<td><i class="conum" data-value="2"></i><b>2</b></td>
@@ -1938,22 +1993,30 @@ public <span class="type">class</span> <span class="class">DomainAppDomManifest<
</table>
</div>
</div>
-<div class="sect2">
-<h3 id="_to_run">5.2. To run</h3>
+<div class="sect3">
+<h4 id="_to_run">5.2.2. To run</h4>
<div class="paragraph">
-<p>The plugin is activated by enabling the profile and invoking the <code>test</code> phase:</p>
+<p>The plugin is activated by default, so is run simply using:</p>
</div>
<div class="listingblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="bash">mvn test -Disis-validate</code></pre>
+<pre class="CodeRay highlight"><code data-lang="bash">mvn test</code></pre>
</div>
</div>
<div class="paragraph">
<p>This will run any tests, and then also - because the plugin is activated by the <code>isis-validate</code> property and bound to the <code>test</code> phase, will run the plugin’s <code>validate</code> goal.</p>
</div>
+<div class="paragraph">
+<p>If for any reason you want to disable the validation, use:</p>
</div>
-<div class="sect2">
-<h3 id="_example_of_failure">5.3. Example of failure</h3>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="bash">mvn test -Dskip.isis-validate</code></pre>
+</div>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_example_of_failure">5.2.3. Example of failure</h4>
<div class="paragraph">
<p>In the <a href="ug.html#_ug_getting-started_simpleapp-archetype">SimpleApp</a> application the <code>SimpleObject</code> defines an <code>updateName</code> action. This has a supporting method:</p>
</div>
@@ -1972,7 +2035,7 @@ public <span class="type">class</span> <span class="class">DomainAppDomManifest<
</div>
</div>
<div class="paragraph">
-<p>Running <code>mvn -Disis-valdate test</code> then generates this output:</p>
+<p>Running <code>mvn test</code> then generates this output:</p>
</div>
<div class="listingblock">
<div class="content">
@@ -2003,8 +2066,8 @@ public <span class="type">class</span> <span class="class">DomainAppDomManifest<
<p>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).</p>
</div>
</div>
-<div class="sect2">
-<h3 id="_custom_validation_rules">5.4. Custom validation rules</h3>
+<div class="sect3">
+<h4 id="_custom_validation_rules">5.2.4. Custom validation rules</h4>
<div class="paragraph">
<p>It is also possible to customize the validation, explained <a href="ug.html#_ug_extending_programming-model_custom-validator">here</a>. For example, you could enforce project-specific conventions by implementing a custom <code>MetaModelValidator</code>, and registering using a configuration property.</p>
</div>
@@ -2024,8 +2087,8 @@ public <span class="type">class</span> <span class="class">DomainAppDomManifest<
</div>
</div>
</div>
-<div class="sect2">
-<h3 id="_1_9_0_version">5.5. 1.9.0 version</h3>
+<div class="sect3">
+<h4 id="_1_9_0_version">5.2.5. 1.9.0 version</h4>
<div class="paragraph">
<p>The <code>1.9.0</code> version of the plugin requires slightly different configuratoin. Rather than using an <code>AppManifest</code>, instead the configuration directory containing <code>isis.properties</code> is specified:</p>
</div>
@@ -2108,6 +2171,431 @@ public <span class="type">class</span> <span class="class">DomainAppDomManifest<
</div>
</div>
</div>
+<div class="sect2">
+<h3 id="_cg_isis-maven-plugin_xsd">5.3. <code>xsd</code> goal (<code>1.11.0-SNAPSHOT</code>)</h3>
+<div class="paragraph">
+<p>The <code>xsd</code> goal of the <code>isis-maven-plugin</code> uses the <a href="rg.html#_rg_services-api_manpage-JaxbService"><code>JaxbService</code></a> to
+generate XSD schemas from any JAXB-annotated <a href="ug.html#_ug_more-advanced_view-models">view model/DTOs</a>.</p>
+</div>
+<div class="paragraph">
+<p>This is instead of and preferable to using the JAXB <a href="https://jaxb.java.net/2.2.4/docs/schemagen.html">schemagen</a>
+tool, because it uses the framework’s support (via
+<a href="rg.html#_rg_annotations_manpage-XmlJavaValueType"><code>@XmlJavaValueType</code></a>) to translate any references to domain
+objects into <code>OidDto</code>s (as defined by the Apache Isis <a href="rg.html#_rg_schema-common">common schema</a>).</p>
+</div>
+<div class="paragraph">
+<p>The <code>xsd</code> goal defines the following properties:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><code>appManifest</code> - fully qualified class name for the app manifest used to bootstrap the application (see discussion above)</p>
+</li>
+<li>
+<p><code>jaxbClasses</code> - a list of <a href="rg.html#_ug_more-advanced_view-models_jaxb">JAXB-annotated view model</a> classes;</p>
+</li>
+<li>
+<p><code>output</code> - (optional) subdirectory under the <code>target</code> directory to generate the XSDs<br></p>
+<div class="paragraph">
+<p>Defaults to <code>generated-resources/isis-xsd</code></p>
+</div>
+</li>
+<li>
+<p><code>separate</code> - (optional) whether to create separate directories for each JAXB-class.<br></p>
+<div class="paragraph">
+<p>Defaults to <code>false</code>. Most DTO classes will reference one another or the <a href="rg.html#_rg_schema-common">common schema</a>. 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.</p>
+</div>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>As a convenience to any (Java) consumers, 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: while 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.</p>
+</div>
+<div class="paragraph">
+<p>The diagram below shows how these different plugins fit together:</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<a class="image" href="images/maven-plugin/xsd-goal.png"><img src="images/maven-plugin/xsd-goal.png" alt="xsd goal" width="800px"></a>
+</div>
+</div>
+<div class="paragraph">
+<p>The sections below explain in more detail how to configure the <code>xsd</code> plugin (and other plugins).</p>
+</div>
+<div class="sect3">
+<h4 id="_cg_isis-maven-plugin_xsd">5.3.1. <code>xsd</code> submodule</h4>
+<div class="paragraph">
+<p>We recommend creating a new submodule that will perform the following build steps:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>run the <code>xsd</code> goal (in the <code>generate-resources</code> phase) to generate the XSDs from the specified view model/DTOs</p>
+</li>
+<li>
+<p>use the <a href="http://maven.apache.org/plugins/maven-assembly-plugin/">maven-assembly-plugin</a> to bundle the
+generated XSD files into a zip file.</p>
+</li>
+<li>
+<p>use the <code>xjc-gen</code> to generate corresponding DTO classes from the XSDs.<br></p>
+<div class="paragraph">
+<p>These are <em>not</em> 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)</p>
+</div>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>For example, here is the <code>pom.xml</code> file for the (non-ASF)
+<a href="http://github.com/isisaddons/isis-app-todoapp">Isis addons' todoapp</a> example app’s <code>todoapp-xsd</code> submodule.</p>
+</div>
+<div class="paragraph">
+<p>First, the usual boilerplate:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="xml"><span class="preprocessor"><?xml version="1.0" encoding="UTF-8"?></span>
+<span class="tag"><project</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://maven.apache.org/POM/4.0.0</span><span class="delimiter">"</span></span> <span class="attribute-name">xmlns:xsi</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://www.w3.org/2001/XMLSchema-instance</span><span class="delimiter">"</span></span> <span class="attribute-name">xsi:schemaLocation</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd</span><span class="delimiter">"</span></span><span class="tag">></span>
+ <span class="tag"><modelVersion></span>4.0.0<span class="tag"></modelVersion></span>
+
+ <span class="tag"><parent></span>
+ <span class="tag"><groupId></span>org.isisaddons.app<span class="tag"></groupId></span>
+ <span class="tag"><artifactId></span>todoapp<span class="tag"></artifactId></span>
+ <span class="tag"><version></span>1.11.0-SNAPSHOT<span class="tag"></version></span>
+ <span class="tag"></parent></span>
+
+ <span class="tag"><artifactId></span>todoapp-xsd<span class="tag"></artifactId></span>
+ <span class="tag"><name></span>Isis Addons ToDoApp XSD<span class="tag"></name></span>
+
+ <span class="tag"><dependencies></span>
+ <span class="tag"><dependency></span>
+ <span class="tag"><groupId></span>${project.groupId}<span class="tag"></groupId></span>
+ <span class="tag"><artifactId></span>todoapp-app<span class="tag"></artifactId></span> <i class="conum" data-value="1"></i><b>(1)</b>
+ <span class="tag"></dependency></span>
+ <span class="tag"></dependencies></span>
+
+ <span class="tag"><profiles></span>
+ <span class="tag"><profile></span>
+ <span class="tag"><id></span>isis-xsd<span class="tag"></id></span> <i class="conum" data-value="2"></i><b>(2)</b>
+ ...
+ <span class="tag"></profile></span>
+ <span class="tag"><profile></span>
+ <span class="tag"><id></span>xjc<span class="tag"></id></span> <i class="conum" data-value="3"></i><b>(3)</b>
+ ...
+ <span class="tag"></profile></span>
+ <span class="tag"></profiles></span>
+<span class="tag"></project></span></code></pre>
+</div>
+</div>
+<div class="colist arabic">
+<table>
+<tr>
+<td><i class="conum" data-value="1"></i><b>1</b></td>
+<td>depends on the rest of the application’s modules</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="2"></i><b>2</b></td>
+<td>XSD generation, to run the <code>xsd</code> goal and then assemble into a zip file; within a profile for modularity</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="3"></i><b>3</b></td>
+<td>XJC generation, to run the <code>xjc</code> to generate Java DTO classes from XSDs; within a profile for modularity</td>
+</tr>
+</table>
+</div>
+<div class="sect4">
+<h5 id="_xsd_profile">XSD profile</h5>
+<div class="paragraph">
+<p>The <code>isis-xsd</code> profile runs the <code>xsd</code> goal of the <code>isis-maven-plugin</code>; these are then zipped up by the assembly plugin:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="xml"><span class="tag"><profile></span>
+ <span class="tag"><id></span>isis-xsd<span class="tag"></id></span>
+ <span class="tag"><activation></span>
+ <span class="tag"><property></span>
+ <span class="tag"><name></span>!skip.isis-xsd<span class="tag"></name></span> <i class="conum" data-value="1"></i><b>(1)</b>
+ <span class="tag"></property></span>
+ <span class="tag"></activation></span>
+ <span class="tag"><build></span>
+ <span class="tag"><plugins></span>
+ <span class="tag"><plugin></span>
+ <span class="tag"><groupId></span>org.apache.isis.tool<span class="tag"></groupId></span>
+ <span class="tag"><artifactId></span>isis-maven-plugin<span class="tag"></artifactId></span>
+ <span class="tag"><version></span>${isis.version}<span class="tag"></version></span>
+ <span class="tag"><configuration></span>
+ <span class="tag"><appManifest></span>todoapp.dom.ToDoAppDomManifest<span class="tag"></appManifest></span> <i class="conum" data-value="2"></i><b>(2)</b>
+ <span class="tag"><jaxbClasses></span> <i class="conum" data-value="3"></i><b>(3)</b>
+ <span class="tag"><jaxbClass></span>todoapp.app.viewmodels.todoitem.v1_0.ToDoItemDto<span class="tag"></jaxbClass></span>
+ <span class="tag"><jaxbClass></span>todoapp.app.viewmodels.todoitem.v1_1.ToDoItemDto<span class="tag"></jaxbClass></span>
+ <span class="tag"></jaxbClasses></span>
+ <span class="tag"></configuration></span>
+ <span class="tag"><dependencies></span>
+ <span class="tag"><dependency></span>
+ <span class="tag"><groupId></span>${project.groupId}<span class="tag"></groupId></span>
+ <span class="tag"><artifactId></span>todoapp-dom<span class="tag"></artifactId></span>
+ <span class="tag"><version></span>${project.version}<span class="tag"></version></span>
+ <span class="tag"></dependency></span>
+ <span class="tag"><dependency></span> <i class="conum" data-value="4"></i><b>(4)</b>
+ <span class="tag"><groupId></span>com.google.guava<span class="tag"></groupId></span>
+ <span class="tag"><artifactId></span>guava<span class="tag"></artifactId></span>
+ <span class="tag"><version></span>16.0.1<span class="tag"></version></span>
+ <span class="tag"></dependency></span>
+ <span class="tag"></dependencies></span>
+ <span class="tag"><executions></span>
+ <span class="tag"><execution></span>
+ <span class="tag"><phase></span>generate-sources<span class="tag"></phase></span> <i class="conum" data-value="5"></i><b>(5)</b>
+ <span class="tag"><goals></span>
+ <span class="tag"><goal></span>xsd<span class="tag"></goal></span> <i class="conum" data-value="6"></i><b>(6)</b>
+ <span class="tag"></goals></span>
+ <span class="tag"></execution></span>
+ <span class="tag"></executions></span>
+ <span class="tag"></plugin></span>
+ <span class="tag"><plugin></span>
+ <span class="tag"><artifactId></span>maven-assembly-plugin<span class="tag"></artifactId></span> <i class="conum" data-value="7"></i><b>(7)</b>
+ <span class="tag"><version></span>2.5.3<span class="tag"></version></span>
+ <span class="tag"><configuration></span>
+ <span class="tag"><descriptor></span>src/assembly/dep.xml<span class="tag"></descriptor></span> <i class="conum" data-value="8"></i><b>(8)</b>
+ <span class="tag"></configuration></span>
+ <span class="tag"><executions></span>
+ <span class="tag"><execution></span>
+ <span class="tag"><id></span>create-archive<span class="tag"></id></span>
+ <span class="tag"><phase></span>package<span class="tag"></phase></span>
+ <span class="tag"><goals></span>
+ <span class="tag"><goal></span>single<span class="tag"></goal></span>
+ <span class="tag"></goals></span>
+ <span class="tag"></execution></span>
+ <span class="tag"></executions></span>
+ <span class="tag"></plugin></span>
+ <span class="tag"></plugins></span>
+ <span class="tag"></build></span>
+<span class="tag"></profile></span></code></pre>
+</div>
+</div>
+<div class="colist arabic">
+<table>
+<tr>
+<td><i class="conum" data-value="1"></i><b>1</b></td>
+<td>enabled <em>unless</em> <code>skip.isis-xsd</code> property specified</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="2"></i><b>2</b></td>
+<td>specify the app manifest to bootstrap the Isis runtime within the maven plugin</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="3"></i><b>3</b></td>
+<td>enumerate all JAXB-annotated view models</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="4"></i><b>4</b></td>
+<td>workaround to avoid conflict with plexus-default</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="5"></i><b>5</b></td>
+<td>by default is bound to <code>generate-resources</code>, but bind instead to <code>generate-sources</code> if also running the <code>xjc</code> profile: the XSD are an input to <code>xjc</code>, but it is bound by default to <code>generate-sources</code> and the <code>generate-sources</code> phase runs before the <code>generate-resources</code>.</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="6"></i><b>6</b></td>
+<td>run the <code>xsd</code> goal</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="7"></i><b>7</b></td>
+<td>define the assembly plugin</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="8"></i><b>8</b></td>
+<td>assembles the XSD schemas into a zip file, as defined by the <code>dep.xml</code> file (see below).</td>
+</tr>
+</table>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="xml"><span class="tag"><assembly</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2</span><span class="delimiter">"</span></span>
+ <span class="attribute-name">xmlns:xsi</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://www.w3.org/2001/XMLSchema-instance</span><span class="delimiter">"</span></span>
+ <span class="attribute-name">xsi:schemaLocation</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2</span>
+ <span class="content">http://maven.apache.org/xsd/assembly-1.1.2.xsd</span><span class="delimiter">"</span></span><span class="tag">></span>
+ <span class="tag"><id></span>xsd<span class="tag"></id></span>
+ <span class="tag"><formats></span>
+ <span class="tag"><format></span>zip<span class="tag"></format></span>
+ <span class="tag"></formats></span>
+ <span class="tag"><fileSets></span>
+ <span class="tag"><fileSet></span>
+ <span class="tag"><directory></span>${project.build.directory}/generated-resources/isis-xsd<span class="tag"></directory></span> <i class="conum" data-value="1"></i><b>(1)</b>
+ <span class="tag"><outputDirectory></span>/<span class="tag"></outputDirectory></span>
+ <span class="tag"></fileSet></span>
+ <span class="tag"></fileSets></span>
+<span class="tag"></assembly></span></code></pre>
+</div>
+</div>
+<div class="colist arabic">
+<table>
+<tr>
+<td><i class="conum" data-value="1"></i><b>1</b></td>
+<td>the location that the <code>xsd</code> goal writes to.</td>
+</tr>
+</table>
+</div>
+</div>
+<div class="sect4">
+<h5 id="_xjc_profile">XJC profile</h5>
+<div class="paragraph">
+<p>The <code>xjc</code> profile reads the XSD generated by the <code>xsd</code> 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.</p>
+</div>
+<div class="paragraph">
+<p>The <code>xjc</code> profile is defined as:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="xml"><span class="tag"><profile></span>
+ <span class="tag"><id></span>xjc<span class="tag"></id></span>
+ <span class="tag"><activation></span>
+ <span class="tag"><property></span>
+ <span class="tag"><name></span>!skip.xjc<span class="tag"></name></span> <i class="conum" data-value="1"></i><b>(1)</b>
+ <span class="tag"></property></span>
+ <span class="tag"></activation></span>
+ <span class="tag"><build></span>
+ <span class="tag"><plugins></span>
+ <span class="tag"><plugin></span>
+ <span class="tag"><groupId></span>org.jvnet.jaxb2.maven2<span class="tag"></groupId></span>
+ <span class="tag"><artifactId></span>maven-jaxb2-plugin<span class="tag"></artifactId></span>
+ <span class="tag"><version></span>0.12.3<span class="tag"></version></span>
+ <span class="tag"><executions></span>
+ <span class="tag"><execution></span>
+ <span class="tag"><id></span>xjc-generate<span class="tag"></id></span>
+ <span class="tag"><phase></span>generate-sources<span class="tag"></phase></span>
+ <span class="tag"><goals></span>
+ <span class="tag"><goal></span>generate<span class="tag"></goal></span>
+ <span class="tag"></goals></span>
+ <span class="tag"></execution></span>
+ <span class="tag"></executions></span>
+ <span class="tag"><configuration></span>
+ <span class="tag"><removeOldOutput></span>true<span class="tag"></removeOldOutput></span>
+ <span class="tag"><schemaDirectory></span> <i class="conum" data-value="2"></i><b>(2)</b>
+ target/generated-resources/isis-xsd/viewmodels.app.todoapp/todoitem
+ <span class="tag"></schemaDirectory></span>
+ <span class="tag"><schemaIncludes></span> <i class="conum" data-value="3"></i><b>(3)</b>
+ <span class="tag"><schemaInclude></span>v1_0/todoitem.xsd<span class="tag"></schemaInclude></span>
+ <span class="tag"><schemaInclude></span>v1_1/todoitem.xsd<span class="tag"></schemaInclude></span>
+ <span class="tag"></schemaIncludes></span>
+ <span class="tag"><catalog></span>src/main/resources/catalog.xml<span class="tag"></catalog></span> <i class="conum" data-value="4"></i><b>(4)</b>
+ <span class="tag"></configuration></span>
+ <span class="tag"></plugin></span>
+ <span class="tag"><plugin></span>
+ <span class="tag"><groupId></span>org.codehaus.mojo<span class="tag"></groupId></span>
+ <span class="tag"><artifactId></span>build-helper-maven-plugin<span class="tag"></artifactId></span> <i class="conum" data-value="5"></i><b>(5)</b>
+ <span class="tag"><version></span>1.9.1<span class="tag"></version></span>
+ <span class="tag"><executions></span>
+ <span class="tag"><execution></span>
+ <span class="tag"><id></span>add-source<span class="tag"></id></span>
+ <span class="tag"><phase></span>generate-sources<span class="tag"></phase></span>
+ <span class="tag"><goals></span>
+ <span class="tag"><goal></span>add-source<span class="tag"></goal></span>
+ <span class="tag"></goals></span>
+ <span class="tag"><configuration></span>
+ <span class="tag"><sources></span>
+ <span class="tag"><source></span>target/generated-sources/xjc<span class="tag"></source></span> <i class="conum" data-value="6"></i><b>(6)</b>
+ <span class="tag"></sources></span>
+ <span class="tag"></configuration></span>
+ <span class="tag"></execution></span>
+ <span class="tag"></executions></span>
+ <span class="tag"></plugin></span>
+ <span class="tag"></plugins></span>
+ <span class="tag"></build></span>
+<span class="tag"></profile></span></code></pre>
+</div>
+</div>
+<div class="colist arabic">
+<table>
+<tr>
+<td><i class="conum" data-value="1"></i><b>1</b></td>
+<td>enabled <em>unless</em> <code>skip.xjc</code> property specified</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="2"></i><b>2</b></td>
+<td>specifies the directory that the XSD schemas were generated to by the <code>isis-maven-plugin</code></td>
+</tr>
+<tr>
+<td><i class="conum" data-value="3"></i><b>3</b></td>
+<td>specify each of the XSDs to be processed</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="4"></i><b>4</b></td>
+<td>catalog file indicates the location of the referenced <a href="_rg_schema-common">common schema</a> XSDs.</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="5"></i><b>5</b></td>
+<td>the <code>build-helper-maven-plugin</code> adds the Java source generated by the <code>xjc</code> plugin so that it can be compiled and
+packaged as any other code</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="6"></i><b>6</b></td>
+<td>the location that the <code>xjc</code> plugin generates its source code.</td>
+</tr>
+</table>
+</div>
+<div class="paragraph">
+<p>The referenced <code>catalog.xml</code> file instructs the <code>xjc</code> plugin how to resolve referenced schema locations. Only a
+reference for the Apache Isis <a href="_rg_schema-common">common schema</a> is likely to be needed:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="xml"><span class="preprocessor"><?xml version="1.0" encoding="UTF-8"?></span>
+<span class="doctype"><!DOCTYPE catalog
+ PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN"
+ "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd"></span>
+<span class="tag"><catalog</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">"</span><span class="content">urn:oasis:names:tc:entity:xmlns:xml:catalog</span><span class="delimiter">"</span></span><span class="tag">></span>
+ <span class="tag"><public</span> <span class="attribute-name">publicId</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://isis.apache.org/schema/common</span><span class="delimiter">"</span></span>
+ <span class="attribute-name">uri</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://isis.apache.org/schema/common/common.xsd</span><span class="delimiter">"</span></span><span class="tag">/></span> <i class="conum" data-value="1"></i><b>(1)</b>
+<span class="tag"></catalog></span></code></pre>
+</div>
+</div>
+<div class="colist arabic">
+<table>
+<tr>
+<td><i class="conum" data-value="1"></i><b>1</b></td>
+<td>resolve the common schema from the Apache Isis website</td>
+</tr>
+</table>
+</div>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_to_run_2">5.3.2. To run</h4>
+<div class="paragraph">
+<p>The plugin is activated by default, so is run simply using:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="bash">mvn package</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>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.</p>
+</div>
+<div class="paragraph">
+<p>If for any reason you want to disable the generation of the DTOs, use:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="bash">mvn package -Dskip.xjc</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>If you want to disable the generation of both the XSDs and the DTOs, use:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="bash">mvn package -Dskip.xjc -Dskip.isis-xsd</code></pre>
+</div>
+</div>
+</div>
+</div>
+</div>
</div>
<div class="sect1">
<h2 id="_cg_building-isis">6. Building Apache Isis</h2>
@@ -7778,11 +8266,27 @@ xxx<br>
<li><a href="#_cg_cmd-line">4. Command Line and CI</a></li>
<li><a href="#_cg_isis-maven-plugin">5. Apache Isis Maven Plugin</a>
<ul class="sectlevel2">
-<li><a href="#__code_dom_code_project">5.1. <code>dom</code> project</a></li>
-<li><a href="#_to_run">5.2. To run</a></li>
-<li><a href="#_example_of_failure">5.3. Example of failure</a></li>
-<li><a href="#_custom_validation_rules">5.4. Custom validation rules</a></li>
-<li><a href="#_1_9_0_version">5.5. 1.9.0 version</a></li>
+<li><a href="#__code_appmanifest_code">5.1. <code>AppManifest</code></a></li>
+<li><a href="#_cg_isis-maven-plugin_validate">5.2. <code>validate</code> goal</a>
+<ul class="sectlevel3">
+<li><a href="#__code_dom_code_submodule">5.2.1. <code>dom</code> submodule</a></li>
+<li><a href="#_to_run">5.2.2. To run</a></li>
+<li><a href="#_example_of_failure">5.2.3. Example of failure</a></li>
+<li><a href="#_custom_validation_rules">5.2.4. Custom validation rules</a></li>
+<li><a href="#_1_9_0_version">5.2.5. 1.9.0 version</a></li>
+</ul>
+</li>
+<li><a href="#_cg_isis-maven-plugin_xsd">5.3. <code>xsd</code> goal (<code>1.11.0-SNAPSHOT</code>)</a>
+<ul class="sectlevel3">
+<li><a href="#_cg_isis-maven-plugin_xsd">5.3.1. <code>xsd</code> submodule</a>
+<ul class="sectlevel4">
+<li><a href="#_xsd_profile">XSD profile</a></li>
+<li><a href="#_xjc_profile">XJC profile</a></li>
+</ul>
+</li>
+<li><a href="#_to_run_2">5.3.2. To run</a></li>
+</ul>
+</li>
</ul>
</li>
<li><a href="#_cg_building-isis">6. Building Apache Isis</a>
http://git-wip-us.apache.org/repos/asf/isis-site/blob/c8287a03/content/guides/images/maven-plugin/xsd-goal.png
----------------------------------------------------------------------
diff --git a/content/guides/images/maven-plugin/xsd-goal.png b/content/guides/images/maven-plugin/xsd-goal.png
new file mode 100644
index 0000000..88c7b6e
Binary files /dev/null and b/content/guides/images/maven-plugin/xsd-goal.png differ
http://git-wip-us.apache.org/repos/asf/isis-site/blob/c8287a03/content/guides/images/maven-plugin/xsd-goal.pptx
----------------------------------------------------------------------
diff --git a/content/guides/images/maven-plugin/xsd-goal.pptx b/content/guides/images/maven-plugin/xsd-goal.pptx
new file mode 100644
index 0000000..62d3a8a
Binary files /dev/null and b/content/guides/images/maven-plugin/xsd-goal.pptx differ
http://git-wip-us.apache.org/repos/asf/isis-site/blob/c8287a03/content/guides/ug.html
----------------------------------------------------------------------
diff --git a/content/guides/ug.html b/content/guides/ug.html
index c0572ff..2c0abc7 100644
--- a/content/guides/ug.html
+++ b/content/guides/ug.html
@@ -6067,7 +6067,7 @@ et al) this state _can</em> include collections.</p>
examples are taken from the (non-ASF) <a href="http://github.com/isisaddons/isis-app-todoapp">Isis addons' todoapp</a>.</p>
</div>
<div class="sect4">
-<h5 id="_use_packages_to_version_dtos">Use packages to version DTOs</h5>
+<h5 id="_ug_more-advanced_view-models_jaxb_using-packages-to-version">Use packages to version DTOs</h5>
<div class="paragraph">
<p>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
@@ -6085,8 +6085,7 @@ representation of its underlying <code>ToDoItem</code> entity):</p>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@XmlRootElement</span>(name = <span class="string"><span class="delimiter">"</span><span class="content">toDoItemDto</span><span class="delimiter">"</span></span>) <i class="conum" data-value="1"></i><b>(1)</b>
<span class="annotation">@XmlType</span>(
- namespace = <span class="string"><span class="delimiter">"</span><span class="content">http://viewmodels.app.todoapp/v1/todoitem</span><span class="delimiter">"</span></span>, <i class="conum" data-value="2"></i><b>(2)</b>
- propOrder = { <i class="conum" data-value="3"></i><b>(3)</b>
+ propOrder = { <i class="conum" data-value="2"></i><b>(2)</b>
<span class="string"><span class="delimiter">"</span><span class="content">description</span><span class="delimiter">"</span></span>,
<span class="string"><span class="delimiter">"</span><span class="content">category</span><span class="delimiter">"</span></span>,
<span class="string"><span class="delimiter">"</span><span class="content">subcategory</span><span class="delimiter">"</span></span>,
@@ -6094,11 +6093,11 @@ representation of its underlying <code>ToDoItem</code> entity):</p>
}
)
<span class="annotation">@DomainObjectLayout</span>(
- titleUiEvent = TitleUiEvent.Doop.class <i class="conum" data-value="4"></i><b>(4)</b>
+ titleUiEvent = TitleUiEvent.Doop.class <i class="conum" data-value="3"></i><b>(3)</b>
)
<span class="directive">public</span> <span class="type">class</span> <span class="class">ToDoItemDto</span> <span class="directive">implements</span> Dto {
<span class="annotation">@XmlElement</span>(required = <span class="predefined-constant">true</span>)
- <span class="annotation">@Getter</span> <span class="annotation">@Setter</span> <i class="conum" data-value="5"></i><b>(5)</b>
+ <span class="annotation">@Getter</span> <span class="annotation">@Setter</span> <i class="conum" data-value="4"></i><b>(4)</b>
<span class="directive">protected</span> <span class="predefined-type">String</span> description;
<span class="annotation">@XmlElement</span>(required = <span class="predefined-constant">true</span>)
@@ -6121,18 +6120,14 @@ representation of its underlying <code>ToDoItem</code> entity):</p>
</tr>
<tr>
<td><i class="conum" data-value="2"></i><b>2</b></td>
-<td>specify the XML schema namespace to which this element type belongs</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="3"></i><b>3</b></td>
<td>all properties in the class must be listed; (they can be ignored using <code>@XmlTransient</code>)</td>
</tr>
<tr>
-<td><i class="conum" data-value="4"></i><b>4</b></td>
+<td><i class="conum" data-value="3"></i><b>3</b></td>
<td>demonstrating use of UI events for a subscriber to provide the DTO’s title; see <a href="rg.html#_rg_annotations_manpage-DomainObjectLayout_titleUiEvent"><code>@DomainObjectLayout#titleUiEvent()</code></a>.</td>
</tr>
<tr>
-<td><i class="conum" data-value="5"></i><b>5</b></td>
+<td><i class="conum" data-value="4"></i><b>4</b></td>
<td>optional; JAXB metadata can specify such attributes as required/optional</td>
</tr>
</table>
@@ -6143,43 +6138,32 @@ representation of its underlying <code>ToDoItem</code> entity):</p>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@javax</span>.xml.bind.annotation.XmlSchema(
- namespace = <span class="string"><span class="delimiter">"</span><span class="content">http://viewmodels.app.todoapp/v1/todoitem</span><span class="delimiter">"</span></span>, <i class="conum" data-value="1"></i><b>(1)</b>
- xmlns = {
- <span class="annotation">@javax</span>.xml.bind.annotation.XmlNs(
- namespaceURI = <span class="string"><span class="delimiter">"</span><span class="content">http://isis.apache.org/schema/common</span><span class="delimiter">"</span></span>, <i class="conum" data-value="2"></i><b>(2)</b>
- prefix = <span class="string"><span class="delimiter">"</span><span class="content">common</span><span class="delimiter">"</span></span>
- )
- },
+ namespace = <span class="string"><span class="delimiter">"</span><span class="content">http://viewmodels.app.todoapp/todoitem/v1_0/todoitem.xsd</span><span class="delimiter">"</span></span>, <i class="conum" data-value="1"></i><b>(1)</b>
elementFormDefault = javax.xml.bind.annotation.XmlNsForm.QUALIFIED
)
-<span class="keyword">package</span> <span class="namespace">todoapp.app.viewmodels.todoitem.v1_0</span>; <i class="conum" data-value="3"></i><b>(3)</b></code></pre>
+<span class="keyword">package</span> <span class="namespace">todoapp.app.viewmodels.todoitem.v1_0</span>; <i class="conum" data-value="2"></i><b>(2)</b></code></pre>
</div>
</div>
<div class="colist arabic">
<table>
<tr>
<td><i class="conum" data-value="1"></i><b>1</b></td>
-<td>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)</td>
+<td>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).</td>
</tr>
<tr>
<td><i class="conum" data-value="2"></i><b>2</b></td>
-<td>define an alias for all of other Java types used within the DTO class. It’s recommended that the Apache Isis <a href="rg.html#_rg_schema-common">common schema</a> is always be defined; any references to persistent entities will resultin usage
-of this schema.</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="3"></i><b>3</b></td>
<td>the package in which the DTO resides.</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>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".</p>
+also include a version "v1_0".</p>
</div>
</div>
<div class="sect4">
-<h5 id="_versioning">Versioning</h5>
+<h5 id="_ug_more-advanced_view-models_jaxb_semantic-versioning">Semantic Versioning</h5>
<div class="paragraph">
<p>Versioning DTOs enables us to make changes without breaking existing consumers of the data. We can distinguish two
types of changes:</p>
@@ -6217,7 +6201,6 @@ copy-n-paste rather than through inheritance.</p>
...
<span class="annotation">@XmlRootElement</span>(name = <span class="string"><span class="delimiter">"</span><span class="content">toDoItemDto</span><span class="delimiter">"</span></span>)
<span class="annotation">@XmlType</span>(
- namespace = <span class="string"><span class="delimiter">"</span><span class="content">http://viewmodels.app.todoapp/v1_1/todoitem</span><span class="delimiter">"</span></span>,
propOrder = {
<span class="string"><span class="delimiter">"</span><span class="content">toDoItem</span><span class="delimiter">"</span></span>,
<span class="string"><span class="delimiter">"</span><span class="content">similarItems</span><span class="delimiter">"</span></span>
@@ -6235,19 +6218,15 @@ for <code>v1_0</code>:</p>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@javax</span>.xml.bind.annotation.XmlSchema(
- namespace = <span class="string"><span class="delimiter">"</span><span class="content">http://viewmodels.app.todoapp/v1_1/todoitem</span><span class="delimiter">"</span></span>,
+ namespace = <span class="string"><span class="delimiter">"</span><span class="content">http://viewmodels.app.todoapp/todoitem/v1_1/todoitem.xsd</span><span class="delimiter">"</span></span>, <i class="conum" data-value="1"></i><b>(1)</b>
xmlns = {
- <span class="annotation">@javax</span>.xml.bind.annotation.XmlNs(
+ <span class="annotation">@javax</span>.xml.bind.annotation.XmlNs( <i class="conum" data-value="2"></i><b>(2)</b>
namespaceURI = <span class="string"><span class="delimiter">"</span><span class="content">http://isis.apache.org/schema/common</span><span class="delimiter">"</span></span>,
prefix = <span class="string"><span class="delimiter">"</span><span class="content">common</span><span class="delimiter">"</span></span>
),
<span class="annotation">@javax</span>.xml.bind.annotation.XmlNs(
- namespaceURI = <span class="string"><span class="delimiter">"</span><span class="content">http://viewmodels.app.todoapp/v1_0/todoitem</span><span class="delimiter">"</span></span>,
+ namespaceURI = <span class="string"><span class="delimiter">"</span><span class="content">http://viewmodels.app.todoapp/todoitem/v1_0/todoitem.xsd</span><span class="delimiter">"</span></span>,
prefix = <span class="string"><span class="delimiter">"</span><span class="content">todoitem-v1_0</span><span class="delimiter">"</span></span>
- ),
- <span class="annotation">@javax</span>.xml.bind.annotation.XmlNs(
- namespaceURI = <span class="string"><span class="delimiter">"</span><span class="content">http://viewmodels.app.todoapp/v1_1/todoitem</span><span class="delimiter">"</span></span>,
- prefix = <span class="string"><span class="delimiter">"</span><span class="content">todoitem-v1_1</span><span class="delimiter">"</span></span>
)
},
elementFormDefault = javax.xml.bind.annotation.XmlNsForm.QUALIFIED
@@ -6255,9 +6234,21 @@ for <code>v1_0</code>:</p>
<span class="keyword">package</span> <span class="namespace">todoapp.app.viewmodels.todoitem.v1_1</span>;</code></pre>
</div>
</div>
+<div class="colist arabic">
+<table>
+<tr>
+<td><i class="conum" data-value="1"></i><b>1</b></td>
+<td>namespace URI for DTO in this class.</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="2"></i><b>2</b></td>
+<td>aliases for any other namespaces referenced.</td>
+</tr>
+</table>
+</div>
</div>
<div class="sect4">
-<h5 id="_referencing_domain_entities">Referencing Domain Entities</h5>
+<h5 id="_ug_more-advanced_view-models_jaxb_referencing-domain-entities">Referencing Domain Entities</h5>
<div class="paragraph">
<p>It’s quite common for view models to be "backed by" (be projections of) some underlying domain entity. The
<code>ToDoItemDto</code> we’ve been using as the example in this section is an example: there is an underlying <code>ToDoItem</code> entity.</p>
@@ -6303,7 +6294,7 @@ public <span class="type">class</span> <span class="class">ToDoItemDto</span> <s
</div>
</div>
<div class="sect4">
-<h5 id="_collections_3">Collections</h5>
+<h5 id="_ug_more-advanced_view-models_jaxb_collections">Collections</h5>
<div class="paragraph">
<p>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.</p>
@@ -6341,6 +6332,19 @@ to handle the memento string in some other fashion (eg substituting it with a GU
on the server).</p>
</div>
</div>
+<div class="sect4">
+<h5 id="_generating_xsds_and_dtos">Generating XSDs and DTOs</h5>
+<div class="paragraph">
+<p>The <a href="cg.html#_cg_isis-maven-plugin">Apache Isis maven plugin</a> provides the <a href="cg.html#_cg_isis-maven-plugin_xsd">xsd</a> goal that allows the XSDs to be generated from any JAXB-annotated view models.
+These use the <a href="rg.html#_rg_services-api_manpage-JaxbService"><code>JaxbService</code></a> to generate the schemas; using the
+standard <code>schemagen</code> command line will not correctly interpret any references to domain entities as OIDs.</p>
+</div>
+<div class="paragraph">
+<p>The documentation for the <code>xsd</code> 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.</p>
+</div>
+</div>
</div>
</div>
<div class="sect2">
@@ -15584,10 +15588,11 @@ TODO
<li><a href="#_ug_more-advanced_view-models_programming-model">5.3.2. Programming Model</a></li>
<li><a href="#_ug_more-advanced_view-models_jaxb">5.3.3. JAXB-annotated DTOs (<code>1.11.0-SNAPSHOT</code>)</a>
<ul class="sectlevel4">
-<li><a href="#_use_packages_to_version_dtos">Use packages to version DTOs</a></li>
-<li><a href="#_versioning">Versioning</a></li>
-<li><a href="#_referencing_domain_entities">Referencing Domain Entities</a></li>
-<li><a href="#_collections_3">Collections</a></li>
+<li><a href="#_ug_more-advanced_view-models_jaxb_using-packages-to-version">Use packages to version DTOs</a></li>
+<li><a href="#_ug_more-advanced_view-models_jaxb_semantic-versioning">Semantic Versioning</a></li>
+<li><a href="#_ug_more-advanced_view-models_jaxb_referencing-domain-entities">Referencing Domain Entities</a></li>
+<li><a href="#_ug_more-advanced_view-models_jaxb_collections">Collections</a></li>
+<li><a href="#_generating_xsds_and_dtos">Generating XSDs and DTOs</a></li>
</ul>
</li>
</ul>