You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2015/07/10 09:41:36 UTC
[07/10] isis git commit: ISIS-1133: pulling together the contributors
guide.
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_dg_intellij.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_dg_intellij.adoc b/adocs/documentation/src/main/asciidoc/guides/_dg_intellij.adoc
deleted file mode 100644
index 4e6b48d..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_dg_intellij.adoc
+++ /dev/null
@@ -1,396 +0,0 @@
-[[_dg_intellij]]
-= Setting up IntelliJ IDEA
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../../../
-:_imagesdir: images/
-:toc: right
-
-
-This appendix describes how to install and setup IntelliJ, then how to import an application into IntelliJ and run it.
-
-
-[NOTE]
-====
-This document relates to IntelliJ Community Edition 14.1.1, with screenshots taken for Windows.
-====
-
-== Installing and Setting up
-
-This section covers installation and setup.
-
-=== Download and Install
-
-https://www.jetbrains.com/idea/download/[Download] latest version of IntelliJ Community Edition, and install:
-
-Start the wizard, click through the welcome page:
-
-.IntelliJ Installation Wizard - Welcome page
-image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/010-welcome-page.png[width="400px"]
-
-Choose the location to install the IDE:
-
-.IntelliJ Installation Wizard - Choose Location
-image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/020-choose-location.png[width="400px"]
-
-Adjust any installation options as you prefer:
-
-.IntelliJ Installation Wizard - Installation Options
-image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/030-installation-options.png[width="400px"]
-
-and the start menu:
-
-.IntelliJ Installation Wizard - Start Menu Folder
-image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/040-start-menu-folder.png[width="400px"]
-
-and finish up the wizard:
-
-.IntelliJ Installation Wizard - Completing the Wizard
-image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/050-completing.png[width="400px"]
-
-Later on we'll specify the Apache Isis/ASF code style settings, so for now select `I do not want to import settings`:
-
-.IntelliJ Installation Wizard - Import Settings
-image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/060-import-settings-or-not.png[width="400px"]
-
-Finally, if you are young and trendy, set the UI theme to Darcula:
-
-.IntelliJ Installation Wizard Set UI Theme
-image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/070-set-ui-theme.png[width="600px"]
-
-
-
-
-=== New Project
-
-In IntelliJ a project can contain multiple modules; these need not be physically located together. (If you are previously an Eclipse user, you can think of it as similar to an Eclipse workspace).
-
-Start off by creating a new project:
-
-.IntelliJ Create New Project
-image::{_imagesdir}appendices/dev-env/intellij-idea/020-create-new-project/010-new-project-create.png[width="400px"]
-
-We want to create a new *Java* project:
-
-.IntelliJ Create New Project - Create a Java project
-image::{_imagesdir}appendices/dev-env/intellij-idea/020-create-new-project/020-java-project-setup-jdk.png[width="600px"]
-
-We therefore need to specify the JDK.
-
-NOTE: at the time of writing Apache Isis supports only Java 7; Java 8 is scheduled for support in Apache Isis v1.9.0
-
-
-.IntelliJ Create New Java Project - Select the JDK
-image::{_imagesdir}appendices/dev-env/intellij-idea/020-create-new-project/030-java-project-select-jdk.png[width="300px"]
-
-Specify the directory containing the JDK:
-
-.IntelliJ Create New Project - Select the JDK location
-image::{_imagesdir}appendices/dev-env/intellij-idea/020-create-new-project/050-name-and-location.png[width="400px"]
-
-Finally allow IntelliJ to create the directory for the new project:
-
-.IntelliJ Create New Project
-image::{_imagesdir}appendices/dev-env/intellij-idea/020-create-new-project/060-create-dir.png[width="200px"]
-
-
-
-=== Import Settings
-
-Next we need to configure IntelliJ with ASF/Apache Isis' standard templates and coding conventions. These are bundled as the `settings.jar` JAR file link:resources/appendices/dev-env/intellij/isis-settings.jar[download from the Apache Isis website]).
-
-Import using: `File > Import Settings`, and specify the directory that you have downloaded the file to:
-
-.IntelliJ Import Settings - Specify JAR file
-image::{_imagesdir}appendices/dev-env/intellij-idea/030-import-settings/010-settings-import-jar.png[width="400px"]
-
-Select all the (two) categories of settings available in the JAR file:
-
-.IntelliJ Import Settings - Select all categories
-image::{_imagesdir}appendices/dev-env/intellij-idea/030-import-settings/020-select-all.png[width="300px"]
-
-And then restart:
-
-.IntelliJ Import Settings - Restart
-image::{_imagesdir}appendices/dev-env/intellij-idea/030-import-settings/030-restart.png[width="200px"]
-
-
-
-=== Other Settings
-
-There are also some other miscellaneous settings that we recommend that you adjust (though these are not critical).
-
-First, specify an up-to-date Maven installation, using `File > Settings` (or `IntelliJ > Preferences` if on MacOS):
-
-.IntelliJ Other Settings - Maven Installation
-image::{_imagesdir}appendices/dev-env/intellij-idea/040-other-settings/010-maven-installation.png[width="600px"]
-
-Still on the Maven settings page, configure as follows:
-
-.IntelliJ Other Settings - Maven Configuration
-image::{_imagesdir}appendices/dev-env/intellij-idea/040-other-settings/020-maven-configuration.png[width="600px"]
-
-On the compiler settings page, ensure that `build automatically` is enabled (and optionally `compile independent modules in parallel`):
-
-.IntelliJ Other Settings - Compiler Settings
-image::{_imagesdir}appendices/dev-env/intellij-idea/040-other-settings/030-build-automatically.png[width="600px"]
-
-On the auto import page, check the `optimize imports on the fly` and `add unambiguous imports on the fly`
-
-.IntelliJ Other Settings - Auto Import
-image::{_imagesdir}appendices/dev-env/intellij-idea/040-other-settings/040-auto-import.png[width="600px"]
-
-
-
-=== Plugins
-
-You might also want to set up some additional plugins, using `File > Settings > Plugins` (or equivalently `File > Other Settings > Configure Plugins`).
-
-Recommended are:
-
-* link:https://plugins.jetbrains.com/plugin/7179?pr=idea[Maven Helper] plugin
-+
-More on this below.
-
-* link:https://github.com/asciidoctor/asciidoctor-intellij-plugin[AsciiDoctor] plugin
-+
-Useful if you are doing any authoring of documents.
-
-Some others you might like to explore are:
-
-.IntelliJ Plugins
-image::{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/020-some-plugins-confirmation.png[width="600px"]
-
-==== Maven Helper Plugin
-
-This plugin provides a couple of great features. One is better visualization of dependency trees (similar to Eclipse).
-
-If you open a `pom.xml` file, you'll see an additional "Dependencies" tab:
-
-image::{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/010-dependency-tab.png[width="600px",link="{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/010-dependency-tab.png"]
-
-Clicking on this gives a graphical tree representation of the dependencies, similar to that obtained by `mvn dependency:tree`, but filterable.
-
-image::{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/020-dependency-as-tree.png[width="600px",link="{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/020-dependency-as-tree.png"]
-
-The plugin also provides the ability to easily run a Maven goal on a project:
-
-image::{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/030-maven-run-goal.png[width="600px",link="{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/030-maven-run-goal.png"]
-
-This menu can also be bound to a keystroke so that it is available as a pop-up:
-
-image::{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/040-maven-quick-run.png[width="600px",link="{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/040-maven-quick-run.png"]
-
-
-
-== Importing and Managing Maven Modules
-
-Let's load in some actual code! We do this by importing the Maven modules.
-
-First up, open up the Maven tool window (`View > Tool Windows > Maven Projects`). You can then use the 'plus' button to add Maven modules. In the screenshot you can see we've loaded in Apache Isis core; the modules are listed in the _Maven Projects_ window and corresponding (IntelliJ) modules are shown in the _Projects_ window:
-
-.IntelliJ Maven Module Management - Importing Maven modules
-image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/010-maven-modules-view.png[width="730px"]
-
-We can then import another module (from some other directory). For example, here we are importing the Isis Addons' todoapp example:
-
-
-.IntelliJ Maven Module Management - Importing another Module
-image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/020-adding-another-module.png[width="400px"]
-
-You should then see the new Maven module loaded in the _Projects_ window and also the _Maven Projects_ window:
-
-.IntelliJ Maven Module Management -
-image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/030-other-module-added.png[width="730px"]
-
-If any dependencies are already loaded in the project, then IntelliJ will automatically update the CLASSPATH to resolve to locally held modules (rather from `.m2/repository` folder). So, for example (assuming that the `<version>` is correct, of course), the Isis todoapp will have local dependencies on the Apache Isis core.
-
-You can press F4 (or use `File > Project Structure`) to see the resolved classpath for any of the modules loaded into the project.
-
-If you want to focus on one set of code (eg the Isis todoapp but not Apache Isis core) then you _could_ remove the module; but better is to ignore those modules. This will remove from the the _Projects_ window but keep them available in the _Maven Projects_ window for when you next want to work on them:
-
-.IntelliJ Maven Module Management - Ignoring Modules
-image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/040-ignoring-modules.png[width="730px"]
-
-Confirm that it's ok to ignore these modules:
-
-.IntelliJ Maven Module Management - Ignoring Modules (ctd)
-image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/050-ignoring-modules-2.png[width="300px"]
-
-All being well you should see that the _Projects_ window now only contains the code you are working on. Its classpath dependencies will be adjusted (eg to resolve to Apache Isis core from `.m2/repository`):
-
-.IntelliJ Maven Module Management - Updated Projects Window
-image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/060-ignored-modules.png[width="730px"]
-
-
-
-== Running
-
-Let's see how to run both the app and the tests.
-
-=== Running the App
-
-Once you've imported your Isis application, we should run it. We do this by creating a Run configuration, using `Run > Edit Configurations`.
-
-Set up the details as follows:
-
-.IntelliJ Running the App - Run Configuration
-image::{_imagesdir}appendices/dev-env/intellij-idea/110-running-the-app/010-run-configuration.png[width="600px"]
-
-We specify the `Main class` to be `org.apache.isis.WebServer`; this is a wrapper around Jetty. It's possible to pass program arguments to this (eg to automatically install fixtures), but for now leave this blank.
-
-Also note that `Use classpath of module` is the webapp module for your app, and that the `working directory` is `$MODULE_DIR$`.
-
-Next, and most importantly, configure the DataNucleus enhancer to run for your `dom` goal. This can be done by defining a Maven goal to run before the app:
-
-.IntelliJ Running the App - Datanucleus Enhancer Goal
-image::{_imagesdir}appendices/dev-env/intellij-idea/110-running-the-app/020-datanucleus-enhancer-goal.png[width="400px"]
-
-The `-o` flag in the goal means run off-line; this will run faster.
-
-WARNING: if you forget to set up the enhancer goal, or don't run it on the correct (dom) module, then you will get all sorts of errors when you startup. These usually manifest themselves as class cast exception in DataNucleus.
-
-You should now be able to run the app using `Run > Run Configuration`. The same configuration can also be used to debug the app if you so need.
-
-
-=== Running the Unit Tests
-
-The easiest way to run the unit tests is just to right click on the `dom` module in the _Project Window_, and choose run unit tests. Hopefully your tests will pass (!).
-
-.IntelliJ Running the App - Unit Tests Run Configuration
-image::{_imagesdir}appendices/dev-env/intellij-idea/110-running-the-app/030-running-unit-tests.png[width="600px"]
-
-As a side-effect, this will create a run configuration, very similar to the one we manually created for the main app:
-
-.IntelliJ Running the App - Unit Tests Run Configuration
-image::{_imagesdir}appendices/dev-env/intellij-idea/110-running-the-app/040-running-unit-tests-run-configuration.png[width="600px"]
-
-Thereafter, you should run units by selecting this configuration (if you use the right click approach you'll end up with lots of run configurations, all similar).
-
-=== Running the Integration Tests
-
-Integration tests can be run in the same way as unit tests, however the `dom` module must also have been enhanced.
-
-One approach is to initially run the tests use the right click on the `integtests` module; the tests will fail because the code won't have been enhanced, but we can then go and update the run configuration to run the datanucleus enhancer goal (same as when running the application):
-
-.IntelliJ Running the App - Integration Tests Run Configuration
-image::{_imagesdir}appendices/dev-env/intellij-idea/110-running-the-app/050-running-integration-tests-run-configuration.png[width="600px"]
-
-
-
-
-== Hints and Tips
-
-=== Keyboard Shortcuts Cheat Sheets
-
-You can download 1-page PDFs cheat sheets for IntelliJ's keyboard shortcuts:
-* for link:https://www.jetbrains.com/idea/docs/IntelliJIDEA_ReferenceCard.pdf[Windows]
-* for MacOS:https://www.jetbrains.com/idea/docs/IntelliJIDEA_ReferenceCard_Mac.pdf[MacOS]
-
-Probably the most important shortcut on them is for `Find Action`:
-- `ctrl-shift-A` on Windows
-- `cmd-shift-A` on MacOS.
-
-This will let you search for any action just by typing its name.
-
-### Switching between Tool Windows and Editors
-
-The Tool Windows are the views around the editor (to left, bottom and right). It's possible to move these around to your preferred locations.
-
-* Use `alt-1` through `alt-9` (or `cmd-1` through `alt-9`) to select the tool windows
-** Press it twice and the tool window will hide itself; so can use to toggle
-* If in the _Project Window_ (say) and hit enter on a file, then it will be shown in the editor, but (conveniently) the focus remains in the tool window. To switch to the editor, just press `Esc`.
-** If in the _Terminal Window_, you'll need to press `Shift-Esc`.
-* If on the editor and want to locate the file in (say) the _Project Window_, use `alt-F1`.
-* To change the size of any tool window, use `ctrl-shift-arrow`
-
-Using these shortcuts you can easily toggle between the tool windows and the editor, without using the mouse. Peachy!
-
-=== Navigating Around
-
-For all of the following, you don't need to type every letter, typing "ab" will actually search for ".*a.*b.*".
-
-* to open classes or files or methods that you know the name of:
-** `ctrl-N` to open class
-** `ctrl-shift-N` to open a file
-** (bit fiddly this) `ctrl-shift-alt-N` to search for any symbol.
-* open up dialog of recent files: `ctrl-E`
-* search for any file: `shift-shift`
-
-Navigating around:
-* find callers of a method (the call hierarchy): `ctrl-alt-H`
-* find subclasses or overrides: `ctrl-alt-B`
-* find superclasses/interface/declaration: `ctrl-B`
-
-Viewing the structure (ie outline) of a class
-* `ctrl-F12` will pop-up a dialog showing all members
-** hit `ctrl-F12` again to also see inherited members
-
-
-=== Editing
-
-* Extend selection using `ctrl-W`
-** and contract it down again using `ctrl-shift-W`
-* to duplicate a line, it's `ctrl-D`
-** if you have some text selected (or even some lines), it'll actually duplicate the entire selection
-* to delete a line, it's `ctrl-X`
-* to move a line up or down: `shift-alt-up` and `shift-alt-down`
-** if you have selected several lines, it'll move them all togethe
-* `ctrl-shift-J` can be handy for joining lines together
-** just hit enter to split them apart (even in string quotes; IntelliJ will "do the right thing")
-
-### Intentions and Code Completion
-
-Massively useful is the "Intentions" popup; IntelliJ tries to guess what you might want to do. You can activate this using`alt-enter`, whenever you see a lightbulb/tooltip in the margin of the current line.
-
-Code completion usually happens whenever you type '.'. You can also use `ctrl-space` to bring these up.
-
-In certain circumstances (eg in methods0) you can also type `ctrl-shift-space` to get a smart list of methods etc that you might want to call. Can be useful.
-
-Last, when invoking a method, use `ctrl-P` to see the parameter types.
-
-
-=== Refactoring
-
-Loads of good stuff on the `Refactor` menu; most used are:
-
-* Rename (`shift-F6`)
-* Extract
-** method: `ctrl-alt-M`
-** variable: `ctrl-alt-V`
-* Inline method/variable: `ctrl-alt-N`
-* Change signature
-
-If you can't remember all those shortcuts, just use `ctrl-shift-alt-T` (might want to rebind that to something else!) and get a context-sensitive list of refactorings available for the currently selected object
-
-
-=== Troubleshooting
-
-When a Maven module is imported, IntelliJ generates its own project files (suffix `.ipr`), and the application is actually built from that.
-
-Occasionally these don't keep in sync (even if auto-import of Maven modules has been enabled).
-
-To fix the issue, try:
-* reimport module
-* rebuild selected modules/entire project
-* remove and then re-add the project
-* restart, invalidating caches
-* hit StackOverflow (!)
-
-One thing worth knowing; IntelliJ actively scans the filesystem all the time. It's therefore (almost always) fine to build the app from the Maven command line; IntelliJ will detect the changes and keep in sync. If you want to force that, use `File > Synchronize`, `ctrl-alt-Y`.
-
-
-
-
-== Advanced
-
-In this section are a couple of options that will reduce the length of the change code/build/deploy/review feedback loop.
-
-
-=== Setting up Dynamic Reloading
-
-NOTE: TODO - see link:http://blog.jetbrains.com/idea/2013/07/get-true-hot-swap-in-java-with-dcevm-and-intellij-idea/[IntelliJ blog].
-
-
-=== Setting up JRebel
-
-NOTE: TODO
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations.adoc
index 6801073..213df78 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations.adoc
@@ -1,4 +1,4 @@
-[[_rg-annotations]]
+[[_rg_annotations]]
= Annotations
: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: ../
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ViewModel.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ViewModel.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ViewModel.adoc
index a06df8a..4637983 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ViewModel.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ViewModel.adoc
@@ -33,7 +33,7 @@ Note that there is a `DomainObjectContainer#newViewModelInstance(.)`; this is fo
====
-The view model's memento will be derived from the value of the view model object's properties. Any xref:rg.adoc#_rg_annotations_manpage-Property_notPersisted[`@Property#notPersisted()`] properties will be excluded from the memento, as will any http://isis.apache.org/reference/recognized-annotations/Programmatic.html[@Programmatic] properties. Properties that are merely http://isis.apache.org/reference/recognized-annotations/Hidden-deprecated.html[@Hidden] are included in the memento.
+The view model's memento will be derived from the value of the view model object's properties. Any xref:rg.adoc#_rg_annotations_manpage-Property_notPersisted[`@Property#notPersisted()`] properties will be excluded from the memento, as will any xref:rg.adoc#_rg_annotations_manpage-Programmatic[`@Programmatic`] properties. Properties that are merely xref:rg.adoc#_rg_annotations_manpage-Property_hidden[hidden] _are_ included in the memento.
Only properties supported by the configured xref:rg.adoc#_rg_services-api_manpage-MementoService[`MementoService`] can be used. The default implementation supports all the value types and persisted entities.
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_utility_manpage-ObjectContracts.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_utility_manpage-ObjectContracts.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_utility_manpage-ObjectContracts.adoc
index 241af3c..618fc8d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_utility_manpage-ObjectContracts.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_utility_manpage-ObjectContracts.adoc
@@ -51,9 +51,9 @@ isis.persistor.datanucleus.impl.datanucleus.persistenceByReachabilityAtCommit=fa
== The issue in more detail
-Consider the entities:
+Consider the link:http://yuml.me/edit/742ad446[entities]:
- Party <->* AgreementRole <*-> Agreement
+image::{_imagesdir}reference-classes/issue-in-more-detail.png[link="{_imagesdir}reference-classes/issue-in-more-detail.png"]
In the course of a transaction, the `Agreement` entity is loaded into memory (not necessarily modified), and then new ``AgreementRole``s are associated to it.
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_jdo-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_jdo-api.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_jdo-api.adoc
index 010fb81..8db6b78 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_jdo-api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_jdo-api.adoc
@@ -19,10 +19,10 @@ For example:
[source,java]
----
-@RequestScoped // <1>
+@RequestScoped // <1>
@DomainService(nature=NatureOfService.DOMAIN)
public class ObjectChangedListenerService
- implements javax.jdo.listener.StoreLifecycleListener { // <1>
+ implements javax.jdo.listener.StoreLifecycleListener { // <2>
@Programmatic
@PostConstruct
public void init() {
@@ -34,7 +34,7 @@ public class ObjectChangedListenerService
getPmFactory().removeInstanceLifecycleListener(this);
}
private PersistenceManager getPersistenceManager() {
- return jdoSupport.getPersistenceManager(); // <3>
+ return jdoSupport.getPersistenceManager(); // <3>
}
@Programmatic
public void preStore (InstanceLifecycleEvent event) { ... }
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_rg_object-layout_application-menu.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_object-layout_application-menu.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_object-layout_application-menu.adoc
index 3843f46..0067cf1 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_object-layout_application-menu.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_object-layout_application-menu.adoc
@@ -87,7 +87,7 @@ public class Parties ... { ... }
Note that only the `menuOrder` of the _first_ domain service is significant in placing the menus along the menu bar;
thereafter the purpose of the `menuOrder` is to order the menu services sections on the menu itself.
-== Ordering of a service's actions within a menu
+== Ordering menu actions
For a given service, the actions within a section on a menu is determined by the `@MemberOrder` annotation. Thus, for
the `Units` domain service, its actions are annotated:
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_rg_object-layout_dynamic.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_object-layout_dynamic.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_object-layout_dynamic.adoc
index 8bc6c02..546caed 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_object-layout_dynamic.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_object-layout_dynamic.adoc
@@ -105,7 +105,7 @@ Note also that the layout file may contain entries for xref:ug.adoc#_ug_how-tos_
-== Downloading an initial layout file
+== Downloading an initial layout
The fastest way to get started is to use the (non-ASF) link:http://github.com/isisaddons/isis-module-devutils[Isis addons' devutils] module to download the layout file (derived from any existing static metadata defined by annotations).
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_runtime.adoc
index 255287c..651c695 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_runtime.adoc
@@ -1,5 +1,5 @@
[[_rg_runtime]]
-= Runtime Configuration
+= Configuration Properties
: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/
@@ -20,7 +20,6 @@ include::_rg_runtime_configuration-files.adoc[leveloffset=+1]
include::_rg_runtime_specifying-components.adoc[leveloffset=+1]
include::_rg_runtime_configuring-core.adoc[leveloffset=+1]
include::_rg_runtime_configuring-datanucleus.adoc[leveloffset=+1]
-include::_rg_runtime_web-xml.adoc[leveloffset=+1]
include::_rg_runtime_application-specific.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_deployment-types.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_deployment-types.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_deployment-types.adoc
index f3aeb76..a17a6e9 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_deployment-types.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_deployment-types.adoc
@@ -66,7 +66,7 @@ Wicket's mechanism for specifying the "configuration" is to use a context parame
Most Apache Isis applications will consist of at least the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] and optionally the xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer]. When both viewers are deployed in the same app, then the bootstrapping is performed by Wicket, and so the deployment type is configured as described in the previous section.
-In some cases though you may be using Apache Isis to provide a REST API only, that is, you won't have deployed the Wicket viewer. In these cases your app will be bootstrapped using Apache Isis' xref:rg.adoc#_rg_runtime_web-xml_servlet-context-listeners[ `IsisWebAppBootstrapper`].
+In some cases though you may be using Apache Isis to provide a REST API only, that is, you won't have deployed the Wicket viewer. In these cases your app will be bootstrapped using Apache Isis' xref:rg.adoc#_rg_web-xml_servlet-context-listeners[ `IsisWebAppBootstrapper`].
In this case the deployment type is specified through an Apache Isis-specific context parameter, called `isis.deploymentType`:
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_specifying-components.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_specifying-components.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_specifying-components.adoc
index 0c40fa4..59a14b2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_specifying-components.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_specifying-components.adoc
@@ -57,7 +57,7 @@ The values "datanucleus", "shiro" etc are actually aliases for concrete implemen
It is -- at least in theory -- possible to specify a fully qualified class name to replace any of these components. This is probably feasible for the two security APIs and the `services-installer` API; but replacing the persistor (JDO/DataNucleus) is much trickier because we rely on the JDO/DN for certain functionality (such as object dirtying and lazy loading) that is not defined within this API.
-As for the viewers, these are specified indirectly by way of the filters and servlets in the `web.xml` file (discussed xref:rg.adoc#_rg_runtime_web-xml[below]). However, the configuration of which viewers to initialize is declared through a context parameter:
+As for the viewers, these are specified indirectly by way of the filters and servlets in the xref:rg.adoc#_rg_web-xml[`web.xml`] file. However, the configuration of which viewers to initialize is declared through a context parameter:
[source,xml]
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_web-xml.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_web-xml.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_web-xml.adoc
deleted file mode 100644
index 4d7cee4..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_web-xml.adoc
+++ /dev/null
@@ -1,463 +0,0 @@
-[[_rg_runtime_web-xml]]
-= `web.xml`
-: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 provides two different viewers, the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] and the xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer]. You can deploy both of these concurrently, or deploy just the Wicket viewer, or deploy just the Restful Objects viewer. The configuration in `web.xml` varies accordingly, both in terms of the servlet context listeners, filters and servlets.
-
-If you are using Apache Isis' integration with Apache Shiro (for security) then this also needs configuring in `web.xml`. See the xref:ug.adoc#_ug_security_configuring-isis-to-use-shiro[security chapter] for full details on this topic.
-
-The servlets and filters are mapped to three main pipelines:
-
-* `/wicket` - the Wicket viewer UI
-* `/restful` - the Restful Objects resources (REST API)
-* other paths, also static resources (such as `.png`, `.css`)
-
-With the following key:
-
-image::{_imagesdir}runtime/web-xml/key.png[width="800px",link="{_imagesdir}runtime/web-xml/key.png"]
-
-the diagram below shows the components to be configured if deploying both the Wicket viewer and Restful Objects viewer:
-
-image::{_imagesdir}runtime/web-xml/wicket-and-ro.png[width="800px",link="{_imagesdir}runtime/web-xml/wicket-and-ro.png"]
-
-Here the Wicket viewer is responsible for the main bootstrapping of Apache Isis itself, in other words the shared (global) metadata; this is done by the `IsisWicketApplication` class (extending the `WicketApplication` Wicket API). This class is also responsible for Apache Isis' own session and transaction management.
-
-The Restful Objects viewer - being a JAX-RS application implemented using the RestEasy framework - requires the `RestEasyBootstrapper` servlet context listener. It is this context listener that also sets up the `RestfulObjectsApplication`, which is then delegated to by the RestEasy `HttpServletDispatcher`. This pipeline uses the `IsisSessionFilter` and `IsisTransactionFilterForRestfulObjects` to perform the session and transaction management before it hits the RestEasy servlet.
-
-If only the Wicket viewer is deployed, then the diagram is more or less the same: the RestEasy servlet, context listener and supporting filters are simply removed:
-
-image::{_imagesdir}runtime/web-xml/wicket-only.png[width="800px",link="{_imagesdir}runtime/web-xml/wicket-only.png"]
-
-Finally, if only the Restful Objects viewer is deployed, then things change a little more subtly. Here, the Wicket filter is no longer needed. In its place, though the `IsisWebAppBootstrapper` context listener is required: this is responsible for seting up the shared (global) metadata.
-
-image::{_imagesdir}runtime/web-xml/ro-only.png[width="800px",link="{_imagesdir}runtime/web-xml/ro-only.png"]
-
-The following sections detail these various listeners, filters and servlets in more detail.
-
-
-
-[[_rg_runtime_web-xml_servlet-context-listeners]]
-== Servlet Context Listeners
-
-Servlet context listeners are used to perform initialization on application startup. Both Shiro (if configured as the security mechanism) and RestEasy (for the Restful Objects viewer) require their own context listener. In addition, if the Wicket viewer is _not_ being used, then additional Apache Isis-specific listener is required for bootstrapping of the Apache Isis framework itself.
-
-
-=== `EnvironmentLoaderListener` (Shiro)
-
-NOTE: WIP
-
-definition:
-
-[source,xml]
-----
-<listener>
- <listener-class>org.apache.shiro.web.env.EnvironmentLoaderListener</listener-class>
-</listener>
-----
-
-
-
-=== `IsisWebAppBootstrapper`
-
-The `IsisWebAppBootstrapper` servlet context listener bootstraps the shared (global) metadata for the Apache Isis framework. This listener is not required (indeed must not be configured) if the Wicket viewer is in use.
-
-NOTE: WIP
-
-definition:
-
-[source,xml]
-----
-<listener>
- <listener-class>org.apache.isis.core.webapp.IsisWebAppBootstrapper</listener-class>
-</listener>
-----
-
-context parameters:
-
-[source,xml]
-----
-<context-param>
- <param-name>deploymentType</param-name>
- <param-value>SERVER_PROTOTYPE</param-value>
-</context-param>
-<context-param>
- <param-name>isis.viewers</param-name>
- <param-value>restfulobjects</param-value>
-</context-param>
-----
-
-
-=== `ResteasyBootstrap` (RestEasy)
-
-The `ResteasyBootstrap` servlet context listener initializes the RestEasy runtime, specifying that classes (namely, those specified in Isis' `RestfulObjectsApplication`) to be exposed as REST resources. It is required if the Restful Objects viewer is to be deployed.
-
-NOTE: WIP
-
-definition:
-
-[source,xml]
-----
-<listener>
- <listener-class>org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap</listener-class>
-</listener>
-----
-
-There are two relevant context parameters:
-
-[source,xml]
-----
-<context-param>
- <param-name>javax.ws.rs.Application</param-name> <!--1-->
- <param-value>org.apache.isis.viewer.restfulobjects.server.RestfulObjectsApplication</param-value>
-</context-param>
-<context-param>
- <param-name>resteasy.servlet.mapping.prefix</param-name>
- <param-value>/restful/</param-value> <!--2-->
-</context-param>
-----
-<1> used by RestEasy to determine the JAX-RS resources and other related configuration
-<2> should correspond to the filter mapping of the `HttpServletDispatcher` servlet
-
-
-
-[[_rg_runtime_web-xml_servlets]]
-== Servlets
-
-NOTE: WIP
-
-
-=== `HttpServletDispatcher` (RestEasy)
-
-NOTE: WIP
-
-
-definition:
-
-[source,xml]
-----
-<servlet>
- <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
- <servlet-class>org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher</servlet-class>
-</servlet>
-----
-
-mapping:
-
-[source,xml]
-----
-<servlet-mapping>
- <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
- <url-pattern>/restful/*</url-pattern>
-</servlet-mapping>
-----
-
-
-=== `ResourceServlet`
-
-NOTE: WIP
-
-definition
-
-[source,xml]
-----
-<servlet>
- <servlet-name>Resource</servlet-name>
- <servlet-class>org.apache.isis.core.webapp.content.ResourceServlet</servlet-class>
-</servlet>
-----
-
-mapping:
-
-[source,xml]
-----
-<servlet-mapping>
- <servlet-name>Resource</servlet-name>
- <url-pattern>*.css</url-pattern>
-</servlet-mapping>
-<servlet-mapping>
- <servlet-name>Resource</servlet-name>
- <url-pattern>*.png</url-pattern>
-</servlet-mapping>
-<servlet-mapping>
- <servlet-name>Resource</servlet-name>
- <url-pattern>*.jpg</url-pattern>
-</servlet-mapping>
-<servlet-mapping>
- <servlet-name>Resource</servlet-name>
- <url-pattern>*.gif</url-pattern>
-</servlet-mapping>
-<servlet-mapping>
- <servlet-name>Resource</servlet-name>
- <url-pattern>*.js</url-pattern>
-</servlet-mapping>
-<servlet-mapping>
- <servlet-name>Resource</servlet-name>
- <url-pattern>*.html</url-pattern>
-</servlet-mapping>
-<servlet-mapping>
- <servlet-name>Resource</servlet-name>
- <url-pattern>*.swf</url-pattern>
-</servlet-mapping>
-----
-
-
-
-
-[[_rg_runtime_web-xml_filters]]
-== Filters
-
-The order in which filters appear in `web.xml` matters: first to last they define a pipeline. This is shown in the above diagrams, and the subsections also list the in the same order that they should appear in your `web.xml`.
-
-=== `ShiroFilter` (Shiro)
-
-NOTE: WIP
-
-definition:
-
-[source,xml]
-----
-<filter>
- <filter-name>ShiroFilter</filter-name>
- <filter-class>org.apache.shiro.web.servlet.ShiroFilter</filter-class>
-</filter>
-----
-
-mapping:
-
-[source,xml]
-----
-<filter-mapping>
- <filter-name>ShiroFilter</filter-name>
- <url-pattern>/*</url-pattern>
-</filter-mapping>
-----
-
-
-=== `IsisLogOnExceptionFilter`
-
-NOTE: WIP
-
-definition:
-
-[source,xml]
-----
-<filter>
- <filter-name>IsisLogOnExceptionFilter</filter-name>
- <filter-class>org.apache.isis.core.webapp.diagnostics.IsisLogOnExceptionFilter</filter-class>
-</filter>
-----
-
-
-mapping:
-
-[source,xml]
-----
-<filter-mapping>
- <filter-name>IsisLogOnExceptionFilter</filter-name>
- <url-pattern>/wicket/*</url-pattern>
-</filter-mapping>
-<filter-mapping>
- <filter-name>IsisLogOnExceptionFilter</filter-name>
- <url-pattern>/restful/*</url-pattern>
-</filter-mapping>
-----
-
-
-
-=== `ResourceCachingFilter`
-
-NOTE: WIP
-
-definition:
-
-[source,xml]
-----
-<filter>
- <filter-name>ResourceCachingFilter</filter-name>
- <filter-class>org.apache.isis.core.webapp.content.ResourceCachingFilter</filter-class>
- <init-param>
- <param-name>CacheTime</param-name> <!--1-->
- <param-value>86400</param-value>
- </init-param>
-</filter>
-----
-<1> cache time, in seconds
-
-mapping:
-
-[source,xml]
-----
-<filter-mapping>
- <filter-name>ResourceCachingFilter</filter-name>
- <url-pattern>*.js</url-pattern>
-</filter-mapping>
-<filter-mapping>
- <filter-name>ResourceCachingFilter</filter-name>
- <url-pattern>*.css</url-pattern>
-</filter-mapping>
-<filter-mapping>
- <filter-name>ResourceCachingFilter</filter-name>
- <url-pattern>*.png</url-pattern>
-</filter-mapping>
-<filter-mapping>
- <filter-name>ResourceCachingFilter</filter-name>
- <url-pattern>*.jpg</url-pattern>
-</filter-mapping>
-<filter-mapping>
- <filter-name>ResourceCachingFilter</filter-name>
- <url-pattern>*.gif</url-pattern>
-</filter-mapping>
-<filter-mapping>
- <filter-name>ResourceCachingFilter</filter-name>
- <url-pattern>*.html</url-pattern>
-</filter-mapping>
-<filter-mapping>
- <filter-name>ResourceCachingFilter</filter-name>
- <url-pattern>*.swf</url-pattern>
-</filter-mapping>
-----
-
-
-=== `WicketFilter`
-
-NOTE: WIP
-
-
-definition:
-
-[source,xml]
-----
-<filter>
- <filter-name>WicketFilter</filter-name>
- <filter-class>org.apache.wicket.protocol.http.WicketFilter</filter-class>
- <init-param>
- <param-name>applicationClassName</param-name> <!--1-->
- <param-value>domainapp.webapp.SimpleApplication</param-value>
- </init-param>
-</filter>
-----
-<1> specify the application (subclass of `IsisWicketApplication`) to use
-
-mapping:
-
-[source,xml]
-----
-<filter-mapping>
- <filter-name>WicketFilter</filter-name>
- <url-pattern>/wicket/*</url-pattern>
-</filter-mapping>
-----
-
-This filter reads one context parameter:
-[source,xml]
-----
-<context-param>
- <param-name>configuration</param-name>
- <param-value>deployment</param-value> <!--1-->
-</context-param>
-----
-<1> alternatively set to "development"; see xref:rg.adoc#_rg_runtime_deployment-types[deployment types] for further discussion.
-
-
-=== `IsisSessionFilter`
-
-The `IsisSessionFilter` is responsible for the (persistence) session management; in effect a wrapper around DataNucleus' `PersistenceManager` object. It is only required for the Restful Objects viewer.
-
-[source,xml]
-----
-<filter>
- <filter-name>IsisSessionFilterForRestfulObjects</filter-name>
- <filter-class>org.apache.isis.core.webapp.IsisSessionFilter</filter-class>
- <init-param>
- <param-name>authenticationSessionStrategy</param-name> <!--1-->
- <param-value>
- org.apache.isis.viewer.restfulobjects.server.authentication.AuthenticationSessionStrategyBasicAuth
- </param-value>
- </init-param>
- <init-param>
- <param-name>whenNoSession</param-name> <!--2-->
- <param-value>basicAuthChallenge</param-value>
- </init-param>
- <!--
- <init-param>
- <param-name>restricted</param-name> <!--3-->
- <param-value>...</param-value>
- </init-param>
- <init-param>
- <param-name>redirectToOnException</param-name> <!--4-->
- <param-value>...</param-value>
- </init-param>
- -->
-</filter>
-----
-<1> pluggable strategy for determining what the authentication session (credentials) are of the request
-<2> what the servlet should do if no existing session was found; typically a 401, or can issue a Basic Auth challenge
-<3> List of paths that are allowed through even if not authenticated. The servlets mapped to these paths are expected to be able to deal with there being no session. Typically they will be logon pages.
-<4> where to redirect to if an exception occurs.
-
-
-This filter should be mapped to the `servlet-name` for the RestEasy `HttpServletDispatcher`; for example:
-
-[source,xml]
-----
-<filter-mapping>
- <filter-name>IsisSessionFilterForRestfulObjects</filter-name>
- <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
-</filter-mapping>
-----
-
-
-
-
-=== `IsisTransactionFilterForRestfulObjects`
-
-NOTE: WIP
-
-definition:
-
-[source,xml]
-----
-<filter>
- <filter-name>IsisTransactionFilterForRestfulObjects</filter-name>
- <filter-class>org.apache.isis.viewer.restfulobjects.server.webapp.IsisTransactionFilterForRestfulObjects</filter-class>
-</filter>
-----
-
-This filter should be mapped to the `servlet-name` for the RestEasy `HttpServletDispatcher`; for example:
-
-[source,xml]
-----
-<filter-mapping>
- <filter-name>IsisTransactionFilterForRestfulObjects</filter-name>
- <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
-</filter-mapping>
-----
-
-
-
-[[_rg_runtime_web-xml_context-parameters]]
-== Configuration Files
-
-However Apache Isis is bootstrapped (using the `IsisWicketApplication` or using `IsisWebAppBootstrapper`), it will read a number of configuration files, such as `isis.properties`.
-
-By default these are read from `WEB-INF` directory.
-
- <context-param>
- <param-name>isis.config.dir</param-name>
- <param-value>location of your config directory if fixed</param-value>
- </context-param>
- -->
-
-
- <!--
- determines which additional configuration files to search for
- -->
- <context-param>
- <param-name>isis.viewers</param-name>
- <param-value>wicket,restfulobjects</param-value>
- </context-param>
-
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_rg_web-xml.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_web-xml.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_web-xml.adoc
new file mode 100644
index 0000000..93d09ce
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_web-xml.adoc
@@ -0,0 +1,463 @@
+[[_rg_web-xml]]
+= `web.xml`
+: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 provides two different viewers, the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] and the xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer]. You can deploy both of these concurrently, or deploy just the Wicket viewer, or deploy just the Restful Objects viewer. The configuration in `web.xml` varies accordingly, both in terms of the servlet context listeners, filters and servlets.
+
+If you are using Apache Isis' integration with Apache Shiro (for security) then this also needs configuring in `web.xml`. See the xref:ug.adoc#_ug_security_configuring-isis-to-use-shiro[security chapter] for full details on this topic.
+
+The servlets and filters are mapped to three main pipelines:
+
+* `/wicket` - the Wicket viewer UI
+* `/restful` - the Restful Objects resources (REST API)
+* other paths, also static resources (such as `.png`, `.css`)
+
+With the following key:
+
+image::{_imagesdir}runtime/web-xml/key.png[width="800px",link="{_imagesdir}runtime/web-xml/key.png"]
+
+the diagram below shows the components to be configured if deploying both the Wicket viewer and Restful Objects viewer:
+
+image::{_imagesdir}runtime/web-xml/wicket-and-ro.png[width="800px",link="{_imagesdir}runtime/web-xml/wicket-and-ro.png"]
+
+Here the Wicket viewer is responsible for the main bootstrapping of Apache Isis itself, in other words the shared (global) metadata; this is done by the `IsisWicketApplication` class (extending the `WicketApplication` Wicket API). This class is also responsible for Apache Isis' own session and transaction management.
+
+The Restful Objects viewer - being a JAX-RS application implemented using the RestEasy framework - requires the `RestEasyBootstrapper` servlet context listener. It is this context listener that also sets up the `RestfulObjectsApplication`, which is then delegated to by the RestEasy `HttpServletDispatcher`. This pipeline uses the `IsisSessionFilter` and `IsisTransactionFilterForRestfulObjects` to perform the session and transaction management before it hits the RestEasy servlet.
+
+If only the Wicket viewer is deployed, then the diagram is more or less the same: the RestEasy servlet, context listener and supporting filters are simply removed:
+
+image::{_imagesdir}runtime/web-xml/wicket-only.png[width="800px",link="{_imagesdir}runtime/web-xml/wicket-only.png"]
+
+Finally, if only the Restful Objects viewer is deployed, then things change a little more subtly. Here, the Wicket filter is no longer needed. In its place, though the `IsisWebAppBootstrapper` context listener is required: this is responsible for seting up the shared (global) metadata.
+
+image::{_imagesdir}runtime/web-xml/ro-only.png[width="800px",link="{_imagesdir}runtime/web-xml/ro-only.png"]
+
+The following sections detail these various listeners, filters and servlets in more detail.
+
+
+
+[[_rg_web-xml_servlet-context-listeners]]
+== Servlet Context Listeners
+
+Servlet context listeners are used to perform initialization on application startup. Both Shiro (if configured as the security mechanism) and RestEasy (for the Restful Objects viewer) require their own context listener. In addition, if the Wicket viewer is _not_ being used, then additional Apache Isis-specific listener is required for bootstrapping of the Apache Isis framework itself.
+
+
+=== `EnvironmentLoaderListener` (Shiro)
+
+NOTE: WIP
+
+definition:
+
+[source,xml]
+----
+<listener>
+ <listener-class>org.apache.shiro.web.env.EnvironmentLoaderListener</listener-class>
+</listener>
+----
+
+
+
+=== `IsisWebAppBootstrapper`
+
+The `IsisWebAppBootstrapper` servlet context listener bootstraps the shared (global) metadata for the Apache Isis framework. This listener is not required (indeed must not be configured) if the Wicket viewer is in use.
+
+NOTE: WIP
+
+definition:
+
+[source,xml]
+----
+<listener>
+ <listener-class>org.apache.isis.core.webapp.IsisWebAppBootstrapper</listener-class>
+</listener>
+----
+
+context parameters:
+
+[source,xml]
+----
+<context-param>
+ <param-name>deploymentType</param-name>
+ <param-value>SERVER_PROTOTYPE</param-value>
+</context-param>
+<context-param>
+ <param-name>isis.viewers</param-name>
+ <param-value>restfulobjects</param-value>
+</context-param>
+----
+
+
+=== `ResteasyBootstrap` (RestEasy)
+
+The `ResteasyBootstrap` servlet context listener initializes the RestEasy runtime, specifying that classes (namely, those specified in Isis' `RestfulObjectsApplication`) to be exposed as REST resources. It is required if the Restful Objects viewer is to be deployed.
+
+NOTE: WIP
+
+definition:
+
+[source,xml]
+----
+<listener>
+ <listener-class>org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap</listener-class>
+</listener>
+----
+
+There are two relevant context parameters:
+
+[source,xml]
+----
+<context-param>
+ <param-name>javax.ws.rs.Application</param-name> <!--1-->
+ <param-value>org.apache.isis.viewer.restfulobjects.server.RestfulObjectsApplication</param-value>
+</context-param>
+<context-param>
+ <param-name>resteasy.servlet.mapping.prefix</param-name>
+ <param-value>/restful/</param-value> <!--2-->
+</context-param>
+----
+<1> used by RestEasy to determine the JAX-RS resources and other related configuration
+<2> should correspond to the filter mapping of the `HttpServletDispatcher` servlet
+
+
+
+[[_rg_web-xml_servlets]]
+== Servlets
+
+NOTE: WIP
+
+
+=== `HttpServletDispatcher` (RestEasy)
+
+NOTE: WIP
+
+
+definition:
+
+[source,xml]
+----
+<servlet>
+ <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
+ <servlet-class>org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher</servlet-class>
+</servlet>
+----
+
+mapping:
+
+[source,xml]
+----
+<servlet-mapping>
+ <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
+ <url-pattern>/restful/*</url-pattern>
+</servlet-mapping>
+----
+
+
+=== `ResourceServlet`
+
+NOTE: WIP
+
+definition
+
+[source,xml]
+----
+<servlet>
+ <servlet-name>Resource</servlet-name>
+ <servlet-class>org.apache.isis.core.webapp.content.ResourceServlet</servlet-class>
+</servlet>
+----
+
+mapping:
+
+[source,xml]
+----
+<servlet-mapping>
+ <servlet-name>Resource</servlet-name>
+ <url-pattern>*.css</url-pattern>
+</servlet-mapping>
+<servlet-mapping>
+ <servlet-name>Resource</servlet-name>
+ <url-pattern>*.png</url-pattern>
+</servlet-mapping>
+<servlet-mapping>
+ <servlet-name>Resource</servlet-name>
+ <url-pattern>*.jpg</url-pattern>
+</servlet-mapping>
+<servlet-mapping>
+ <servlet-name>Resource</servlet-name>
+ <url-pattern>*.gif</url-pattern>
+</servlet-mapping>
+<servlet-mapping>
+ <servlet-name>Resource</servlet-name>
+ <url-pattern>*.js</url-pattern>
+</servlet-mapping>
+<servlet-mapping>
+ <servlet-name>Resource</servlet-name>
+ <url-pattern>*.html</url-pattern>
+</servlet-mapping>
+<servlet-mapping>
+ <servlet-name>Resource</servlet-name>
+ <url-pattern>*.swf</url-pattern>
+</servlet-mapping>
+----
+
+
+
+
+[[_rg_web-xml_filters]]
+== Filters
+
+The order in which filters appear in `web.xml` matters: first to last they define a pipeline. This is shown in the above diagrams, and the subsections also list the in the same order that they should appear in your `web.xml`.
+
+=== `ShiroFilter` (Shiro)
+
+NOTE: WIP
+
+definition:
+
+[source,xml]
+----
+<filter>
+ <filter-name>ShiroFilter</filter-name>
+ <filter-class>org.apache.shiro.web.servlet.ShiroFilter</filter-class>
+</filter>
+----
+
+mapping:
+
+[source,xml]
+----
+<filter-mapping>
+ <filter-name>ShiroFilter</filter-name>
+ <url-pattern>/*</url-pattern>
+</filter-mapping>
+----
+
+
+=== `IsisLogOnExceptionFilter`
+
+NOTE: WIP
+
+definition:
+
+[source,xml]
+----
+<filter>
+ <filter-name>IsisLogOnExceptionFilter</filter-name>
+ <filter-class>org.apache.isis.core.webapp.diagnostics.IsisLogOnExceptionFilter</filter-class>
+</filter>
+----
+
+
+mapping:
+
+[source,xml]
+----
+<filter-mapping>
+ <filter-name>IsisLogOnExceptionFilter</filter-name>
+ <url-pattern>/wicket/*</url-pattern>
+</filter-mapping>
+<filter-mapping>
+ <filter-name>IsisLogOnExceptionFilter</filter-name>
+ <url-pattern>/restful/*</url-pattern>
+</filter-mapping>
+----
+
+
+
+=== `ResourceCachingFilter`
+
+NOTE: WIP
+
+definition:
+
+[source,xml]
+----
+<filter>
+ <filter-name>ResourceCachingFilter</filter-name>
+ <filter-class>org.apache.isis.core.webapp.content.ResourceCachingFilter</filter-class>
+ <init-param>
+ <param-name>CacheTime</param-name> <!--1-->
+ <param-value>86400</param-value>
+ </init-param>
+</filter>
+----
+<1> cache time, in seconds
+
+mapping:
+
+[source,xml]
+----
+<filter-mapping>
+ <filter-name>ResourceCachingFilter</filter-name>
+ <url-pattern>*.js</url-pattern>
+</filter-mapping>
+<filter-mapping>
+ <filter-name>ResourceCachingFilter</filter-name>
+ <url-pattern>*.css</url-pattern>
+</filter-mapping>
+<filter-mapping>
+ <filter-name>ResourceCachingFilter</filter-name>
+ <url-pattern>*.png</url-pattern>
+</filter-mapping>
+<filter-mapping>
+ <filter-name>ResourceCachingFilter</filter-name>
+ <url-pattern>*.jpg</url-pattern>
+</filter-mapping>
+<filter-mapping>
+ <filter-name>ResourceCachingFilter</filter-name>
+ <url-pattern>*.gif</url-pattern>
+</filter-mapping>
+<filter-mapping>
+ <filter-name>ResourceCachingFilter</filter-name>
+ <url-pattern>*.html</url-pattern>
+</filter-mapping>
+<filter-mapping>
+ <filter-name>ResourceCachingFilter</filter-name>
+ <url-pattern>*.swf</url-pattern>
+</filter-mapping>
+----
+
+
+=== `WicketFilter`
+
+NOTE: WIP
+
+
+definition:
+
+[source,xml]
+----
+<filter>
+ <filter-name>WicketFilter</filter-name>
+ <filter-class>org.apache.wicket.protocol.http.WicketFilter</filter-class>
+ <init-param>
+ <param-name>applicationClassName</param-name> <!--1-->
+ <param-value>domainapp.webapp.SimpleApplication</param-value>
+ </init-param>
+</filter>
+----
+<1> specify the application (subclass of `IsisWicketApplication`) to use
+
+mapping:
+
+[source,xml]
+----
+<filter-mapping>
+ <filter-name>WicketFilter</filter-name>
+ <url-pattern>/wicket/*</url-pattern>
+</filter-mapping>
+----
+
+This filter reads one context parameter:
+[source,xml]
+----
+<context-param>
+ <param-name>configuration</param-name>
+ <param-value>deployment</param-value> <!--1-->
+</context-param>
+----
+<1> alternatively set to "development"; see xref:rg.adoc#_rg_runtime_deployment-types[deployment types] for further discussion.
+
+
+=== `IsisSessionFilter`
+
+The `IsisSessionFilter` is responsible for the (persistence) session management; in effect a wrapper around DataNucleus' `PersistenceManager` object. It is only required for the Restful Objects viewer.
+
+[source,xml]
+----
+<filter>
+ <filter-name>IsisSessionFilterForRestfulObjects</filter-name>
+ <filter-class>org.apache.isis.core.webapp.IsisSessionFilter</filter-class>
+ <init-param>
+ <param-name>authenticationSessionStrategy</param-name> <!--1-->
+ <param-value>
+ org.apache.isis.viewer.restfulobjects.server.authentication.AuthenticationSessionStrategyBasicAuth
+ </param-value>
+ </init-param>
+ <init-param>
+ <param-name>whenNoSession</param-name> <!--2-->
+ <param-value>basicAuthChallenge</param-value>
+ </init-param>
+ <!--
+ <init-param>
+ <param-name>restricted</param-name> <!--3-->
+ <param-value>...</param-value>
+ </init-param>
+ <init-param>
+ <param-name>redirectToOnException</param-name> <!--4-->
+ <param-value>...</param-value>
+ </init-param>
+ -->
+</filter>
+----
+<1> pluggable strategy for determining what the authentication session (credentials) are of the request
+<2> what the servlet should do if no existing session was found; typically a 401, or can issue a Basic Auth challenge
+<3> List of paths that are allowed through even if not authenticated. The servlets mapped to these paths are expected to be able to deal with there being no session. Typically they will be logon pages.
+<4> where to redirect to if an exception occurs.
+
+
+This filter should be mapped to the `servlet-name` for the RestEasy `HttpServletDispatcher`; for example:
+
+[source,xml]
+----
+<filter-mapping>
+ <filter-name>IsisSessionFilterForRestfulObjects</filter-name>
+ <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
+</filter-mapping>
+----
+
+
+
+
+=== `IsisTransactionFilterForRestfulObjects`
+
+NOTE: WIP
+
+definition:
+
+[source,xml]
+----
+<filter>
+ <filter-name>IsisTransactionFilterForRestfulObjects</filter-name>
+ <filter-class>org.apache.isis.viewer.restfulobjects.server.webapp.IsisTransactionFilterForRestfulObjects</filter-class>
+</filter>
+----
+
+This filter should be mapped to the `servlet-name` for the RestEasy `HttpServletDispatcher`; for example:
+
+[source,xml]
+----
+<filter-mapping>
+ <filter-name>IsisTransactionFilterForRestfulObjects</filter-name>
+ <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
+</filter-mapping>
+----
+
+
+
+[[_rg_web-xml_context-parameters]]
+== Configuration Files
+
+However Apache Isis is bootstrapped (using the `IsisWicketApplication` or using `IsisWebAppBootstrapper`), it will read a number of configuration files, such as `isis.properties`.
+
+By default these are read from `WEB-INF` directory.
+
+ <context-param>
+ <param-name>isis.config.dir</param-name>
+ <param-value>location of your config directory if fixed</param-value>
+ </context-param>
+ -->
+
+
+ <!--
+ determines which additional configuration files to search for
+ -->
+ <context-param>
+ <param-name>isis.viewers</param-name>
+ <param-value>wicket,restfulobjects</param-value>
+ </context-param>
+
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_tg_pet-clinic.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_tg_pet-clinic.adoc b/adocs/documentation/src/main/asciidoc/guides/_tg_pet-clinic.adoc
new file mode 100644
index 0000000..3c0994f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_tg_pet-clinic.adoc
@@ -0,0 +1,557 @@
+[[_ug_tutorials_pet-clinic]]
+= Pet Clinic
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+This is a step-by-step tutorial to build up a simple "petclinic" application, starting from the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype].
+
+It consists of just three domain classes (http://yuml.me/edit/3db2078c[http://yuml.me/3db2078c]):
+
+image::{_imagesdir}tutorials/pet-clinic/domain-model.png[link="{_imagesdir}tutorials/pet-clinic/domain-model.png"]
+
+
+This supports the following use cases:
+
+* register a Pet
+* register an Owner
+* maintain a Pet's details
+* check in a Pet to visit the clinic
+* enter a diagnosis
+
+check out a Pet to visit the clinic
+
+Either follow along or check out the tags from the corresponding https://github.com/danhaywood/isis-app-petclinic[github repo].
+
+== Prerequisites
+
+You'll need:
+
+* Java 7 JDK
+* http://maven.apache.org/[Maven] 3.2.x
+* an IDE, such as http://www.eclipse.org/[Eclipse] or https://www.jetbrains.com/idea/[IntelliJ IDEA].
+
+
+
+
+== Run the archetype
+
+Throughout this tutorial you can, if you wish, just checkout from the github repo wherever you see a "git checkout" note:
+
+[TIP]
+====
+[source,bash]
+----
+git checkout https://github.com/danhaywood/isis-app-petclinic/commit/249abe476797438d83faa12ff88365da2c362451
+----
+
+====
+
+[NOTE]
+====
+This tutorial was developed against Apache Isis 1.8.0-SNAPSHOT. Since then 1.8.0 has been released, so simply replace "1.8.0-SNAPSHOT" for "1.8.0" wherever it appears in the `pom.xml` files.
+====
+
+
+Run the simpleapp archetype to build an empty Isis application:
+
+
+[source,bash]
+----
+mvn archetype:generate \
+ -D archetypeGroupId=org.apache.isis.archetype \
+ -D archetypeArtifactId=simpleapp-archetype \
+ -D archetypeVersion=1.8.0 \
+ -D groupId=com.mycompany \
+ -D artifactId=petclinic \
+ -D version=1.0-SNAPSHOT \
+ -D archetypeRepository=http://repository-estatio.forge.cloudbees.com/snapshot/ \
+ -B
+----
+
+This will generate the app in a `petclinic` directory. Move the contents back:
+
+[source,bash]
+----
+mv petclinic/* .
+rmdir petclinic
+----
+
+
+
+
+== Build and run
+
+Start off by building the app from the command line:
+
+[source,bash]
+----
+mvn clean install
+----
+
+Once that's built then run using:
+
+[source,bash]
+----
+mvn antrun:run -P self-host
+----
+
+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[http://localhost:8080]
+
+Alternatively, you can run using the mvn-jetty-plugin:
+
+[source,bash]
+----
+mvn jetty:run
+----
+
+This will accomplish the same thing, though the webapp is mounted at a slightly different URL
+
+
+
+
+== Using the app
+
+Navigate to the Wicket UI (eg http://localhost:8080/wicket[http://localhost:8080/wicket]), and login (sven/pass).
+
+image::{_imagesdir}tutorials/pet-clinic/010-01-login-page.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/010-01-login-page.png"]
+
+
+
+The home page should be shown:
+
+image::{_imagesdir}tutorials/pet-clinic/010-02-home-page.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/010-02-home-page.png"]
+
+
+
+Install the fixtures (example test data) using the `Prototyping` menu:
+
+image::{_imagesdir}tutorials/pet-clinic/010-03-prototyping-menu.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/010-03-prototyping-menu.png"]
+
+
+
+List all objects using the `Simple Objects` menu:
+
+image::{_imagesdir}tutorials/pet-clinic/010-04-simpleobjects.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/010-04-simpleobjects.png"]
+
+
+To return the objects created:
+
+image::{_imagesdir}tutorials/pet-clinic/010-05-simpleobject-list.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/010-05-simpleobject-list.png"]
+
+
+
+Experiment some more, to:
+
+* create a new object
+* list all objects
+
+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.
+
+
+
+
+== Dev environment
+
+Set up xref:cg.adoc#_cg_ide[an IDE] and import the project to be able to run and debug the app.
+
+Then set up a launch configuration so that you can run the app from within the IDE. To save having to run the fixtures
+every time, specify the following system properties:
+
+[source,bash]
+----
+-Disis.persistor.datanucleus.install-fixtures=true -Disis.fixtures=fixture.simple.scenario.SimpleObjectsFixture
+----
+
+For example, here's what a launch configuration in IntelliJ idea looks like:
+
+image::{_imagesdir}tutorials/pet-clinic/020-01-idea-configuration.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/020-01-idea-configuration.png"]
+
+
+
+where the "before launch" maven goal (to run the DataNucleus enhancer) is defined as:
+
+
+image::{_imagesdir}tutorials/pet-clinic/020-02-idea-configuration.png[width="400px",link="{_imagesdir}tutorials/pet-clinic/020-02-idea-configuration.png"]
+
+
+
+
+== Explore codebase
+
+Apache Isis applications are organized into several Maven modules. Within your IDE navigate to the various classes and correlate back to the generated UI:
+
+* `petclinic` : parent module
+* `petclinic-dom`: domain objects module
+** entity: `dom.simple.SimpleObject`
+** repository: `dom.simple.SimpleObjects`
+* `petclinic-fixture`: fixtures module
+** fixture script:`fixture.simple.SimpleObjectsFixture`
+* `petclinic-integtests`: integration tests module
+* `petclinic-webapp`: webapp module
+** (builds the WAR file)
+
+
+
+
+== Testing
+
+Testing is of course massively important, and Apache Isis makes both unit testing and (end-to-end) integration testing easy. Building the app from the Maven command line ("mvn clean install") will run all tests, but you should also run the tests from within the IDE.
+
+* `myapp-dom` unit tests
+* run
+* inspect, eg
+ - `SimpleObjectTest`
+* `myapp-integtests` integration tests
+* run
+* inspect, eg:
+** `integration.tests.smoke.SimpleObjectsTest`
+** `integration.specs.simple.SimpleObjectSpec_listAllAndCreate.feature`
+* generated report, eg
+ - `myapp/integtests/target/cucumber-html-report/index.html`
+** change test in IDE, re-run (in Maven)
+
+If you have issues with the integration tests, make sure that the domain classes have been enhanced by the DataNucleus enhancer. (The exact mechanics depends on the IDE being used).
+
+
+
+
+== Update POM files
+
+[TIP]
+====
+[source,bash]
+----
+git checkout https://github.com/danhaywood/isis-app-petclinic/commit/68904752bc2de9ebb3c853b79236df2b3ad2c944
+----
+
+====
+
+The POM files generated by the simpleapp archetype describe the app as "SimpleApp". Update them to say "PetClinic" instead.
+
+
+
+
+== Delete the BDD specs
+
+[TIP]
+====
+[source,bash]
+----
+git checkout https://github.com/danhaywood/isis-app-petclinic/commit/9046226249429b269325dfa2baccf03635841c20
+----
+
+====
+
+
+During this tutorial we're going to keep the integration tests in-sync with the code, but we're going to stop short of writing BDD/Cucumber specs.
+
+Therefore delete the BDD feature spec and glue in the `integtest` module:
+
+* `integration/specs/*`
+* `integration/glue/*`
+
+
+
+
+== Rename artifacts
+
+[TIP]
+====
+[source,bash]
+----
+git checkout https://github.com/danhaywood/isis-app-petclinic/commit/bee3629c0b64058f939b6dd20f226be31810fc66
+----
+
+====
+
+
+Time to start refactoring the app. The heart of the PetClinic app is the `Pet` concept, so go through the code and refactor. While we're at it, refactor the app itself from "SimpleApp" to "PetClinicApp".
+
+See the git commit for more detail, but in outline, the renames required are:
+
+* in the `dom` module's production code
+** `SimpleObject` -> `Pet` (entity)
+** `SimpleObjects` -> `Pets` (repository domain service)
+** `SimpleObject.layout.json` -> `Pet.layout.json` (layout hints for the `Pet` entity)
+** delete the `SimpleObject.png`, and add a new `Pet.png` (icon shown against all `Pet` instances).
+* in the `dom` module's unit test code
+** `SimpleObjectTest` -> `PetTest` (unit tests for `Pet` entity)
+** `SimpleObjectsTest` -> `PetsTest` (unit tests for `Pets` domain service)
+* in the `fixture` module:
+** `SimpleObjectsFixturesService` -> `PetClinicAppFixturesService` (rendered as the prototyping menu in the UI)
+** `SimpleObjectsTearDownService` -> `PetClinicAppTearDownService` (tear down all objects between integration tests)
+** `SimpleObjectAbstract` -> `PetAbstract` (abstract class for setting up a single pet object
+*** and corresponding subclasses to set up sample data (eg `PetForFido`)
+** `SimpleObjectsFixture` -> `PetsFixture` (tear downs system and then sets up all pets)
+* in the `integtest` module:
+** `SimpleAppSystemInitializer` -> `PetClinicAppSystemInitializer` (bootstraps integration tests with domain service/repositories)
+** `SimpleAppIntegTest` -> `PetClinicAppIntegTest` (base class for integration tests)
+** `SimpleObjectTest` -> `PetTest` (integration test for `Pet` entity)
+** `SimpleObjectsTest` -> `PetsTest` (integration test for `Pets` domain service)
+* in the `webapp` module:
+** `SimpleApplication` -> `PetClinicApplication`
+** update `isis.properties`
+** update `web.xml`
+
+
+Note that `Pet` has both both Isis and JDO annotations:
+
+[source,java]
+----
+@javax.jdo.annotations.PersistenceCapable(identityType=IdentityType.DATASTORE) // <1>
+@javax.jdo.annotations.DatastoreIdentity( // <2>
+ strategy=javax.jdo.annotations.IdGeneratorStrategy.IDENTITY,
+ column="id")
+@javax.jdo.annotations.Version( // <3>
+ strategy=VersionStrategy.VERSION_NUMBER,
+ column="version")
+@javax.jdo.annotations.Unique(name="Pet_name_UNQ", members = {"name"}) // <4>
+@ObjectType("PET") // <5>
+@Bookmarkable // <6>
+public class Pet implements Comparable<Pet> {
+ ...
+}
+----
+
+where:
+
+<1> `@PersistenceCapable` and
+<2> `@DatastoreIdentity` specify a surrogate `Id` column to be used as the primary key
+<3> `@Version` provides support for optimistic locking
+<4> `@Unique` enforces a uniqueness constraint so that no two `Pet`s can have the same name (unrealistic, but can refactor later)
+<5> `@ObjectType` is used by Apache Isis for its own internal "OID" identifier; this also appears in the URL in Apache Isis' Wicket viewer and REST API
+<6> `@Bookmarkable` indicates that the object can be automatically bookmarked in Apache Isis' Wicket viewer
+
+[NOTE]
+====
+The `@ObjectType` and `@Bookmarkable` annotations have since been deprecated, replaced with `@DomainObject(objectType=...)` and `@DomainObjectLayout(bookmarking=...)`
+====
+
+
+The `Pets` domain service also has Isis annotations:
+
+[source,java]
+----
+@DomainService(repositoryFor = Pet.class)
+@DomainServiceLayout(menuOrder = "10")
+public class Pets {
+ ...
+}
+----
+
+where:
+
+* `DomainService` indicates that the service should be instantiated automatically (as a singleton)
+* `DomainServiceLayout` provides UI hints, in this case the positioning of the menu for the actions provided by the service
+
+To run the application will require an update to the IDE configuration, for the changed name of the fixture class:
+
+
+image::{_imagesdir}tutorials/pet-clinic/030-01-idea-configuration-updated.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/030-01-idea-configuration-updated.png"]
+
+
+Running the app should now show `Pet`s:
+
+image::{_imagesdir}tutorials/pet-clinic/030-02-updated-app.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/030-02-updated-app.png"]
+
+
+
+
+
+== Update package names
+
+[TIP]
+====
+[source,bash]
+----
+git checkout https://github.com/danhaywood/isis-app-petclinic/commit/55ec36e520191f5fc8fe7f5b89956814eaf13317
+----
+
+====
+
+
+
+The classes created by the simpleapp archetype are by default in the `simple` package. Move these classes to `pets` package instead. Also adjust package names where they appear as strings:
+
+* in `PetClinicAppFixturesService`, change the package name from "fixture.simple" to "fixture.pets".
+* in `PetClinicAppSystemInitializer`, change the package name "dom.simple" to "dom.pets", and similarly "fixture.simple" to "fixture.pets"
+* in `WEB-INF/isis.properties`, similarly change the package name "dom.simple" to "dom.pets", and similarly "fixture.simple" to "fixture.pets"
+
+To run the application will require a further update to the IDE configuration, for the changed package of the fixture class:
+
+
+image::{_imagesdir}tutorials/pet-clinic/040-01-idea-configuration-updated.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/040-01-idea-configuration-updated.png"]
+
+
+
+== Add `PetSpecies` enum
+
+[TIP]
+====
+[source,bash]
+----
+git checkout https://github.com/danhaywood/isis-app-petclinic/commit/55c9cd28ff960220719b3dc7cb8abadace8d0829
+----
+
+====
+
+
+Each `Pet` is of a particular species. Model these as an enum called `PetSpecies`:
+
+[source,java]
+----
+public enum PetSpecies {
+ Cat,
+ Dog,
+ Budgie,
+ Hamster,
+ Tortoise
+}
+----
+
+Introduce a new property on `Pet` of this type:
+
+[source,java]
+----
+public class Pet {
+ ...
+ private PetSpecies species;
+ @javax.jdo.annotations.Column(allowsNull = "false")
+ public PetSpecies getSpecies() { return species; }
+ public void setSpecies(final PetSpecies species) { this.species = species; }
+ ...
+}
+----
+
+Update fixtures, unit tests and integration tests.
+
+
+
+
+== Icon to reflect pet species
+
+[TIP]
+====
+[source,bash]
+----
+git checkout https://github.com/danhaywood/isis-app-petclinic/commit/2212765694693eb463f8fa88bab1bad154add0cb
+----
+
+====
+
+
+Rather than using a single icon for a domain class, instead a different icon can be supplied for each instance. We can therefore have different icon files for each pet, reflecting that pet's species.
+
+[source,java]
+----
+public class Pet {
+ ...
+ public String iconName() {
+ return getSpecies().name();
+ }
+ ...
+}
+----
+
+Download corresponding icon files (`Dog.png`, `Cat.png` etc)
+
+Running the app shows the `Pet` and its associated icon:
+
+image::{_imagesdir}tutorials/pet-clinic/050-01-list-all.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/050-01-list-all.png"]
+
+
+
+with the corresponding view of the `Pet`:
+
+image::{_imagesdir}tutorials/pet-clinic/050-02-view-pet.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/050-02-view-pet.png"]
+
+
+== Add pet's `Owner`
+
+[TIP]
+====
+[source,bash]
+----
+git checkout https://github.com/danhaywood/isis-app-petclinic/commit/6f92a8ee8e76696d005da2a8b7a746444d017546
+----
+
+====
+
+
+Add the `Owner` entity and corresponding `Owners` domain service (repository). Add a query to find `Order`s by name:
+
+[source,java]
+----
+...
+@javax.jdo.annotations.Queries( {
+ @javax.jdo.annotations.Query(
+ name = "findByName", language = "JDOQL",
+ value = "SELECT "
+ + "FROM dom.owners.Owner "
+ + "WHERE name.matches(:name)")
+})
+public class Owner ... {
+ ...
+}
+----
+
+and `findByName(...)` in `Owners`:
+
+[source,java]
+----
+public class Owners {
+ ...
+ public List<Owner> findByName(
+ @ParameterLayout(named = "Name")
+ final String name) {
+ final String nameArg = String.format(".*%s.*", name);
+ final List<Owner> owners = container.allMatches(
+ new QueryDefault<>(
+ Owner.class,
+ "findByName",
+ "name", nameArg));
+ return owners;
+ }
+ ...
+}
+----
+
+Add an `owner` property to `Pet`, with supporting `autoCompleteXxx()` method (so that available owners are shown in a drop-down list box):
+
+[source,java]
+----
+public class Pet ... {
+ ...
+ private Owner owner;
+ @javax.jdo.annotations.Column(allowsNull = "false")
+ public Owner getOwner() { return owner; }
+ public void setOwner(final Owner owner) { this.owner = owner; }
+ public Collection<Owner> autoCompleteOwner(final @MinLength(1) String name) {
+ return owners.findByName(name);
+ }
+ ...
+}
+----
+
+Also updated fixture data to set up a number of `Owner`s, and associate each `Pet` with an `Owner`. Also add unit tests and integration tests for `Owner`/`Owners` and updated for `Pet`/`Pets`.
+
+When running the app, notice the new `Owners` menu:
+
+image::{_imagesdir}tutorials/pet-clinic/060-01-owners-menu.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/060-01-owners-menu.png"]
+
+which when invoked returns all `Owner` objects:
+
+image::{_imagesdir}tutorials/pet-clinic/060-02-owners-list.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/060-02-owners-list.png"]
+
+
+Each `Pet` also indicates its corresponding `Owner`:
+
+image::{_imagesdir}tutorials/pet-clinic/060-03-pets-list.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/060-03-pets-list.png"]
+
+
+And, on editing a `Pet`, a new `Owner` can be specified using the autoComplete:
+
+image::{_imagesdir}tutorials/pet-clinic/060-04-pet-owner-autoComplete.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/060-04-pet-owner-autoComplete.png"]
+