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 2017/08/01 12:43:58 UTC
[3/6] isis git commit: ISIS-1674: updates documentation to reference
helloworld archetype where necessary.
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started.adoc
index 553ab0e..f11d1d3 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started.adoc
@@ -7,40 +7,34 @@
-To get you up and running quickly, Apache Isis provides a xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] to setup a simple application as the basis of your own apps.
-This is deliberately kept quite minimal so that you won't have to spend lots of time removing generated artifacts.
+To get you up and running quickly, Apache Isis provides two archetypes:
+
+* xref:../ugfun/ugfun.adoc#_ugfun_getting-started_helloworld-archetype[HelloWorld archetype] generates a one domain class application so you can quickly learn about Apache Isis by trying it out. +
++
+For simplisty, the generated application is a single Maven module containing both the business logic classes and the bootstrapping code.
+
+* xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype], a slightly more sophisticated one domain class version suitable for use as the basis of your own apps. +
++
+This is still quite minimal so that you won't have to spend lots of time removing generated artifacts.
On the other hand, it does set up a standard multi-module maven structure with unit- and integration tests pre-configured, as well as a webapp module so that you can easily run your app.
We strongly recommend that you preserve this structure as you develop your own Isis application.
-In this chapter we also discuss the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_datanucleus-enhancer[DataNucleus enhancer]. link:http://www.datanucleus.org/[DataNucleus] is the reference implementation of the JDO (Java data objects) spec, and Apache Isis integrates with DataNucleus as its persistence layer.
+In this chapter we also discuss the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_datanucleus-enhancer[DataNucleus enhancer].
+link:http://www.datanucleus.org/[DataNucleus] is the reference implementation of the JDO (Java Data Objects) spec, and Apache Isis integrates with DataNucleus as its persistence layer.
The enhancer performs post-processing on the bytecode of your persistent domain entities, such that they can be persisted by Apache Isis' JDO/DataNucleus objectstore.
[NOTE]
====
-The xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] automatically configures the enhancer, so there's little you need to do at this stage.
+The xref:../ugfun/ugfun.adoc#_ugfun_getting-started_helloworld-archetype[HelloWorld] and xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp] archetypes automatically configures the enhancer, so there's little you need to do at this stage.
+
Even so we feel it's a good idea to be aware of this critical part of Apache Isis runtime; if the enhancer does not run, then you'll find the app fails to start with (what will seem like) quite an obscure exception message.
====
-== Prerequisites
-
-Apache Isis is a Java based framework, so in terms of prerequisites, you'll need to install:
-
-* Java 7 or 8 JDK
-* link:http://maven.apache.org[Apache Maven] 3.0.5 or later
-
-You'll probably also want to use an IDE; the Apache Isis committers use either IntelliJ or Eclipse; in the xref:../dg/dg.adoc#_dg_ide[Developers' Guide] we have detailed setup instructions for using these two IDEs.
-If you're a NetBeans user you should have no problems as it too has strong support for Maven.
-
-When building and running within an IDE, you'll also need to configure the Datanucleus enhancer.
-This is implemented as a Maven plugin, so in the case of IntelliJ, it's easy enough to run the enhancer as required.
-It should be just as straightforward for NetBeans too.
-
-For Eclipse the maven integration story is a little less refined.
-All is not lost, however; DataNucleus also has an implementation of the enhancer as an Eclipse plugin, which usually works well enough.
-
+include::_ugfun_getting-started_prerequisites[leveloffset=+1]
+include::_ugfun_getting-started_helloworld-archetype.adoc[leveloffset=+1]
include::_ugfun_getting-started_simpleapp-archetype.adoc[leveloffset=+1]
include::_ugfun_getting-started_datanucleus-enhancer.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_datanucleus-enhancer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_datanucleus-enhancer.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_datanucleus-enhancer.adoc
index f6d7fdd..f3de3d1 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_datanucleus-enhancer.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_datanucleus-enhancer.adoc
@@ -6,7 +6,8 @@
-link:http://www.datanucleus.org/[DataNucleus] is the reference implementation of the JDO (Java data objects) spec, and Apache Isis integrates with DataNucleus as its persistence layer. Datanucleus is a very powerful library, allowing domain entities to be mapped not only to relational database tables, but also to NoSQL stores such as link:http://neo4j.com/[Neo4J], link:http://www.mongodb.org/[MongoDB] and link:http://cassandra.apache.org/[Apache Cassandra].
+link:http://www.datanucleus.org/[DataNucleus] is the reference implementation of the JDO (Java data objects) spec, and Apache Isis integrates with DataNucleus as its persistence layer.
+Datanucleus is a very powerful library, allowing domain entities to be mapped not only to relational database tables, but also to NoSQL stores such as link:http://neo4j.com/[Neo4J], link:http://www.mongodb.org/[MongoDB] and link:http://cassandra.apache.org/[Apache Cassandra].
With such power comes a little bit of complexity to the development environment: all domain entities must be enhanced through the DataNucleus enhancer.
@@ -17,72 +18,15 @@ Bytecode enhancement is actually a requirement of the JDO spec; the process is d
What this means is that the enhancer -- available as both a Maven plugin and as an Eclipse plugin -- must, one way or another, be integrated into your development environment.
-If working from the Maven command line, JDO enhancement is done using the `maven-datanucleus-plugin`. As of 1.9.0, we put all the configuration into an (always active) profile:
+If working from the Maven command line, JDO enhancement is done using the `maven-datanucleus-plugin`.
-[TIP]
-====
-The configuration described below is automatically set up by the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
-====
-
-
-[source,xml]
-----
-<profile>
- <id>enhance</id>
- <activation>
- <activeByDefault>true</activeByDefault>
- </activation>
- <properties>
- <datanucleus-maven-plugin.version>4.0.1</datanucleus-maven-plugin.version>
- </properties>
- <build>
- <plugins>
- <plugin>
- <groupId>org.datanucleus</groupId>
- <artifactId>datanucleus-maven-plugin</artifactId>
- <version>${datanucleus-maven-plugin.version}</version>
- <configuration>
- <fork>false</fork>
- <log4jConfiguration>${basedir}/log4j.properties</log4jConfiguration>
- <verbose>true</verbose>
- <props>${basedir}/datanucleus.properties</props>
- </configuration>
- <executions>
- <execution>
- <phase>process-classes</phase>
- <goals>
- <goal>enhance</goal>
- </goals>
- </execution>
- </executions>
- </plugin>
- </plugins>
- </build>
- <dependencies>
- <dependency>
- <groupId>org.datanucleus</groupId>
- <artifactId>datanucleus-core</artifactId>
- </dependency>
- <dependency>
- <groupId>org.datanucleus</groupId>
- <artifactId>datanucleus-jodatime</artifactId>
- </dependency>
- <dependency>
- <groupId>org.datanucleus</groupId>
- <artifactId>datanucleus-api-jdo</artifactId>
- </dependency>
- </dependencies>
-</profile>
-----
-
-The xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] sets up the plugin correctly in the `dom` (domain object model) module. (It's actually a little bit more complex to cater for users of the Eclipse IDE using Eclipse's m2e plugin).
+Both the xref:ugfun.adoc#_ugfun_getting-started_helloworld-archetype[HelloWorld] and xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp] Maven archetypes generate applications that have this plugin pre-configured.
+== META-INF/persistence.xml
-== `META-INF/persistence.xml`
-
-It's also a good idea to ensure that the `dom` module has a JDO `META-INF/persistence.xml` file:
+It's also a good idea to ensure that every domain module(s) containing entities has a JDO `META-INF/persistence.xml` file:
[source,xml]
----
@@ -95,9 +39,10 @@ It's also a good idea to ensure that the `dom` module has a JDO `META-INF/persis
</persistence-unit>
</persistence>
----
-<1> change as required; typically is the name of the app.
+<1> change as required; typically is the name of the domain module.
+
+Again, the applications generated by both the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_helloworld-archetype[HelloWorld] and xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[Simpleapp] Maven archetypes do this.
-Again, the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] does this.
[WARNING]
====
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_helloworld-archetype.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_helloworld-archetype.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_helloworld-archetype.adoc
new file mode 100644
index 0000000..83543f7
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_helloworld-archetype.adoc
@@ -0,0 +1,296 @@
+[[_ugfun_getting-started_helloworld-archetype]]
+= HelloWorld Archetype (`1.15.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/
+
+
+The quickest way to start learning about Apache Isis is to run the `helloworld` archetype.
+This will generate a tiny Apache Isis app, consisting of a simple one-class domain model, called `HelloWorldObject`, and a supporting `HelloWorldObjects` domain service.
+Both the business logic and supporting bootstrapping classes are in a single Maven module (in different Java packages).
+
+[TIP]
+====
+We don't recommend that you use the helloworld archetype as the basis for your own applications.
+Instead, use the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[simpleapp archetype].
+This also creates a minimal application, but provides more structure and example tests, useful as you build out your own app.
+====
+
+
+[[_ugfun_getting-started_helloworld-archetype_generating-the-app]]
+== Generating the App
+
+Create a new directory, and `cd` into that directory.
+
+To build the app from the latest stable release, then run the following command:
+
+[source,bash]
+----
+mvn archetype:generate \
+ -D archetypeGroupId=org.apache.isis.archetype \
+ -D archetypeArtifactId=helloworld-archetype \
+ -D archetypeVersion=1.15.0 \
+ -D groupId=com.mycompany \
+ -D artifactId=myapp \
+ -D version=1.0-SNAPSHOT \
+ -B
+----
+
+where:
+
+- `groupId` represents your own organization, and
+- `artifactId` is a unique identifier for this app within your organization.
+- `version` is the initial (snapshot) version of your app
+
+The archetype generation process will then run; it only takes a few seconds.
+
+We also maintain the archetype for the most current `-SNAPSHOT`; an app generated with this archetype will contain the latest features of Apache Isis, but the usual caveats apply: some features still in development may be unstable.
+
+The process is almost identical to that for stable releases, however the `archetype:generate` goal is called with slightly different arguments:
+
+[source,bash]
+----
+mvn archetype:generate \
+ -D archetypeGroupId=org.apache.isis.archetype \
+ -D archetypeArtifactId=helloworld-archetype \
+ -D archetypeVersion=1.15.0-SNAPSHOT \
+ -D groupId=com.mycompany \
+ -D artifactId=myapp \
+ -D version=1.0-SNAPSHOT \
+ -D archetypeRepository=http://repository-estatio.forge.cloudbees.com/snapshot/ \
+ -B
+----
+
+where as before:
+
+- `groupId` represents your own organization, and
+- `artifactId` is a unique identifier for this app within your organization.
+- `version` is the initial (snapshot) version of your app
+
+but also:
+
+- `archetypeVersion` is the SNAPSHOT version of Apache Isis.
+- `archetypeRepository` specifies the location of our snapshot repo (hosted on link:http://www.cloudbees.com[CloudBees]), and
+
+The archetype generation process will then run; it only takes a few seconds.
+
+
+
+[[_ugfun_getting-started_helloworld-archetype_building-the-app]]
+== Building the App
+
+Switch into the root directory of your newly generated app, and build your app:
+
+[source,bash]
+----
+cd myapp
+mvn clean install
+----
+
+where `myapp` is the `artifactId` entered above.
+
+
+
+
+[[_ugfun_getting-started_helloworld-archetype_running-the-app]]
+== Running the App
+
+The `helloworld` archetype generates a single WAR file, configured to run both the xref:../ugvw/ugvw.adoc#[Wicket viewer] and the xref:../ugvro/ugvro.adoc#[Restful Objects viewer].
+The archetype also configures the DataNucleus/JDO Objectstore to use an in-memory HSQLDB connection.
+
+Once you've built the app, you can run the WAR in a variety of ways.
+
+
+=== Using mvn Jetty plugin
+
+First, you could run the WAR in a Maven-hosted Jetty instance, though you need to `cd` into the `webapp` module:
+
+[source,bash]
+----
+mvn jetty:run
+----
+
+
+You can also provide a system property to change the port:
+
+[source,bash]
+----
+mvn jetty:run -D jetty.port=9090
+----
+
+
+=== Using a regular servlet container
+
+You can also take the built WAR file and deploy it into a standalone servlet container such as [Tomcat](http://tomcat.apache.org).
+The default configuration does not require any configuration of the servlet container; just drop the WAR file into the `webapps` directory.
+
+
+
+=== From within the IDE
+
+Most of the time, though, you'll probably want to run the app from within your IDE.
+The mechanics of doing this will vary by IDE; see the xref:../dg/dg.adoc#_dg_ide[Developers' Guide] for details of setting up Eclipse or IntelliJ IDEA.
+Basically, though, it amounts to running `org.apache.isis.WebServer`, and ensuring that the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_datanucleus-enhancer[DataNucleus enhancer] has properly processed all domain entities.
+
+Here's what the setup looks like in IntelliJ IDEA:
+
+image::{_imagesdir}getting-started/helloworld.png[width="600px",link="{_imagesdir}getting-started/helloworld.png"]
+
+with the maven goal to run the DataNucleus enhancer (discussed in more detail xref:ugfun.adoc#_ugfun_getting-started_datanucleus-enhancer[here]) before launch defined as:
+
+image::{_imagesdir}getting-started/helloworld-before-launch.png[width="600px",link="{_imagesdir}getting-started/helloworld-before-launch.png"]
+
+
+
+[[_ugfun_getting-started_helloworld-archetype_using-the-app]]
+== Using the App
+
+When you start the app, you'll be presented with a welcome page from which you can access the webapp using either the xref:../ugvw/ugvw.adoc#[Wicket viewer] or the xref:../ugvro/ugvro.adoc#[Restful Objects viewer]:
+
+image::{_imagesdir}getting-started/using-hello-world/010-root-page.png[width="600px",link="{_imagesdir}getting-started/using-hello-world/010-root-page.png"]
+
+The Wicket viewer provides a human usable web UI (implemented, as you might have guessed from its name, using link:http://wicket.apache.org[Apache Wicket]), so choose that and navigate to the login page:
+
+image::{_imagesdir}getting-started/using-hello-world/020-login-to-wicket-viewer.png[width="600px",link="{_imagesdir}getting-started/using-hello-world/020-login-to-wicket-viewer.png"]
+
+The app itself is configured to run using xref:../ugsec/ugsec.adoc#[shiro security], as configured in the `WEB-INF/shiro.ini` config file. You can login with:
+
+* username: _sven_
+* password: _pass_
+
+
+Once you've logged in you'll see the default home page:
+
+image::{_imagesdir}getting-started/using-hello-world/030-home-page.png[width="600px",link="{_imagesdir}getting-started/using-hello-world/030-home-page.png"]
+
+
+The application is configured to run with an in-memory database, so initially there is no data.
+Create an object using the menu:
+
+image::{_imagesdir}getting-started/using-hello-world/040-create-object-from-menu.png[width="600px",link="{_imagesdir}getting-started/using-hello-world/040-create-object-from-menu.png"]
+
+which brings up a modal dialog:
+
+image::{_imagesdir}getting-started/using-hello-world/050-create-object-from-menu-prompt.png[width="600px",link="{_imagesdir}getting-started/using-hello-world/050-create-object-from-menu-prompt.png"]
+
+hitting OK returns the created object:
+
+image::{_imagesdir}getting-started/using-hello-world/060-created-object.png[width="600px",link="{_imagesdir}getting-started/using-hello-world/060-created-object.png"]
+
+The above functionality is implemented by link:https://github.com/apache/isis/blob/master/example/application/helloworld/src/main/java/domainapp/dom/impl/HelloWorldObjects.java#L43[this code]:
+
+[source,java]
+----
+@Action(semantics = SemanticsOf.NON_IDEMPOTENT)
+@MemberOrder(sequence = "1")
+public HelloWorldObject create(
+ @Parameter(maxLength = 40)
+ @ParameterLayout(named = "Name")
+ final String name) {
+ final HelloWorldObject object = new HelloWorldObject(name);
+ serviceRegistry.injectServicesInto(object);
+ repositoryService.persist(object);
+ return object;
+}
+----
+
+The `HelloWorldObject` contains a couple of properties, and a single action to update that property.
+
+* The `name` property is read-only, and can only be modified using the `updateName` action. +
++
+For example:
++
+image::{_imagesdir}getting-started/using-hello-world/070-update-name.png[width="600px",link="{_imagesdir}getting-started/using-hello-world/070-update-name.png"]
++
+The above functionality is implemented by link:https://github.com/apache/isis/blob/master/example/application/helloworld/src/main/java/domainapp/dom/impl/HelloWorldObject.java#L73[this code]: +
++
+[source,java]
+----
+@Action(
+ semantics = SemanticsOf.IDEMPOTENT,
+ command = CommandReification.ENABLED,
+ publishing = Publishing.ENABLED
+)
+public HelloWorldObject updateName(
+ @Parameter(maxLength = 40)
+ @ParameterLayout(named = "Name")
+ final String name) {
+ setName(name);
+ return this;
+}
+----
+
+* The `notes` property is editable, and can be edited in-place. +
++
+For example:
++
+image::{_imagesdir}getting-started/using-hello-world/080-edit-notes.png[width="600px",link="{_imagesdir}getting-started/using-hello-world/080-edit-notes.png"]
+
+It's also possible to delete an object:
+
+
+The above functionality is implemented by link:https://github.com/apache/isis/blob/master/example/application/helloworld/src/main/java/domainapp/dom/impl/HelloWorldObject.java#L87[this code]:
+
+[source,java]
+----
+@Action(semantics = SemanticsOf.NON_IDEMPOTENT_ARE_YOU_SURE)
+public void delete() {
+ final String title = titleService.titleOf(this);
+ messageService.informUser(String.format("'%s' deleted", title));
+ repositoryService.removeAndFlush(this);
+}
+----
+
+This uses three services provided by the framework; these are injected into the domain object automatically.
+
+
+Going back to the home page (link:http://localhost:8080[localhost:8080]) we can use link:https://swagger.io/[Swagger UI] as a front-end to the REST API provided by the Restful Objects viewer.
+
+image::{_imagesdir}getting-started/using-hello-world/200-swagger-ui-before-reload.png[width="600px",link="{_imagesdir}getting-started/using-hello-world/200-swagger-ui-before-reload.png"]
+
+The Swagger UI is created dynamically from a Swagger schema definition (the schema definition file itself can be downloaded from the Wicket viewer's "Prototyping" menu).
+ This Swagger schema definition groups resources according to Apache Isis metadata:
+
+image::{_imagesdir}getting-started/using-hello-world/210-helloworld-resources.png[width="600px",link="{_imagesdir}getting-started/using-hello-world/210-helloworld-resources.png"]
+
+For example, an object can be created using the resource that represents the `HelloWorldObjects#create` action:
+
+image::{_imagesdir}getting-started/using-hello-world/220-create-object-thru-rest-api.png[width="600px",link="{_imagesdir}getting-started/using-hello-world/220-create-object-thru-rest-api.png"]
+
+The response indicates that the object was successfully created:
+
+image::{_imagesdir}getting-started/using-hello-world/230-create-object-thru-rest-api-response.png[width="600px",link="{_imagesdir}getting-started/using-hello-world/230-create-object-thru-rest-api-response.png"]
+
+The Swagger UI also provides a resource to retrieve any object:
+
+image::{_imagesdir}getting-started/using-hello-world/240-retrieve-object-using-rest-api.png[width="600px",link="{_imagesdir}getting-started/using-hello-world/240-retrieve-object-using-rest-api.png"]
+
+This results in a representation of the domain object (as per the requested `Response Content Type`, ie `ACCEPT` header):
+
+image::{_imagesdir}getting-started/using-hello-world/250-retrieve-object-using-rest-api-response.png[width="600px",link="{_imagesdir}getting-started/using-hello-world/250-retrieve-object-using-rest-api-response.png"]
+
+
+The Swagger UI is provided as a convenience; the REST API is actually a complete hypermedia API (in other words you can follow the links to access all the behaviour exposed in the regular Wicket app).
+The REST API implemented by Apache Isis is specified in the link:http://www.restfulobjects.org[Restful Object spec].
+
+
+[[_ugfun_getting-started_helloworld-archetype_experimenting]]
+== Experimenting
+
+Once you are familiar with the generated app, try modifying it.
+There is plenty of guidance on this site; start with this guide (fundamentals) and then look at the other guides available the main xref:../../documentation.adoc#[documentation] page.
+
+If you use IntelliJ IDEA or Eclipse, do also install the xref:../dg/dg.adoc#__dg_ide_intellij_live-templates[live templates (for IntelliJ)] / xref:../dg/dg.adoc#__dg_ide_eclipse_editor-templates[editor templates (for Eclipse)]; these will help you follow the Apache Isis naming conventions.
+
+If you run into issues, please don't hesitate to ask for help on the link:http://isis.apache.org/help.html[users mailing list].
+
+
+[[_ugfun_getting-started_helloworld-archetype_moving-on]]
+== Moving on
+
+When you are ready to start working on your own app, we _don't_ recommend building on top of the helloworld app.
+
+Instead, we suggest that you start with the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[simpleapp archetype] instead.
+Although a little more complex, it provides more structure and tests, all of which will help you as your application grows.
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_prerequisites.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_prerequisites.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_prerequisites.adoc
new file mode 100644
index 0000000..a90832e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_prerequisites.adoc
@@ -0,0 +1,28 @@
+[[_ugfun_getting-started_prerequisites.adoc]]
+= Prerequisites
+: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/
+
+
+
+Apache Isis is a Java based framework, so in terms of prerequisites, you'll need to install:
+
+* Java 7 or 8 JDK
+* link:http://maven.apache.org[Apache Maven] 3.x
+
+You'll probably also want to use an IDE; the Apache Isis committers use either IntelliJ or Eclipse; in the xref:../dg/dg.adoc#_dg_ide[Developers' Guide] we have detailed setup instructions for using these two IDEs.
+If you're a NetBeans user you should have no problems as it too has strong support for Maven.
+
+When building and running within an IDE, you'll also need to configure the Datanucleus enhancer.
+This is implemented as a Maven plugin, so in the case of IntelliJ, it's easy enough to run the enhancer as required.
+It should be just as straightforward for NetBeans too.
+
+For Eclipse the maven integration story is a little less refined.
+All is not lost, however; DataNucleus also has an implementation of the enhancer as an Eclipse plugin, which usually works well enough.
+
+
+include::_ugfun_getting-started_helloworld-archetype.adoc[leveloffset=+1]
+include::_ugfun_getting-started_simpleapp-archetype.adoc[leveloffset=+1]
+include::_ugfun_getting-started_datanucleus-enhancer.adoc[leveloffset=+1]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_simpleapp-archetype.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_simpleapp-archetype.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_simpleapp-archetype.adoc
index c2b51a9..29c63d9 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_simpleapp-archetype.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_simpleapp-archetype.adoc
@@ -5,14 +5,32 @@
:_imagesdir: images/
-The quickest way to get started with Apache Isis is to run the simple archetype. This will generate a very simple one-class domain model, called `SimpleObject`, with a single property `name`.
+The quickest way to get started building an application "for real" is to run the `simpleapp` archetype.
+Like the xref:ugfun.adoc#_ugfun_getting-started_helloworld-archetype[helloworld archetype], this too will generate a very simple one-class domain model (an entity called `SimpleObject` with a couple of properties).
-There is also a corresponding `SimpleObjects` domain service which acts as a repository for `SimpleObject` entity. From this you can easily rename these initial classes, and extend to build up your own Apache Isis domain application.
+However, the generated application also provides more structure to assist you as your application grows.
+For example:
-Finally, the domain service also includes a `HomePageViewModel` which acts as a home page for the app.
+* the application is multi-module, separating out the business logic (`module-simple` Maven module) from the bootstrapping modules (`application` Maven module and the `webapp` module)
+* the `SimpleObjectRepository` service (to create/retrieve instances) is separate from the `SimpleObjectMenu` menu service (for the UI); the former is delegated to by the latter.
+* a `HomePageViewModel` service acts as a home page for the app.
+* there are example integration tests, BDD tests as well as unit tests
+
+* there are example fixture scripts for use both when prototyping and used by the integration and BDD tests
+
+* the xref:../rgmvn.adoc#[Apache Isis Maven plugin] to xref:../rgmvn.adoc#_rgmvn_validate[validate] your domain model is pre-configured
+
+* Maven plugins to package your app as a Docker image is pre-configured
+
+
+From this you can easily rename these initial classes, and extend to build up your own Apache Isis domain application.
+
+
+
+[[_ugfun_getting-started_simpleapp-archetype_generating-the-app]]
== Generating the App
Create a new directory, and `cd` into that directory.
@@ -72,6 +90,7 @@ The archetype generation process will then run; it only takes a few seconds.
+[[_ugfun_getting-started_simpleapp-archetype_building-the-app]]
== Building the App
Switch into the root directory of your newly generated app, and build your app:
@@ -87,9 +106,11 @@ where `myapp` is the `artifactId` entered above.
+[[_ugfun_getting-started_simpleapp-archetype_running-the-app]]
== Running the App
-The `simpleapp` archetype generates a single WAR file, configured to run both the xref:../ugvw/ugvw.adoc#[Wicket viewer] and the xref:../ugvro/ugvro.adoc#[Restful Objects viewer]. The archetype also configures the DataNucleus/JDO Objectstore to use an in-memory HSQLDB connection.
+The `simpleapp` archetype generates a single WAR file, configured to run both the xref:../ugvw/ugvw.adoc#[Wicket viewer] and the xref:../ugvro/ugvro.adoc#[Restful Objects viewer].
+The archetype also configures the DataNucleus/JDO Objectstore to use an in-memory HSQLDB connection.
Once you've built the app, you can run the WAR in a variety of ways.
@@ -114,137 +135,126 @@ mvn -pl webapp jetty:run -D jetty.port=9090
=== Using a regular servlet container
-You can also take the built WAR file and deploy it into a standalone servlet container such as [Tomcat](http://tomcat.apache.org). The default configuration does not require any configuration of the servlet container; just drop the WAR file into the `webapps` directory.
+You can also take the built WAR file and deploy it into a standalone servlet container such as [Tomcat](http://tomcat.apache.org).
+The default configuration does not require any configuration of the servlet container; just drop the WAR file into the `webapps` directory.
-=== From within the IDE
-
-Most of the time, though, you'll probably want to run the app from within your IDE. The mechanics of doing this will vary by IDE; see the xref:../dg/dg.adoc#_dg_ide[Developers' Guide] for details of setting up Eclipse or IntelliJ IDEA. Basically, though, it amounts to running `org.apache.isis.WebServer`, and ensuring that the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_datanucleus-enhancer[DataNucleus enhancer] has properly processed all domain entities.
-
-Here's what the setup looks like in IntelliJ IDEA:
-
-image::{_imagesdir}getting-started/simpleapp-webapp.png[width="600px",link="{_imagesdir}getting-started/simpleapp-webapp.png"]
-
-
-
-== Running with Fixtures
-
-It is also possible to start the application with a pre-defined set of data; useful for demos or manual exploratory testing. This is done by specifying a xref:../ugtst/ugtst.adoc#_ugtst_fixture-scripts[fixture script] on the command line.
-
-If you are running the app from an IDE, then you can specify the fixture script using the `--fixture` flag. The archetype provides the `domainapp.fixture.scenarios.RecreateSimpleObjects` fixture script, for example:
-
-image::{_imagesdir}getting-started/simpleapp-webapp-with-fixtures.png[width="600px",link="{_imagesdir}getting-started/simpleapp-webapp-with-fixtures.png"]
-
-Alternatively, you can run with a different xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`] using the `--appManifest` (or `-m`) flag. The archetype provides
-`domainapp.app.DomainAppAppManifestWithFixtures` which specifies the aforementioned `RecreateSimpleObjects` fixture.
-
-
-
-== Using the App
-
-[NOTE]
-====
-These screenshots are for v1.10.0.
-====
-
+=== Using Docker
-When you start the app, you'll be presented with a welcome page from which you can access the webapp using either the xref:../ugvw/ugvw.adoc#[Wicket viewer] or the xref:../ugvro/ugvro.adoc#[Restful Objects viewer]:
+It's also possible to package up the application as a docker image to run as a container.
-image::{_imagesdir}getting-started/using-simple-app/010-root-page.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/010-root-page.png"]
-
-
-The Wicket viewer provides a human usable web UI (implemented, as you might have guessed from its name, using link:http://wicket.apache.org[Apache Wicket]), so choose that and navigate to the login page:
-
-image::{_imagesdir}getting-started/using-simple-app/020-login-to-wicket-viewer.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/020-login-to-wicket-viewer.png"]
-
-The app itself is configured to run using xref:../ugsec/ugsec.adoc#[shiro security], as configured in the `WEB-INF/shiro.ini` config file. You can login with:
-
-* username: _sven_
-* password: _pass_
-
-The application is configured to run with an in-memory database, and (unless you started the app with fixture scripts as described above), initially there is no data. We can though run a fixture script from the app itself:
-
-image::{_imagesdir}getting-started/using-simple-app/030-home-page-run-fixture-scripts.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/030-home-page-run-fixture-scripts.png"]
-
-The fixture script creates three objects, and the action returns the first of these:
+* To package up the application as a docker image (specifying the docker image name as a system property): +
++
+[source,bash]
+----
+mvn install -Dmavenmixin-docker -Ddocker-plugin.imageName=mycompany/myapp
+----
++
+Alternatively, define the `${docker-plugin.imageName}` in the `webapp` module and use simply: +
++
+[source,bash]
+----
+mvn install -Dmavenmixin-docker
+----
++
+The packaged image can be viewed using `docker images`.
-image::{_imagesdir}getting-started/using-simple-app/040-first-object.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/040-first-object.png"]
+* To run a docker image previously packaged: +
++
+[source,bash]
+----
+docker container run -d -p 8080:8080 mycompany/myapp
+----
++
+This can then be accessed at link:http://localhost:8080[localhost:8080].
++
+See link:https://github.com/danhaywood/java-mavenmixin-docker#how-to-consume[mavenmixin-docker] for further details on how to run docker images.
-The application generated is deliberaetly very minimal; we don't want you to have to waste valuable time removing generated files. The object contains a single "name" property, and a single action to update that property:
+* To upload the application as a docker image to link:https://hub.docker.com[docker hub] (or some other docker registry): +
++
+[source,bash]
+----
+mvn -pl webapp deploy -Dmavenmixin-docker
+----
++
+This assumes that the `${docker-plugin.imageName}` property has been defined, _and_ also that docker registry credentials have been specified in `~/.m2/settings.xml`.
+Once more, see link:https://github.com/danhaywood/java-mavenmixin-docker#how-to-configure[mavenmixin-docker] for further details.
-image::{_imagesdir}getting-started/using-simple-app/050-update-name-prompt.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/050-update-name-prompt.png"]
-When you hit OK, the object is updated:
-image::{_imagesdir}getting-started/using-simple-app/060-object-updated.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/060-object-updated.png"]
+=== From within the IDE
+Most of the time, though, you'll probably want to run the app from within your IDE.
+The mechanics of doing this will vary by IDE; see the xref:../dg/dg.adoc#_dg_ide[Developers' Guide] for details of setting up Eclipse or IntelliJ IDEA.
+Basically, though, it amounts to running `org.apache.isis.WebServer`, and ensuring that the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_datanucleus-enhancer[DataNucleus enhancer] has properly processed all domain entities.
-For your most signficant domain entities you'll likely have a domain service to retrieve or create instances of those obejcts. In the generated app we have a "Simple Objects" domain service that lets us list all objects:
+Here's what the setup looks like in IntelliJ IDEA:
-image::{_imagesdir}getting-started/using-simple-app/070-list-all-prompt.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/070-list-all-prompt.png"]
+image::{_imagesdir}getting-started/simpleapp-webapp.png[width="600px",link="{_imagesdir}getting-started/simpleapp-webapp.png"]
-whereby we see the three objects created by the fixture script (one having been updated):
+with the maven goal to run the DataNucleus enhancer (discussed in more detail xref:ugfun.adoc#_ugfun_getting-started_datanucleus-enhancer[here]) before launch defined as:
-image::{_imagesdir}getting-started/using-simple-app/080-list-all.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/080-list-all.png"]
+image::{_imagesdir}getting-started/simpleapp-webapp-before-launch.png[width="600px",link="{_imagesdir}getting-started/simpleapp-webapp-before-launch.png"]
-and we can also use the domain service to create new instances:
-image::{_imagesdir}getting-started/using-simple-app/090-create.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/090-create.png"]
-prompting us for the mandatory information (the name):
+[[_ugfun_getting-started_simpleapp-archetype_running-with-fixtures]]
+== Running with Fixtures
-image::{_imagesdir}getting-started/using-simple-app/100-create-prompt.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/100-create-prompt.png"]
+It is also possible to start the application with a pre-defined set of data; useful for demos or manual exploratory testing.
+This is done by specifying a xref:../ugtst/ugtst.adoc#_ugtst_fixture-scripts[fixture script] on the command line.
-which, of course, returns the newly created object:
+If you are running the app from an IDE, then you can specify the fixture script using the `--fixture` flag. The archetype provides the `domainapp.fixture.scenarios.RecreateSimpleObjects` fixture script, for example:
-image::{_imagesdir}getting-started/using-simple-app/110-object-created.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/110-object-created.png"]
+image::{_imagesdir}getting-started/simpleapp-webapp-with-fixtures.png[width="600px",link="{_imagesdir}getting-started/simpleapp-webapp-with-fixtures.png"]
-When we list all objects again, we can see that the object was indeed created:
+Alternatively, you can run with a different xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`] using the `--appManifest` (or `-m`) flag.
+The archetype provides
+`domainapp.app.DomainAppAppManifestWithFixtures` which specifies the aforementioned `RecreateSimpleObjects` fixture.
-image::{_imagesdir}getting-started/using-simple-app/120-list-all.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/120-list-all.png"]
-Going back to the home page (link:http://localhost:8080[localhost:8080]) we can also access the Restful Objects viewer. The generated application is configured to use HTTP Basic Auth:
-image::{_imagesdir}getting-started/using-simple-app/220-login-to-restful-viewer.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/220-login-to-restful-viewer.png"]
+== Using the App
-The Restful Objects viewer provides a REST API for computer-to-computer interaction, but we can still interact with it from a browser:
+The generated application is almost identical similar to that generated by xref:ugfun.adoc#_ugfun_getting-started_helloworld-archetype[helloworld archetype]; a description of how to use it can be found xref:ugfun.adoc#_ugfun_getting-started_helloworld-archetype_using-the-app[here].
-image::{_imagesdir}getting-started/using-simple-app/230-home-page.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/230-home-page.png"]
+One additional feature that the simpleapp contains over the helloworld app is a home page.
+This shows all domain objects (as installed by fixture scripts, described xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype_running-with-fixtures[above]).
-[TIP]
-====
-Depending on your browser, you may need to install plugins. For Chrome, we recommend json-view (which renders the JSON indented and automatically detects hyperlinks) and REST Postman.
-====
+image::{_imagesdir}getting-started/using-simple-app/030-home-page.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/030-home-page.png"]
-The REST API is a complete hypermedia API, in other words you can follow the links to access all the behaviour exposed in the regular Wicket app. For example, we can navigate to the `listAll/invoke` resource:
+It's also possible to run fixture scripts from the app itself:
-image::{_imagesdir}getting-started/using-simple-app/240-list-all-invoke.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/240-list-all-invoke.png"]
+image::{_imagesdir}getting-started/using-simple-app/040-run-fixture-script-menu.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/040-run-fixture-script-menu.png"]
-which when invoked (with an HTTP GET) will return a representation of the domain objects.
+Some fixture scripts may allow their default behaviour to be tweaked ((eg specify how many objects to create):
-image::{_imagesdir}getting-started/using-simple-app/250-list-all-results.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/250-list-all-results.png"]
+image::{_imagesdir}getting-started/using-simple-app/050-run-fixture-script-prompt.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/050-run-fixture-script-prompt.png"]
+The table summarises the resultant fixtures that were run:
-To log in, use `sven/pass`.
+image::{_imagesdir}getting-started/using-simple-app/060-run-fixture-script-result.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/060-run-fixture-script-result.png"]
+Navigating back to the home page shows the newly created objects:
+image::{_imagesdir}getting-started/using-simple-app/070-home-page.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/070-home-page.png"]
== Modifying the App
-Once you are familiar with the generated app, you'll want to start modifying it. There is plenty of guidance on this site; check out the 'programming model how-tos' section on the main xref:../../documentation.adoc#[documentation] page first).
+Once you are familiar with the generated app, you'll want to start modifying it.
+There is plenty of guidance on this site; start with this guide (fundamentals) and then look at the other guides available the main xref:../../documentation.adoc#[documentation] page.
If you use IntelliJ IDEA or Eclipse, do also install the xref:../dg/dg.adoc#__dg_ide_intellij_live-templates[live templates (for IntelliJ)] / xref:../dg/dg.adoc#__dg_ide_eclipse_editor-templates[editor templates (for Eclipse)]; these will help you follow the Apache Isis naming conventions.
-
-
== App Structure
-As noted above, the generated app is a very simple application consisting of a single domain object that can be easily renamed and extended. The intention is not to showcase all of Apache Isis' capabilities; rather it is to allow you to very easily modify the generated application (eg rename `SimpleObject` to `Customer`) without having to waste time deleting lots of generated code.
+As noted above, the generated app is a very simple application consisting of a single domain object that can be easily renamed and extended.
+The intention is not to showcase all of Apache Isis' capabilities; rather it is to allow you to very easily modify the generated application (eg rename `SimpleObject` to `Customer`) without having to waste time deleting lots of generated code.
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_properties.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_properties.adoc
index 692335b..712dc92 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_properties.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_properties.adoc
@@ -27,7 +27,7 @@ It's also possible (using annotations) to define a link table to hold foreign ke
Apache Isis recognises some of these annotations for JDO/DataNucleus and JAXB and infers some domain semantics from them (for example, the maximum allowable length of a string property).
Since writing getter and setter methods adds quite a bit of boilerplate, it's common to use link:https://projectlombok.org/[Project Lombok] to code generate these methods at compile time (using Java's annotation processor) simply by adding the `@lombok.Getter` and `@lombok.Setter` annotations to the field.
-The xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] uses this approach.
+The xref:ugfun.adoc#_ugfun_getting-started_helloworld-archetype[HelloWorld] and xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp] archetypes use this approach.
[[__ugfun_programming-model_properties_value-vs-reference-types]]
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/helloworld-before-launch.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/helloworld-before-launch.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/helloworld-before-launch.png
new file mode 100644
index 0000000..9e09d8f
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/helloworld-before-launch.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/helloworld.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/helloworld.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/helloworld.png
new file mode 100644
index 0000000..3f70ba1
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/helloworld.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/simpleapp-webapp-before-launch.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/simpleapp-webapp-before-launch.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/simpleapp-webapp-before-launch.png
new file mode 100644
index 0000000..de1ca7e
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/simpleapp-webapp-before-launch.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/simpleapp-webapp-with-fixtures.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/simpleapp-webapp-with-fixtures.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/simpleapp-webapp-with-fixtures.png
index 1dd885a..292698f 100644
Binary files a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/simpleapp-webapp-with-fixtures.png and b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/simpleapp-webapp-with-fixtures.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/simpleapp-webapp.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/simpleapp-webapp.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/simpleapp-webapp.png
index 771451b..482531b 100644
Binary files a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/simpleapp-webapp.png and b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/simpleapp-webapp.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/010-root-page.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/010-root-page.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/010-root-page.png
new file mode 100644
index 0000000..b5a91d7
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/010-root-page.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/020-login-to-wicket-viewer.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/020-login-to-wicket-viewer.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/020-login-to-wicket-viewer.png
new file mode 100644
index 0000000..f98dc5f
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/020-login-to-wicket-viewer.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/030-home-page.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/030-home-page.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/030-home-page.png
new file mode 100644
index 0000000..47b18fe
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/030-home-page.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/040-create-object-from-menu.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/040-create-object-from-menu.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/040-create-object-from-menu.png
new file mode 100644
index 0000000..c2d0dcf
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/040-create-object-from-menu.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/050-create-object-from-menu-prompt.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/050-create-object-from-menu-prompt.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/050-create-object-from-menu-prompt.png
new file mode 100644
index 0000000..f225db6
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/050-create-object-from-menu-prompt.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/060-created-object.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/060-created-object.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/060-created-object.png
new file mode 100644
index 0000000..b407187
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/060-created-object.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/070-update-name.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/070-update-name.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/070-update-name.png
new file mode 100644
index 0000000..e72cfa8
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/070-update-name.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/080-edit-notes.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/080-edit-notes.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/080-edit-notes.png
new file mode 100644
index 0000000..35a9813
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/080-edit-notes.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/090-delete-object.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/090-delete-object.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/090-delete-object.png
new file mode 100644
index 0000000..2156258
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/090-delete-object.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/100-object-deleted.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/100-object-deleted.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/100-object-deleted.png
new file mode 100644
index 0000000..46aa8e3
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/100-object-deleted.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/200-swagger-ui-before-reload.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/200-swagger-ui-before-reload.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/200-swagger-ui-before-reload.png
new file mode 100644
index 0000000..00fbac8
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/200-swagger-ui-before-reload.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/210-helloworld-resources.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/210-helloworld-resources.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/210-helloworld-resources.png
new file mode 100644
index 0000000..41c826e
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/210-helloworld-resources.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/220-create-object-thru-rest-api.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/220-create-object-thru-rest-api.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/220-create-object-thru-rest-api.png
new file mode 100644
index 0000000..f6dbc45
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/220-create-object-thru-rest-api.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/230-create-object-thru-rest-api-response.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/230-create-object-thru-rest-api-response.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/230-create-object-thru-rest-api-response.png
new file mode 100644
index 0000000..cf5fa41f
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/230-create-object-thru-rest-api-response.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/240-retrieve-object-using-rest-api.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/240-retrieve-object-using-rest-api.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/240-retrieve-object-using-rest-api.png
new file mode 100644
index 0000000..dab4cf0
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/240-retrieve-object-using-rest-api.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/250-retrieve-object-using-rest-api-response.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/250-retrieve-object-using-rest-api-response.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/250-retrieve-object-using-rest-api-response.png
new file mode 100644
index 0000000..825629c
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-hello-world/250-retrieve-object-using-rest-api-response.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/010-root-page.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/010-root-page.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/010-root-page.png
deleted file mode 100644
index 74e5ff9..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/010-root-page.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/020-login-to-wicket-viewer.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/020-login-to-wicket-viewer.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/020-login-to-wicket-viewer.png
deleted file mode 100644
index fc0d919..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/020-login-to-wicket-viewer.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/030-home-page-run-fixture-scripts.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/030-home-page-run-fixture-scripts.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/030-home-page-run-fixture-scripts.png
deleted file mode 100644
index 3a1bb54..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/030-home-page-run-fixture-scripts.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/030-home-page.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/030-home-page.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/030-home-page.png
new file mode 100644
index 0000000..db90e27
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/030-home-page.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/040-first-object.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/040-first-object.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/040-first-object.png
deleted file mode 100644
index bc999ee..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/040-first-object.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/040-run-fixture-script-menu.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/040-run-fixture-script-menu.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/040-run-fixture-script-menu.png
new file mode 100644
index 0000000..3d55dab
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/040-run-fixture-script-menu.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/050-run-fixture-script-prompt.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/050-run-fixture-script-prompt.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/050-run-fixture-script-prompt.png
new file mode 100644
index 0000000..fb8e703
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/050-run-fixture-script-prompt.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/050-update-name-prompt.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/050-update-name-prompt.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/050-update-name-prompt.png
deleted file mode 100644
index 166e533..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/050-update-name-prompt.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/060-object-updated.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/060-object-updated.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/060-object-updated.png
deleted file mode 100644
index d34888a..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/060-object-updated.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/060-run-fixture-script-result.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/060-run-fixture-script-result.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/060-run-fixture-script-result.png
new file mode 100644
index 0000000..b79034f
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/060-run-fixture-script-result.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/070-home-page.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/070-home-page.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/070-home-page.png
new file mode 100644
index 0000000..047b5a0
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/070-home-page.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/070-list-all-prompt.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/070-list-all-prompt.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/070-list-all-prompt.png
deleted file mode 100644
index 59cc275..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/070-list-all-prompt.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/080-list-all.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/080-list-all.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/080-list-all.png
deleted file mode 100644
index e3e67cf..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/080-list-all.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/090-create.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/090-create.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/090-create.png
deleted file mode 100644
index f5708ec..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/090-create.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/100-create-prompt.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/100-create-prompt.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/100-create-prompt.png
deleted file mode 100644
index 9829512..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/100-create-prompt.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/110-object-created.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/110-object-created.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/110-object-created.png
deleted file mode 100644
index 31696f3..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/110-object-created.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/120-list-all.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/120-list-all.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/120-list-all.png
deleted file mode 100644
index 75a4e04..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/120-list-all.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/220-login-to-restful-viewer.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/220-login-to-restful-viewer.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/220-login-to-restful-viewer.png
deleted file mode 100644
index 1b364b5..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/220-login-to-restful-viewer.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/230-home-page.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/230-home-page.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/230-home-page.png
deleted file mode 100644
index d032e68..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/230-home-page.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/240-list-all-invoke.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/240-list-all-invoke.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/240-list-all-invoke.png
deleted file mode 100644
index 57971ef..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/240-list-all-invoke.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/250-list-all-results.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/250-list-all-results.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/250-list-all-results.png
deleted file mode 100644
index b8c8b8b..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/250-list-all-results.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_disabling-persistence-by-reachability.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_disabling-persistence-by-reachability.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_disabling-persistence-by-reachability.adoc
index 4cb1f58..05dfa3f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_disabling-persistence-by-reachability.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_disabling-persistence-by-reachability.adoc
@@ -4,17 +4,22 @@
:_basedir: ../../
:_imagesdir: images/
-By default, JDO/DataNucleus supports the concept of link:http://www.datanucleus.org/products/datanucleus/jdo/persistence.html#persistence_by_reachability[persistence-by-reachability]. That is, if
-a non-persistent entity is associated with an already-persistent entity, then DataNucleus will detect this and will automatically persist the associated object. Put another way: there is no need to call Apache Isis' `DomainObjectContainer#persist(.)` or `DomainObjectContainer#persistIfNotAlready(.)` methods.
+
+By default, JDO/DataNucleus supports the concept of link:http://www.datanucleus.org/products/datanucleus/jdo/persistence.html#persistence_by_reachability[persistence-by-reachability].
+That is, if a non-persistent entity is associated with an already-persistent entity, then DataNucleus will detect this and will automatically persist the associated object.
+Put another way: there is no need to call Apache Isis' `RepositoryService#persist(.)` or `RepositoryService#persistAndFlush(.)` methods.
However, convenient though this feature is, you may find that it causes performance issues.
[WARNING]
====
-DataNucleus' persistence-by-reachability may cause performance issues. We strongly recommend that you disable it.
+DataNucleus' persistence-by-reachability may cause performance issues.
+We strongly recommend that you disable it.
====
-One scenario in particular where this performance issues can arise is if your entities implement the `java.lang.Comparable` interface, and you have used Apache Isis' xref:../rgcms/rgcms.adoc#_rgcms_classes_utility_ObjectContracts[`ObjectContracts`] utility class. The issue here is that `ObjectContracts` implementation can cause DataNucleus to recursively rehydrate a larger number of associated entities. (More detail below).
+One scenario in particular where this performance issues can arise is if your entities implement the `java.lang.Comparable` interface, and you have used Apache Isis' xref:../rgcms/rgcms.adoc#_rgcms_classes_utility_ObjectContracts[`ObjectContracts`] utility class.
+The issue here is that `ObjectContracts` implementation can cause DataNucleus to recursively rehydrate a larger number of associated entities.
+(More detail below).
We therefore recommend that you disable persistence-by-reachability by adding the following to `persistor_datanucleus.properties`:
@@ -23,11 +28,9 @@ We therefore recommend that you disable persistence-by-reachability by adding th
isis.persistor.datanucleus.impl.datanucleus.persistenceByReachabilityAtCommit=false
----
-This change has been made to the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]
-
-If you do disable this feature, then you will (of course) need to ensure that you explicitly persist all entities using the `DomainObjectContainer#persist(.)` or `DomainObjectContainer#persistIfNotAlready(.)` methods.
-
+This change has been made to both the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_helloworld-archetype[HelloWorld] and xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp] archetypes.
+If you do disable this feature, then you will (of course) need to ensure that you explicitly persist all entities using the `RepositoryService#persist(.)` or `RepositoryService#persistAndFlush(.)` methods.
@@ -79,10 +82,12 @@ public class Party {
DataNucleus's persistence-by-reachability algorithm adds the `AgreementRole` instances into a `SortedSet`, which causes `AgreementRole#compareTo()` to fire:
-* the evaluation of the "agreement" property delegates back to the `Agreement`, whose own `Agreement#compareTo()` uses the scalar `reference` property. As the `Agreement` is already in-memory, this does not trigger any further database queries
+* the evaluation of the "agreement" property delegates back to the `Agreement`, whose own `Agreement#compareTo()` uses the scalar `reference` property.
+As the `Agreement` is already in-memory, this does not trigger any further database queries
* the evaluation of the "startDate" property is just a scalar property of the `AgreementRole`, so will already in-memory
-* the evaluation of the "party" property delegates back to the `Party`, whose own `Party#compareTo()` requires the uses the scalar `reference` property. However, since the `Party` is not yet in-memory, using the `reference` property triggers a database query to "rehydrate" the `Party` instance.
+* the evaluation of the "party" property delegates back to the `Party`, whose own `Party#compareTo()` requires the uses the scalar `reference` property.
+However, since the `Party` is not yet in-memory, using the `reference` property triggers a database query to "rehydrate" the `Party` instance.
In other words, in figuring out whether `AgreementRole` requires the persistence-by-reachability algorithm to run, it causes the adjacent associated entity `Party` to also be retrieved.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_configuring-isis-to-use-shiro.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_configuring-isis-to-use-shiro.adoc b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_configuring-isis-to-use-shiro.adoc
index ebaae1d..a3dfef3 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_configuring-isis-to-use-shiro.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_configuring-isis-to-use-shiro.adoc
@@ -5,13 +5,15 @@
:_imagesdir: images/
-Apache Isis' security mechanism is configurable, specifying an `Authenticator` and an `Authorizor` (non-public) APIs. The Shiro security mechanism is an integration wih Apache Shiro that implements both interfaces.
+Apache Isis' security mechanism is configurable, specifying an `Authenticator` and an `Authorizor` (non-public) APIs.
+The Shiro security mechanism is an integration wih Apache Shiro that implements both interfaces.
[TIP]
====
-The xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] is pre-configured to use Apache Shiro, so much of what follows is set up already.
+Both the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_helloworld-archetype[HelloWorld] and xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp] archetypes are pre-configured to use Apache Shiro, so much of what follows may well have been set up already.
====
+
== Telling Apache Isis to use Shiro
To tell Apache Isis to use Shiro, update the `WEB-INF/isis.properties` file:
@@ -26,26 +28,26 @@ This installs the appropriate implementation (the `ShiroAuthenticatorOrAuthorizo
image::{_imagesdir}security/security-apis-impl/configure-isis-to-use-shiro.png[width="600px"]
-The figure above doesn't tell the whole story; we haven't yet seen how Shiro itself is configured to use realms. The `ShiroAuthenticatorOrAuthorizor` is in essence the glue between the Apache Isis runtime and Shiro.
+The figure above doesn't tell the whole story; we haven't yet seen how Shiro itself is configured to use realms.
+The `ShiroAuthenticatorOrAuthorizor` is in essence the glue between the Apache Isis runtime and Shiro.
+
== Configuring Shiro Authenticator
-The `ShiroAuthenticatorOrAuthorizor` class itself supports a single optional property. This can
-be configured in `authentication_shiro.properties` file:
+The `ShiroAuthenticatorOrAuthorizor` class itself supports a single optional property.
+This can be configured in `authentication_shiro.properties` file:
[source,ini]
----
isis.authentication.shiro.autoLogoutIfAlreadyAuthenticated=false
----
-This configuration property only comes into effect for the xref:../ugvro/ugvro.adoc#[Restful Objects viewer]; if set then
-the Shiro subject - if found to be still authenticated - will be logged out anyway and then re-authenticated.
+This configuration property only comes into effect for the xref:../ugvro/ugvro.adoc#[Restful Objects viewer]; if set then the Shiro subject - if found to be still authenticated - will be logged out anyway and then re-authenticated.
[WARNING]
====
-This auto-logout behaviour was the default prior to `1.13.0`, but is believed to be the root cause of some
-exceptions caused by a possible race condition. There should generally be no need to change this property from its
-default (`false`).
+This auto-logout behaviour was the default prior to `1.13.0`, but is believed to be the root cause of some exceptions caused by a possible race condition.
+There should generally be no need to change this property from its default (`false`).
====
@@ -82,7 +84,8 @@ The `shiro.ini` file is used to specify the realm(s) that Shiro will delegate to
securityManager.realms = $realmName
----
-Shiro's ini file supports a "poor-man's" dependency injection (link:https://shiro.apache.org/configuration.html[their words]), and so `$realmName` in the above example is a reference to a realm defined elsewhere in `shiro.ini`. The subsequent sections describe the specifics for thevarious realm implementations available to you.
+Shiro's ini file supports a "poor-man's" dependency injection (link:https://shiro.apache.org/configuration.html[their words]), and so `$realmName` in the above example is a reference to a realm defined elsewhere in `shiro.ini`.
+The subsequent sections describe the specifics for thevarious realm implementations available to you.
It's also possible to configure Shiro to support multiple realms.
@@ -94,5 +97,3 @@ securityManager.realms = $realm1,$realm2
You can learn more about Shiro realms in the link:http://shiro.apache.org/realm.html[Shiro documentation].
-
-