You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by bu...@apache.org on 2014/11/19 06:35:02 UTC
svn commit: r929734 - in /websites/staging/isis/trunk: cgi-bin/ content/
content/intro/tutorials/apacheconeu-2014.html
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>