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/04/27 21:31:58 UTC
[08/11] isis git commit: ISIS-1133: more on the listen.rb,
renaming included .adoc files.
ISIS-1133: more on the listen.rb, renaming included .adoc files.
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/08f6b036
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/08f6b036
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/08f6b036
Branch: refs/heads/ISIS-1133
Commit: 08f6b03625b736372f44e1729cbcb30f304086fc
Parents: 90f26cf
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Mon Apr 27 19:35:28 2015 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Mon Apr 27 19:35:28 2015 +0100
----------------------------------------------------------------------
adocs/documentation/README.md | 49 ++-
adocs/documentation/listen.rb | 92 ++---
.../user-guide/_user-guide_appendices.adoc | 8 +
.../_user-guide_appendices_dev-env.adoc | 8 +
..._user-guide_appendices_dev-env_intellij.adoc | 362 +++++++++++++++++++
.../_user-guide_background-execution.adoc | 40 ++
.../_user-guide_config-and-deployment.adoc | 93 +++++
.../user-guide/_user-guide_core-concepts.adoc | 20 +
...user-guide_core-concepts_apache-isis-vs.adoc | 14 +
...ser-guide_core-concepts_building-blocks.adoc | 234 ++++++++++++
...re-concepts_framework-provided-services.adoc | 82 +++++
.../_user-guide_core-concepts_principles.adoc | 76 ++++
.../user-guide/_user-guide_extending.adoc | 25 ++
..._user-guide_extending_programming-model.adoc | 16 +
.../user-guide/_user-guide_getting-started.adoc | 9 +
...ide_getting-started_simpleapp-archetype.adoc | 7 +
.../user-guide/_user-guide_how-tos.adoc | 39 ++
.../_user-guide_how-tos_business-rules.adoc | 57 +++
.../_user-guide_how-tos_class-structure.adoc | 173 +++++++++
..._user-guide_how-tos_contributed-members.adoc | 15 +
.../user-guide/_user-guide_how-tos_crud.adoc | 18 +
.../_user-guide_how-tos_derived-members.adoc | 33 ++
...r-guide_how-tos_drop-downs-and-defaults.adoc | 30 ++
...user-guide_how-tos_entity-relationships.adoc | 11 +
.../_user-guide_how-tos_error-handling.adoc | 11 +
.../user-guide/_user-guide_how-tos_i18n.adoc | 7 +
.../_user-guide_how-tos_multi-tenancy.adoc | 7 +
...ser-guide_how-tos_persistence-lifecycle.adoc | 7 +
.../_user-guide_how-tos_tips-n-tricks.adoc | 32 ++
...uide_how-tos_tips-n-tricks_are-you-sure.adoc | 47 +++
...ips-n-tricks_overriding-jdo-annotations.adoc | 5 +
.../_user-guide_how-tos_triggering-events.adoc | 136 +++++++
.../_user-guide_how-tos_ui-hints.adoc | 55 +++
...er-guide_integrating-with-other-systems.adoc | 11 +
.../user-guide/_user-guide_isis-addons.adoc | 44 +++
.../user-guide/_user-guide_reference.adoc | 25 ++
...-guide_reference_applib-utility-classes.adoc | 144 ++++++++
.../_user-guide_reference_cmd-line-args.adoc | 31 ++
...uide_reference_convenience-superclasses.adoc | 8 +
.../_user-guide_reference_domain-services.adoc | 8 +
...-guide_reference_recognized-annotations.adoc | 8 +
...nce_recognized-configuration-properties.adoc | 28 ++
...user-guide_reference_recognized-methods.adoc | 8 +
.../_user-guide_reference_value-types.adoc | 14 +
.../_user-guide_reference_web-xml.adoc | 8 +
.../user-guide/_user-guide_restful-viewer.adoc | 35 ++
.../user-guide/_user-guide_testing.adoc | 22 ++
...er-guide_testing_bdd-integ-test-support.adoc | 7 +
.../_user-guide_testing_fake-data.adoc | 11 +
.../_user-guide_testing_fixture-scripts.adoc | 65 ++++
.../_user-guide_testing_integ-test-support.adoc | 19 +
.../_user-guide_testing_unit-test-support.adoc | 200 ++++++++++
.../user-guide/_user-guide_troubleshooting.adoc | 13 +
...ide_troubleshooting_datanucleus-logging.adoc | 10 +
.../user-guide/_user-guide_wicket-viewer.adoc | 74 ++++
.../asciidoc/user-guide/_user-guide_xxx.adoc | 0
.../main/asciidoc/user-guide/user-guide.adoc | 28 +-
.../user-guide/user-guide_appendices.adoc | 8 -
.../user-guide_appendices_dev-env.adoc | 8 -
.../user-guide_appendices_dev-env_intellij.adoc | 362 -------------------
.../user-guide_background-execution.adoc | 40 --
.../user-guide_config-and-deployment.adoc | 93 -----
.../user-guide/user-guide_core-concepts.adoc | 20 -
...user-guide_core-concepts_apache-isis-vs.adoc | 14 -
...ser-guide_core-concepts_building-blocks.adoc | 234 ------------
...re-concepts_framework-provided-services.adoc | 82 -----
.../user-guide_core-concepts_principles.adoc | 73 ----
.../user-guide/user-guide_extending.adoc | 25 --
.../user-guide_extending_programming-model.adoc | 16 -
.../user-guide/user-guide_getting-started.adoc | 9 -
...ide_getting-started_simpleapp-archetype.adoc | 7 -
.../asciidoc/user-guide/user-guide_how-tos.adoc | 39 --
.../user-guide_how-tos_business-rules.adoc | 57 ---
.../user-guide_how-tos_class-structure.adoc | 173 ---------
.../user-guide_how-tos_contributed-members.adoc | 15 -
.../user-guide/user-guide_how-tos_crud.adoc | 18 -
.../user-guide_how-tos_derived-members.adoc | 33 --
...r-guide_how-tos_drop-downs-and-defaults.adoc | 30 --
...user-guide_how-tos_entity-relationships.adoc | 11 -
.../user-guide_how-tos_error-handling.adoc | 11 -
.../user-guide/user-guide_how-tos_i18n.adoc | 7 -
.../user-guide_how-tos_multi-tenancy.adoc | 7 -
...ser-guide_how-tos_persistence-lifecycle.adoc | 7 -
.../user-guide_how-tos_tips-n-tricks.adoc | 32 --
...uide_how-tos_tips-n-tricks_are-you-sure.adoc | 47 ---
...ips-n-tricks_overriding-jdo-annotations.adoc | 5 -
.../user-guide_how-tos_triggering-events.adoc | 136 -------
.../user-guide/user-guide_how-tos_ui-hints.adoc | 55 ---
...er-guide_integrating-with-other-systems.adoc | 11 -
.../user-guide/user-guide_isis-addons.adoc | 44 ---
.../user-guide/user-guide_reference.adoc | 25 --
...-guide_reference_applib-utility-classes.adoc | 144 --------
.../user-guide_reference_cmd-line-args.adoc | 31 --
...uide_reference_convenience-superclasses.adoc | 8 -
.../user-guide_reference_domain-services.adoc | 8 -
...-guide_reference_recognized-annotations.adoc | 8 -
...nce_recognized-configuration-properties.adoc | 28 --
...user-guide_reference_recognized-methods.adoc | 8 -
.../user-guide_reference_value-types.adoc | 14 -
.../user-guide_reference_web-xml.adoc | 8 -
.../user-guide/user-guide_restful-viewer.adoc | 35 --
.../asciidoc/user-guide/user-guide_testing.adoc | 22 --
...er-guide_testing_bdd-integ-test-support.adoc | 7 -
.../user-guide_testing_fake-data.adoc | 11 -
.../user-guide_testing_fixture-scripts.adoc | 65 ----
.../user-guide_testing_integ-test-support.adoc | 19 -
.../user-guide_testing_unit-test-support.adoc | 200 ----------
.../user-guide/user-guide_troubleshooting.adoc | 13 -
...ide_troubleshooting_datanucleus-logging.adoc | 10 -
.../user-guide/user-guide_wicket-viewer.adoc | 74 ----
110 files changed, 2571 insertions(+), 2535 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/08f6b036/adocs/documentation/README.md
----------------------------------------------------------------------
diff --git a/adocs/documentation/README.md b/adocs/documentation/README.md
index cd27474..00df8ba 100644
--- a/adocs/documentation/README.md
+++ b/adocs/documentation/README.md
@@ -39,9 +39,43 @@ Put the following information in your ~/.m2/settings.xml file
</server>
+Naming Conventions
+------------------
+
+<pre>
+xxx-xxx/xxx-xxx.adoc
+ _xxx-xxx_ppp-ppp.adoc
+ _xxx-xxx_qqq-qqq.adoc
+ _xxx-xxx_qqq-qqq_mmm-mmm.adoc
+ _xxx-xxx_qqq-qqq_nnn-nnn.adoc
+
+xxx-xxx/images/ppp-ppp
+ ppp-ppp
+
+xxx-xxx/resources/
+ ppp-ppp/
+ qqq-qqq/
+ qqq-qqq/mmm-mmm/
+ qqq-qqq/nnn-nnn/
+</pre>
+
+Build and Review (using Maven)
+-----------------------
+
+To build the documentation locally prior to release, simply use:
+
+ mvn site
+
+The site will be generated at `target/site/index.html`.
+
+Then open the browser on [localhost:8000](http://localhost:8000/).
+
+
Instant Preview (optional)
---------------
+
+
To build
download ruby 2.0.0
@@ -53,7 +87,7 @@ download ruby 2.0.0
download and install devkit for the Ruby 2.0 installation:
* [http://rubyinstaller.org/downloads/](rubyinstaller.org/downloads)
-* https://github.com/oneclick/rubyinstaller/wiki/Development-Kit
+* [https://github.com/oneclick/rubyinstaller/wiki/Development-Kit](Ruby DevKit installation)
install:
@@ -70,17 +104,8 @@ To review, recommend running a Python server:
python -m SimpleHTTPServer
-
-Build and Review (using Maven)
------------------------
-
-To build the documentation locally prior to release, simply use:
-
- mvn site
-
-The site will be generated at `target/site/index.html`.
-
-Then open the browser on [localhost:8000](http://localhost:8000/).
+Uses:
+*
Publish procedure
-----------------
http://git-wip-us.apache.org/repos/asf/isis/blob/08f6b036/adocs/documentation/listen.rb
----------------------------------------------------------------------
diff --git a/adocs/documentation/listen.rb b/adocs/documentation/listen.rb
index 20438d8..db058dc 100644
--- a/adocs/documentation/listen.rb
+++ b/adocs/documentation/listen.rb
@@ -7,73 +7,81 @@ require 'bundler/setup'
Bundler.require(:default)
+# https://github.com/guard/listen
-#https://github.com/guard/listen
+# to suppress
$CELLULOID_DEBUG=false
$CELLULOID_TEST=false
-#
-#guard 'shell' do
-# watch(/^.*\.adoc$/) {|m|
-# #Asciidoctor.convert_file(m[0], :in_place => true)
-# puts "Hello, Ruby!";
-# }
-#end
-scriptDir = File.absolute_path File.dirname(__FILE__)
+#scriptDir = File.absolute_path File.dirname(__FILE__)
templateDir = File.absolute_path '../template'
-targetDir = File.absolute_path 'target/site'
+srcBaseDir = File.absolute_path 'src/main/asciidoc'
+targetBaseDir = File.absolute_path 'target/site'
workingDir = Dir.pwd
-templateDirPath = Pathname.new templateDir
-targetDirPath = Pathname.new targetDir
-workingDirPath = Pathname.new workingDir
+#templatePath = Pathname.new templateDir
+srcBasePath = Pathname.new srcBaseDir
+targetBasePath = Pathname.new targetBaseDir
+workingPath = Pathname.new workingDir
-listener = Listen.to('src/foo', 'src/bar') do |modified, added, removed|
- unless modified.length==0
- modified.each { |file|
+#puts "workingDir: #{workingDir}"
+#puts "workingPath: #{workingPath}"
- dir = File.dirname file
- base = File.basename file
+#puts "srcBaseDir: #{srcBaseDir}"
+#puts "srcBasePath: #{srcBasePath}"
- #puts "modified #{file}"
- #puts "dir: #{dir}"
- #puts "base: #{base}"
+#puts "targetBaseDir: #{targetBaseDir}"
+#puts "targetBasePath: #{targetBasePath}"
- dirPath = Pathname.new dir
+puts ""
+puts ""
+puts ""
+puts "now monitoring..."
+puts ""
- srcRel = dirPath.relative_path_from workingDirPath
- #templateRel = dirPath.relative_path_from templateDirPath
-
- targetRelPath = targetDirPath + srcRel
- destinationDir = File.absolute_path targetRelPath.to_s
+def process(file)
+ puts "regenerating #{file}..."
+end
- Dir.chdir(dir)
+i=0
+listener = Listen.to('src/main/asciidoc/user-guide') do |modified, added, removed|
+ unless modified.length==0
+ modified.each { |file|
- #puts "dir: #{dir}"
- #puts "file: #{file}"
- #puts "templateDir: #{templateDir}"
- #puts "destinationDir: #{destinationDir}"
+ srcDir = File.dirname file
+ srcBase = File.basename file
- FileUtils.mkdir_p destinationDir
+ srcSplit = srcBase.split('_')
+ if srcSplit[0].length==0 then
+ regenerate = srcSplit[1] + ".adoc"
+ else
+ regenerate = srcBase
+ end
- #attributes = {:imagesdir => '', :toc => 'right', :icons => 'font', :source-highlighter => 'coderay'}
+ srcPath = Pathname.new srcDir
+ srcRel = srcPath.relative_path_from srcBasePath
+ targetRelPath = targetBasePath + srcRel
+ targetRelDir = File.absolute_path targetRelPath.to_s
- #Asciidoctor.convert_file(file, :in_place => true, :backend => 'html', :eruby => 'erb', :template_dir => templateDir, :destination_dir => targetRelDir, :attributes => attributes)
+ #puts "regenerate: #{regenerate}"
+ #puts "targetRelPath: #{targetRelPath}"
+ #puts "targetRelDir: #{targetRelDir}"
- #Asciidoctor.convert_file(file, :in_place => true, :backend => 'html', :eruby => 'erb', :template_dir => templateDir, :destination_dir => targetRelDir)
+ process regenerate
+ Dir.chdir srcDir
+ FileUtils.mkdir_p targetRelDir
- cmd = "asciidoctor #{file} --backend html --eruby erb --template-dir '#{templateDir}' --destination-dir='#{destinationDir}' -a imagesdir='' -a toc=right -a icons=font -a source-highlighter=coderay"
+ #cmd = "asciidoctor #{regenerate} --backend html --eruby erb --template-dir '#{templateDir}' --destination-dir='#{targetRelDir}' -a imagesdir='' -a toc=right -a icons=font -a source-highlighter=coderay"
+ cmd = "asciidoctor #{regenerate} --backend html --eruby erb --template-dir '#{templateDir}' --destination-dir='#{targetRelDir}' -a imagesdir='' -a toc=right -a icons=font"
+ i=i+1
puts ""
- puts cmd
-
-#Asciidoctor.convert_file file, :in_place => true, :backend => 'html', :eruby => 'erb', :template_dir => templateDir, :destination_dir => targetRelDir
-
+ puts "#{i}: #{cmd}"
system cmd
- Dir.chdir(workingDir)
+ Dir.chdir workingDir
}
end
unless added.length==0
http://git-wip-us.apache.org/repos/asf/isis/blob/08f6b036/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices.adoc
new file mode 100644
index 0000000..87eebb0
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices.adoc
@@ -0,0 +1,8 @@
+= Appendices
+: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/
+
+IMPORTANT: TODO
+
+include::_user-guide_appendices_dev-env.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/08f6b036/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_dev-env.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_dev-env.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_dev-env.adoc
new file mode 100644
index 0000000..f9347cd
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_dev-env.adoc
@@ -0,0 +1,8 @@
+= Setting up a Development Environment
+: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/
+
+IMPORTANT: TODO
+
+include::_user-guide_appendices_dev-env_intellij.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/08f6b036/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_dev-env_intellij.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_dev-env_intellij.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_dev-env_intellij.adoc
new file mode 100644
index 0000000..2a2b07d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_dev-env_intellij.adoc
@@ -0,0 +1,362 @@
+= 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
+
+
+
+## Setting up and Configurating IntelliJ
+
+### Download and Install
+
+WARNING: This doc used IntelliJ Community Edition 14.1.1, with screenshots taken for Windows. If you're a MacOS user, I'm sure you can adapt :-)
+
+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/intellij010-installing/010-welcome-page.png[width="400px"]
+
+Choose the location to install the IDE:
+
+.IntelliJ Installation Wizard - Choose Location
+image::{_imagesdir}appendices/dev-env/intellij010-installing/020-choose-location.png[width="400px"]
+
+Adjust any installation options as you prefer:
+
+.IntelliJ Installation Wizard - Installation Options
+image::{_imagesdir}appendices/dev-env/intellij010-installing/030-installation-options.png[width="400px"]
+
+and the start menu:
+
+.IntelliJ Installation Wizard - Start Menu Folder
+image::{_imagesdir}appendices/dev-env/intellij010-installing/040-start-menu-folder.png[width="400px"]
+
+and finish up the wizard:
+
+.IntelliJ Installation Wizard - Completing the Wizard
+image::{_imagesdir}appendices/dev-env/intellij010-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/intellij010-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/intellij010-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/intellij020-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/intellij020-create-new-project/020-java-project-setup-jdk.png[width="600px"]
+
+We therefore need to specify the JDK.
+
+NOTE: at the time of writing Isis supports only Java 7; Java 8 is scheduled for support in Isis v1.9.0
+
+
+.IntelliJ Create New Java Project - Select the JDK
+image::{_imagesdir}appendices/dev-env/intellij020-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/intellij020-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/intellij020-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 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/intellij030-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/intellij030-import-settings/020-select-all.png[width="300px"]
+
+And then restart:
+
+.IntelliJ Import Settings - Restart
+image::{_imagesdir}appendices/dev-env/intellij030-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/intellij040-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/intellij040-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/intellij040-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/intellij040-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
++
+Provides better visualization of dependency trees (similar to Eclipse)
+* 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/intellij050-some-plugins/020-some-plugins-confirmation.png[width="400px"]
+
+
+
+
+## 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 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/intellij100-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/intellij100-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/intellij100-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 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 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/intellij100-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/intellij100-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 Isis core from `.m2/repository`):
+
+.IntelliJ Maven Module Management - Updated Projects Window
+image::{_imagesdir}appendices/dev-env/intellij100-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/intellij110-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/intellij110-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/intellij110-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/intellij110-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/intellij110-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
+
+IMPORTANT: TODO
+
+### Setting up JRebel
+
+IMPORTANT: TODO
http://git-wip-us.apache.org/repos/asf/isis/blob/08f6b036/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_background-execution.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_background-execution.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_background-execution.adoc
new file mode 100644
index 0000000..3221cde
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_background-execution.adoc
@@ -0,0 +1,40 @@
+= Background Execution
+: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/
+
+IMPORTANT: TODO
+
+
+
+## JDO Implementation
+
+The `BackgroundCommandExecutionFromBackgroundCommandServiceJdo` is a concrete subclass of link:../../../../reference/non-ui/background-command-execution.html[BackgroundCommandExecution]. The intended use is for the class to be instantiated regularly (eg every 10 seconds) by a scheduler such as http://quartz.org[Quartz]) to poll for `Command`s to be executed, and then execute them.
+
+As you might imagine, this implementation queries for `Command`s persisted by the JDO implementations of link:../services/command-service-jdo.html[CommandService] and link:../services/background-command-service-jdo.html[BackgroundCommandService], using the `BackgroundCommandServiceJdoRepository`.
+
+The diagram below shows the inheritance hierarchy for this class:
+
+.Inheritance Hierarchy for `BackgroundCommandExecution`
+image::http://yuml.me/363b335f[width="600px"]
+
+
+[NOTE]
+====
+In 1.6.0 this implementation was released as part of `org.apache.isis.core:isis-module-command-jdo:1.6.0` and was also released as an http://github.com/isisaddons/isis-module-command[Isis addon] module.
+
+In 1.7.0+ only the http://github.com/isisaddons/isis-module-command[Isis addon] (non-ASF) implementation is released.
+====
+
+
+## Footnote
+
+NOTE: The diagrams on this page were created using http://yuml.me[yuml.me].
+
+[source]
+.DSL (http://yuml.me/edit/363b335f[yuml.me/363b335f]):
+----
+[AbstractIsisSessionTemplate|#doExecute()]^-[BackgroundCommandExecution|#findBackgroundCommandsToExecute()]
+[BackgroundCommandExecution]^-[BackgroundCommandExecutionFromBackgroundCommandServiceJdo]
+[BackgroundCommandExecutionFromBackgroundCommandServiceJdo]->injected[BackgroundCommandServiceJdoRepository|findBackgroundCommandsNotYetStarted()]
+----
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/08f6b036/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_config-and-deployment.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_config-and-deployment.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_config-and-deployment.adoc
new file mode 100644
index 0000000..55621d5
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_config-and-deployment.adoc
@@ -0,0 +1,93 @@
+= Configuration and Deployment
+: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/
+
+IMPORTANT: TODO
+
+## Configuration Files
+
+Isis' own configuration properties are simple key-value pairs, typically held in in the `WEBINF/isis.properties` file.
+
+## Configuring the Webapp
+
+When running an Isis webapp, configuration properties are read from configuration files held in the `WEB-INF` directory.
+
+### Isis configuration
+
+The `WEBINF/isis.properties` file is always read and must exist.
+
+In addition, the following other properties are searched for and if present also read:
+
+* `viewer_wicket.properties` - if the Wicket UI (viewer) is in use
+* `viewer_restfulobjects.properties` - if the Restful Objects REST API (viewer) is in use
+* `viewer.properties` - for any shared UI configuration
+* `persistor_datanucleus.properties` - assuming the JDO/DataNucleus objectstore is in use
+* `persistor.properties` - for any shared objectstore configuration. This typically is used to hold `JDBC` ``URL``s
+
+### Shiro configuration
+
+`WEB-INF/shiro.ini`
+
+### Configuring Isis to use Shiro
+
+For more on some specific use cases, see <<Configuring Shiro>>
+
+
+### JDO/DataNucleus configuration
+
+Any Isis properties with the prefix `isis.persistor.datanucleus.impl` are passed through directly to the JDO/DataNucleus objectstore (with the prefix stripped off, of course).
+
+DataNucleus will itself search for additional XML mapping files, eg `mappings.jdo`. These an be used to override any annotations of annotated entities.
+
+## Configuring the Integration Tests
+
+Integration tests are configured programmatically, with a default set of properties to bootstrap the JDO/DataNucleus objectstore using an HSQLDB in-memory database.
+
+These can be overridden by subclassing `IsisConfigurationForJdoIntegTests`.
+
+
+
+## Isis Configuration Properties
+
+### Deployment Types
+
+
+
+## Configuring Shiro
+
+### Configuring Shiro to use LDAP
+
+### Format of Isis Permissions
+
+
+
+## Configuring DataNucleus
+
+### persistence.xml file
+
+### Eagerly Registering Entity Types
+
+### Disabling persistence-by-reachability
+
+### Transaction Management
+
+
+## Deployment
+
+### Externalized Configuration
+
+### JVM Args
+
+### Using a JNDI Datasource
+
+
+
+## NoSQL Support
+
+### Deploying on the Google App Engine
+
+### Using Neo4J
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/08f6b036/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts.adoc
new file mode 100644
index 0000000..8078d8d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts.adoc
@@ -0,0 +1,20 @@
+= Core Concepts
+: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/
+
+IMPORTANT: TODO
+
+include::_user-guide_core-concepts_principles.adoc[leveloffset=+1]
+
+include::_user-guide_core-concepts_apache-isis-vs.adoc[leveloffset=+1]
+
+include::_user-guide_core-concepts_building-blocks.adoc[leveloffset=+1]
+
+include::_user-guide_core-concepts_framework-provided-services.adoc[leveloffset=+2]
+
+
+## Honouring the Single Responsibility Principle
+
+### Behaviourally Complete vs Contributions
+
http://git-wip-us.apache.org/repos/asf/isis/blob/08f6b036/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_apache-isis-vs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_apache-isis-vs.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_apache-isis-vs.adoc
new file mode 100644
index 0000000..c64344a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_apache-isis-vs.adoc
@@ -0,0 +1,14 @@
+= Apache Isis vs ...
+: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/
+
+IMPORTANT: TODO
+
+## vs Spring
+
+## vs JEE
+
+## vs Grails
+
+## vs Angular
http://git-wip-us.apache.org/repos/asf/isis/blob/08f6b036/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_building-blocks.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_building-blocks.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_building-blocks.adoc
new file mode 100644
index 0000000..50044a0
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_building-blocks.adoc
@@ -0,0 +1,234 @@
+= Building Blocks
+: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/
+
+IMPORTANT: TODO
+
+## A MetaModel with Explicit and Inferred Semantics
+
+* use of annotations
+** reuse JEE annotations where possible
+* layout hints are overridable, to avoid restarting the app/speed up feedback
+
+
+## Domain Objects and Domain Services
+
+* domain model
+** domain objects
+*** domain entity
+*** view model
+** domain service
+** value type
+
+Anything else can be (should be) ignored by annotating with `@Programmatic`.
+
+
+
+## Properties, Collections and Actions
+
+
+
+## Domain Entities vs View Models
+
+`@DomainObject(nature=...)`
+
+
+
+## Domain Services
+
+Domain services consist of a set of logically grouped actions, and as such follow the same conventions as for entities. However, a service cannot have (persisted) properties, nor can it have (persisted) collections.
+
+Domain services are instantiated once and once only by the framework, and are used to centralize any domain logic that does not logically belong in a domain entity or value. Isis will automatically inject services into every domain entity that requests them, and into each other.
+
+For convenience you can inherit from AbstractService or one of its subclasses, but this is not mandatory.
+
+### Domain Services vs View Services
+
+`@DomainService(nature=...)`
+
+.Factories, Repositories and Services
+****
+A distinction is sometimes made between a factory (that creates object) and a repository (that is used to find existing objects). You will find them discussed separately in Evans' link:Domain Driven Design[http://books.google.com/books/about/Domain_Driven_Design.html?id=hHBf4YxMnWMC], for example.
+
+In Apache Isis these are all implemented as domain services. Indeed, it is quite common to have a domain service that acts as both a factory and a repository.
+****
+
+## Value Objects (Primitives)
+
+
+
+## Contributions
+
+
+
+## Event Bus
+
+
+
+
+
+
+=== Registering domain services
+
+As noted link:../../how-tos/how-to-09-010-How-to-register-domain-services,-repositories-and-factories.html[elsewhere], domain services (which includes repositories and factories) should be registered in the `isis.properties` configuration file, under `isis.services` key (a comma-separated list):
+
+For example:
+
+[source]
+----
+isis.services = com.mycompany.myapp.employee.Employees\,
+ com.mycompany.myapp.claim.Claims\,
+ ...
+----
+
+This will then result in the framework instantiating a single instance of each of the services listed.
+
+If all services reside under a common package, then the `isis.services.prefix` can specify this prefix:
+
+[source]
+----
+isis.services.prefix = com.mycompany.myapp
+isis.services = employee.Employees,\
+ claim.Claims,\
+ ...
+----
+
+This is quite rare, however; you will often want to use default implementations of domain services that are provided by the framework and so will not reside under this prefix.
+
+Examples of framework-provided services (as defined in the applib) can be found referenced from the main link:../../documentation.html[documentation] page. They include clock, auditing, publishing, exception handling, view model support, snapshots/mementos, and user/application settings management.
+
+=== Service scopes
+
+By default all domain services are considered to be singletons, and thread-safe.
+
+Sometimes though a service's lifetime is applicable only to a single request; in other words it is request-scoped.
+
+The CDI annotation `@javax.enterprise.context.RequestScoped` is used to indicate this fact:
+
+[source]
+----
+ @javax.enterprise.context.RequestScoped
+ public class MyService extends AbstractService {
+ ...
+ }
+----
+
+The framework provides a number of request-scoped services; these can be found referenced from the main link:../../documentation.html[documentation] page. They include scratchpad service, query results caching, and support for co-ordinating bulk actions.
+
+=== (Suppressing) contributed actions
+
+Any n-parameter action provided by a service will automatically be contributed to the list of actions for each of its (entity) parameters. From the viewpoint of the entity the action is called a contributed action.
+
+For example, given a service:
+
+[source]
+----
+public interface Library {
+ public Loan borrow(Loanable l, Borrower b);
+}
+----
+
+and the entities:
+
+[source]
+----
+public class Book implements Loanable { ... }y
+----
+
+and
+
+[source]
+----
+public class LibraryMember implements Borrower { ... }
+----
+
+then the `borrow(...)` action will be contributed to both `Book` and to `LibraryMember`.
+
+This is an important capability because it helps to decouple the concrete classes from the services.
+
+If necessary, though, this behaviour can be suppressed by annotating the service action with `@org.apache.isis.applib.annotations.NotContributed`.
+
+For example:
+
+[source]
+----
+public interface Library {
+ @NotContributed
+ public Loan borrow(Loanable l, Borrower b);
+}
+----
+
+If annotated at the interface level, then the annotation will be inherited by every concrete class. Alternatively the annotation can be applied at the implementation class level and only apply to that particular implementation.
+
+Note that an action annotated as being `@NotContributed` will still appear in the service menu for the service. If an action should neither be contributed nor appear in service menu items, then simply annotate it as `@Hidden`.
+
+=== (Suppressing) service menu items
+
+By default every action of a service (by which we also mean repositories and factories) will be rendered in the viewer, eg as a menu item for that service menu. This behaviour can be suppressed by annotating the action using `@org.apache.isis.applib.annotations.NotInServiceMenu`.
+
+For example:
+
+[source]
+----
+public interface Library {
+ @NotInServiceMenu
+ public Loan borrow(Loanable l, Borrower b);
+}
+----
+
+Note that an action annotated as being `@NotInServiceMenu` will still be contributed. If an action should neither be contributed nor appear in service menu items, then simply annotate it as `@Hidden`.
+
+Alternatively, this can be performed using a supporting method:
+
+[source]
+----
+public class LibraryImpl implements Library {
+ public Loan borrow(Loanable l, Borrower b) { ... }
+ public boolean notInServiceMenuBorrow() { ... }
+}
+----
+
+=== (Suppressing) service menus
+
+If none of the service menu items should appear, then the service itself should be annotated as `@Hidden`.
+
+For example:
+
+[source]
+----
+@Hidden
+public interface EmailService {
+ public void sendEmail(String to, String from, String subject, String body);
+ public void forwardEmail(String to, String from, String subject, String body);
+}
+----
+
+=== Initializing Services
+
+Services can optionally declare lifecycle callbacks to initialize them (when the app is deployed) and to shut them down (when the app is undeployed).
+
+An Isis session _is_ available when initialization occurs (so services can interact with the object store, for example).
+
+==== Initialization
+
+The framework will call any `public` method annotated with `@javax.annotation.PostConstruct` and with either no arguments of an argument of type `Map<String,String>`:
+
+or
+
+In the latter case, the framework passes in the configuration (`isis.properties` and any other component-specific configuration files).
+
+==== Shutdown
+
+Shutdown is similar; the framework will call any method annotated with `@javax.annotation.PreDestroy`:
+
+=== The getId() method
+
+Optionally, a service may provide a `getId()` method:
+
+[source]
+----
+public String getId()
+----
+
+This method returns a logical identifier for a service, independent of its implementation. Currently it used only by perspectives, providing a label by which to record the services that are available for a current user's profile. <!--See ? for more about profiles and perspectives.-->
http://git-wip-us.apache.org/repos/asf/isis/blob/08f6b036/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_framework-provided-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_framework-provided-services.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_framework-provided-services.adoc
new file mode 100644
index 0000000..36011ea
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_framework-provided-services.adoc
@@ -0,0 +1,82 @@
+= Framework-provided Services
+: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/
+
+IMPORTANT: TODO
+
+## API vs SPI
+
+Most framework domain services are API: they exist to provide support functionality to the application's domain objects and services. In this case an implementation of the service will be available, either by Apache Isis itself or by Isis Addons (non ASF).
+
+Some framework domain services are SPI: they exist primarily so that the application can influence the framework's behaviour. In these cases there is (usually) no default implementation; it is up to the application to provide an implementation.
+
+## Autoregistration of Domain services
+
+Where a domain service has an implementation, it is (almost always) automatically registered just by virtue of being on the `CLASSPATH`.
+
+The one exception is <<ExceptionRecognizer>>.
+
+It is possible to replacing automatically-registered domain services.
+
+
+## Overview of Domain Services
+
+Unless indicated as SPI, each of the following has an implementation in Isis core.
+
+### `DomainObjectContainer`
+
+### `ClockService`
+
+### `IsisSupportJdo`
+
+### `ExceptionRecognizer`
+
+### `WrapperFactory`
+
+### `EventBusService`
+
+### Commands/Background
+
+#### `CommandContext`
+
+#### `BackgroundService`
+
+### Information Sharing
+
+#### `ScratchPad`
+
+#### `ActionInvocationContext`
+
+#### `QueryResultsCache`
+
+### `EmailService`
+
+### UserManagement
+
+#### `UserProfileService` (SPI)
+
+#### `UserRegistrationService` (SPI)
+
+#### `EmailNotificationService`
+
+
+### Bookmarks and Mementos
+
+#### `BookmarkService`
+
+#### `MementoService`
+
+#### `DeepLinkService`
+
+#### `XmlSnapshotService`
+
+
+
+
+
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/08f6b036/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_principles.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_principles.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_principles.adoc
new file mode 100644
index 0000000..9bf2143
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_principles.adoc
@@ -0,0 +1,76 @@
+= Principles
+: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/
+
+IMPORTANT: TODO
+
+## Domain-Driven Design
+
+### Ubiquitous Language
+
+IMPORTANT: TODO
+
+yada yada
+
+
+## Naked Objects Pattern
+
+[TIP]
+.Object Interface Mapping
+====
+Just as an ORM (such as link:http://datanucleus.org[DataNucleus] or link:http:hibernate.org[Hibernate]) maps domain entities to a database, you can think of Naked Objects as an OIM - mapping domain objects to a user interface.
+====
+
+* multiple UIs.
+
+
+
+## Hexagonal Architecture
+
+Originally described by Alistair Cockburn, the link:http://alistair.cockburn.us/Hexagonal+architecture[Hexagonal Architecture] ...
+
+[TIP]
+====
+The hexagonal architecture is also known as the link:http://c2.com/cgi/wiki?PortsAndAdaptersArchitecture:[Ports and Adapters] architecture or (less frequently) as the link:http://jeffreypalermo.com/blog/the-onion-architecture-part-1/[Onion] architecture.
+====
+
+
+
+## Decoupled Modules
+
+Using:
+
+* dependency injection of services
+* OO design techniques, eg dependency inversion principle
+* an in-memory event bus
+* applib
+
+.Aspect Oriented
+****
+Although not implemented using an aspect-oriented language such as AspectJ, Isis takes considerable inspiration from AOP concepts.
+
+For example, the UI visualization automatically provided by Isis can be thought of (and is!) treating the UI as a cross-cutting concern.
+
+Isis' also has support for traits/mixins through its <<Contributions>>. This allows functionality from one class (a domain service) to be rendered as if it belongs to another (a domain object).
+
+
+* aspect-oriented design, such as traits/mix-ins (see <<Contributions>>) and interceptors and UI visualization as a cross-cutting concern
+****
+
+
+
+## Focuses on its Key Responsibilities
+
+* Isis is at heart a metamodel with runtime, and coordinates interations using an AOP set of principles
+* Apache Isis vs Isis Addons
+* Apache Isis vs Shiro vs DataNucleus
+
+
+
+## Testable Applications
+
+While Apache Isis can be used (very effectively) for simple CRUD-style applications, it is also intended to be used for complex business domains. Ensuring that the business logic in such applications is correct means that the framework must (and does) provide robust testing support, both for developer-level unit testing and business-level (end-to-end) integration testing.
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/08f6b036/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending.adoc
new file mode 100644
index 0000000..ac791b6
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending.adoc
@@ -0,0 +1,25 @@
+= Extending
+: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/
+
+IMPORTANT: TODO
+
+include::_user-guide_extending_programming-model.adoc[leveloffset=+1]
+
+
+
+## Extending the Wicket viewer
+
+### Writing a custom theme
+
+### Replacing page elements
+
+### Custom pages
+
+
+
+
+## Extending the Restful viewer
+
+### Custom Representations
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/08f6b036/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_programming-model.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_programming-model.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_programming-model.adoc
new file mode 100644
index 0000000..c1d7d89
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_programming-model.adoc
@@ -0,0 +1,16 @@
+= Extending the Programming Model
+: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/
+
+IMPORTANT: TODO
+
+## Disallowing deprecated annotations
+
+## Custom validator
+
+## Finetuning the Programming Model
+
+## Layout metadata reader
+
+## Listener to create DB schema objects
http://git-wip-us.apache.org/repos/asf/isis/blob/08f6b036/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_getting-started.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_getting-started.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_getting-started.adoc
new file mode 100644
index 0000000..5c05a27
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_getting-started.adoc
@@ -0,0 +1,9 @@
+= Getting Started
+: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/
+
+IMPORTANT: TODO
+
+include::_user-guide_getting-started_simpleapp-archetype.adoc[leveloffset=+1]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/08f6b036/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_getting-started_simpleapp-archetype.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_getting-started_simpleapp-archetype.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_getting-started_simpleapp-archetype.adoc
new file mode 100644
index 0000000..1decbc9
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_getting-started_simpleapp-archetype.adoc
@@ -0,0 +1,7 @@
+= SimpleApp Archetype
+: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/
+
+IMPORTANT: TODO
+
http://git-wip-us.apache.org/repos/asf/isis/blob/08f6b036/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos.adoc
new file mode 100644
index 0000000..9f9b933
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos.adoc
@@ -0,0 +1,39 @@
+= How-tos
+: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/
+
+IMPORTANT: TODO
+
+include::_user-guide_how-tos_class-structure.adoc[leveloffset=+1]
+
+include::_user-guide_how-tos_entity-relationships.adoc[leveloffset=+1]
+
+include::_user-guide_how-tos_contributed-members.adoc[leveloffset=+1]
+
+include::_user-guide_how-tos_derived-members.adoc[leveloffset=+1]
+
+include::_user-guide_how-tos_crud.adoc[leveloffset=+1]
+
+include::_user-guide_how-tos_ui-hints.adoc[leveloffset=+1]
+
+include::_user-guide_how-tos_business-rules.adoc[leveloffset=+1]
+
+include::_user-guide_how-tos_drop-downs-and-defaults.adoc[leveloffset=+1]
+
+include::_user-guide_how-tos_triggering-events.adoc[leveloffset=+1]
+
+include::_user-guide_how-tos_tips-n-tricks.adoc[leveloffset=+1]
+
+include::_user-guide_how-tos_error-handling.adoc[leveloffset=+1]
+
+include::_user-guide_how-tos_i18n.adoc[leveloffset=+1]
+
+include::_user-guide_how-tos_multi-tenancy.adoc[leveloffset=+1]
+
+include::_user-guide_how-tos_persistence-lifecycle.adoc[leveloffset=+1]
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/08f6b036/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_business-rules.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_business-rules.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_business-rules.adoc
new file mode 100644
index 0000000..c78f198
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_business-rules.adoc
@@ -0,0 +1,57 @@
+= Business Rules
+: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/
+
+IMPORTANT: TODO
+
+## Visibility ("see it")
+
+### Hide a Property
+
+### Hide a Collection
+
+### Hide an Action
+
+### Hide a Contributed Property, Collection or Action
+
+### All Members Hidden
+
+## Usability ("use it")
+
+### Disable a Property
+
+### Disable a Collection
+
+### Disable an Action
+
+### Disable a Contributed Property, Collection or Action
+
+### All Members Unmodifiable (Disabling the Edit Button)
+
+Sometimes an object is unmodifiable.
+
+In the Wicket viewer this means disabling the edit button.
+
+#### Declarative
+
+`@DomainObject(editing=...)`
+
+#### Imperative
+
+
+
+## Validity ("do it")
+
+### Validate (change to) a Property
+
+### Validate (adding or removing from) a Collection
+
+### Validate (arguments to invoke) an Action
+
+### Validating a Contributed Property, Collection or Action
+
+### Declarative validation using `@MustSatisfy`
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/08f6b036/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure.adoc
new file mode 100644
index 0000000..7468105
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure.adoc
@@ -0,0 +1,173 @@
+= Class Structure
+: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/
+
+IMPORTANT: TODO
+
+
+
+
+
+## Class Definition
+
+Classes are defined both to Isis and (if any entity) also to JDO/DataNucleus.
+
+
+
+
+We use Java packages as a way to group related domain objects together; the package name forms a namespace. We can then reason about all the classes in that package/namespace as a single unit.
+
+In the same way that Java packages act as a namespace for domain objects, it's good practice to map domain entities to their own (database) schemas.
+
+[NOTE]
+====
+As of 1.9.0-SNAPSHOT, all the IsisAddons modules (not ASF) define their own (database) schemas.
+
+For example:
+
+[source,java]
+----
+@javax.jdo.annotations.PersistenceCapable( ...
+ schema = "isissecurity",
+ table = "ApplicationUser")
+public class ApplicationUser ... { ... }
+----
+
+and
+
+[source,java]
+----
+@javax.jdo.annotations.PersistenceCapable( ...
+ schema = "isisaudit",
+ table="AuditEntry")
+public class AuditEntry ... { ... }
+----
+
+This results in CREATE TABLE statements such as:
+
+[source,sql]
+----
+CREATE TABLE isissecurity."ApplicationUser" (
+ ...
+)
+----
+
+and
+
+[source,sql]
+----
+CREATE TABLE isisaudit."AuditEntry" (
+ ...
+)
+----
+
+If you don't want to use schemas, then note that you can override the `@PersistenceCapable` annotation by providing XML annotations (`mappings.jdo` files).
+====
+
+
+
+
+## Property
+
+
+### Value vs Reference Types
+
+
+The annotations for mapping value types tend to be different for properties vs action parameters, because JDO annotations are only valid on properties. The table in <<Mapping Value Types>> provides a handy reference for the each.
+
+### Optional Properties
+
+
+### Mapping String (Length)
+
+### Mapping JODA Dates
+
+### Mapping BigDecimals
+
+### Mapping Blobs
+
+### Mapping Passwords
+
+
+[NOTE]
+.Lazy Loading
+====
+
+====
+
+
+
+
+## Collection
+
+
+[NOTE]
+====
+While Isis support collections of references, the framework (currently) does not support collections of values. That is, it isn't possible to define a collection of type `Set<String>`.
+
+Or, actually, you can, because that is a valid mapping supported by JDO/DataNucleus . However, Isis has no default visualization.
+
+The workaround is to mark the collection as `@Programmatic`, as described in <<Ignoring Methods>>. This ensures that the collection is ignored by Isis.
+====
+
+
+
+## Actions
+
+[NOTE]
+====
+While Isis support actions whose parameters' types are scalar (values such as `String`, `int`, or references such as `Customer`), the framework (currently) does not support parameter types that are collections or maps.
+
+The workaround is to mark the collection as `@Programmatic`, as described in <<Ignoring Methods>>. This ensures that the collection is ignored by Isis.
+====
+
+
+### Optional Action Argument
+
+## String Length Of Action Parameter
+
+## BigDecimal Precision Of Action Parameter
+
+### Mapping String (Length)
+
+### Mapping JODA Dates
+
+### Mapping BigDecimals
+
+### Mapping Blobs
+
+
+
+
+
+## Mapping Value Types
+
+table of:
+.
+|value type
+|property
+|action parameter
+
+|string (length)
+|
+|
+
+|big decimal (precision)
+|
+|
+
+|Isis blob
+|
+|
+
+|optional
+|`@Column(allowsNull="true")`
+|`ParameterLayout(optionality=Optionality.OPTIONAL`) or `@Optional`
+
+
+## Ignoring Methods
+
+Sometimes you want to define a `public` method on a domain object that is not intended to be rendered in Isis' UI.
+
+To exclude such methods, use the `@Programmatic` annotation.
http://git-wip-us.apache.org/repos/asf/isis/blob/08f6b036/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_contributed-members.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_contributed-members.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_contributed-members.adoc
new file mode 100644
index 0000000..394cdfb
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_contributed-members.adoc
@@ -0,0 +1,15 @@
+= Contributed Members
+: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/
+
+IMPORTANT: TODO
+
+## Contributed Action
+
+## Contributed Property
+
+## Contributed Collection
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/08f6b036/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_crud.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_crud.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_crud.adoc
new file mode 100644
index 0000000..229e2c6
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_crud.adoc
@@ -0,0 +1,18 @@
+= Object Management (CRUD)
+: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/
+
+IMPORTANT: TODO
+
+## Injecting Services
+
+## Instantiating and Persisting Objects
+
+## Finding Objects
+
+## Deleting Objects
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/08f6b036/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_derived-members.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_derived-members.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_derived-members.adoc
new file mode 100644
index 0000000..c0e8e8e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_derived-members.adoc
@@ -0,0 +1,33 @@
+= Derived Members
+: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/
+
+IMPORTANT: TODO
+
+## Derived Property
+
+## Derived Collection
+
+
+.Inlining query-only repository action
+****
+While derived properties and derived collections typically "walk the graph" to associated objects, there is nothing to prevent the returned value being the result of invoking a repository (domain service) action.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ ...
+ public List<Order> getMostRecentOrders() {
+ return orderRepo.findMostRecentOrders(this, 5);
+ }
+}
+----
+****
+
+## Trigger on property change
+
+## Trigger on collection change
+
http://git-wip-us.apache.org/repos/asf/isis/blob/08f6b036/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_drop-downs-and-defaults.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_drop-downs-and-defaults.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_drop-downs-and-defaults.adoc
new file mode 100644
index 0000000..643c705
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_drop-downs-and-defaults.adoc
@@ -0,0 +1,30 @@
+= Drop Downs and Defaults
+: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/
+
+IMPORTANT: TODO
+
+## For Properties
+
+### Choices for Property
+
+### Auto-complete for property
+
+### Default for property
+
+## For Action Parameters
+
+### Choices for action parameter
+
+### Dependent choices for action params
+
+### Auto-complete for action param
+
+### Default for action param
+
+## For both Properties and Action Parameters
+
+### Drop-down for limited number of instances
+
+### Auto-complete (repository-based)
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/08f6b036/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_entity-relationships.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_entity-relationships.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_entity-relationships.adoc
new file mode 100644
index 0000000..b7f7d7f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_entity-relationships.adoc
@@ -0,0 +1,11 @@
+= Entity Relationships
+: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/
+
+IMPORTANT: TODO
+
+## Mapping Mandatory and Optional Properties
+
+## Managed 1-m bidirectional relationships
+
http://git-wip-us.apache.org/repos/asf/isis/blob/08f6b036/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_error-handling.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_error-handling.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_error-handling.adoc
new file mode 100644
index 0000000..8564571
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_error-handling.adoc
@@ -0,0 +1,11 @@
+= Error Handling
+: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/
+
+IMPORTANT: TODO
+
+## Raise message/errors to users
+
+
+## Exception Recognizers
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/08f6b036/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_i18n.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_i18n.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_i18n.adoc
new file mode 100644
index 0000000..adc5590
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_i18n.adoc
@@ -0,0 +1,7 @@
+= i18n
+: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/
+
+IMPORTANT: TODO
+
http://git-wip-us.apache.org/repos/asf/isis/blob/08f6b036/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_multi-tenancy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_multi-tenancy.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_multi-tenancy.adoc
new file mode 100644
index 0000000..4f99008
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_multi-tenancy.adoc
@@ -0,0 +1,7 @@
+= Multi-tenancy
+: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/
+
+IMPORTANT: TODO
+