Author: buildbot
Date: Wed Nov 19 05:35:02 2014
New Revision: 929734
Log:
Staging update by buildbot for isis
Modified:
websites/staging/isis/trunk/cgi-bin/ (props changed)
websites/staging/isis/trunk/content/ (props changed)
websites/staging/isis/trunk/content/intro/tutorials/apacheconeu-2014.html
Propchange: websites/staging/isis/trunk/cgi-bin/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Wed Nov 19 05:35:02 2014
@@ -1 +1 @@
-1640489
+1640491
Propchange: websites/staging/isis/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Wed Nov 19 05:35:02 2014
@@ -1 +1 @@
-1640489
+1640491
Modified:
websites/staging/isis/trunk/content/intro/tutorials/apacheconeu-2014.html
==============================================================================
--- websites/staging/isis/trunk/content/intro/tutorials/apacheconeu-2014.html
(original)
+++ websites/staging/isis/trunk/content/intro/tutorials/apacheconeu-2014.html
Wed Nov 19 05:35:02 2014
@@ -424,11 +424,25 @@
<p><div class="apacheconeu2014"></p>
<p><div class="note">
-A half-day tutorial (at least!) on developing domain-driven apps using Apache
Isis.
+A half-day tutorial on developing domain-driven apps using Apache Isis.
</div></p>
+<p>Actually, you could spend a full day working through this tutorial if you
wanted to... so pick and choose the bits that look interesting.</p>
+
+<h2>Prerequisites</h2>
+
+<p>You'll need:</p>
+
+<ul>
+<li>Java 7 JDK</li>
+<li><a href="http://maven.apache.org/";>Maven</a> 3.2.x</li>
+<li>an IDE, such as <a href="http://www.eclipse.org/";>Eclipse</a> or <a
href="https://www.jetbrains.com/idea/";>IntelliJ IDEA</a>.</li>
+</ul>
+
<h2>Run the archetype</h2>
+<p>As per the <a
href="http://isis.apache.org/intro/getting-started/simpleapp-archetype.html";>Isis
website</a>, run the simpleapp archetype to build an empty Isis application.
We recommend you use the snapshot release:</p>
+
<pre><code>mvn archetype:generate \
-D archetypeGroupId=org.apache.isis.archetype \
-D archetypeArtifactId=simpleapp-archetype \
@@ -442,34 +456,46 @@ A half-day tutorial (at least!) on devel
<h2>Build and run</h2>
+<p>Start off by building the app from the command line:</p>
+
<pre><code>cd myapp
mvn clean install
</code></pre>
-<p>then</p>
+<p>Once that's built then run using:</p>
<pre><code>mvn antrun:run -P self-host
</code></pre>
-<p>or alternatively</p>
+<p>A splash screen should appear offering to start up the app. Go ahead and
start; the web browser should be opened at http://localhost:8080</p>
+
+<p>Alternatively, you can run using the mvn-jetty-plugin:</p>
<pre><code>mvn jetty:run
</code></pre>
+<p>This will accomplish the same thing, though the webapp is mounted at a
slightly different URL</p>
+
<h2>Using the app</h2>
+<p>Navigate to the Wicket UI (eg http://localhost:8080/wicket), and login
(sven/pass).</p>
+
+<p>Once at the home page:</p>
+
<ul>
<li>install fixtures</li>
-<li>list all</li>
-<li>create new</li>
-<li>list all </li>
+<li>list all objects</li>
+<li>create a new object</li>
+<li>list all objects</li>
</ul>
+<p>Go back to the splash screen, and quit the app. Note that the database
runs in-memory (using HSQLDB) so any data created will be lost between runs.</p>
+
<h2>Dev environment</h2>
<p>Set up an IDE and import the project to be able to run and debug the app</p>
-<h4>Configure</h4>
+<p>To configure the app, use these links:</p>
<ul>
<li>IDE:
@@ -480,11 +506,12 @@ mvn clean install
<li>Set up IDE <a
href="http://isis.apache.org/intro/resources/editor-templates.html";>editor
templates</a></li>
</ul>
-<h4>Run</h4>
+<p>Then set up a launch configuration and check that you can:</p>
<ul>
<li>Run the app from within the IDE</li>
-<li>Run with different deploymentTypes, note whether <code>@Prototype</code>
actions are available or not:
+<li>Run the app in debug mode</li>
+<li>Run with different deploymentTypes; note whether <code>@Prototype</code>
actions are available or not:
<ul>
<li><code>--type SERVER_PROTOTYPE</code></li>
<li><code>--type SERVER</code></li>
@@ -540,7 +567,7 @@ mvn clean install
<h2>Prototyping</h2>
-<p>Exclude the <code>integtests</code> module.</p>
+<p>Although testing is important, in this tutorial we want to concentrate on
how to write features and to iterate quickly. So for now, exclude the
<code>integtests</code> module. Later on in the tutorial we'll add the tests
back in so you can learn how to write automated tests for the features of your
app.</p>
<p>In the parent <code>pom.xml</code>:</p>
@@ -570,7 +597,7 @@ mvn clean install
<p><img src="http://yuml.me/a070d071"; alt="" /></p>
-<p>which in yuml.me's DSL is:</p>
+<p>In case you're interested, the above diagram was built using
[yuml.me][http://yuml.me]; the DSL that defines this diagram is:</p>
<pre>
[Visit|-checkIn:DateTime;-checkout:DateTime;-diagnosis:String|+checkin();+checkout();+addNote()]->[Pet|-name:String;-species:PetSpecies]
@@ -579,7 +606,7 @@ mvn clean install
<h2>Domain entity</h2>
-<p>Most domain objects in Apache Isis applications are persistent entities.</p>
+<p>Most domain objects in Apache Isis applications are persistent entities.
In the simpleapp archetype the <code>SimpleObject</code> is an example. We can
start developing our app by refactoring that class:</p>
<ul>
<li>rename the <code>SimpleObject</code> class
@@ -600,7 +627,9 @@ mvn clean install
<h2>Domain service</h2>
-<p>Domain services either act as factories or repositories to entities, or
(more generally) can be used to "bridge across" to other domains/bounded
contexts. Most are application-scoped, but they can also be request-scoped if
required.</p>
+<p>Domain services often act as factories or repositories to entities; more
generally can be used to "bridge across" to other domains/bounded contexts.
Most are application-scoped, but they can also be request-scoped if
required.</p>
+
+<p>In the simpleapp archetype the <code>SimpleObjects</code> service is a
factory/repository for the original <code>SimpleObject</code> entity. For our
app it therefore makes sense to refactor that class into our own first
service:</p>
<ul>
<li>rename the <code>SimpleObjects</code> class
@@ -638,9 +667,11 @@ mvn clean install
<li>and update to delete from the appropriate underlying database table(s)</li>
<li>use the injected <a
href="http://isis.apache.org/components/objectstores/jdo/services/isisjdosupport-service.html";>IsisJdoSupport</a>
domain service.</li>
</ul></li>
-<li>update to create new instances of domain entity
+<li>refactor/rename the fixture script classes that create instances your
entity:
<ul>
-<li>inject in the corresponding domain service</li>
+<li><code>SimpleObjectsFixture</code>, which sets up a set of objects for a
given scenario</li>
+<li><code>SimpleObjectForFoo</code>, <code>SimpleObjectForBar</code>,
<code>SimpleObjectForBaz</code> and their superclass,
<code>SimpleObjectAbstract</code></li>
+<li>note that domain services can be injected into these fixture scripts</li>
</ul></li>
</ul>
@@ -719,6 +750,7 @@ mvn clean install
<ul>
<li>see also this <a
href="http://isis.apache.org/components/viewers/wicket/static-layouts.html";>static
layouts</a> documentation</li>
</ul></li>
+<li>use the <a
href="http://isis.apache.org/reference/recognized-annotations/about.html";>@LabelAt</a>
annotation to position property labels either to the LEFT, TOP or NONE</li>
</ul>
<h2>Reference properties</h2>
@@ -793,7 +825,7 @@ mvn clean install
<h2>Dynamic Layout</h2>
-<p>Up to this point we've been using annotations (<code>@MemberOrder</code>,
<code>@MemberGroupLayout</code>, <code>@Named</code> and so on) for UI hints.
However, the feedback loop is not good: it requires us stopping the app,
editing the code, recompiling and running again. So instead, all these UI
hints (and more) can be specified dynamically, using a corresponding
<code>.layout.json</code> file. If edited while the app is running, it will be
reloaded automatically (in IntelliJ, use Run>Reload Changed Classes):</p>
+<p>Up to this point we've been using annotations (<code>@MemberOrder</code>,
<code>@MemberGroupLayout</code>, <code>@Named</code>, <code>@LabelAt</code> and
so on) for UI hints. However, the feedback loop is not good: it requires us
stopping the app, editing the code, recompiling and running again. So instead,
all these UI hints (and more) can be specified dynamically, using a
corresponding <code>.layout.json</code> file. If edited while the app is
running, it will be reloaded automatically (in IntelliJ, use Run>Reload Changed
Classes):</p>
<ul>
<li>Delete the <code>@MemberOrder</code> and <code>@MemberGroupLayout</code>
annotations and instead specify layout hints using a <a
href="http://isis.apache.org/components/viewers/wicket/dynamic-layouts.html";>.layout.json</a>
file.</li>
@@ -811,7 +843,7 @@ mvn clean install
<p>Or, more pithily: "see it, use it, do it"</p>
-<h3>See it!</h3>
+<h4>See it!</h4>
<ul>
<li>Use the <a
href="http://isis.apache.org/reference/recognized-annotations/Hidden.html";>@Hidden</a>
annotation to make properties/collections/actions invisible
@@ -821,14 +853,14 @@ mvn clean install
<li>Use the <code>hideXxx()</code> supporting method on <a
href="http://isis.apache.org/how-tos/how-to-02-010-How-to-hide-a-property.html";>properties</a>,
<a
href="http://isis.apache.org/how-tos/how-to-02-020-How-to-hide-a-collection.html";>collections</a>
and <a
href="http://isis.apache.org/how-tos/how-to-02-030-How-to-hide-an-action.html";>actions</a>
to make a property/collection/action invisible according to some imperative
rule</li>
</ul>
-<h3>Use it!</h3>
+<h4>Use it!</h4>
<ul>
<li>Use the <a
href="http://isis.apache.org/reference/recognized-annotations/Disabled.html";>@Disabled</a>
annotation to make properties read-only/actions non-invokable ('greyed
out')</li>
<li>Use the <code>disabledXxx()</code> supporting method on <a
href="http://isis.apache.org/how-tos/how-to-02-050-How-to-prevent-a-property-from-being-modified.html";>properties</a>
and <a
href="http://isis.apache.org/how-tos/how-to-02-070-How-to-prevent-an-action-from-being-invoked.html";>actions</a>
to make a property/action disabled according to some imperative rule</li>
</ul>
-<h3>Do it!</h3>
+<h4>Do it!</h4>
<ul>
<li>Validate string properties or action paramters:
@@ -843,7 +875,9 @@ mvn clean install
</ul></li>
</ul>
-<h2>Dashboard (home page)</h2>
+<h2>Home page</h2>
+
+<p>The Wicket UI will automatically invoke the "home page" action, if
available. This is a no-arg action of one of the domain services, that can
return either an object (eg representing the current user) or a standalone
action.</p>
<ul>
<li>Add the <a
href="http://isis.apache.org/reference/recognized-annotations/HomePage.html";>@HomePage</a>
annotation to one (no more) of the domain services' no-arg actions</li>
@@ -851,7 +885,15 @@ mvn clean install
<h2>Decoupling using Contributions</h2>
-<h3>Contributed Actions</h3>
+<p>One of Isis' most powerful features is the ability for the UI to combine
functionality from domain services into the representation of an entity. The
effect is similar to traits or mix-ins in other languages, however the "mixing
in" is done at runtime, within the Isis metamodel. In Isis' terminology, we
say that the domain service action is contributed to the entity.</p>
+
+<p>Any action of a domain service that has a domain entity type as one of its
parameter types will (by default) be contributed. If the service action takes
more than one argument, or does not have safe semantics, then it will be
contributed as an entity action. If the service action has precisely one
parameter type (that of the entity) and has safe semantics then it will be
contributed either as a collection or as a property (dependent on whether it
returns a collection of a scalar).</p>
+
+<p>Why are contributions so useful? Because the service action will match not
on the entity type, but also on any of the entity's supertypes (all the way up
to <code>java.lang.Object</code>). That means that you can apply the <a
href="http://en.wikipedia.org/wiki/Dependency_inversion_principle";>dependency
inversion principle</a> to ensure that the modules of your application have
acyclic dependencies; but in the UI it can still appear as if there are
bidirectional dependencies between those modules. The lack of bidirectional
dependencies can help save your app degrading into a <a
href="http://en.wikipedia.org/wiki/Big_ball_of_mud";>big ball of mud</a>.</p>
+
+<p>Finally, note that the layout of contributed actions/collections/properties
can be specified using the <code>.layout.json</code> file (and it is highly
recommended that you do so).</p>
+
+<h4>Contributed Actions</h4>
<ul>
<li>Write a new domain service
@@ -871,7 +913,7 @@ mvn clean install
<li>should be rendered "as if" an action of the entity</li>
</ul>
-<h3>Contributed Collections</h3>
+<h4>Contributed Collections</h4>
<ul>
<li>Write a new domain service (or update the one previously)</li>
@@ -888,7 +930,7 @@ mvn clean install
<li>use <code>.layout.json</code> to position as required</li>
</ul>
-<h3>Contributed Properties</h3>
+<h4>Contributed Properties</h4>
<ul>
<li>As for contributed collections, write a new domain service with a
query-only action accepting exactly 1 arg (a domain entity); except:
@@ -971,6 +1013,10 @@ mvn clean install
<p>TODO</p>
+<h2>Configuring to use an external database</h2>
+
+<p>TODO</p>
+
<p></div></p>
