You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by mg...@apache.org on 2015/12/13 15:31:08 UTC

[01/52] [abbrv] isis git commit: ISIS-1234: extracted configuration guide from rg.adoc.

Repository: isis
Updated Branches:
  refs/heads/ISIS-1224-select2-v4 bd2a54bc0 -> 7b5bfad70


http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_UserRegistrationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_UserRegistrationService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_UserRegistrationService.adoc
index f334080..eaf5d63 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_UserRegistrationService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_UserRegistrationService.adoc
@@ -95,4 +95,4 @@ The most common use case is to allow users to sign-up through Apache Isis' Wicke
 * xref:rgsvc.adoc#_rgsvc-spi_EmailNotificationService[`EmailNotificationService`]
 * `UserRegistrationService` (this service)
 
-The `EmailService` in particular requires additional xref:rg.adoc#_rg_runtime_configuring-core[configuration properties] to specify the external SMTP service.
\ No newline at end of file
+The `EmailService` in particular requires additional xref:rgcfg.adoc#_rgcfg_configuring-core[configuration properties] to specify the external SMTP service.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_action-icons-and-css.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_action-icons-and-css.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_action-icons-and-css.adoc
index 892fd3b..2bf891d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_action-icons-and-css.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_action-icons-and-css.adoc
@@ -21,7 +21,7 @@ Alternatively, you can specify these hints dynamically in the xref:ug.adoc#_ug_o
 
 Rather than annotating every action with xref:rgant.adoc#_rgant-ActionLayout_cssClassFa[`@ActionLayout#cssClassFa()`] and xref:rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`] you can instead specify the UI hint globally using regular expressions.
 
-The xref:rg.adoc#_rg_runtime_configuring-core[configuration property] `isis.reflector.facet.cssClassFa.patterns` is a comma separated list of key:value pairs, eg:
+The xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.reflector.facet.cssClassFa.patterns` is a comma separated list of key:value pairs, eg:
 
 [source,ini]
 ----
@@ -40,7 +40,7 @@ isis.reflector.facet.cssClassFa.patterns=\
 where the key is a regex matching action names (eg `create.*`) and the value is a link:http://fortawesome.github.io/Font-Awesome/icons/[font-awesome] icon name (eg `fa-plus`) to be applied (as per `@CssClassFa()`) to all action members matching the regex.
 
 
-Similarly, the xref:rg.adoc#_rg_runtime_configuring-core[configuration property] `isis.reflector.facet.cssClass.patterns` is a comma separated list of key:value pairs, eg:
+Similarly, the xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.reflector.facet.cssClass.patterns` is a comma separated list of key:value pairs, eg:
 
 [source,ini]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_ugbtb_deployment_externalized-configuration.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_deployment_externalized-configuration.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_deployment_externalized-configuration.adoc
index dbdd804..6864e37 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_deployment_externalized-configuration.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_deployment_externalized-configuration.adoc
@@ -6,7 +6,7 @@
 
 
 
-As described xref:rg.adoc#_rg_runtime_configuration-files[here], by default Apache Isis itself bootstraps from the `isis.properties` configuration file.  It will also read configuration from the (optional) component/implementation-specific configuration files (such as
+As described xref:rgcfg.adoc#_rgcfg_configuration-files[here], by default Apache Isis itself bootstraps from the `isis.properties` configuration file.  It will also read configuration from the (optional) component/implementation-specific configuration files (such as
 `persistor_datanucleus.properties` or `viewer_wicket.properties`), and also (optional) component-specific configuration
 files (such as `persistor.properties` or `viewer.properties`).
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_ugbtb_deployment_tomcat.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_deployment_tomcat.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_deployment_tomcat.adoc
index a12c568..d37c599 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_deployment_tomcat.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_deployment_tomcat.adoc
@@ -25,4 +25,4 @@ The xref:rgsvc.adoc#_rgsvc-api_WrapperFactory[`WrapperFactory`] uses link:http:/
 
 == Using a JNDI Datasource
 
-See the guidance in the xref:rg.adoc#_rg_runtime_configuring-datanucleus_using-jndi-data-source[configuring datanucleus] section.
\ No newline at end of file
+See the guidance in the xref:rgcfg.adoc#_rgcfg_configuring-datanucleus_using-jndi-data-source[configuring datanucleus] section.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_decoupling_db-schemas.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_decoupling_db-schemas.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_decoupling_db-schemas.adoc
index 781b423..687fb32 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_decoupling_db-schemas.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_decoupling_db-schemas.adoc
@@ -49,7 +49,7 @@ CREATE TABLE isisaudit."AuditEntry" (
 
 [TIP]
 ====
-If for some reason you don't want to use schemas (though we strongly recommend that you do), then note that you can override the `@PersistenceCapable` annotation by providing XML metadata (the `mappings.jdo` file); see the section on xref:rg.adoc#_rg_runtime_configuring-datanucleus[configuring DataNucleus Overriding Annotations] for more details.
+If for some reason you don't want to use schemas (though we strongly recommend that you do), then note that you can override the `@PersistenceCapable` annotation by providing XML metadata (the `mappings.jdo` file); see the section on xref:rgcfg.adoc#_rgcfg_configuring-datanucleus[configuring DataNucleus Overriding Annotations] for more details.
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_i18n.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_i18n.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_i18n.adoc
index 838c9ef..2f1d35e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_i18n.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_i18n.adoc
@@ -90,8 +90,8 @@ If however the service is configured to run in write mode, then it instead recor
 
 To make the service as convenient as possible to use, the service configures itself as follows:
 
-* if running in prototype mode xref:rg.adoc#_rg_runtime_deployment-types[deployment type] or during integration tests, then the service runs in *write* mode, in which case it records all translations into the `.pot` file.  The `.pot` file is written out when the system is shutdown.
-* if running in server (production) mode xref:rg.adoc#_rg_runtime_deployment-types[deployment type], then the service runs in *read* mode. It is also possible to set a configuration setting in `isis.properties` to force read mode even if running in prototype mode (useful to manually test/demo the translations).
+* if running in prototype mode xref:rgcfg.adoc#_rgcfg_deployment-types[deployment type] or during integration tests, then the service runs in *write* mode, in which case it records all translations into the `.pot` file.  The `.pot` file is written out when the system is shutdown.
+* if running in server (production) mode xref:rgcfg.adoc#_rgcfg_deployment-types[deployment type], then the service runs in *read* mode. It is also possible to set a configuration setting in `isis.properties` to force read mode even if running in prototype mode (useful to manually test/demo the translations).
 
 When running in write mode the original text is returned to the caller untranslated. If in read mode, then the translated `.po` files are read and translations provided as required.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_ugbtb_web-xml.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_web-xml.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_web-xml.adoc
index 1dc3a24..8646d4f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_web-xml.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_web-xml.adoc
@@ -362,7 +362,7 @@ This filter reads one context parameter:
     <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.
+<1> alternatively set to "development"; see xref:rgcfg.adoc#_rgcfg_deployment-types[deployment types] for further discussion.
 
 
 === `IsisSessionFilter`

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_ugsec_usage-by-isis-viewers.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugsec_usage-by-isis-viewers.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugsec_usage-by-isis-viewers.adoc
index bd4fd66..06f5514 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugsec_usage-by-isis-viewers.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugsec_usage-by-isis-viewers.adoc
@@ -6,7 +6,7 @@
 
 
 
-By and large the security mechanisms within Isis are transparent to the rest of the framework (the xref:ugvw.adoc#[Wicket Viewer] and xref:ugvro.adoc#[Restful Objects viewer], and the overall xref:rg.adoc#_rg_runtime[runtime]).
+By and large the security mechanisms within Isis are transparent to the rest of the framework (the xref:ugvw.adoc#[Wicket Viewer] and xref:ugvro.adoc#[Restful Objects viewer], and the overall xref:rgcfg.adoc#_rgcfg[runtime]).
 
 That said, it is the responsibility of the viewers to ensure that there is a viewers to ensure that for each request there is a valid user session present.  The sections below explain how this works.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_ugvro_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugvro_hints-and-tips.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugvro_hints-and-tips.adoc
index 1bfbd2b..c499e65 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugvro_hints-and-tips.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugvro_hints-and-tips.adoc
@@ -87,7 +87,7 @@ Use `$resource.put(...)` or `$resource.post(...)` instead.
 
 == Pretty printing
 
-The JSON representations generated by the Restful Objects viewer are in compact form if the xref:rg.adoc#_rg_runtime_deployment-types[deployment type] is SERVER (ie production), but will automatically be "pretty printed" (in other words indented) if the deployment type is PROTOTYPE.
+The JSON representations generated by the Restful Objects viewer are in compact form if the xref:rgcfg.adoc#_rgcfg_deployment-types[deployment type] is SERVER (ie production), but will automatically be "pretty printed" (in other words indented) if the deployment type is PROTOTYPE.
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_ugvw_customisation_brand-logo.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugvw_customisation_brand-logo.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugvw_customisation_brand-logo.adoc
index ba30812..9aadf0e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugvw_customisation_brand-logo.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugvw_customisation_brand-logo.adoc
@@ -56,7 +56,7 @@ protected Module newIsisWicketModule() {
 If the logo is hosted locally, add to the relevant directory (eg `src/main/webapp/images`). It is also valid for the
 URL to be absolute.
 
-You may also wish to tweak the xref:rg.adoc#_rg_runtime_application-specific_application-css[`application.css`]. For example, a logo with height 40px works well with the following:
+You may also wish to tweak the xref:rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css`]. For example, a logo with height 40px works well with the following:
 
 [source,css]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_ugvw_customisation_tweaking-css-classes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugvw_customisation_tweaking-css-classes.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugvw_customisation_tweaking-css-classes.adoc
index b2d0f97..01eb3d2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugvw_customisation_tweaking-css-classes.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugvw_customisation_tweaking-css-classes.adoc
@@ -15,7 +15,7 @@ The HTML generated by the Wicket viewer include plenty of CSS classes so that yo
 }
 ----
 
-These customizations should generally be added to xref:rg.adoc#_rg_runtime_application-specific_application-css[`application.css]`; this file is included by default in every webpage served up by the Wicket viewer.
+These customizations should generally be added to xref:rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css]`; this file is included by default in every webpage served up by the Wicket viewer.
 
 
 
@@ -44,7 +44,7 @@ For example, the `ToDoItem` object of the Isis addons example https://github.com
 </div>
 ----
 
-The xref:rg.adoc#_rg_runtime_application-specific_application-css[`application.css`] file is the place to add application-specific styles. By way of an example, if (for some reason) we wanted to completely hide the notes value, we could do so using:
+The xref:rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css`] file is the place to add application-specific styles. By way of an example, if (for some reason) we wanted to completely hide the notes value, we could do so using:
 
 [source,css]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_ugvw_layout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugvw_layout.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugvw_layout.adoc
index fe4c2a9..75b5e5e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugvw_layout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugvw_layout.adoc
@@ -8,7 +8,7 @@
 
 The wicket viewer has full support for the various methods of specifying the xref:ug.adoc#_ug_object-layout[layout of objects], either statically or dynamically.
 
-Dynamic reloading is automatically supported when running in xref:rg.adoc#_rg_runtime_deployment-types[prototype (development) mode], the Wicket viewer automatically rebuilds the metamodel for each class as it is rendered.    Conversely, do note that the Wicket viewer will *not* pick up new metadata if running in production/server mode.
+Dynamic reloading is automatically supported when running in xref:rgcfg.adoc#_rgcfg_deployment-types[prototype (development) mode], the Wicket viewer automatically rebuilds the metamodel for each class as it is rendered.    Conversely, do note that the Wicket viewer will *not* pick up new metadata if running in production/server mode.
 
 
 [TIP]

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/rg.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rg.adoc b/adocs/documentation/src/main/asciidoc/guides/rg.adoc
index 05b304e..8b49fba 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rg.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rg.adoc
@@ -1,5 +1,5 @@
 [[rg]]
-= Reference Guide
+= Classes, Methods and Schema
 :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/
@@ -7,12 +7,15 @@
 
 
 [[_rg]]
-== Reference Guide
+= Classes, Methods and Schema
 
-This reference guide describes in detail the various elements of the Apache Isis Programming Model.  Most notably these are the xref:rgant.adoc#_rgant[annotations] (such as `@DomainObject`), and the reserved and prefix xref:rg.adoc#_rg_methods[methods] (such as `title()` and `validate...()`); it also includes various utility and supporting xref:rg.adoc#_rg_classes[classes].
+This reference guide lists and describes various elements of the the Apache Isis Programming Model, specifically
+reserved and prefix xref:rg.adoc#_rg_methods[methods] (such as `title()` and `validate...()`) and various utility and
+supporting xref:rg.adoc#_rg_classes[classes].
 
+It also describes the xref:rg.adoc#_rg_schema[XSD schema] defined by Apache Isis.  One use case is for the
+JAXB serialization of view models (`1.11.0-SNAPSHOT`).
 
-Also part of the reference manual are the details of how to influence the xref:ug.adoc#_ug_object-layout[UI layout] of your domain objects (this is ultimately just a type of metadata), and it catalogues all the various xref:rg.adoc#_rg_runtime[configuration properties] available that influence the behaviour of the framework and the API domain services.
 
 This reference guide does _not_ describe how to actually build an Apache Isis application; for that see the *xref:ug.adoc#_ug[Users' Guide]*.  The reference guide also doesn't explain how to setup your development environment; for that see the *xref:cg.adoc#_cg[Contributors' Guide]*.
 
@@ -21,5 +24,4 @@ This reference guide does _not_ describe how to actually build an Apache Isis ap
 
 include::_rg_methods.adoc[leveloffset=+1]
 include::_rg_classes.adoc[leveloffset=+1]
-include::_rg_runtime.adoc[leveloffset=+1]
 include::_rg_schema.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/rgcfg.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcfg.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcfg.adoc
new file mode 100644
index 0000000..a1d2d07
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcfg.adoc
@@ -0,0 +1,32 @@
+[[rgcfg]]
+= 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/
+
+
+[[_rgcfg]]
+== Configuration Properties
+
+Apache Isis' own configuration properties are simple key-value pairs, typically held in the `WEBINF/isis.properties`
+file and other related files. This guide describes how to configure an Apache Isis application.
+
+
+[NOTE]
+====
+Configuration properties for the viewers can be found in the xref:ugvw.adoc#[Wicket Viewer] chapter and the xref:ugvro.adoc#[RestfulObjects viewer] chapter.  Likewise[details of configuring security (Apache Shiro) can be found in the xref:ugsec.adoc#[Security] chapter.
+
+Also, note that by default the configuration values are part of the built WAR file.  Details on how to override these configuration properties externally for different environments can be found in the xref:ugbtb.adoc#_ugbtb_deployment[Deployment] chapter.
+====
+
+
+include::_rgcfg_deployment-types.adoc[leveloffset=+1]
+include::_rgcfg_configuration-files.adoc[leveloffset=+1]
+include::_rgcfg_specifying-components.adoc[leveloffset=+1]
+include::_rgcfg_configuring-core.adoc[leveloffset=+1]
+include::_rgcfg_configuring-datanucleus.adoc[leveloffset=+1]
+
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/ug.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ug.adoc b/adocs/documentation/src/main/asciidoc/guides/ug.adoc
index 9a05fec..de52f80 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ug.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ug.adoc
@@ -10,10 +10,13 @@
 == Fundamentals
 
 This guide introduces the xref:ug.adoc#_ug_core-concepts[core concepts] and ideas behind Apache Isis,
-and tells you how to xref:ug.adoc#_ug_getting-started[get started] with a Maven archetype.  It also describes a
-number of xref:ug.adoc#_ug_how-tos[how-to]s, and catalog various xref:ug.adoc#_ug_faqs.adoc[FAQ]s.
+and tells you how to xref:ug.adoc#_ug_getting-started[get started] with a Maven archetype.
 
-Other guides are:
+It also describes a number of xref:ug.adoc#_ug_how-tos[how-to]s, describes how to influence the
+xref:ug.adoc#_ug_object-layout[UI layout] of your domain objects (this is ultimately just a type of metadata), and it
+ catalogues various xref:ug.adoc#_ug_faqs.adoc[FAQ]s.
+
+Other user guides are:
 
 * xref:ugvw.adoc#[Wicket viewer]
 * xref:ugvro.adoc#[Restful Objects viewer]
@@ -21,11 +24,18 @@ Other guides are:
 * xref:ugtst.adoc#[Testing]
 * xref:ugbtb.adoc#[Beyond the Basics]
 
+Other reference guides are:
+
+* xref:rgant.adoc#[Annotations]
+* xref:rgsvc.adoc#[Domain Services]
+* xref:rgcfg.adoc#[Configuration Properties]
+* xref:rg.adoc#[Classes, Methods and Schema]
 
 This users' guide is _not_ intended as a reference manual; for that see the *xref:rg.adoc#_rg[Reference Guide]*.  This
 guide also doesn't explain how to setup your development environment; for that see the *xref:cg.adoc#_cg[Contributors' Guide]*.
 
 
+
 include::_ug_core-concepts.adoc[leveloffset=+1]
 include::_ug_getting-started.adoc[leveloffset=+1]
 


[32/52] [abbrv] isis git commit: ISIS-1243: adding screencast to docs

Posted by mg...@apache.org.
ISIS-1243: adding screencast to docs


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/e135d7f0
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/e135d7f0
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/e135d7f0

Branch: refs/heads/ISIS-1224-select2-v4
Commit: e135d7f02988c8b48b09dd4f780cd04a31f3207a
Parents: db566dc
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Fri Dec 4 16:27:19 2015 +0000
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Fri Dec 4 16:27:19 2015 +0000

----------------------------------------------------------------------
 .../asciidoc/guides/_ugvro_simplified-representations.adoc    | 7 +++++++
 1 file changed, 7 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/e135d7f0/adocs/documentation/src/main/asciidoc/guides/_ugvro_simplified-representations.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugvro_simplified-representations.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugvro_simplified-representations.adoc
index 51f68d7..76fe65e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugvro_simplified-representations.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugvro_simplified-representations.adoc
@@ -44,6 +44,13 @@ Accept: application/json;profile="urn:org.apache.isis/v1"
 Not every resource supports this header, but the most commonly accessed ones do.  In each case the server will set the
 `Content-Type` header so that the client knows how to process the representation.
 
+The screencast below demonstrates the feature.
+
+video::HMSqapQDY_4[youtube,width="853px",height="480px"]
+
+
+And the table below explains in a little more detail what is returned when this profile is activated.
+
 [cols="1a,4a", options="header"]
 |===
 


[31/52] [abbrv] isis git commit: ISIS-1275: new config property for RO to relax Accept header checking (impl, plus updated docs)

Posted by mg...@apache.org.
ISIS-1275: new config property for RO to relax Accept header checking (impl, plus updated docs)


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/db566dc3
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/db566dc3
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/db566dc3

Branch: refs/heads/ISIS-1224-select2-v4
Commit: db566dc380036ef96f00f63d7fc8eea9db353450
Parents: ff92fd0
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Fri Dec 4 15:14:57 2015 +0000
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Fri Dec 4 15:14:57 2015 +0000

----------------------------------------------------------------------
 .../asciidoc/guides/_ugvro_configuration-properties.adoc | 11 +++++++++++
 .../specloader/specimpl/ObjectMemberAbstract.java        |  2 +-
 .../service/RepresentationServiceContentNegotiator.java  |  1 -
 .../ContentNegotiationServiceForRestfulObjectsV1_0.java  |  8 +++++++-
 4 files changed, 19 insertions(+), 3 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/db566dc3/adocs/documentation/src/main/asciidoc/guides/_ugvro_configuration-properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugvro_configuration-properties.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugvro_configuration-properties.adoc
index 0fe9e9f..eddb031 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugvro_configuration-properties.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugvro_configuration-properties.adoc
@@ -35,6 +35,17 @@ http://restfulobjects.org[Restful Object spec].
 | `true`,`false` (`_false_`)
 |A mechanism for reducing the number of round-trips by eagerly rendering collections; discussed xref:ugvro.adoc#_ugvro_ro-spec_extensions_minimizing-round-trips_honor-ui-hints[here].
 
+|`isis.viewer.restfulobjects.` +
+`strictAcceptChecking` +
+(`1.11.0-SNAPSHOT`)
+| `true`,`false` (`_false_`)
+|Whether to strictly enforce the `Accept` header checking for the default RO-spec representations (by the
+`ContentNegotiationServiceForRestfulObjectsV1_0` service). Will otherwise accept anything.  +
++
+This is convenient because it allows the `Accept` header to be set to that of the
+xref:ugvro.adoc#_ugvro_simplified-representations[Apache Isis profile] for all resources, rather than simply the
+handful of resources that supported that profile.
+
 |===
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/db566dc3/core/metamodel/src/main/java/org/apache/isis/core/metamodel/specloader/specimpl/ObjectMemberAbstract.java
----------------------------------------------------------------------
diff --git a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/specloader/specimpl/ObjectMemberAbstract.java b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/specloader/specimpl/ObjectMemberAbstract.java
index 2fc4fc3..4467827 100644
--- a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/specloader/specimpl/ObjectMemberAbstract.java
+++ b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/specloader/specimpl/ObjectMemberAbstract.java
@@ -348,7 +348,7 @@ public abstract class ObjectMemberAbstract implements ObjectMember {
             }
             return singularName;
         }
-        final int indexOfUnderscore = singularName.lastIndexOf('_');
+        final int indexOfUnderscore = singularName.indexOf('_');
         if (indexOfUnderscore == -1) {
             return singularName;
         }

http://git-wip-us.apache.org/repos/asf/isis/blob/db566dc3/core/viewer-restfulobjects-rendering/src/main/java/org/apache/isis/viewer/restfulobjects/rendering/service/RepresentationServiceContentNegotiator.java
----------------------------------------------------------------------
diff --git a/core/viewer-restfulobjects-rendering/src/main/java/org/apache/isis/viewer/restfulobjects/rendering/service/RepresentationServiceContentNegotiator.java b/core/viewer-restfulobjects-rendering/src/main/java/org/apache/isis/viewer/restfulobjects/rendering/service/RepresentationServiceContentNegotiator.java
index abfdaf3..65ced88 100644
--- a/core/viewer-restfulobjects-rendering/src/main/java/org/apache/isis/viewer/restfulobjects/rendering/service/RepresentationServiceContentNegotiator.java
+++ b/core/viewer-restfulobjects-rendering/src/main/java/org/apache/isis/viewer/restfulobjects/rendering/service/RepresentationServiceContentNegotiator.java
@@ -47,7 +47,6 @@ public class RepresentationServiceContentNegotiator implements RepresentationSer
 
     @PostConstruct
     public void init(final Map<String, String> properties) {
-
     }
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/db566dc3/core/viewer-restfulobjects-rendering/src/main/java/org/apache/isis/viewer/restfulobjects/rendering/service/conneg/ContentNegotiationServiceForRestfulObjectsV1_0.java
----------------------------------------------------------------------
diff --git a/core/viewer-restfulobjects-rendering/src/main/java/org/apache/isis/viewer/restfulobjects/rendering/service/conneg/ContentNegotiationServiceForRestfulObjectsV1_0.java b/core/viewer-restfulobjects-rendering/src/main/java/org/apache/isis/viewer/restfulobjects/rendering/service/conneg/ContentNegotiationServiceForRestfulObjectsV1_0.java
index e24b6f9..d78e0e4 100644
--- a/core/viewer-restfulobjects-rendering/src/main/java/org/apache/isis/viewer/restfulobjects/rendering/service/conneg/ContentNegotiationServiceForRestfulObjectsV1_0.java
+++ b/core/viewer-restfulobjects-rendering/src/main/java/org/apache/isis/viewer/restfulobjects/rendering/service/conneg/ContentNegotiationServiceForRestfulObjectsV1_0.java
@@ -61,9 +61,12 @@ public class ContentNegotiationServiceForRestfulObjectsV1_0 implements ContentNe
 
     private static final DateFormat ETAG_FORMAT = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSSZ");
 
+    private boolean strictAcceptChecking;
+
     @PostConstruct
     public void init(final Map<String, String> properties) {
-
+        final String strictAcceptCheckingStr = properties.get("isis.viewer.restfulobjects.strictAcceptChecking");
+        this.strictAcceptChecking = "true".equalsIgnoreCase(strictAcceptCheckingStr);
     }
 
     @PreDestroy
@@ -236,6 +239,9 @@ public class ContentNegotiationServiceForRestfulObjectsV1_0 implements ContentNe
     private void ensureCompatibleAcceptHeader(
             final RepresentationType representationType,
             final List<MediaType> acceptableMediaTypes) {
+        if(!strictAcceptChecking) {
+            return;
+        }
         if (representationType == null) {
             return;
         }


[22/52] [abbrv] isis git commit: ISIS-1243: renamed ug.adoc to ugfun.adoc. Added standard section to each of the guides so can navigate between each easily.

Posted by mg...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints.adoc
deleted file mode 100644
index 0c582d2..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints.adoc
+++ /dev/null
@@ -1,15 +0,0 @@
-[[_ug_how-tos_ui-hints]]
-= UI Hints
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-The Apache Isis programming model includes several mechanisms for a domain object to provide UI hints.  These range from their title (so an end-user can distinguish one object from another) through to hints that can impact their CSS styling.
-
-include::_ug_how-tos_ui-hints_object-titles-and-icons.adoc[leveloffset=+1]
-include::_ug_how-tos_ui-hints_names-and-descriptions.adoc[leveloffset=+1]
-include::_ug_how-tos_ui-hints_layout.adoc[leveloffset=+1]
-include::_ug_how-tos_ui-hints_eager-rendering.adoc[leveloffset=+1]
-include::_ug_how-tos_ui-hints_action-icons-and-css.adoc[leveloffset=+1]
-include::_ug_how-tos_ui_are-you-sure.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_action-icons-and-css.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_action-icons-and-css.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_action-icons-and-css.adoc
deleted file mode 100644
index 2bf891d..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_action-icons-and-css.adoc
+++ /dev/null
@@ -1,58 +0,0 @@
-[[_ug_how-tos_ui-hints_action-icons-and-css]]
-= Action Icons and CSS
-: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 allows link:http://fortawesome.github.io/Font-Awesome/icons/[font awesome] icons to be associated with each action, and for link:http://getbootstrap.com/css/#buttons[Bootstrap CSS] to be applied to action rendered as buttons.
-
-These UI hint can be applied either to individual actions, or can be applied en-masse using pattern matching.
-
-== Per action
-
-NOTE: TODO - xref:rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`] and xref:rgant.adoc#_rgant-ActionLayout_cssClassFa[`@ActionLayout#cssClassFa()`]
-
-
-Alternatively, you can specify these hints dynamically in the xref:ug.adoc#_ug_object-layout[`Xxx.layout.json`] for the entity.
-
-
-== Per pattern matching
-
-Rather than annotating every action with xref:rgant.adoc#_rgant-ActionLayout_cssClassFa[`@ActionLayout#cssClassFa()`] and xref:rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`] you can instead specify the UI hint globally using regular expressions.
-
-The xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.reflector.facet.cssClassFa.patterns` is a comma separated list of key:value pairs, eg:
-
-[source,ini]
-----
-isis.reflector.facet.cssClassFa.patterns=\
-                        new.*:fa-plus,\
-                        add.*:fa-plus-square,\
-                        create.*:fa-plus,\
-                        list.*:fa-list, \
-                        all.*:fa-list, \
-                        download.*:fa-download, \
-                        upload.*:fa-upload, \
-                        execute.*:fa-bolt, \
-                        run.*:fa-bolt
-----
-
-where the key is a regex matching action names (eg `create.*`) and the value is a link:http://fortawesome.github.io/Font-Awesome/icons/[font-awesome] icon name (eg `fa-plus`) to be applied (as per `@CssClassFa()`) to all action members matching the regex.
-
-
-Similarly, the xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.reflector.facet.cssClass.patterns` is a comma separated list of key:value pairs, eg:
-
-[source,ini]
-----
-isis.reflector.facet.cssClass.patterns=\
-                        delete.*:btn-warning
-----
-
-where (again)the key is a regex matching action names (eg `delete.*`) and the value is a link:http://getbootstrap.com/css/[Bootstrap] CSS button class (eg `btn-warning) to be applied (as per `@CssClass()`) to all action members matching the regex.
-
-[TIP]
-====
-We strongly recommend that you use this technique rather than annotating each action with xref:rgant.adoc#_rgant-ActionLayout_cssClassFa[`@ActionLayout#cssClassFa()`] or xref:rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`].  Not only is the code more maintainable, you'll also find that it forces you to be consistent in your action names.
-====
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_eager-rendering.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_eager-rendering.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_eager-rendering.adoc
deleted file mode 100644
index 0e92f5f..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_eager-rendering.adoc
+++ /dev/null
@@ -1,58 +0,0 @@
-[[_ug_how-tos_ui-hints_eager-rendering]]
-= Eager rendering
-: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/
-
-
-By default, collections all rendered lazily, in other words in a "collapsed" table view:
-
-NOTE: TODO - screenshot here
-
-For the more commonly used collections we want to show the table expanded:
-
-NOTE: TODO - screenshot here
-
-For this we annotate the collection using the `@CollectionLayout(render=RenderType.EAGERLY`; for example
-
-[source,java]
-----
-@javax.jdo.annotations.Persistent(table="ToDoItemDependencies")
-private Set<ToDoItem> dependencies = new TreeSet<>();
-@Collection
-@CollectionLayout(
-    render = RenderType.EAGERLY
-)
-public Set<ToDoItem> getDependencies() {
-    return dependencies;
-}
-----
-
-Alternatively, it can be specified the `Xxx.layout.json` file:
-
-[source,javascript]
-----
-"dependencies": {
-    "collectionLayout": {
-        "render": "EAGERLY"
-    },
-}
-----
-
-[WARNING]
-====
-It might be thought that collections that are eagerly rendered should also be eagerly loaded from the database by enabling the `defaultFetchGroup` attribute:
-
-[source,java]
-----
-@javax.jdo.annotations.Persistent(table="ToDoItemDependencies", defaultFetchGroup="true")
-private Set<ToDoItem> dependencies = new TreeSet<>();
-...
-----
-
-While this can be done, it's likely to be a bad idea, because doing so will cause DataNucleus to query for more data than required even if the object is being rendered within some referencing object's table.
-
-Of course, your mileage may vary, so don't think you can't experiment.
-====
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_layout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_layout.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_layout.adoc
deleted file mode 100644
index 92c0be8..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_layout.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-[[_ug_how-tos_ui-hints_layout]]
-= Layout
-: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/
-
-
-See the xref:ug.adoc#_ug_object-layout[object layout] chapter.
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_names-and-descriptions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_names-and-descriptions.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_names-and-descriptions.adoc
deleted file mode 100644
index dbb56dd..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_names-and-descriptions.adoc
+++ /dev/null
@@ -1,47 +0,0 @@
-[[_ug_how-tos_ui-hints_names-and-descriptions]]
-= Names and Descriptions
-: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/
-
-NOTE: TODO
-
-
-
-NOTE: see also xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[Internationalization]
-
-== Class (object)
-
-NOTE: TODO - xref:rgant.adoc#_rgant-DomainObjectLayout_named[`@DomainObjectLayout#named()`], xref:rgant.adoc#_rgant-DomainObjectLayout_describedAs[`@DomainObjectLayout#describedAs()`]
-
-
-== Property
-
-NOTE: TODO - xref:rgant.adoc#_rgant-PropertyLayout_named[`@PropertyLayout#named()`], xref:rgant.adoc#_rgant-PropertyLayout_describedAs[`@PropertyLayout#describedAs()`]
-
-
-
-== Collections
-
-NOTE: TODO - xref:rgant.adoc#_rgant-CollectionLayout_named[`@CollectionLayout#named()`], xref:rgant.adoc#_rgant-CollectionLayout_describedAs[`@CollectionLayout#describedAs()`]
-
-
-
-== Actions
-
-NOTE: TODO - xref:rgant.adoc#_rgant-ActionLayout_named[`@ActionLayout#named()`], xref:rgant.adoc#_rgant-ActionLayout_describedAs[`@ActionLayout#describedAs()`]
-
-
-== Action Parameters
-
-NOTE: TODO - xref:rgant.adoc#_rgant-ParameterLayout_named[`@ParameterLayout#named()`], xref:rgant.adoc#_rgant-ParameterLayout_describedAs[`@ParameterLayout#describedAs()`]
-
-
-[TIP]
-====
-If you're running on Java 8, then note that it's possible to write Isis applications without using `@ParameterLayout(named=...)` annotation.  Support for this can be found in the link:http://github.com/isisaddons/isis-metamodel-paraname8[Isis addons' paraname8] metamodel extension (non-ASF).  (In the future we'll fold this into core).  See also our guidance on xref:release-notes.adoc#_migration-notes_1.8.0-to-1.9.0_upgrading-to-java8[upgrading to Java 8].
-====
-
-
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_object-titles-and-icons.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_object-titles-and-icons.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_object-titles-and-icons.adoc
deleted file mode 100644
index 1ec22ed..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_object-titles-and-icons.adoc
+++ /dev/null
@@ -1,97 +0,0 @@
-[[_ug_how-tos_ui-hints_object-titles-and-icons]]
-= Object Titles and Icons
-: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/
-
-
-In Apache Isis every object is identified to the user by a title (label) and an icon.  This is shown in several places: as the main heading for an object; as a link text for an object referencing another object, and also in tables representing collections of objects.
-
-The icon is often the same for all instances of a particular class, but it's also possible for an individual instance to return a custom icon.  This could represent the state of that object (eg a shipped order, say, or overdue library book).
-
-It is also possible for an object to provide a CSS class hint.  In conjunction with xref:ugvw.adoc#_ugvw_customisation_tweaking-css-classes[customized CSS] this can be used to apply arbitrary styling; for example each object could be rendered in a page with a different background colour.
-
-
-== Object Title
-
-The object title is a label to identify an object to the end-user.  Generally the object title is a label to identify an object to the end-user.  There is no requirement for it to be absolutely unique, but it should be "unique enough" to distinguish the object from other object's likely to be rendered on the same page.
-
-The title is always shown with an icon, so there is generally no need for the title to include information about the object's type.  For example the title of a customer object shouldn't include the literal string "Customer"; it can just have the customer's name, reference or some other meaningful business identifier.
-
-
-=== Declarative style
-
-The xref:rgant.adoc#_rgant-Title[`@Title`] annotation can be used build up the title of an object from its constituent parts.
-
-For example:
-
-[source,java]
-----
-public class Customer {
-    @Title(sequence="1", append=" ")
-    public String getFirstName() { ... }
-    @Title(sequence="2")
-    public Product getLastName() { ... }
-    ...
-}
-----
-
-might return "Arthur Clarke", while:
-
-[source,java]
-----
-public class CustomerAlt {
-    @Title(sequence="2", prepend=", ")
-    public String getFirstName() { ... }
-
-    @Title(sequence="1")
-    public Product getLastName() { ... }
-    ...
-}
-----
-
-could return "Clarke, Arthur".
-
-Note that the sequence is in Dewey Decimal Format.  This allows a subclass to intersperse information within the title.  For example (please forgive this horrible domain modelling (!)):
-
-
-[source,java]
-----
-public class Author extends Customer {
-    @Title(sequence="1.5", append=". ")
-    public String getMiddleInitial() { ... }
-    ...
-}
-----
-
-could return "Arthur C. Clarke".
-
-
-[TIP]
-====
-Titles can sometimes get be long and therefore rather cumbersome in "parented" tables.  If `@Title` has been used then the Wicket viewer will automatically exclude portions of the title belonging to the owning object.
-====
-
-
-=== Imperative style
-
-NOTE: TODO - see xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`]
-
-
-
-
-== Object Icon
-
-The icon is often the same for all instances of a particular class, but it's also possible for an individual instance to return a custom icon.  This could represent the state of that object (eg a shipped order, say, or overdue library book).
-
-NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`], xref:rgant.adoc#_rgant-DomainObjectLayout_cssClassFa[`@DomainObjectLayout#cssClassFa()`]
-
-
-
-
-== Object CSS Styling
-
-
-It is also possible for an object to return a xref:rgcms.adoc#_rgcms_methods_reserved_cssClass[CSS class].  In conjunction with xref:ugvw.adoc#_ugvw_customisation_tweaking-css-classes[customized CSS] this can be used to apply arbitrary styling; for example each object could be rendered in a page with a different background colour.
-
-NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_reserved_cssClass[`cssClass()`], xref:rgant.adoc#_rgant-DomainObjectLayout_cssClass[`@DomainObjectLayout#cssClass()`] xref:rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`], xref:rgant.adoc#_rgant-PropertyLayout_cssClass[`@PropertyLayout#cssClass()`], xref:rgant.adoc#_rgant-CollectionLayout_cssClass[`@CollectionLayout#cssClass()`]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui_are-you-sure.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui_are-you-sure.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui_are-you-sure.adoc
deleted file mode 100644
index 2ce9903..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui_are-you-sure.adoc
+++ /dev/null
@@ -1,76 +0,0 @@
-[[_ug_how-tos_ui_are-you-sure]]
-= 'Are you sure?' idiom
-: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/
-
-
-Sometimes an action might perform irreversible changes.  In such a case it's probably a good idea for the UI to require that the
-end-user explicitly confirms that they intended to invoke the action.
-
-== Using action semantics
-
-One way to meet this requirement is using the framework's built-in xref:rgant.adoc#_rgant-Action_semantics[`@Action#semantics()`] attribute:
-
-[source,java]
-----
-@Action(
-        semantics = SemanticsOf.IDEMPOTENT_ARE_YOU_SURE
-)
-public SimpleObject updateName(
-        @Parameter(maxLength = NAME_LENGTH)
-        @ParameterLayout(named = "New name")
-        final String name) {
-    setName(name);
-    return this;
-}
-----
-
-
-This will render as:
-
-image::{_imagesdir}/how-tos/tips-n-tricks/action-semantics-are-you-sure.png[]
-
-
-== Using a checkbox
-
-An alternative approach (for all versions of the framework) is to require the end-user to check a dummy checkbox parameter (and prevent the action from being invoked if the user hasn't checked that parameter).
-
-For example:
-
-image::{_imagesdir}/how-tos/tips-n-tricks/are-you-sure.png[]
-
-[NOTE]
-====
-Note that these screenshots shows an earlier version of the xref:ugvw.adoc#[Wicket viewer] UI (specifically, pre 1.8.0).
-====
-
-If the user checks the box:
-
-image::{_imagesdir}/how-tos/tips-n-tricks/are-you-sure-happy-case.png[]
-
-then the action will complete.
-
-However, if the user fails to check the box, then a validation message is shown:
-
-image::{_imagesdir}/how-tos/tips-n-tricks/are-you-sure-sad-case.png[]
-
-
-
-The code for this is pretty simple:
-
-[source,java]
-----
-public List<ToDoItem> delete(@Named("Are you sure?") boolean areYouSure) {
-    container.removeIfNotAlready(this);
-    container.informUser("Deleted " + container.titleOf(this));
-    return toDoItems.notYetComplete();          // <1>
-}
-public String validateDelete(boolean areYouSure) {
-    return areYouSure? null: "Please confirm you are sure";
-}
-----
-<1> invalid to return `this` (cannot render a deleted object)
-
-Note that the action itself does not use the boolean parameter, it is only
-used by the supporting xref:rgcms.adoc#_rgcms_methods_prefixes_validate[`validate...()`] method.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_object-layout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_object-layout.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_object-layout.adoc
deleted file mode 100644
index abd4e99..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_object-layout.adoc
+++ /dev/null
@@ -1,18 +0,0 @@
-[[_ug_object-layout]]
-= Object Layout
-: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/
-
-
-In implementing the http://en.wikipedia.org/wiki/Naked_objects[naked objects pattern], Apache Isis aims to infer as much information from the domain classes as possible.  Nevertheless, some metadata relating solely to the UI is inevitably required.
-
-
-This chapter describes how this is done both for domain objects -- statically or dynamically -- and for the application menu bar (containing domain service' actions).
-
-include::_ug_object-layout_static.adoc[leveloffset=+1]
-include::_ug_object-layout_dynamic.adoc[leveloffset=+1]
-include::_ug_object-layout_application-menu.adoc[leveloffset=+1]
-include::_ug_object-layout_static-vs-dynamic.adoc[leveloffset=+1]
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_object-layout_application-menu.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_object-layout_application-menu.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_object-layout_application-menu.adoc
deleted file mode 100644
index 922c3a0..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_object-layout_application-menu.adoc
+++ /dev/null
@@ -1,171 +0,0 @@
-[[_ug_object-layout_application-menu]]
-= Application Menu Layout
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The actions of domain services are made available as an application menu bar. By default each domain service
-corresponds to a single menu on this menu bar, with its actions as the drop-down menu items. This is rarely exactly
-what is required, however. The `@MemberOrder` and `@DomainServiceLayout` annotations can be used to rearrange the
-placement of menu items.
-
-The screenshots below are taken from http://github.com/estatio/estatio[Estatio], an open source estate management
-application built using Apache Isis.
-
-== @DomainServiceLayout
-
-Menus for domain services can be placed either on a primary, secondary or tertiary menu bar.
-
-image::{_imagesdir}wicket-viewer/application-menu/layout-menus.png[width="800px",link="{_imagesdir}wicket-viewer/application-menu/layout-menus.png"]
-
-Within a single top-level menu (eg "Fixed Assets") there can be actions from multiple services. The Wicket viewer
-automatically adds a divider between each:
-
-image::{_imagesdir}wicket-viewer/application-menu/dividers.png[width="400px",link="{_imagesdir}wicket-viewer/application-menu/dividers.png"]
-
-In the example above the top-level menu combines the actions from the `Properties`, `Units` and `FixedAssetRegistrations`
-services. The `Properties` service is annotated:
-
-[source,java]
-----
-@DomainServiceLayout(
-        named="Fixed Assets",
-        menuBar = DomainServiceLayout.MenuBar.PRIMARY,
-        menuOrder = "10.1"
-)
-public class Properties ... { ... }
-----
-
-while the `Units` service is annotated:
-
-[source,java]
-----
-@DomainServiceLayout(
-        named="Fixed Assets",
-        menuBar = DomainServiceLayout.MenuBar.PRIMARY,
-        menuOrder = "10.2"
-)
-public class Units ... { ... }
-----
-
-and similarly `FixedAssetRegistrations` is annotated:
-
-[source,java]
-----
-@DomainServiceLayout(
-        named="Fixed Assets",
-        menuBar = DomainServiceLayout.MenuBar.PRIMARY,
-        menuOrder = "10.3"
-)
-public class FixedAssetRegistrations ... { ... }
-----
-
-Note that in all three cases the value of the `named` attribute and the `menuBar` attribute is the same: "Fixed Assets"
-and PRIMARY. This means that all will appear on a "Fixed Assets" menu in the primary menu bar.
-
-Meanwhile the value of `menuOrder` attribute is significant for two reasons:
-
-* for these three services on the same ("Fixed Assets") top-level menu, it determines the relative order of their sections (`Properties` first, then `Units`, then `FixedAssetRegistrations`)
-* it determines the placement of the top-level menu itself ("Fixed Assets") with respect to other top-level menus on the menu bar.
-
-To illustrate this latter point, the next top-level menu on the menu bar, "Parties", is placed after "Fixed Assets"
- because the `menuOrder` of the first of its domain services, namely the `Parties` service, is higher than that for
- "Fixed Assets":
-
-[source,java]
-----
-@DomainServiceLayout(
-        named="Parties",
-        menuBar = DomainServiceLayout.MenuBar.PRIMARY,
-        menuOrder = "20.1"
-)
-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 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:
-
-[source,java]
-----
-public class Units extends EstatioDomainService<Unit> {
-
-    @MemberOrder(sequence = "1")
-    public Unit newUnit( ... ) { ... }
-
-    @MemberOrder(sequence = "2")
-    public List<Unit> findUnits( ... ) { ... }
-
-    @ActionLayout( prototype = true )
-    @MemberOrder(sequence = "99")
-    public List<Unit> allUnits() { ... }
-    ...
-}
-----
-
-Note that the last is also a prototype action (meaning it is only displayed in SERVER_PROTOTYPE (=Wicket Development) mode).
-In the UI it is rendered in italics.
-
-(It is possible to override this place of a given action by specifying `@MemberOrder(name=&quot;...&quot;)` where the name is
-that of a top-level menu. Prior to 1.8.0 this was the only way of doing things, as of 1.8.0 its use
-is not recommended).
-
-== Tertiary menubar
-
-The tertiary menu bar consists of a single unnamed menu, rendered underneath the user's login, top right. This is
-intended primarily for actions pertaining to the user themselves, eg their account, profile or settings:
-
-image::{_imagesdir}wicket-viewer/application-menu/tertiary.png[width="300px",link="{_imagesdir}wicket-viewer/application-menu/tertiary.png"]
-
-Domain services' actions can be associated with the tertiary menu using the same `@DomainServiceLayout` annotation. For
-example, the `updateEpochDate(...)` and `listAllSettings(...)` actions come from the following service:
-
-[source,java]
-----
-@DomainServiceLayout(
-        menuBar = DomainServiceLayout.MenuBar.TERTIARY,
-        menuOrder = "10.1"
-)
-public class EstatioAdministrationService ... {
-
-    @MemberOrder(sequence = "1")
-    public void updateEpochDate( ... ) { ... }
-
-    @MemberOrder(sequence = "2")
-    public List<ApplicationSetting> listAllSettings() { ... }
-    ...
-}
-----
-
-Because the number of items on the tertiary menu is expected to be small and most will pertain to the current user, the
-viewer does _not_ place dividers between actions from different services on the tertiary menu.
-
-
-== Isis Add-on modules
-
-Some of the (non-ASF) link:http://isisaddons.org[Isis Addons] modules also provide services whose actions appear in top-level menus.
-
-The http://github.com/isisaddons/isis-module-security[security]'s module places its domain service menus in three
-top-level menus:
-
-* its `ApplicationUsers`, `ApplicationRoles`, `ApplicationPermission`, `ApplicationFeatureViewModels` and
- `ApplicationTenancies` domain services are all grouped together in a single "Security" top-level menu, on the
- SECONDARY menu bar
-
-* its `SecurityModuleAppFixturesService` domain service, which allows the security modules' fixture scripts to be run,
- is placed on a "Prototyping" top-level menu, also on the SECONDARY menu bar
-
-* its `MeService` domain service, which provides the `me()` action, is placed on the TERTIARY menu bar.
-
-Meanwhile the http://github.com/isisaddons/isis-module-devutils[devutils] module places its actions - to download layouts and
-so forth - on a "Prototyping" top-level menu, on the SECONDARY menu bar.
-
-Currently there is no facility to alter the placement of these services. However, their UI can be suppressed
-using security or using a xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling_vetoing-visibility[vetoing subscriber].
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_object-layout_dynamic.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_object-layout_dynamic.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_object-layout_dynamic.adoc
deleted file mode 100644
index 9bda79a..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_object-layout_dynamic.adoc
+++ /dev/null
@@ -1,113 +0,0 @@
-[[_ug_object-layout_dynamic]]
-= Dynamic Object Layout
-: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/
-
-
-
-Metadata providing UI hints can be specified either statically, using annotations, or dynamically, using a `.layout.json` file.  This section describes the dynamic approach, using the file.
-
-
-== JSON layout file
-
-The JSON layout file for class `Xxx` takes the name `Xxx.layout.json`, and resides in the same package as the class.
-The format of the file is:
-
-[source,javascript]
-----
-{
-  "columns": [                                // list of columns
-    {
-      "span": 6,                              // span of the left-hand property column
-      "memberGroups": {                       // ordered map of member (property) groups
-        "General": {                          // member group name
-          "members": {
-            "description": {                  // property, no associated actions, but with UI hint
-              "propertyLayout": {
-                "typicalLength": 50           // UI hint for size of field (no longer used in ISIS 1.8.0)
-              }
-            },
-            "category": {},
-            "complete": {                     // property, with associated actions
-              "propertyLayout": {
-                "describedAs": "Whether this todo item has been completed"
-              },
-              "actions": {
-                "completed": {
-                  "actionLayout": {
-                    "named": "Done",          // naming UI hint
-                    "cssClass": "x-highlight" // CSS UI hint
-                  }
-                },
-                "notYetCompleted": {
-                  "actionLayout": {
-                    "named": "Not done"
-                  }
-                }
-              }
-            }
-          },
-          "Misc": {
-            "members": {
-              "notes": {
-                "propertyLayout": {
-                  "multiLine": 5              // UI hint for text area
-                }
-              },
-              "versionSequence": {}
-            }
-          }
-        }
-      }
-    },
-    {
-      "span": 6,                              // span of the middle property column
-      "memberGroups": { ... }
-    },
-    {
-      "span": 0                               // span of the right property column (if any)
-    },
-    {
-      "span": 6,
-      "collections": {                        // ordered map of collections
-        "dependencies": {                     // collection, with associated actions
-          "collectionLayout": {
-            "paged": 10,                      // pagination UI hint
-            "render": "EAGERLY"               // lazy-loading UI hint
-          },
-          "actions": {
-            "add":{},
-            "delete": {}
-          },
-        },
-        "similarItems": {}                    // collection, no associated actions
-      }
-    }
-  ],
-  "actions": {                                // actions not associated with any member
-    "delete": {},
-    "duplicate": {
-      "actionLayout": {
-        "named": {
-          "value": "Clone"
-        }
-      }
-    }
-  }
-}
-----
-
-Although advisable, it is not necessary to list all class members in this file. Any members not listed with be
-ordered according either to annotations (if present) or fallback/default values.
-
-Note also that the layout file may contain entries for xref:ug.adoc#_ug_how-tos_contributed-members[contributed associations and actions]; this allows each contributee classes to define their own layout for their contributions, possibly overriding any static metadata on the original domain service contributor.
-
-
-
-== 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/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_object-layout_static-vs-dynamic.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_object-layout_static-vs-dynamic.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_object-layout_static-vs-dynamic.adoc
deleted file mode 100644
index b534e57..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_object-layout_static-vs-dynamic.adoc
+++ /dev/null
@@ -1,26 +0,0 @@
-[[_ug_object-layout_static-vs-dynamic]]
-= Static vs Dynamic Layouts
-: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/
-
-
-
-
-Using xref:ug.adoc#_ug_object-layout_dynamic[dynamic object layout]s using JSON has the huge benefit that the layout can be updated without requiring a recompile of the code and redeploy of the app.  Many developers also find it easier to rationalize about layout when all the hints are collated together in a single place (rather than scattered across the class members as annotations).
-
-Another benefit of dynamic layout is that UI hints can be provided for xref:ug.adoc#_ug_how-tos_contributed-members[contributed associations and actions] that are synthesised at runtime.
-
-The main downsides of using dynamic layouts are a lack of typesafety (a typo will result in the metadata not being picked up for the element) and syntactic fragility (an invalid JSON document will result in no metadata for the entire class).
-
-Also, dynamic layouts have no notion of inheritance, whereas the dewey-decimal format `@MemberOrder` annotation allows the metadata of the subclass its superclasses to fit together relatively seamlessly.
-
-
-
-== Best of both worlds?
-
-Using the (non-ASF) link:http://github.com/isisaddons/isis-jrebel-plugin[Isis addons' jrebel] plugin comes close to getting the best of both words: metadata is specified in a type-safe way using annotations, but can be reloaded automatically.
-
-The downsides are licensing cost, and also the fact that metadata for contributed actions in the contributee class cannot be specified.
-
-Another open source alternative that you might also like to explore is DCEVM; there's a good write-up on the link:http://blog.jetbrains.com/idea/2013/07/get-true-hot-swap-in-java-with-dcevm-and-intellij-idea/[IntelliJ blog].
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_object-layout_static.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_object-layout_static.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_object-layout_static.adoc
deleted file mode 100644
index e706944..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_object-layout_static.adoc
+++ /dev/null
@@ -1,159 +0,0 @@
-[[_ug_object-layout_static]]
-= Static Object Layout
-: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/
-
-
-Metadata providing UI hints can be specified either statically, using annotations, or dynamically, using a `.layout.json` file.  This section describes the static approach, using annotations.
-
-
-
-== `@MemberOrder`
-
-The `@MemberOrder` annotation is used to specify the relative order of domain class properties, collections and actions.
-
-The annotation defines two attributes, `name()` and `sequence()`.  Their usage depends on the member type:
-
-* for properties, the `name()` is used to group properties together.  The `sequence()` then orders properties within these groups. If no `name()` is specified then the property is placed in a fallback "General" group, called "General". +
-+
-The name of these "member groups" are then referenced by xref:rgant.adoc#_rgant-MemberGroupLayout[`@MemberGroupLayout`].
-
-* for collections, the `name()` attribute is (currently) unused.  The `sequence()` orders collections relative to one another
-
-* for actions, the `name()` attribute associates an action with either a property or with a collection. +
-+
-If the `name()` attribute matches a property name, then the action's button is rendered close to the property, according to xref:rgant.adoc#_rgant-ActionLayout_position[`@ActionLayout#position()`] attribute. +
-+
-On the other hand if the `name() attribute matches a collection name, then the action's button is rendered on the collection's header. +
-+
-If there is no `name()` value, then the action is considered to pertain to the object as a whole, and its button is rendered close to the object's icon and title.
-+
-Within any of these, the `sequence()` then determines the relative ordering of the action with respect to other actions that have been similarly associated with properties/collections or left as "free-standing".
-
-
-For example:
-
-[source,java]
-----
-public class ToDoItem {
-    @MemberOrder(sequence="1")
-    public String getDescription() { ... }
-    @MemberOrder(sequence="2")
-    public String getCategory() { ... }
-    @MemberOrder(sequence="3")
-    public boolean isComplete() { ... }
-    @MemberOrder(name="Detail", sequence="1")
-    public LocalDate getDueBy() { ... }
-    @MemberOrder(name="Detail", sequence="2")
-    public BigDecimal getCost() { ... }
-    @MemberOrder(name="Detail", sequence="4")
-    public String getNotes() { ... }
-    @MemberOrder(name="Misc", sequence="99")
-    public Long getVersionSequence() { ... }
-    ...
-}
-----
-
-This defines three property (or member) groups, "General", "Detail" and "Misc"; "General" is the default if no `name` attribute is specified. Properties in the same member group are rendered together, as a fieldset.
-
-In addition, actions can optionally be associated (rendered close to) either properties or actions. This is done by overloading the `@MemberOrder`'s `name` attribute, holding the value of the property or collection.
-
-For example:
-
-[source,java]
-----
-public class ToDoItem {
-    @MemberOrder(sequence="3")
-    public boolean isComplete() { ... }
-    @MemberOrder(name="complete", sequence="1")
-    public ToDoItem completed() { ...}
-    @MemberOrder(name="complete", sequence="2")
-    public ToDoItem notYetCompleted() { ...}
-
-    @MemberOrder(sequence="1")
-    public SortedSet<ToDoItem> getDependencies() { ... }
-    @MemberOrder(name="dependencies", sequence="1")
-    public ToDoItem add(ToDoItem t) { ...}
-    @MemberOrder(name="dependencies", sequence="2")
-    public ToDoItem remove(ToDoItem t) { ...}
-    ...
-}
-----
-
-will associate the `completed()` and `notYetCompleted()` actions with the `complete` property, and will associate the `add()` and `remove()` actions with the `dependencies` collection.
-
-
-The value of `sequence()` is a string.  The simplest convention (as shown in the example above) is to use numbers -- 1, 2, 3 -- though it is a better idea to leave gaps in the numbers -- 10, 20, 30 perhaps -- such that a new member may be added without having to edit existing numbers.  A useful alternative is to adopt the 'dewey-decimal' notation -- 1, 1.1, 1.2, 2, 3, 5.1.1, 5.2.2, 5.2, 5.3 -- which allows for an indefinite amount of future insertion.  It also allows subclasses to insert their class members as required.
-
-
-
-
-== `@MemberGroupLayout`
-
-The `@MemberGroupLayout` annotation specifies the relative positioning of property groups as being either in a left column, a middle column or in a right column.  The annotation also specifies the relative width of the columns.
-
-The property groups in this case are those that are inferred from the `@MemberOrder#name()` attribute.
-
-For example:
-
-[source,java]
-----
-@MemberGroupLayout(
-     columnSpans={3,3,0,6},
-     left={"General", "Misc"},
-     middle="Detail"
- )
-public class ToDoItem {
-    ...
-}
-----
-
-Four values are given in the `columnSpans` attribute. The first three are the relative widths of the three columns of property groups. The fourth, meanwhile, indicates the width of a final column that holds all the collections of the object.
-
-The values of these spans are taken as proportions of 12 virtual columns across the page (this taken from the link:http://getbootstrap.com/2.3.2/[Bootstrap] library).
-
-For example:
-
-* `{3,3,0,6}` indicates:
-** a left column of properties taking up 25% of the width
-** a middle column of properties taking up 25% of the width
-** a right column of collections taking up 50% of the width
-* `{2,6,0,4}` indicates:
-** a left column of properties taking up ~16% of the width
-** a middle column of properties taking up 50% of the width
-** a right column of collections taking up ~33% of the width
-* `{2,3,3,4}` indicates:
-** a left column of properties taking up ~16% of the width
-** a middle column of properties taking up 25% of the width
-** a right column of properties taking up 25% of the width
-** a far right column of collections taking up ~33% of the width
-
-If the sum of all the columns exceeds 12, then the collections are placed underneath the properties, taking up the full span. For example:
-
-* {4,4,4,12} indicates:
-** a left column of properties taking up ~33% of the width
-** a middle column of properties taking up ~33% of the width
-** a right column of properties taking up ~33% of the width
-** the collections underneath the property columns, taking up the full width
-
-== Example Layouts
-
-Below are sketches for the layout of the https://github.com/apache/isis/blob/f38fdb92941172eabb12e0943509f239e6d5925f/example/application/quickstart_wicket_restful_jdo/dom/src/main/java/dom/todo/ToDoItem.java[ToDoItem] class of the Isis addons example https://github.com/isisaddons/isis-app-todoapp/[todoapp] (not ASF):
-
-The first divides the properties into two equal sized columns (6-6-0) and puts the collections underneath (12):
-
-image::{_imagesdir}reference-layout/6-6-0-12.png[width="720px",link="{_imagesdir}reference-layout/6-6-0-12.png"]
-
-The next divides the collections into three equal sized columns (4-4-4) and again puts the collections underneath (12):
-
-image::{_imagesdir}reference-layout/4-4-4-12.png[width="720px",link="{_imagesdir}reference-layout/4-4-4-12.png"]
-
-The last puts the properties into a single column (4-0) and places the collections into the other larger column (8-0):
-
-image::{_imagesdir}reference-layout/4-0-8-0.png[width="720px",link="{_imagesdir}reference-layout/4-0-8-0.png"]
-
-
-== Other Annotations
-
-As of 1.8.0, all the layout annotations have been consolidated into the various `XxxLayout` annotations: xref:rgant.adoc#_rgant-ActionLayout, [`@ActionLayout`] xref:rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`],  xref:rgant.adoc#_rgant-DomainObjectLayout[`@DomainObjectLayout`],  xref:rgant.adoc#_rgant-DomainServiceLayout[`@DomainServiceLayout`],  xref:rgant.adoc#_rgant-ParameterLayout[`@ParameterLayout`], xref:rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`], and xref:rgant.adoc#_rgant-ViewModelLayout[`@ViewModelLayout`]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugbtb_deployment_neo4j.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_deployment_neo4j.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_deployment_neo4j.adoc
index 9671be1..9587662 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_deployment_neo4j.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_deployment_neo4j.adoc
@@ -6,7 +6,7 @@
 
 As of 1.8.0 Apache Isis has experimental support for Neo4J, courtesy of DataNucleus' http://www.datanucleus.org/products/datanucleus/datastores/neo4j.html[Neo4J Datastore] implementation.
 
-The xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype] has been updated so that they can be optionally run under Neo4J.
+The xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] has been updated so that they can be optionally run under Neo4J.
 
 [TIP]
 ====
@@ -44,13 +44,13 @@ Add the following dependency to the `webapp` project's `pom.xml`:
 ----
 <1> for Isis v1.9.0, use the value shown.  for Isis v1.8.0, use 3.2.3.
 
-In the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype] this is defined under the "neo4j" profile so can be activated using `-P neo4j`.
+In the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] this is defined under the "neo4j" profile so can be activated using `-P neo4j`.
 
 == Try it out!
 
 If you want to quickly try out neo4j for yourself:
 
-* run the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype] (v1.8.0)
+* run the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] (v1.8.0)
 
 * build the app:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_decoupling_contributions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_decoupling_contributions.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_decoupling_contributions.adoc
index abf48c8..29a75c2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_decoupling_contributions.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_decoupling_contributions.adoc
@@ -15,7 +15,7 @@ singletons, whereas mixins are instantiated as required (by the framework) and t
 
 For more on contributed services:
 
-* the syntax of writing contributed actions/properties/collections is described in this xref:ug.adoc#_ug_how-tos_contributed-members[how-to]
+* the syntax of writing contributed actions/properties/collections is described in this xref:ug.adoc#_ugfun_how-tos_contributed-members[how-to]
 
 * there's also useful information in the reference guide, discussing the xref:rgant.adoc#_rgant-DomainService_nature[@DomainService#nature()] attribute, for the `NatureOfService.VIEW_CONTRIBUTIONS_ONLY` nature.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_i18n.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_i18n.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_i18n.adoc
index e119bac..b7064a1 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_i18n.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_i18n.adoc
@@ -110,7 +110,7 @@ However, for an application to be fully internationalized, any validation messag
 
 The first part of the puzzle is tackled by an extension to Apache Isis' programming model.  Whereas previously the `disableXxx()` / `validateXxx()` / `title()` methods could only return a `java.lang.String`, they may now optionally return a `TranslatableString` (defined in Isis applib) instead.
 
-Here's a (silly) example from the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype]:
+Here's a (silly) example from the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]:
 
 [source,java]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_view-models_use-cases.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_view-models_use-cases.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_view-models_use-cases.adoc
index 214fcd6..a9e523d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_view-models_use-cases.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_view-models_use-cases.adoc
@@ -87,7 +87,7 @@ what the use cases are that those domain entities are trying to support.  You ce
 domain layer that could support every conceivable use case before starting to think about view models.
 
 Instead, you should iterate.  Identify the use case/story/end-user objective that you will deliver value to the
-business.  Then build out the minimum domain entities to support that use case (refining the xref:ug.adoc#_ug_core-concepts_philosophy_domain-driven-design_ubiquitous-language[ubiquitous language] as you
+business.  Then build out the minimum domain entities to support that use case (refining the xref:ug.adoc#_ugfun_core-concepts_philosophy_domain-driven-design_ubiquitous-language[ubiquitous language] as you
 go).  Then, identify if there any view models that could be introduced which would simplify the end-user interactions
 with the system (perhaps automating several related use cases together).
 ****

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugbtb_programming-model_custom-validator.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_programming-model_custom-validator.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_programming-model_custom-validator.adoc
index 0af1926..31777f3 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_programming-model_custom-validator.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_programming-model_custom-validator.adoc
@@ -17,7 +17,7 @@ You can also impose your own application-specific rules by installing your own m
 
 [TIP]
 ====
-Isis' xref:ug.adoc#_ug_isis-maven-plugin[Maven plugin] will also validate the domain object model during build time.
+Isis' xref:ug.adoc#_ugfun_isis-maven-plugin[Maven plugin] will also validate the domain object model during build time.
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugbtb_programming-model_layout-metadata-reader.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_programming-model_layout-metadata-reader.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_programming-model_layout-metadata-reader.adoc
index dd5940a..d684ac1 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_programming-model_layout-metadata-reader.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_programming-model_layout-metadata-reader.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-The metadata for domain objects is obtained both xref:ug.adoc#_ug_object-layout_static[statically] and xref:ug.adoc#_ug_object-layout_dynamic[dynamically].
+The metadata for domain objects is obtained both xref:ug.adoc#_ugfun_object-layout_static[statically] and xref:ug.adoc#_ugfun_object-layout_dynamic[dynamically].
 
 The default implementation for reading dynamic layout metadata is `org.apache.isis.core.metamodel.layoutmetadata.json.LayoutMetadataReaderFromJson`, which is responsible for reading from the `Xxx.layout.json` files on the classpath (for each domain entity `Xxx`).
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts.adoc
new file mode 100644
index 0000000..9c825e7
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts.adoc
@@ -0,0 +1,22 @@
+[[_ugfun_core-concepts]]
+= 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/
+
+This introductory chapter should give you a good about what Apache Isis actually *is*: the fundamental ideas and principles that it builds upon, how it compares with other frameworks, what the fundamental building blocks are for actually writing an Isis application, and what services and features the framework provides for you to leverage in your own apps.
+
+[TIP]
+====
+Parts of this chapter have been adapted from Dan Haywood's 2009 book, 'Domain Driven Design using Naked Objects'.  We've also added some new insights and made sure the material we've used is relevant to Apache Isis.
+====
+
+
+include::_ugfun_core-concepts_philosophy.adoc[leveloffset=+1]
+include::_ugfun_core-concepts_principles.adoc[leveloffset=+1]
+include::_ugfun_core-concepts_building-blocks.adoc[leveloffset=+1]
+include::_ugfun_core-concepts_framework-provided-services.adoc[leveloffset=+1]
+include::_ugfun_core-concepts_add-ons.adoc[leveloffset=+1]
+include::_ugfun_core-concepts_other-deployment-options.adoc[leveloffset=+1]
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_add-ons.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_add-ons.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_add-ons.adoc
new file mode 100644
index 0000000..8c031b5
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_add-ons.adoc
@@ -0,0 +1,35 @@
+[[_ugfun_core-concepts_add-ons]]
+= Isis Add-ons
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+The link:http://www.isisaddons.org[Isis Addons] website provides a number of reusable modules and other extensions for Apache Isis.  This chapter focuses just on the modules, all of which have a name of the form `isis-module-xxx`.
+
+[WARNING]
+====
+Note that Isis addons, while maintained by Apache Isis committers, are not part of the ASF.
+====
+
+
+
+The modules themselves fall into four broad groups:
+
+* modules that provide an implementations of API defined by Apache Isis +
++
+where Apache Isis has hooks to use the service if defined by provides no implementations of its own.  The http://github.com/isisaddons/isis-module-command[command], http://github.com/isisaddons/isis-module-audit[auditing], http://github.com/isisaddons/isis-module-publishing[publishing], http://github.com/isisaddons/isis-module-security[security]  and http://github.com/isisaddons/isis-module-sessionlogger[sessionlogger] modules fall into this category.  Typically the domain objects themselves wouldn't interact with these services
+
+* modules that provide standalone domain services with their own API and implementation +
++
+These are simply intended to be used by domain objects.  The http://github.com/isisaddons/isis-module-docx[docx], http://github.com/isisaddons/isis-module-excel[excel], http://github.com/isisaddons/isis-module-settings[settings] and http://github.com/isisaddons/isis-module-stringinterpolator[stringinterpolator] fall into this category.
+
+* modules that provide standalone domain entities (and supporting services) for a particular subdomain +
++
+The http://github.com/isisaddons/isis-module-tags[tags] module falls into this category
+
+* modules that provide developer utilities +
++
+Not intended for use by either the framework or domain objects, but provide utilities that the developer themselves might use.  The http://github.com/isisaddons/isis-module-devutils[devutils] module (not suprisingly) falls into this category
+
+Each of the modules has a full README and example application demonstrating their usage.  The sections below briefly outline the capabilities of these modules.

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_building-blocks.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_building-blocks.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_building-blocks.adoc
new file mode 100644
index 0000000..b194875
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_building-blocks.adoc
@@ -0,0 +1,335 @@
+[[_ugfun_core-concepts_building-blocks]]
+= 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/
+
+In this section we run through the main building blocks that make up an Apache Isis application.
+
+[[_ugfun_core-concepts_building-blocks_metamodel]]
+== A MetaModel
+
+At its core, Apache Isis is a metamodel that is built at runtime from the domain classes (eg `Customer.java`), along
+with optional supporting metadata (eg `Customer.layout.json`).
+
+The contents of this metamodel is inferred from the Java classes discovered on the classpath: the entities and
+supporting services, as well the members of those classes.  The detail of the metamodel is generally explicit, usually
+represented by Java annotations such as `@Title` or `@Action`.  Notably the metamodel is
+xref:ugbtb.adoc#_ugbtb_programming-model[extensible]; it is possible to teach Apache Isis new programming
+conventions/rules (and conversely to remove those that are built in).
+
+Most of the annotations recognized by the framework are defined by the Apache Isis framework itself.  For example the
+`@Title` annotation - which identifies how the framework should derive a human-readable label for each rendered
+domain object - is part of the `org.apache.isis.applib.annotations` package.  However the framework also recognizes
+certain other JEE annotations such as `@javax.inject.Inject` (used for dependency injection).
+
+The framework uses DataNucleus for its persistence mechanism.  This is an ORM that implements the JDO and JPA APIs, and
+which can map domain objects either to an RDBMS or to various NoSQL objectstores such as MongoDB or Neo4J.  Apache Isis
+recognizes a number of the JDO annotations such as `@javax.jdo.annotations.Column(allowNulls=...)`.
+
+In addition, the framework builds up the metamodel for each domain object using
+xref:ug.adoc#_ugfun_object-layout[layout hints], such as `Customer.layout.json`.  These provide metadata such as
+grouping elements of the UI together, using multi-column layouts, and so on.  The layout file can be modified while the
+application is still running, and are picked up automatically; a useful way to speed up feedback.
+
+[TIP]
+====
+At the time of writing Apache Isis only recognizes and supports the JDO API, though we expect JPA to be supported
+in the future.  We also expect to generalize support for `.layout.json` to be able to read such metadata from other
+sources.
+====
+
+
+[[_ugfun_core-concepts_building-blocks_types-of-domain-objects]]
+== Type of Domain Objects
+
+Most domain objects that the end-user interacts with are *domain entities*, such as `Customer`, `Order`, `Product` and
+so on.  These are persistent objects and which are mapped to a database (usually relational), using JDO/DataNucleus
+annotations.  From the end-user's perspective the UI displays a single domain object per page; they can then inspect
+and modify its state, and navigate to related objects.
+
+The next type of domain object to discuss is *domain services*.  These are (usually) singleton stateless services
+that provide additional functionality.  The behaviour of these services is rendered in various ways, though the most
+obvious is as the menu actions on the top-level menu bars in the xref:ugvw.adoc#[Wicket viewer]'s UI.
+
+Domain objects can also delegate to domain services; domain services are automatically injected into every other domain
+object; this includes domain entities as well as other services.  This injection of domain services into entities is
+significant: it allows business logic to be implemented in the domain entities, rather than have it "leach away" into
+supporting service layers.  Said another way: it is the means by which Apache Isis helps you avoid the anaemic
+domain model anti-pattern.
+
+As well as domain entities - mapped to a datastore - Apache Isis also supports *view models*.  End users interact with
+view models in the same way as a domain entity, indeed they are unlikely to distinguish one from the other.  However
+view models are _not_ mapped to the underlying database, rather they represent some aggregation of state from one or
+more underlying entities.  Their state is serialized and recreated from their internal identifier; this identifier is
+visible as the object's URL in the xref:ugvw.adoc#[Wicket viewer] or
+xref:ugvro.adoc#[RestfulObjects viewer].
+
+There's no need though for the view model to aggregate the state of regular domain entities.  A view model could also
+be used as a proxy for some externally managed entity, accessed over a web service or REST API; it could even be a
+representation of state held in-memory (such as user preferences, for example).
+
+There are also several types of domain services.  Most easily described are those domain services (discussed above)
+that are represented as the menu actions on top-level menu bars.  Another variation are *contributed services* - domain
+services that contribute behaviour or (derived) state to entities/view models.  Finally domain services may also
+simply provide additional non-UI functionality; an example being to perform an address geocoding lookup against the
+google-maps API.
+
+Also worth mentioning: domain services can also be either singletons (discussed above) or request-scoped; the latter
+being annotated with `@javax.enterprise.context.RequestScoped`.  An example of the request-scoped service is the
+xref:rgsvc.adoc#_rgsvc-api_Scratchpad[`Scratchpad`] service, for sharing arbitrary data between multiple objects.
+
+The final type of domain object is the *mixin*.  These are similar to contributed services in that they also contribute (or rather,
+mixin) both behaviour or (derived) state to entities/view models.  However, they provide a more control over contributed services,
+with a cleaner programming model similar to traits found in other languages.
+
+The diagram below summarizes the various types of domain object:
+
+image::{_imagesdir}core-concepts/building-blocks/types-of-domain-object.png[width="860px",link="{_imagesdir}core-concepts/building-blocks/types-of-domain-object.png"]
+
+
+The Apache Isis programming model uses annotations to distinguish these object types:
+
+* *view models* are annotated either with `@DomainObject(nature=VIEW_MODEL)` or using `@ViewModel`.  Which is used is
+a matter of personal preference.  +
++
+It is also possible to implement the `ViewModel` interface, for finer-grained control.
+
+* *domain entities* that are persisted to the database (as the vast majority will) are annotated with
+`@DomainObject(nature=ENTITY)`. In addition such domain entities are annotated with the JDO/DataNucleus annotation of
+`@javax.jdo.annotations.PersistenceCapable`. +
++
+In addition, if a domain entity is a proxy for state managed in an external system, or merely for some state held
+in-memory, then `@DomainObject(nature=EXTERNAL_ENTITY)` or `@DomainObject(nature=INMEMORY_ENTITY)` can be used.
+
+* *mixins* are annotated either with `@DomainObject(nature=MIXIN)` or using `@Mixin`.  As for view models, which is
+used is a matter of personal preference.
+
+* finally, *domain services*` are annotated with `@DomainService(nature=...)` where the nature is either
+`VIEW_MENU_ONLY` (for domain services whose actions appear on the top-level menu bars), or `VIEW_CONTRIBUTIONS_ONLY`
+(for domain services whose actions are contributed to entities or view models), or `DOMAIN` (for domain services whose
+functionality is simply for other domain objects to invoke programmatically).
++
+It is also possible to specify a nature of simply `VIEW`, this combining `VIEW_MENU_ONLY` and `VIEW_CONTRIBUTIONS_ONLY`.
+This is in fact the default, useful for initial prototyping.  A final nature is `VIEW_REST_ONLY` which is for domain
+services whose functionality is surfaced only by the xref:ugvro.adoc#[RestfulObjects viewer].
+
+Worth emphasising is that domain entities and view models hold state, whereas domain services are generally
+stateless.  If a domain service does hold state (eg the `Scratchpad` service noted above) then it should be
+`@RequestScoped` so that this state is short-lived and usable only within a single request.
+
+
+
+[[_ugfun_core-concepts_building-blocks_objects-members]]
+== Object Members
+
+Every domain object in Apache Isis consists of (at most) three types of members:
+
+* properties, such as a `Customer`'s `firstName
+
+* collections, such as a `Customer`'s `orders` collection of ``Order``s
+
+* actions, such as a `Customer'`s `placeOrder(...)` method.
+
+Some domain objects - specifically domain services and mixins - only have actions.  In the case of contributing services
+and mixins these actions can (depending upon their semantics and signatures) be represented as derived properties or
+collections on the entity/view model to which they contribute/mix-in.
+
+
+=== Properties
+
+Properties follow the standard getter/setter pattern, with the return type being a scalar (a value object or another
+entity or view model).
+
+For example, with:
+
+[source,java]
+----
+public class Customer
+    private String firstName;
+    public String getFirstName() { return firstName; }
+    public void setFirstName(String firstName) { this.firstName = firstName; }
+    ...
+}
+----
+
+the framework infers the `Customer` domain entity, which in turn has a `firstName` string _property_.
+
+
+=== Collections
+
+Collections are also represented by a getter and setter, however the return type is a `Collection` or subtype.
+
+For example, with:
+
+[source,java]
+----
+public class Customer
+    private SortedSet<Order> orders = new TreeSet<Order>();
+    public SortedSet<Order> getOrders() { return orders; }
+    public void setOrders(SortedSet<Order> orders) { this.orders = orders; }
+    ...
+}
+----
+
+the framework infers the `orders` _collection_.
+
+[TIP]
+====
+The most commonly used collection type is `java.util.SortedSet`; entities are most commonly mapped to a relational
+database (ie a datastore with set semantics) and we recommend that all entities define a natural ordering so that when
+rendered in the UI they will be ordered "meaningfully" to the end-user.
+====
+
+
+=== Actions
+
+The third type of object member is actions.  (To a first approximation), actions are all public methods that do not
+represent properties or collections.
+
+For example:
+
+[source,java]
+----
+public class Customer
+    public Customer placeOrder(Product p, int quantity) { ... }
+    ...
+}
+----
+
+corresponds to the `placeOrder` _action_.
+
+[NOTE]
+====
+The above _is_ a simplification; the Apache Isis programming model also recognizes a number of other supporting methods
+each of which has its own prefix such as `hide`, `disable` or `validate`.  These can be considered as "reserved words"
+in Apache Isis, and do _not_ correspond to actions even though they have public visibility.
+====
+
+
+
+== Entities vs View Models
+
+When developing an Apache Isis application you will most likely start off with the persistent domain entities:
+`Customer`, `Order`, `Product`, and so on.  For some applications this may well suffice.  However, if the application
+needs to integrate with other systems, or if the application needs to support reasonably complex business processes,
+then you may need to look beyond just domain entities.
+
+To support these use cases we support view models.  In the same way that an (RDBMS) database view can aggregate and
+abstract from multiple underlying database tables, so a view model sits on top of one or many underlying entities.
+
+View models are not persisted, but nevertheless they can have behaviour (and titles, and icons) just like domain
+entities.  Indeed, to a user of the system there is no particular distinction (again, in the same way that when using
+an RDBMS one can use database views and database tables pretty much interchangeably).
+
+View models generally tend to be associated with supporting a particular use case; logically they are part of the
+application layer, not part of the domain layer (where entities live).
+
+We introduce view models here because they do get mentioned quite often within the users and reference guide.  However,
+we do consider them a more advanced topic; we generally recommend that you build your applications from the domain
+layer up, rather than from the view model down.
+
+For further discussion on view models, see xref:ugbtb.adoc#_ugbtb_more-advanced_view-models[this topic].
+
+
+
+
+[[_ugfun_core-concepts_building-blocks_domain-services]]
+== 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. Apache 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
+
+NOTE: TODO
+
+`@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:http://books.google.com/books/about/Domain_Driven_Design.html?id=hHBf4YxMnWMC[Domain Driven Design], 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.
+****
+
+
+
+[[_ugfun_core-concepts_building-blocks_mixins-and-contributions]]
+== Mixins & Contributions
+
+NOTE: TODO
+
+
+For more information, see xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling_contributions[this topic on contribution]s, and
+xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling_mixins[this topic on mixin]s.
+
+
+
+[[_ugfun_core-concepts_building-blocks_domain-events]]
+== Domain Events
+
+NOTE: TODO; see xref:rgcms.adoc#_rgcms_classes_domainevent[domain event] classes.
+
+
+
+=== UI Events (`1.11.0-SNAPSHOT`)
+
+NOTE: TODO; see xref:rgcms.adoc#_rgcms_classes_uievent[UI event] classes.
+
+
+
+
+[[_ugfun_core-concepts_building-blocks_oid]]
+== OIDs
+
+As well as defining a xref:ug.adoc#_ugfun_core-concepts_building-blocks_metamodel[metamodel] of the structure (domain
+classes) of its domain objects, Apache Isis also manages the runtime instances of said domain objects.
+
+When a domain entity is recreated from the database, the framework keeps track of its identity through an "OID": an
+object identifier.  Fundamentally this is a combination of its type (domain class), along with an identifier.  You can think
+of it as its "primary key", except across all domain entity types.
+
+For portability and resilience, though, the object type is generally an alias for the actual domain class: thus
+"customers.CUS", say, rather than "com.mycompany.myapp.customers.Customer".  This is derived from an annotation.  The
+identifier meanwhile is always converted to a string.
+
+Although simple, the OID is an enormously powerful concept: it represents a URI to any domain object managed by
+a given Apache Isis application.  With it, we have the ability to lookup any arbitrary domain objects.
+
+Some examples:
+
+* an OID allows sharing of information between users, eg as a deep link to be pasted into an email.
+
+* the information within an OID could be converted into a barcode, and stamped onto a PDF form.  When the PDF is
+scanned by the mail room, the barcode could be read to attach the correspondence to the relevant domain object.
+
+* as a handle to any object in an audit record (as used by the
+xref:rgsvc.adoc#_rgsvc-spi_AuditingService[`AuditingService`], in fact).
+
+* and of course both the xref:ugvro.adoc#[RestfulObjects viewer] and
+xref:ugvw.adoc#[Wicket viewer]
+use the oid tuple to look up, render and allow the user to interact with domain objects.
+
+Although the exact content of an OID should be considered opaque by domain objects, it is possible for domain objects
+to obtain OIDs.  These are represented as `Bookmark`s, obtained from the
+xref:rgsvc.adoc#_rgsvc-api_BookmarkService[`BookmarkService`].  Deep links meanwhile can be obtained from
+the xref:rgant.adoc#_rgant-DeepLinkService[`@DeepLinkService`].
+
+OIDs can also be converted into XML format, useful for integration scenarios.  The
+xref:rgcms.adoc#_rgcms_schema-common[common schema] XSD defines the `oidDto` complex type for precisely this purpose.
+
+
+
+[[_ugfun_core-concepts_building-blocks_value-objects]]
+== Value Objects (Primitives)
+
+NOTE: TODO
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_framework-provided-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_framework-provided-services.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_framework-provided-services.adoc
new file mode 100644
index 0000000..b57e68e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_framework-provided-services.adoc
@@ -0,0 +1,54 @@
+[[_ugfun_core-concepts_framework-provided-services]]
+= 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/
+
+
+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.
+
+
+General purpose:
+
+* xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer[`DomainObjectContainer`]
+* xref:rgsvc.adoc#_rgsvc-api_ClockService[`ClockService`]
+* xref:rgsvc.adoc#_rgsvc-api_IsisJdoSupport[`IsisJdoSupport`]
+* xref:rgsvc.adoc#_rgsvc-api_WrapperFactory[`WrapperFactory`]
+* xref:rgsvc.adoc#_rgsvc-api_EventBusService[`EventBusService`]
+* xref:rgsvc.adoc#_rgsvc-api_EmailService[`EmailService`]
+
+Commands/Background/Auditing:
+
+* xref:rgsvc.adoc#_rgsvc-api_CommandContext[`CommandContext`] (SPI)
+* xref:rgsvc.adoc#_rgsvc-spi_CommandService[`CommandService`] (SPI)
+* xref:rgsvc.adoc#_rgsvc-spi_AuditingService[`AuditingService`] (SPI)
+* xref:rgsvc.adoc#_rgsvc-api_BackgroundService[`BackgroundService`]
+* xref:rgsvc.adoc#_rgsvc-spi_BackgroundCommandService[`BackgroundCommandService`] (SPI)
+* xref:rgsvc.adoc#_rgsvc-spi_PublishingService[`PublishingService`] (SPI)
+
+Information Sharing:
+
+* xref:rgsvc.adoc#_rgsvc-api_Scratchpad[`Scratchpad`]
+* xref:rgsvc.adoc#_rgsvc-api_ActionInvocationContext[`ActionInvocationContext`]
+* xref:rgsvc.adoc#_rgsvc-api_QueryResultsCache[`QueryResultsCache`]
+
+
+UserManagement:
+
+* xref:rgsvc.adoc#_rgsvc-spi_UserProfileService[`UserProfileService`] (SPI)
+* xref:rgsvc.adoc#_rgsvc-spi_UserRegistrationService[`UserRegistrationService`] (SPI)
+* xref:rgsvc.adoc#_rgsvc-spi_EmailNotificationService[`EmailNotificationService`] (SPI)
+
+
+Bookmarks and Mementos:
+
+* xref:rgsvc.adoc#_rgsvc-api_BookmarkService[`BookmarkService`]
+* xref:rgsvc.adoc#_rgsvc-api_MementoService[`MementoService`]
+* xref:rgsvc.adoc#_rgsvc-api_DeepLinkService[`DeepLinkService`]
+* xref:rgsvc.adoc#_rgsvc-api_XmlSnapshotService[`XmlSnapshotService`]
+
+
+A full list of services can be found in the xref:rgsvc.adoc#_rgsvc-api[Domain Services (API)]  and xref:rgsvc.adoc#_rgsvc-spi[Domain Services (SPI)] chapters of the reference guide.
+


[35/52] [abbrv] isis git commit: ISIS-1237: started work on swagger integration.

Posted by mg...@apache.org.
ISIS-1237: started work on swagger integration.


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/72cae2f9
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/72cae2f9
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/72cae2f9

Branch: refs/heads/ISIS-1224-select2-v4
Commit: 72cae2f9ab859ab3739601d12c265fe629f812e9
Parents: 2d9b2ee
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Tue Dec 8 07:54:52 2015 +0000
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Tue Dec 8 07:54:52 2015 +0000

----------------------------------------------------------------------
 adocs/documentation/Gemfile.lock                |   3 -
 .../applib/services/swagger/SwaggerService.java |  62 +++
 .../services/swagger/SwaggerServiceMenu.java    |  68 +++
 .../isis/applib/services/swagger/Util.java      |  33 ++
 core/metamodel/pom.xml                          |   5 +
 .../services/swagger/SwaggerServiceDefault.java |  59 +++
 .../services/swagger/internal/SwaggerSpec.java  | 259 ++++++++++
 .../services/swagger/internal/example.json      | 515 +++++++++++++++++++
 .../i18n/po/TranslationServicePoMenu.java       |  37 +-
 9 files changed, 1008 insertions(+), 33 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/72cae2f9/adocs/documentation/Gemfile.lock
----------------------------------------------------------------------
diff --git a/adocs/documentation/Gemfile.lock b/adocs/documentation/Gemfile.lock
index 9b483db..0d4f467 100644
--- a/adocs/documentation/Gemfile.lock
+++ b/adocs/documentation/Gemfile.lock
@@ -45,6 +45,3 @@ DEPENDENCIES
   tilt
   wdm (>= 0.1.0)
   webrick
-
-BUNDLED WITH
-   1.10.6

http://git-wip-us.apache.org/repos/asf/isis/blob/72cae2f9/core/applib/src/main/java/org/apache/isis/applib/services/swagger/SwaggerService.java
----------------------------------------------------------------------
diff --git a/core/applib/src/main/java/org/apache/isis/applib/services/swagger/SwaggerService.java b/core/applib/src/main/java/org/apache/isis/applib/services/swagger/SwaggerService.java
new file mode 100644
index 0000000..901cc62
--- /dev/null
+++ b/core/applib/src/main/java/org/apache/isis/applib/services/swagger/SwaggerService.java
@@ -0,0 +1,62 @@
+/**
+ *  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.
+ */
+package org.apache.isis.applib.services.swagger;
+
+import org.apache.isis.applib.annotation.Action;
+import org.apache.isis.applib.annotation.DomainService;
+import org.apache.isis.applib.annotation.NatureOfService;
+import org.apache.isis.applib.annotation.RestrictTo;
+import org.apache.isis.applib.annotation.ViewModel;
+import org.apache.isis.applib.value.Clob;
+
+public interface SwaggerService {
+
+    public enum Type {
+        /**
+         * Specification for use by third-party clients, ie public use.
+         *
+         * <p>
+         * Restricted only to view models ({@link ViewModel} or equivalent) and {@link DomainService} with a nature
+         * of {@link NatureOfService#VIEW_REST_ONLY}.
+         * </p>
+         */
+        PUBLIC,
+        /**
+         * Specification for use only by internally-managed clients, ie private internal use.
+         *
+         * <p>
+         * Includes specifications of domain entities as well as view models.
+         * </p>
+         */
+        PRIVATE,
+        /**
+         * As {@link #PRIVATE}, also including any prototype actions (where {@link Action#restrictTo()} set to
+         * {@link RestrictTo#PROTOTYPING}).
+         */
+        PRIVATE_WITH_PROTOTYPING;
+
+        public boolean isPublic() {
+            return this == PUBLIC;
+        }
+        public boolean isPrivateWithPrototyping() {
+            return this == PRIVATE_WITH_PROTOTYPING;
+        }
+    }
+
+    public Clob downloadSwaggerSpec(final String fileName, final Type type);
+
+}    

http://git-wip-us.apache.org/repos/asf/isis/blob/72cae2f9/core/applib/src/main/java/org/apache/isis/applib/services/swagger/SwaggerServiceMenu.java
----------------------------------------------------------------------
diff --git a/core/applib/src/main/java/org/apache/isis/applib/services/swagger/SwaggerServiceMenu.java b/core/applib/src/main/java/org/apache/isis/applib/services/swagger/SwaggerServiceMenu.java
new file mode 100644
index 0000000..d1e72b0
--- /dev/null
+++ b/core/applib/src/main/java/org/apache/isis/applib/services/swagger/SwaggerServiceMenu.java
@@ -0,0 +1,68 @@
+/**
+ *  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.
+ */
+package org.apache.isis.applib.services.swagger;
+
+import javax.inject.Inject;
+
+import org.apache.isis.applib.IsisApplibModule;
+import org.apache.isis.applib.annotation.Action;
+import org.apache.isis.applib.annotation.ActionLayout;
+import org.apache.isis.applib.annotation.DomainService;
+import org.apache.isis.applib.annotation.DomainServiceLayout;
+import org.apache.isis.applib.annotation.MemberOrder;
+import org.apache.isis.applib.annotation.NatureOfService;
+import org.apache.isis.applib.annotation.ParameterLayout;
+import org.apache.isis.applib.annotation.RestrictTo;
+import org.apache.isis.applib.annotation.SemanticsOf;
+import org.apache.isis.applib.value.Clob;
+
+
+@DomainService(
+        nature = NatureOfService.VIEW_MENU_ONLY
+)
+@DomainServiceLayout(
+        named = "Prototyping",
+        menuBar = DomainServiceLayout.MenuBar.SECONDARY,
+        menuOrder = "500.800"
+)
+public class SwaggerServiceMenu {
+
+    public static abstract class ActionDomainEvent extends IsisApplibModule.ActionDomainEvent<SwaggerServiceMenu> {
+    }
+
+    public static class DownloadSwaggerSpecDomainEvent extends ActionDomainEvent {}
+
+    @Action(
+            semantics = SemanticsOf.SAFE,
+            domainEvent = DownloadSwaggerSpecDomainEvent.class,
+            restrictTo = RestrictTo.PROTOTYPING
+    )
+    @ActionLayout(
+            cssClassFa = "fa-download"
+    )
+    @MemberOrder(sequence="500.800.1")
+    public Clob downloadSwaggerSpec(
+            @ParameterLayout(named = "Filename")
+            final String fileName,
+            final SwaggerService.Type type) {
+        return swaggerService.downloadSwaggerSpec(Util.withSuffix(fileName, "json"), type);
+    }
+
+
+    @Inject
+    SwaggerService swaggerService;
+}    

http://git-wip-us.apache.org/repos/asf/isis/blob/72cae2f9/core/applib/src/main/java/org/apache/isis/applib/services/swagger/Util.java
----------------------------------------------------------------------
diff --git a/core/applib/src/main/java/org/apache/isis/applib/services/swagger/Util.java b/core/applib/src/main/java/org/apache/isis/applib/services/swagger/Util.java
new file mode 100644
index 0000000..ec07c7f
--- /dev/null
+++ b/core/applib/src/main/java/org/apache/isis/applib/services/swagger/Util.java
@@ -0,0 +1,33 @@
+/**
+ *  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.
+ */
+package org.apache.isis.applib.services.swagger;
+
+class Util {
+
+    private Util(){}
+
+    static String withSuffix(String fileName, String suffix) {
+        if(!suffix.startsWith(".")) {
+            suffix = "." + suffix;
+        }
+        if(!fileName.endsWith(suffix)) {
+            fileName += suffix;
+        }
+        return fileName;
+    }
+
+}

http://git-wip-us.apache.org/repos/asf/isis/blob/72cae2f9/core/metamodel/pom.xml
----------------------------------------------------------------------
diff --git a/core/metamodel/pom.xml b/core/metamodel/pom.xml
index a00706d..629b0a2 100644
--- a/core/metamodel/pom.xml
+++ b/core/metamodel/pom.xml
@@ -93,6 +93,11 @@
             <groupId>org.datanucleus</groupId>
             <artifactId>datanucleus-jodatime</artifactId>
         </dependency>
+        <dependency>
+            <groupId>io.swagger</groupId>
+            <artifactId>swagger-core</artifactId>
+            <version>1.5.4</version>
+        </dependency>
     </dependencies>
 
 </project>

http://git-wip-us.apache.org/repos/asf/isis/blob/72cae2f9/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/SwaggerServiceDefault.java
----------------------------------------------------------------------
diff --git a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/SwaggerServiceDefault.java b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/SwaggerServiceDefault.java
new file mode 100644
index 0000000..fbf3737
--- /dev/null
+++ b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/SwaggerServiceDefault.java
@@ -0,0 +1,59 @@
+/*
+ *  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.
+ */
+package org.apache.isis.core.metamodel.services.swagger;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import org.apache.isis.applib.annotation.DomainService;
+import org.apache.isis.applib.annotation.NatureOfService;
+import org.apache.isis.applib.services.swagger.SwaggerService;
+import org.apache.isis.applib.value.Clob;
+import org.apache.isis.core.metamodel.services.swagger.internal.SwaggerSpec;
+import org.apache.isis.core.metamodel.spec.SpecificationLoader;
+import org.apache.isis.core.metamodel.spec.SpecificationLoaderAware;
+
+@DomainService(
+        nature = NatureOfService.DOMAIN
+)
+public class SwaggerServiceDefault implements SwaggerService, SpecificationLoaderAware {
+
+    @SuppressWarnings("unused")
+    private final static Logger LOG = LoggerFactory.getLogger(SwaggerServiceDefault.class);
+
+    @Override
+    public Clob downloadSwaggerSpec(final String fileName, final Type type) {
+
+        SwaggerSpec swaggerSpec = new SwaggerSpec(specificationLoader);
+
+        String yaml = swaggerSpec.generate(type);
+        return new Clob(fileName, "text/json", yaml);
+    }
+
+    //region > injected dependencies
+    private SpecificationLoader specificationLoader;
+
+    @Override
+    public void setSpecificationLoader(final SpecificationLoader specificationLookup) {
+        this.specificationLoader = specificationLookup;
+    }
+
+    //endregion
+
+}

http://git-wip-us.apache.org/repos/asf/isis/blob/72cae2f9/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpec.java
----------------------------------------------------------------------
diff --git a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpec.java b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpec.java
new file mode 100644
index 0000000..a62c236
--- /dev/null
+++ b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpec.java
@@ -0,0 +1,259 @@
+/*
+ *  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.
+ */
+package org.apache.isis.core.metamodel.services.swagger.internal;
+
+import java.util.Arrays;
+import java.util.Collection;
+import java.util.List;
+
+import org.apache.isis.applib.annotation.NatureOfService;
+import org.apache.isis.applib.filter.Filters;
+import org.apache.isis.applib.services.swagger.SwaggerService;
+import org.apache.isis.core.metamodel.facets.object.domainservice.DomainServiceFacet;
+import org.apache.isis.core.metamodel.spec.ActionType;
+import org.apache.isis.core.metamodel.spec.ObjectSpecification;
+import org.apache.isis.core.metamodel.spec.SpecificationLoader;
+import org.apache.isis.core.metamodel.spec.feature.Contributed;
+import org.apache.isis.core.metamodel.spec.feature.ObjectAction;
+
+import io.swagger.models.Info;
+import io.swagger.models.ModelImpl;
+import io.swagger.models.Operation;
+import io.swagger.models.Path;
+import io.swagger.models.Response;
+import io.swagger.models.Swagger;
+import io.swagger.models.properties.ArrayProperty;
+import io.swagger.models.properties.IntegerProperty;
+import io.swagger.models.properties.ObjectProperty;
+import io.swagger.models.properties.RefProperty;
+import io.swagger.models.properties.StringProperty;
+import io.swagger.util.Json;
+
+public class SwaggerSpec {
+
+    private final SpecificationLoader specificationLoader;
+
+    public SwaggerSpec(final SpecificationLoader specificationLoader) {
+        this.specificationLoader = specificationLoader;
+    }
+
+    public String generate(final SwaggerService.Type type) {
+        final Swagger swagger = new Swagger();
+        swagger.info(new Info()
+                        .version("1.0.0")
+                        .title("Restful Objects"))
+                .path("/",
+                        new Path()
+                            .get(new Operation()
+                                    .description("RO Spec v1.0, section 5.1")
+                                    .consumes("application/json")
+                                    .consumes("application/json;profile=\"urn:org.restfulobjects:repr-types/home-page\"")
+                                    .produces("application/json;profile=\"urn:org.restfulobjects:repr-types/home-page\"")
+                                    .response(200,
+                                            newResponse(Caching.LONG_TERM)
+                                            .description("OK")
+                                            .schema(new RefProperty("#/definitions/home-page"))
+                                    )))
+                .path("/user",
+                        new Path()
+                            .get(new Operation()
+                                    .description("RO Spec v1.0, section 6.1")
+                                    .consumes("application/json")
+                                    .consumes("application/json;profile=\"urn:org.restfulobjects:repr-types/user\"")
+                                    .produces("application/json;profile=\"urn:org.restfulobjects:repr-types/user\"")
+                                    .response(200,
+                                            newResponse(Caching.SHORT_TERM)
+                                            .description("OK")
+                                            .schema(new RefProperty("#/definitions/user"))
+                                    )))
+                .path("/version",
+                        new Path()
+                            .get(new Operation()
+                                    .description("RO Spec v1.0, section 8.1")
+                                    .consumes("application/json")
+                                    .consumes("application/json;profile=\"urn:org.restfulobjects:repr-types/version\"")
+                                    .produces("application/json;profile=\"urn:org.restfulobjects:repr-types/version\"")
+                                    .response(200,
+                                            newResponse(Caching.LONG_TERM)
+                                            .description("OK")
+                                            .schema(new RefProperty("#/definitions/version"))
+                                    )));
+
+        swagger.addDefinition("home-page",
+                new ModelImpl()
+                    .description("RO Spec v1.0, section 5.2")
+                    .type("object")
+                    .property("links", arrayOfLinksGetOnly())
+                        .required("links")
+                    );
+
+        swagger.addDefinition("user",
+                new ModelImpl()
+                    .description("RO Spec v1.0, section 6.2")
+                    .type("object")
+                    .property("userName", stringProperty())
+                    .property("roles", arrayOfStrings())
+                    .property("links", arrayOfLinksGetOnly())
+                    .required("userName")
+                    .required("roles")
+                    .required("links")
+                );
+
+        swagger.addDefinition("version",
+                new ModelImpl()
+                    .description("RO Spec v1.0, section 8.2")
+                    .type("object")
+                    .property("specVersion", stringProperty())
+                    .property("implVersion", stringProperty())
+                    .property("optionalCapabilities",
+                            new ObjectProperty()
+                                .property("blobsClobs", stringProperty())
+                                .property("deleteObjects", stringProperty())
+                                .property("domainModel", stringProperty())
+                                .property("validateOnly", stringProperty())
+                                .property("protoPersistentObjects", stringProperty())
+                            )
+                    .property("links", arrayOfLinksGetOnly())
+                    .property("extensions", new ObjectProperty())
+                    .required("userName")
+                    .required("roles")
+                    .required("links")
+                );
+
+        swagger.addDefinition("link",
+                new ModelImpl()
+                    .type("object")
+                    .property("rel", stringProperty())
+                    .property("href", stringProperty())
+                    .property("title", stringProperty())
+                    .property("method", stringPropertyEnum("GET", "POST", "PUT", "DELETE"))
+                    .property("type", stringProperty())
+                    .property("arguments", new ObjectProperty())
+                    .required("rel")
+                    .required("href")
+                    .required("method")
+        );
+
+        swagger.addDefinition("link-get-only",
+                new ModelImpl()
+                    .type("object")
+                    .property("rel", stringProperty())
+                    .property("href", stringProperty())
+                    .property("title", stringProperty())
+                    .property("method", stringPropertyEnum("GET"))
+                    .property("type", stringProperty())
+                    .required("rel")
+                    .required("href")
+                    .required("method")
+        );
+
+
+        final Collection<ObjectSpecification> allSpecs = specificationLoader.allSpecifications();
+        for (ObjectSpecification serviceSpec : allSpecs) {
+            final DomainServiceFacet domainServiceFacet = serviceSpec.getFacet(DomainServiceFacet.class);
+            if (domainServiceFacet == null) {
+                continue;
+            }
+            if (type.isPublic() && domainServiceFacet.getNatureOfService() != NatureOfService.VIEW_REST_ONLY) {
+                continue;
+            }
+
+            List<ObjectAction> serviceActions = serviceSpec
+                    .getObjectActions(actionTypesFor(type), Contributed.EXCLUDED, Filters.<ObjectAction>any());
+            for (ObjectAction serviceAction : serviceActions) {
+
+            }
+
+        }
+
+
+        return Json.pretty(swagger);
+    }
+
+    StringProperty stringPropertyEnum(String... enumValues) {
+        StringProperty stringProperty = stringProperty();
+        stringProperty._enum(Arrays.asList(enumValues));
+        if(enumValues.length >= 1) {
+            stringProperty._default(enumValues[0]);
+        }
+        return stringProperty;
+    }
+
+    ArrayProperty arrayOfLinksGetOnly() {
+        return new ArrayProperty()
+                .items(new RefProperty("#/definitions/link-get-only"));
+    }
+
+    StringProperty stringProperty() {
+        return new StringProperty();
+    }
+
+    ArrayProperty arrayOfStrings() {
+        return new ArrayProperty().items(stringProperty());
+    }
+
+    private Response newResponse(final Caching caching) {
+        return withCachingHeaders(new Response(), caching);
+    }
+
+    enum Caching {
+        NO_CACHING {
+            @Override public void withHeaders(final Response response) {
+
+            }
+        },
+        SHORT_TERM {
+            @Override public void withHeaders(final Response response) {
+                response
+                        .header("Cache-Control",
+                                new IntegerProperty()
+                                        ._default(3600));
+            }
+        },
+        LONG_TERM {
+            @Override public void withHeaders(final Response response) {
+                response
+                        .header("Cache-Control",
+                                new IntegerProperty()
+                                        ._default(86400));
+            }
+        };
+
+        public abstract void withHeaders(final Response response);
+    }
+    private Response withCachingHeaders(final Response response, final Caching caching) {
+        caching.withHeaders(response);
+
+        return response;
+    }
+
+    private List<ActionType> actionTypesFor(final SwaggerService.Type type) {
+        switch (type) {
+        case PUBLIC:
+            return Arrays.asList(ActionType.USER);
+        case PRIVATE:
+            return Arrays.asList(ActionType.USER);
+        case PRIVATE_WITH_PROTOTYPING:
+            return Arrays.asList(ActionType.USER, ActionType.EXPLORATION, ActionType.PROTOTYPE, ActionType.DEBUG);
+        }
+        throw new IllegalArgumentException("Unrecognized type '" + type + "'");
+    }
+
+
+}

http://git-wip-us.apache.org/repos/asf/isis/blob/72cae2f9/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/example.json
----------------------------------------------------------------------
diff --git a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/example.json b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/example.json
new file mode 100644
index 0000000..7036c06
--- /dev/null
+++ b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/example.json
@@ -0,0 +1,515 @@
+{
+  "swagger": "2.0",
+  "info": {
+    "version": "1.0.0",
+    "title": "Restful Objects"
+  },
+  "paths": {
+    "/": {
+      "get": {
+        "description": "Home page",
+        "produces": [
+          "application/json"
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "schema": {
+              "type": "object",
+              "required": [
+                "links"
+              ],
+              "properties": {
+                "links": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/definitions/LinkRepresentation"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/services": {
+      "get": {
+        "description": "Services",
+        "produces": [
+          "application/json"
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "schema": {
+              "type": "object",
+              "required": [
+                "value",
+                "links"
+              ],
+              "properties": {
+                "value": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/definitions/LinkRepresentation"
+                  }
+                },
+                "links": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/definitions/LinkRepresentation"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/services/SimpleObjects": {
+      "get": {
+        "description": "SimpleObjects service",
+        "produces": [
+          "application/json"
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "schema": {
+              "$ref": "#/definitions/ServiceRepresentation"
+            }
+          }
+        }
+      }
+    },
+    "/services/SimpleObjects/actions/findByName": {
+      "get": {
+        "description": "SimpleObjects findByName action",
+        "produces": [
+          "application/json"
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "schema": {
+              "$ref": "#/definitions/ActionPromptRepresentation"
+            }
+          }
+        }
+      }
+    },
+    "/services/SimpleObjects/actions/findByName/invoke": {
+      "get": {
+        "description": "SimpleObjects findByName invocation result",
+        "consumes": [
+          "application/json"
+        ],
+        "produces": [
+          "application/json;profile=\"urn:org.restfulobjects/repr-types/action-result\"",
+          "application/json;profile=\"urn:org.apache.isis/v1\"",
+          "application/json;profile=\"urn:org.apache.isis/v1\";suppress=\"true\""
+        ],
+        "responses": {
+          "200": {
+            "description": "All objects matching name",
+            "schema": {
+              "$ref": "#/definitions/ActionInvocationRepresentationOfList"
+            }
+          }
+        }
+      }
+    },
+    "/objects/simple.SimpleObject/{id}": {
+      "get": {
+        "description": "representation of simple.SimpleObject",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "id",
+            "required": true,
+            "type": "string"
+          }
+        ],
+        "produces": [
+          "application/json;profile=\"urn:org.restfulobjects/repr-types/object\"",
+          "application/json;profile=\"urn:org.apache.isis/v1\";repr-type=\"object\""
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "schema": {
+              "$ref": "#/definitions/ObjectRepresentation"
+            }
+          }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "ServiceRepresentation": {
+      "type": "object",
+      "required": [
+        "links",
+        "extensions",
+        "title",
+        "serviceId"
+      ],
+      "properties": {
+        "links": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/LinkRepresentation"
+          }
+        },
+        "extensions": {
+          "$ref": "#/definitions/ServiceOrObjectExtensionsRepresentation"
+        },
+        "title": {
+          "type": "string"
+        },
+        "serviceId": {
+          "type": "string"
+        },
+        "members": {
+          "type": "object",
+          "required": [
+            "listAll",
+            "findByName",
+            "create"
+          ],
+          "properties": {
+            "listAll": {
+              "$ref": "#/definitions/ActionRepresentation"
+            },
+            "findByName": {
+              "$ref": "#/definitions/ActionRepresentation"
+            },
+            "create": {
+              "$ref": "#/definitions/ActionRepresentation"
+            }
+          }
+        }
+      }
+    },
+    "ObjectRepresentation": {
+      "type": "object",
+      "required": [
+        "links",
+        "extensions",
+        "title",
+        "domainType",
+        "instanceId",
+        "members"
+      ],
+      "properties": {
+        "links": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/LinkRepresentation"
+          }
+        },
+        "extensions": {
+          "$ref": "#/definitions/ServiceOrObjectExtensionsRepresentation"
+        },
+        "title": {
+          "type": "string"
+        },
+        "domainType": {
+          "type": "string"
+        },
+        "instanceId": {
+          "type": "string"
+        },
+        "members": {
+          "type": "object",
+          "required": [
+            "name",
+            "versionSequence",
+            "downloadJdoMetadata",
+            "updateName"
+          ],
+          "properties": {
+            "name": {
+              "type": "object",
+              "required": [
+                "id",
+                "memberType",
+                "links",
+                "value",
+                "extensions"
+              ],
+              "properties": {
+                "id": {
+                  "type": "string"
+                },
+                "memberType": {
+                  "type": "string",
+                  "default": "property"
+                },
+                "links": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/definitions/LinkRepresentation"
+                  }
+                },
+                "value": {
+                  "type": "string"
+                },
+                "disabledReason": {
+                  "type": "string"
+                },
+                "extensions": {
+                  "type": "object"
+                }
+              }
+            },
+            "versionSequence": {
+              "type": "object",
+              "required": [
+                "id",
+                "memberType",
+                "links",
+                "value",
+                "format",
+                "extensions"
+              ],
+              "properties": {
+                "id": {
+                  "type": "string"
+                },
+                "memberType": {
+                  "type": "string",
+                  "default": "property"
+                },
+                "links": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/definitions/LinkRepresentation"
+                  }
+                },
+                "value": {
+                  "type": "integer"
+                },
+                "format": {
+                  "type": "string"
+                },
+                "disabledReason": {
+                  "type": "string"
+                },
+                "extensions": {
+                  "type": "object"
+                }
+              }
+            },
+            "downloadJdoMetadata": {
+              "$ref": "#/definitions/ActionRepresentation"
+            },
+            "updateName": {
+              "$ref": "#/definitions/ActionRepresentation"
+            }
+          }
+        }
+      }
+    },
+    "ActionPromptRepresentation": {
+      "type": "object",
+      "required": [
+        "id",
+        "memberType",
+        "links",
+        "extensions",
+        "parameters"
+      ],
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "memberType": {
+          "type": "string"
+        },
+        "links": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/LinkRepresentation"
+          }
+        },
+        "extensions": {
+          "type": "object",
+          "required": [
+            "actionType",
+            "actionSemantics"
+          ],
+          "properties": {
+            "actionType": {
+              "type": "string"
+            },
+            "actionSemantics": {
+              "type": "string",
+              "enum": [
+                "safe",
+                "idempotent",
+                "non_idempotent"
+              ]
+            }
+          }
+        },
+        "parameters": {
+          "type": "object",
+          "required": [
+            "name"
+          ],
+          "properties": {
+            "name": {
+              "$ref": "#/definitions/ActionParameterRepresentation"
+            }
+          }
+        }
+      }
+    },
+    "ServiceOrObjectExtensionsRepresentation": {
+      "type": "object",
+      "required": [
+        "oid",
+        "isService",
+        "isPersistent"
+      ],
+      "properties": {
+        "oid": {
+          "type": "string"
+        },
+        "isService": {
+          "type": "boolean"
+        },
+        "isPersistent": {
+          "type": "boolean"
+        }
+      }
+    },
+    "ActionRepresentation": {
+      "type": "object",
+      "required": [
+        "id",
+        "memberType",
+        "links"
+      ],
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "memberType": {
+          "type": "string",
+          "default": "action"
+        },
+        "links": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/LinkRepresentation"
+          }
+        }
+      }
+    },
+    "ActionParameterRepresentation": {
+      "type": "object",
+      "required": [
+        "num",
+        "id",
+        "name",
+        "description"
+      ],
+      "properties": {
+        "num": {
+          "type": "integer"
+        },
+        "id": {
+          "type": "string"
+        },
+        "name": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        }
+      }
+    },
+    "ActionInvocationRepresentationOfList": {
+      "type": "object",
+      "required": [
+        "links",
+        "resulttype",
+        "result"
+      ],
+      "properties": {
+        "links": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/LinkRepresentation"
+          }
+        },
+        "resulttype": {
+          "type": "string",
+          "default": "list"
+        },
+        "result": {
+          "type": "object",
+          "required": [
+            "value",
+            "links",
+            "extensions"
+          ],
+          "properties": {
+            "value": {
+              "type": "array",
+              "items": {
+                "$ref": "#/definitions/LinkRepresentation"
+              }
+            },
+            "links": {
+              "type": "array",
+              "items": {
+                "$ref": "#/definitions/LinkRepresentation"
+              }
+            },
+            "extensions": {
+              "type": "object"
+            }
+          }
+        }
+      }
+    },
+    "LinkRepresentation": {
+      "type": "object",
+      "required": [
+        "rel",
+        "href",
+        "method"
+      ],
+      "properties": {
+        "rel": {
+          "type": "string",
+          "description": "relationship of this Link"
+        },
+        "href": {
+          "type": "string"
+        },
+        "title": {
+          "type": "string"
+        },
+        "method": {
+          "type": "string",
+          "enum": [
+            "GET",
+            "POST",
+            "PUT",
+            "DELETE"
+          ]
+        },
+        "type": {
+          "type": "string"
+        },
+        "arguments": {
+          "type": "object"
+        }
+      }
+    }
+  }
+}
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/72cae2f9/core/runtime/src/main/java/org/apache/isis/core/runtime/services/i18n/po/TranslationServicePoMenu.java
----------------------------------------------------------------------
diff --git a/core/runtime/src/main/java/org/apache/isis/core/runtime/services/i18n/po/TranslationServicePoMenu.java b/core/runtime/src/main/java/org/apache/isis/core/runtime/services/i18n/po/TranslationServicePoMenu.java
index a2873f1..1ffb123 100644
--- a/core/runtime/src/main/java/org/apache/isis/core/runtime/services/i18n/po/TranslationServicePoMenu.java
+++ b/core/runtime/src/main/java/org/apache/isis/core/runtime/services/i18n/po/TranslationServicePoMenu.java
@@ -18,21 +18,23 @@
  */
 package org.apache.isis.core.runtime.services.i18n.po;
 
-import java.util.List;
 import javax.inject.Inject;
-import org.apache.isis.applib.Identifier;
+
 import org.apache.isis.applib.IsisApplibModule;
 import org.apache.isis.applib.annotation.Action;
 import org.apache.isis.applib.annotation.ActionLayout;
 import org.apache.isis.applib.annotation.DomainService;
 import org.apache.isis.applib.annotation.DomainServiceLayout;
 import org.apache.isis.applib.annotation.MemberOrder;
+import org.apache.isis.applib.annotation.NatureOfService;
 import org.apache.isis.applib.annotation.ParameterLayout;
 import org.apache.isis.applib.annotation.RestrictTo;
 import org.apache.isis.applib.annotation.SemanticsOf;
 import org.apache.isis.applib.value.Clob;
 
-@DomainService()
+@DomainService(
+        nature = NatureOfService.VIEW_MENU_ONLY
+)
 @DomainServiceLayout(
         named = "Prototyping",
         menuBar = DomainServiceLayout.MenuBar.SECONDARY,
@@ -41,25 +43,11 @@ import org.apache.isis.applib.value.Clob;
 public class TranslationServicePoMenu {
 
     public static abstract class ActionDomainEvent extends IsisApplibModule.ActionDomainEvent<TranslationServicePoMenu> {
-        public ActionDomainEvent(final TranslationServicePoMenu source, final Identifier identifier) {
-            super(source, identifier);
-        }
-
-        public ActionDomainEvent(final TranslationServicePoMenu source, final Identifier identifier, final Object... arguments) {
-            super(source, identifier, arguments);
-        }
-
-        public ActionDomainEvent(final TranslationServicePoMenu source, final Identifier identifier, final List<Object> arguments) {
-            super(source, identifier, arguments);
-        }
     }
 
     // //////////////////////////////////////
 
     public static class DownloadPotFileDomainEvent extends ActionDomainEvent {
-        public DownloadPotFileDomainEvent(final TranslationServicePoMenu source, final Identifier identifier, final Object... arguments) {
-            super(source, identifier, arguments);
-        }
     }
 
     @Action(
@@ -87,11 +75,7 @@ public class TranslationServicePoMenu {
 
     // //////////////////////////////////////
 
-    public static class ResetTranslationCacheDomainEvent extends ActionDomainEvent {
-        public ResetTranslationCacheDomainEvent(final TranslationServicePoMenu source, final Identifier identifier, final Object... arguments) {
-            super(source, identifier, arguments);
-        }
-    }
+    public static class ResetTranslationCacheDomainEvent extends ActionDomainEvent { }
 
     @Action(
             domainEvent = ResetTranslationCacheDomainEvent.class,
@@ -112,11 +96,7 @@ public class TranslationServicePoMenu {
 
     // //////////////////////////////////////
 
-    public static class SwitchToReadingTranslationsDomainEvent extends ActionDomainEvent {
-        public SwitchToReadingTranslationsDomainEvent(final TranslationServicePoMenu source, final Identifier identifier, final Object... arguments) {
-            super(source, identifier, arguments);
-        }
-    }
+    public static class SwitchToReadingTranslationsDomainEvent extends ActionDomainEvent { }
 
     @Action(
             domainEvent = SwitchToReadingTranslationsDomainEvent.class,
@@ -137,9 +117,6 @@ public class TranslationServicePoMenu {
     // //////////////////////////////////////
 
     public static class SwitchToWritingTranslationsDomainEvent extends ActionDomainEvent {
-        public SwitchToWritingTranslationsDomainEvent(final TranslationServicePoMenu source, final Identifier identifier, final Object... arguments) {
-            super(source, identifier, arguments);
-        }
     }
 
     @Action(


[33/52] [abbrv] isis git commit: ISIS-1243: more updates to RO viewer docs

Posted by mg...@apache.org.
ISIS-1243: more updates to RO viewer docs


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/8817ac99
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/8817ac99
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/8817ac99

Branch: refs/heads/ISIS-1224-select2-v4
Commit: 8817ac990e5602c157354c72193be5b5cb7543e6
Parents: e135d7f
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Fri Dec 4 18:13:58 2015 +0000
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Fri Dec 4 18:13:58 2015 +0000

----------------------------------------------------------------------
 .../_ugvro_simplified-representations.adoc      | 277 ++++++++++++++++---
 1 file changed, 246 insertions(+), 31 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/8817ac99/adocs/documentation/src/main/asciidoc/guides/_ugvro_simplified-representations.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugvro_simplified-representations.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugvro_simplified-representations.adoc
index 76fe65e..412a815 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugvro_simplified-representations.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugvro_simplified-representations.adoc
@@ -49,23 +49,83 @@ The screencast below demonstrates the feature.
 video::HMSqapQDY_4[youtube,width="853px",height="480px"]
 
 
-And the table below explains in a little more detail what is returned when this profile is activated.
+The sections below explain in a little more detail what is returned when this profile is activated.
 
-[cols="1a,4a", options="header"]
-|===
 
-| Resource
-| Description
+[[_ugvro_simplified-representations_domain-object]]
+== Domain Object
 
+If a domain object resource (section 14) is accessed with the Apache Isis profile, the resultant representation is a
+JSON object with simple key/value pairs for each property.
 
-|Domain object +
-(section 14)
-|The representation of a domain object is simple key/value pairs for each property.  The contents of any collections are
-also eagerly returned, consisting of an array of elements of each referenced object.  Each such element contains
-key/value pairs of each property (in other words, a grid of data is returned), along with special `$$href` and
-`$$title` properties. +
+The contents of any collections are also eagerly returned, consisting of an array of elements of each referenced
+object.  Each such element contains key/value pairs of each property (in other words, a grid of data is returned).
+Each element also has a special `$$href` property (so that the client can easily navigate to a resource for that
+object) and a `$$title` property (to use as a label, eg the hyperlink text).
 
-In addition, the representation defined by the RO spec is also included, under a special `$$ro` property. +
+In addition, the representation defined by the RO spec is also included, under a special `$$ro` property.
+
+For example, using the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp], accessing
+this resource:
+
+[source]
+----
+http://localhost:8080/restful/objects/TODO/45
+----
+
+with an `Accept` request header of:
+
+[source]
+----
+Accept: application/json;profile="urn:org.apache.isis/v1"
+----
+
+returns the following representation:
+
+[source]
+----
+{
+  "$$href" : "http://localhost:8080/restful/objects/TODO/45",       // <1>
+  "$$title" : "Buy bread due by 2015-12-04",                        // <2>
+  "description" : "Buy bread",                                      // <3>
+  "category" : "Domestic",
+  "subcategory" : "Shopping",
+  "complete" : false,
+  "atPath" : "/users/sven",
+  ...
+  "similarTo" : [ {                                                 // <4>
+    "$$href" : "http://localhost:8080/restful/objects/TODO/46",
+    "$$title" : "Buy milk due by 2015-12-04",
+    "description" : "Buy milk",
+    "category" : "Domestic",
+    ...
+  }, {
+    "$$href" : "http://localhost:8080/restful/objects/TODO/47",
+    "$$title" : "Buy stamps due by 2015-12-04",
+    "description" : "Buy stamps",
+    "category" : "Domestic",
+    ...
+  },
+     ...
+  } ],
+  "dependencies" : [ ],
+  "$$ro" : {                                                        // <5>
+    "links" : [ ... ],
+    "extensions" : { ... },
+    "title" : "Buy bread due by 2015-12-04",
+    "domainType" : "TODO",
+    "instanceId" : "45",
+    "members" : { ... }
+  }
+}
+----
+<1> hyperlink to the representation
+<2> title of the domain object
+<3> all the properties of the domain object (to which the caller has access), as key/value pairs
+<4> contents of each collection
+<5> special `$$ro` json-prop, being the normal RO Spec representation for this object
+
+with a `Content-Type` header:
 
 [source]
 ----
@@ -73,45 +133,200 @@ Content-Type: application/json;
               profile="urn:org.apache.isis/v1";repr-type="object"
 ----
 
-|Object Collection +
-(section 17)
-|Collections are represented as an array of elements of key/value for each referenced object, and again each element
-the containing the key/value pairs of the properties of that object (a grid, again). +
+
+[[_ugvro_simplified-representations_object-collection]]
+== Domain Object Collection
+
+If a domain object collection (section 17) is accessed with this profile, then the resultant representation is as
+an array of elements of key/value for each referenced object, and again each element the containing the key/value
+pairs of the properties of that object (a grid, again). +
 
 In addition, the representation defined by the RO spec is also included, as a special object with a single `$$ro`
-property. +
+property.
+
+For example, using the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp], accessing
+this resource:
 
 [source]
 ----
-Content-Type: application/json;
-              profile="urn:org.apache.isis/v1";repr-type="object-collection"
+http://localhost:8080/restful/objects/TODO/45/collections/similarTo
 ----
 
-|Action invocation +
-(section 19)
-|If the action returned an object, then the domain object representation described above is returned. +
+with an `Accept` request header of:
 
 [source]
 ----
-Content-Type: application/json;
-              profile="urn:org.apache.isis/v1";repr-type="object"
+Accept: application/json;profile="urn:org.apache.isis/v1"
 ----
 
-If the action returned a list, then the same array representation as (parented) object collections is returned, though
-with a slightly different `Content-Type` to distinguish:
+returns the following representation:
 
 [source]
 ----
-Content-Type: application/json;
-              profile="urn:org.apache.isis/v1";repr-type="list"
+[                                                                   // <1>
+{
+  "$$href" : "http://localhost:8080/restful/objects/TODO/46",       // <2>
+  "$$title" : "Buy milk due by 2015-12-04",                         // <3>
+  "description" : "Buy milk",                                       // <4>
+  "category" : "Domestic",
+  ...
+}, {
+  "$$href" : "http://localhost:8080/restful/objects/TODO/47",
+  "$$title" : "Buy stamps due by 2015-12-04",
+  "description" : "Buy stamps",
+  "category" : "Domestic",
+  ...
+}, {
+  "$$href" : "http://localhost:8080/restful/objects/TODO/48",
+  "$$title" : "Mow lawn due by 2015-12-10",
+  "description" : "Mow lawn",
+  "category" : "Domestic",
+  ...
+},
+...
+, {
+  "$$ro" : {                                                        // <5>
+    "id" : "similarTo",
+    "memberType" : "collection",
+    "links" : [ ... ],
+    "extensions" : { ... },
+    "value" : [ ... ]
+  }
+}
+]
+----
+<1> returns a JSON array, not a JSON object
+<2> hyperlink to the representation
+<3> title of the domain object
+<4> all the properties of the domain object (to which the caller has access), as key/value pairs
+<5> last element is a special object with a single `$$ro` json-prop, being the normal RO Spec representation for this object
+
+with a `Content-Type` header:
+
+[source]
+----
+Content-Type: application/json;profile="urn:org.apache.isis/v1";repr-type="object-collection"
+----
+
+
+[[_ugvro_simplified-representations_action-invocation]]
+== Action Invocation
+
+When an action is invoked, it can return a domain object, a list, a scalar, or return nothing.
+
+=== Returning an Object
+
+If the action returned an object, then the domain object representation described
+xref:ugvro.adoc#_ugvro_simplified-representations_domain-object[above] is returned.
+
+For example, using the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp], accessing
+this resource:
+
+[source]
+----
+http://localhost:8080/restful/objects/TODO/45/actions/updateCost/invoke
 ----
 
-Note that actions returning scalar values or void are not supported; for these the regular RO spec representation will
-be returned.
+with an `Accept` request header of:
 
-|===
+[source]
+----
+Accept: application/json;profile="urn:org.apache.isis/v1"
+----
+
+returns the following representation:
+
+[source]
+----
+
+{
+  "$$href" : "http://localhost:8080/restful/objects/TODO/45",
+  "$$title" : "Buy bread due by 2015-12-04",
+  "description" : "Buy bread",
+  "category" : "Domestic",
+  "subcategory" : "Shopping",
+  "complete" : false,
+  ...
+  "similarTo" : [ ... ]
+  ...
+  "$$ro" : { ... }
+}
+----
+
+with a `Content-Type` of:
+
+[source]
+----
+Content-Type: application/json;profile="urn:org.apache.isis/v1";repr-type="object"
+----
+
+\... in other words no different to a representation obtained of the returned domain object directly.
+
+
+=== Returning a List
+
+On the other hand if the action returned a list (a "standalone" collection, then an array representation is returned.
+This is very similar to that returned by a
+xref:ugvro.adoc#_ugvro_simplified-representations_object-collection[(parented) object collection], though with a
+slightly different `Content-Type` to distinguish.
+
+For example, using the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp], accessing
+this resource:
+
+[source]
+----
+http://localhost:8080/restful/services/ToDoItems/actions/notYetComplete/invoke
+----
+
+with an `Accept` request header of:
+
+[source]
+----
+Accept: application/json;profile="urn:org.apache.isis/v1"
+----
+
+returns the following representation:
+
+[source]
+----
+[ {
+  "$$href" : "http://localhost:8080/restful/objects/TODO/45",
+  "$$title" : "Buy bread due by 2015-12-04",
+  "description" : "Buy bread",
+  "category" : "Domestic",
+  ...
+}, {
+  "$$href" : "http://localhost:8080/restful/objects/TODO/46",
+  "$$title" : "Buy milk due by 2015-12-04",
+  "description" : "Buy milk",
+  "category" : "Domestic",
+  ...
+},
+...
+, {
+  "$$ro" : {
+    "links" : [ ... ]
+    "resulttype" : "list",
+    "result" : { ... }
+      "value" : [ ... ],
+      "links" : [ ... ],
+      "extensions" : { }
+    }
+  }
+} ]
+----
+
+with a `Content-Type` header:
+
+[source]
+----
+Content-Type: application/json;profile="urn:org.apache.isis/v1";repr-type="list"
+----
 
+=== Returning Scalar/Nothing
 
+Note that actions returning scalar values or nothing (which includes `void` actions) are not supported; for these the
+regular RO spec representation will be returned.
 
 
 [[_ugvro_simplified-representations_other-representations]]


[52/52] [abbrv] isis git commit: ISIS-1224 Upgrade select2 from v3.5.2 to v4

Posted by mg...@apache.org.
ISIS-1224 Upgrade select2 from v3.5.2 to v4

In ActionParametersFormPanel do not repaint the complete ReferencePanel/ValueChoicesSelect2Panel but just its Select2 child component.
It the complete parent is repainted then Select2 JS widget somehow looses information about the parent DOM element and renders the drop-down as orphan, i.e. CSS: position:absolute; left:0; top:0;

If only the Select2Choice element is repainted then it just sends its new values as JSON back and doesn't recreate the complete widget but just its options.

The flow is:
1) the user types something in another field
2) the user clicks on Select2
2.1) the 'change' JS event for the first field fires Ajax call
2.1.1) with the old behavior the Ajax response repaints the whole ReferencePanel
2.1.2) with the new behavior the Ajax response repaints only the Select2 options
2.2) the click on Select2 opens its drop-down
2.3) the Ajax response for 2.1) comes and closes Select2 to update it
3) with the new behavior the user has to click second time to show the drop-down again, but at least its CSS position is correct


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/7b5bfad7
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/7b5bfad7
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/7b5bfad7

Branch: refs/heads/ISIS-1224-select2-v4
Commit: 7b5bfad70743279c59cfe3e520ba7feb63098529
Parents: 17d7159
Author: Martin Tzvetanov Grigorov <mg...@apache.org>
Authored: Sun Dec 13 15:21:52 2015 +0100
Committer: Martin Tzvetanov Grigorov <mg...@apache.org>
Committed: Sun Dec 13 15:21:52 2015 +0100

----------------------------------------------------------------------
 .../ui/components/actions/ActionParametersFormPanel.java |  4 ++--
 .../ui/components/scalars/ScalarPanelAbstract.java       |  9 +++++++++
 .../ui/components/scalars/reference/ReferencePanel.java  | 11 ++++++++++-
 .../ui/components/widgets/select2/Select2ChoiceUtil.java |  1 +
 .../widgets/valuechoices/ValueChoicesSelect2Panel.java   | 11 +++++++++++
 5 files changed, 33 insertions(+), 3 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/7b5bfad7/core/viewer-wicket-ui/src/main/java/org/apache/isis/viewer/wicket/ui/components/actions/ActionParametersFormPanel.java
----------------------------------------------------------------------
diff --git a/core/viewer-wicket-ui/src/main/java/org/apache/isis/viewer/wicket/ui/components/actions/ActionParametersFormPanel.java b/core/viewer-wicket-ui/src/main/java/org/apache/isis/viewer/wicket/ui/components/actions/ActionParametersFormPanel.java
index d1d7020..a8cde09 100644
--- a/core/viewer-wicket-ui/src/main/java/org/apache/isis/viewer/wicket/ui/components/actions/ActionParametersFormPanel.java
+++ b/core/viewer-wicket-ui/src/main/java/org/apache/isis/viewer/wicket/ui/components/actions/ActionParametersFormPanel.java
@@ -242,8 +242,8 @@ public class ActionParametersFormPanel extends PanelAbstract<ActionModel> {
                         // this could throw a ConcurrencyException as we may have to reload the 
                         // object adapter of the action in order to compute the choices
                         // (and that object adapter might have changed)
-                        if(paramPanel.updateChoices(pendingArguments)) {
-                            target.add(paramPanel);
+                        if (paramPanel.updateChoices(pendingArguments)) {
+                            paramPanel.repaint(target);
                         }
                     }
                 }

http://git-wip-us.apache.org/repos/asf/isis/blob/7b5bfad7/core/viewer-wicket-ui/src/main/java/org/apache/isis/viewer/wicket/ui/components/scalars/ScalarPanelAbstract.java
----------------------------------------------------------------------
diff --git a/core/viewer-wicket-ui/src/main/java/org/apache/isis/viewer/wicket/ui/components/scalars/ScalarPanelAbstract.java b/core/viewer-wicket-ui/src/main/java/org/apache/isis/viewer/wicket/ui/components/scalars/ScalarPanelAbstract.java
index a9df6fa..13d117c 100644
--- a/core/viewer-wicket-ui/src/main/java/org/apache/isis/viewer/wicket/ui/components/scalars/ScalarPanelAbstract.java
+++ b/core/viewer-wicket-ui/src/main/java/org/apache/isis/viewer/wicket/ui/components/scalars/ScalarPanelAbstract.java
@@ -386,6 +386,15 @@ public abstract class ScalarPanelAbstract extends PanelAbstract<ScalarModel> imp
         return false;
     }
 
+    /**
+     * Repaints this panel of just some of its children
+     *
+     * @param target The Ajax request handler
+     */
+    public void repaint(AjaxRequestTarget target) {
+        target.add(this);
+    }
+
 
     // ///////////////////////////////////////////////////////////////////
 

http://git-wip-us.apache.org/repos/asf/isis/blob/7b5bfad7/core/viewer-wicket-ui/src/main/java/org/apache/isis/viewer/wicket/ui/components/scalars/reference/ReferencePanel.java
----------------------------------------------------------------------
diff --git a/core/viewer-wicket-ui/src/main/java/org/apache/isis/viewer/wicket/ui/components/scalars/reference/ReferencePanel.java b/core/viewer-wicket-ui/src/main/java/org/apache/isis/viewer/wicket/ui/components/scalars/reference/ReferencePanel.java
index 937f990..667b4fe 100644
--- a/core/viewer-wicket-ui/src/main/java/org/apache/isis/viewer/wicket/ui/components/scalars/reference/ReferencePanel.java
+++ b/core/viewer-wicket-ui/src/main/java/org/apache/isis/viewer/wicket/ui/components/scalars/reference/ReferencePanel.java
@@ -24,6 +24,7 @@ import java.util.List;
 import javax.inject.Inject;
 
 import com.google.common.collect.Lists;
+import org.apache.wicket.ajax.AjaxRequestTarget;
 import org.wicketstuff.select2.ChoiceProvider;
 import org.wicketstuff.select2.Select2Choice;
 import org.wicketstuff.select2.Settings;
@@ -534,5 +535,13 @@ public class ReferencePanel extends ScalarPanelAbstract {
         return IsisContext.getConfiguration();
     }
 
-
+    /**
+     * Repaints just the Select2 component
+     *
+     * @param target The Ajax request handler
+     */
+    @Override
+    public void repaint(AjaxRequestTarget target) {
+        target.add(select2Field);
+    }
 }

http://git-wip-us.apache.org/repos/asf/isis/blob/7b5bfad7/core/viewer-wicket-ui/src/main/java/org/apache/isis/viewer/wicket/ui/components/widgets/select2/Select2ChoiceUtil.java
----------------------------------------------------------------------
diff --git a/core/viewer-wicket-ui/src/main/java/org/apache/isis/viewer/wicket/ui/components/widgets/select2/Select2ChoiceUtil.java b/core/viewer-wicket-ui/src/main/java/org/apache/isis/viewer/wicket/ui/components/widgets/select2/Select2ChoiceUtil.java
index 0c059d3..c8ef4d7 100644
--- a/core/viewer-wicket-ui/src/main/java/org/apache/isis/viewer/wicket/ui/components/widgets/select2/Select2ChoiceUtil.java
+++ b/core/viewer-wicket-ui/src/main/java/org/apache/isis/viewer/wicket/ui/components/widgets/select2/Select2ChoiceUtil.java
@@ -35,6 +35,7 @@ public final class Select2ChoiceUtil  {
     public static Select2Choice<ObjectAdapterMemento> newSelect2Choice(String id, final IModel<ObjectAdapterMemento> modelObject, ScalarModel scalarModel) {
         Select2Choice<ObjectAdapterMemento> select2Choice = new Select2Choice<>(id, modelObject, EmptyChoiceProvider.INSTANCE);
         select2Choice.setRequired(scalarModel.isRequired());
+        select2Choice.setOutputMarkupPlaceholderTag(true);
         return select2Choice;
     }
 

http://git-wip-us.apache.org/repos/asf/isis/blob/7b5bfad7/core/viewer-wicket-ui/src/main/java/org/apache/isis/viewer/wicket/ui/components/widgets/valuechoices/ValueChoicesSelect2Panel.java
----------------------------------------------------------------------
diff --git a/core/viewer-wicket-ui/src/main/java/org/apache/isis/viewer/wicket/ui/components/widgets/valuechoices/ValueChoicesSelect2Panel.java b/core/viewer-wicket-ui/src/main/java/org/apache/isis/viewer/wicket/ui/components/widgets/valuechoices/ValueChoicesSelect2Panel.java
index cbfa213..c8f51a1 100644
--- a/core/viewer-wicket-ui/src/main/java/org/apache/isis/viewer/wicket/ui/components/widgets/valuechoices/ValueChoicesSelect2Panel.java
+++ b/core/viewer-wicket-ui/src/main/java/org/apache/isis/viewer/wicket/ui/components/widgets/valuechoices/ValueChoicesSelect2Panel.java
@@ -26,6 +26,7 @@ import com.google.common.base.Function;
 import com.google.common.base.Predicate;
 import com.google.common.collect.Collections2;
 import com.google.common.collect.Lists;
+import org.apache.wicket.ajax.AjaxRequestTarget;
 import org.wicketstuff.select2.ChoiceProvider;
 import org.wicketstuff.select2.Select2Choice;
 
@@ -247,6 +248,16 @@ public class ValueChoicesSelect2Panel extends ScalarPanelAbstract implements Sca
     }
 
     /**
+     * Repaints just the Select2 component
+     *
+     * @param target The Ajax request handler
+     */
+    @Override
+    public void repaint(AjaxRequestTarget target) {
+        target.add(select2Field);
+    }
+
+    /**
      * sets up the choices, also ensuring that any currently held value
      * is compatible.
      */


[41/52] [abbrv] isis git commit: ISIS-1237: object paths and object action paths.

Posted by mg...@apache.org.
ISIS-1237: object paths and object action paths.


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/53ead490
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/53ead490
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/53ead490

Branch: refs/heads/ISIS-1224-select2-v4
Commit: 53ead490bbcbbcc6c378132356cbe79cef6c2561
Parents: 6daa442
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Thu Dec 10 07:59:33 2015 +0000
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Dec 10 07:59:33 2015 +0000

----------------------------------------------------------------------
 .../swagger/internal/SwaggerSpecGenerator.java  | 293 +++++++++++++++----
 1 file changed, 240 insertions(+), 53 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/53ead490/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGenerator.java
----------------------------------------------------------------------
diff --git a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGenerator.java b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGenerator.java
index bfb1489..896d4f0 100644
--- a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGenerator.java
+++ b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGenerator.java
@@ -30,7 +30,9 @@ import org.apache.isis.applib.annotation.NatureOfService;
 import org.apache.isis.applib.filter.Filters;
 import org.apache.isis.applib.services.swagger.SwaggerService;
 import org.apache.isis.core.commons.factory.InstanceUtil;
+import org.apache.isis.core.metamodel.facets.actcoll.typeof.TypeOfFacet;
 import org.apache.isis.core.metamodel.facets.object.domainservice.DomainServiceFacet;
+import org.apache.isis.core.metamodel.facets.object.objectspecid.ObjectSpecIdFacet;
 import org.apache.isis.core.metamodel.services.ServiceUtil;
 import org.apache.isis.core.metamodel.spec.ActionType;
 import org.apache.isis.core.metamodel.spec.ObjectSpecification;
@@ -46,6 +48,7 @@ import io.swagger.models.Path;
 import io.swagger.models.Response;
 import io.swagger.models.Swagger;
 import io.swagger.models.parameters.BodyParameter;
+import io.swagger.models.parameters.PathParameter;
 import io.swagger.models.parameters.QueryParameter;
 import io.swagger.models.properties.ArrayProperty;
 import io.swagger.models.properties.IntegerProperty;
@@ -76,30 +79,65 @@ public class SwaggerSpecGenerator {
         appendLinkDefinitions(swagger);
 
         final Collection<ObjectSpecification> allSpecs = specificationLoader.allSpecifications();
-        for (ObjectSpecification serviceSpec : allSpecs) {
+        for (final ObjectSpecification serviceSpec :  allSpecs) {
+
             final DomainServiceFacet domainServiceFacet = serviceSpec.getFacet(DomainServiceFacet.class);
             if (domainServiceFacet == null) {
                 continue;
             }
-            if (!isVisible(visibility, domainServiceFacet)) {
+            if (visibility.isPublic() &&
+                domainServiceFacet.getNatureOfService() != NatureOfService.VIEW_REST_ONLY) {
+                continue;
+            }
+            if (domainServiceFacet.getNatureOfService() != NatureOfService.VIEW_MENU_ONLY &&
+                domainServiceFacet.getNatureOfService() != NatureOfService.VIEW) {
                 continue;
             }
 
-            List<ActionType> actionTypes = actionTypesFor(visibility);
-            List<ObjectAction> serviceActions = serviceSpec.getObjectActions(
+            final List<ActionType> actionTypes = actionTypesFor(visibility);
+            final List<ObjectAction> serviceActions = serviceSpec.getObjectActions(
                     actionTypes, Contributed.EXCLUDED, Filters.<ObjectAction>any());
-            if(serviceActions.isEmpty()) {
+            if (serviceActions.isEmpty()) {
                 continue;
             }
 
-            final String serviceId = serviceIdFor(serviceSpec);
-
-            final ObjectProperty serviceMembers = appendServicePath(swagger, serviceId);
+            final ObjectProperty serviceMembers = appendServicePath(swagger, serviceSpec);
 
             for (final ObjectAction serviceAction : serviceActions) {
+                if (visibility.isPublic() && !isVisibleForPublic(serviceAction)) {
+                    continue;
+                }
                 appendActionTo(serviceMembers, serviceAction);
+                appendServiceActionInvokePath(swagger, serviceAction);
+            }
+        }
+
+        for (final ObjectSpecification objectSpec : allSpecs) {
+
+            final DomainServiceFacet domainServiceFacet = objectSpec.getFacet(DomainServiceFacet.class);
+            if (domainServiceFacet != null) {
+                continue;
+            }
+
+            if(objectSpec.isAbstract()) {
+                continue;
+            }
+
+            final List<ActionType> actionTypes = actionTypesFor(visibility);
+            final List<ObjectAction> objectActions = objectSpec.getObjectActions(
+                    actionTypes, Contributed.INCLUDED, Filters.<ObjectAction>any());
+            if (objectActions.isEmpty()) {
+                continue;
+            }
+
+            final ObjectProperty objectMembers = appendObjectPath(swagger, objectSpec);
 
-                appendInvokePath(swagger, serviceAction);
+            for (final ObjectAction objectAction : objectActions) {
+                if (visibility.isPublic() && !isVisibleForPublic(objectAction)) {
+                    continue;
+                }
+                appendActionTo(objectMembers, objectAction);
+                appendObjectActionInvokePath(swagger, objectAction);
             }
         }
 
@@ -241,6 +279,77 @@ public class SwaggerSpecGenerator {
         );
     }
 
+    ObjectProperty appendServicePath(final Swagger swagger, final ObjectSpecification objectSpec) {
+
+        final String serviceId = serviceIdFor(objectSpec);
+
+        final Path path = new Path();
+        swagger.path(String.format("/services/%s", serviceId), path);
+
+        path.get(
+                new Operation()
+                        .tag(serviceId)
+                        .description(roSpec("15.1"))
+                        .produces("application/json")
+                        .produces("application/json;profile=urn:org.restfulobjects:repr-types/object")
+                        .response(200,
+                                newResponse(Caching.TRANSACTIONAL)
+                                        .description("OK")
+                                        .schema(new RefProperty("#/definitions/service-" + serviceId)))
+        );
+
+        final ObjectProperty serviceMembers = new ObjectProperty();
+        final ModelImpl serviceRepr =
+                newModel(roSpec("15.1.2") + ": representation of " + serviceId)
+                        .property("title", stringProperty())
+                        .property("serviceId", stringProperty()._default(serviceId))
+                        .property("members", serviceMembers);
+
+        swagger.addDefinition("service-" + serviceId, serviceRepr);
+        return serviceMembers;
+    }
+
+    ObjectProperty appendObjectPath(final Swagger swagger, final ObjectSpecification objectSpec) {
+
+        final String objectType = objectTypeFor(objectSpec);
+
+        final Path path = new Path();
+        swagger.path(String.format("/objects/%s/{objectId}", objectType), path);
+
+        path.get(
+                new Operation()
+                        .tag(objectType)
+                        .description(roSpec("14.1"))
+                        .parameter(
+                                new PathParameter()
+                                        .name("objectId")
+                                        .type("string"))
+                        .produces("application/json")
+                        .produces("application/json;profile=urn:org.restfulobjects:repr-types/object")
+                        .produces("application/json;profile=urn:org.apache.isis/v1")
+                        .produces("application/json;profile=urn:org.apache.isis/v1;suppress=true")
+                        .response(200,
+                                newResponse(Caching.TRANSACTIONAL)
+                                        .description("OK")
+                                        .schema(new RefProperty("#/definitions/object-" + objectType)))
+        );
+
+        final ObjectProperty serviceMembers = new ObjectProperty();
+        final ModelImpl serviceRepr =
+                newModel(roSpec("14.4") + ": representation of " + objectType)
+                        .property("title", stringProperty())
+                        .property("domainType", stringProperty()._default(objectType))
+                        .property("instanceId", stringProperty())
+                        .property("members", serviceMembers);
+
+        swagger.addDefinition("object-" + objectType, serviceRepr);
+        return serviceMembers;
+    }
+
+    private String objectTypeFor(final ObjectSpecification objectSpec) {
+        return objectSpec.getFacet(ObjectSpecIdFacet.class).value().asString();
+    }
+
     void appendActionTo(final ObjectProperty serviceMembers, final ObjectAction serviceAction) {
         String serviceActionId = serviceAction.getId();
 
@@ -261,64 +370,118 @@ public class SwaggerSpecGenerator {
         );
     }
 
-    ObjectProperty appendServicePath(
+    void appendServiceActionInvokePath(
             final Swagger swagger,
-            final String serviceId) {
+            final ObjectAction serviceAction) {
 
-        final String serviceDefinitionId = "service-" + serviceId;
-        final String servicePathStr = "/services/" + serviceId;
+        final ObjectSpecification serviceSpec = serviceAction.getOnType();
+        final String serviceId = serviceIdFor(serviceSpec);
+        final String actionId = serviceAction.getId();
 
-        final Path servicePath = new Path();
-        swagger.path(servicePathStr, servicePath);
+        final List<ObjectActionParameter> parameters = serviceAction.getParameters();
+        final Path path = new Path();
+        swagger.path(String.format("/services/%s/actions/%s/invoke", serviceId, actionId), path);
 
-        servicePath.get(
+        final Operation invokeOperation =
                 new Operation()
                         .tag(serviceId)
-                        .description(roSpec("15.1"))
+                        .description(roSpec("19.1") + ": (invoke) resource of " + serviceId + "#" + actionId)
                         .produces("application/json")
-                        .produces("application/json;profile=urn:org.restfulobjects:repr-types/object")
-                        .response(200,
-                                newResponse(Caching.TRANSACTIONAL)
-                                        .description("OK")
-                                        .schema(new RefProperty("#/definitions/"
-                                                + serviceDefinitionId)))
-        );
+                        .produces("application/json;profile=urn:org.restfulobjects:repr-types/action-result")
+                        .produces("application/json;profile=urn:org.apache.isis/v1")
+                        .produces("application/json;profile=urn:org.apache.isis/v1;suppress=true");
 
-        final ObjectProperty serviceMembers = new ObjectProperty();
-        ModelImpl serviceRepr =
-                newModel(roSpec("15.1.2") + ": representation of " + serviceId)
-                        .property("title", stringProperty())
-                        .property("serviceId", stringProperty()._default(serviceId))
-                        .property("members", serviceMembers);
+        final ActionSemantics.Of semantics = serviceAction.getSemantics();
+        if(semantics.isSafeInNature()) {
+            path.get(invokeOperation);
 
-        swagger.addDefinition(serviceDefinitionId, serviceRepr);
-        return serviceMembers;
+            for (final ObjectActionParameter parameter : parameters) {
+                invokeOperation
+                        .parameter(
+                                new QueryParameter()
+                                        .name(parameter.getId())
+                                        .description(roSpec("2.9.1") + (!Strings.isNullOrEmpty(parameter.getDescription())? (": " + parameter.getDescription()) : ""))
+                                        .required(false)
+                                        .type("string")
+                        );
+            }
+            if(!parameters.isEmpty()) {
+                invokeOperation.parameter(new QueryParameter()
+                        .name("x-isis-querystring")
+                        .description(roSpec("2.10") + ": all (formal) arguments as base64 encoded string")
+                        .required(false)
+                        .type("string"));
+            }
+
+        } else {
+            if (semantics.isIdempotentInNature()) {
+                path.put(invokeOperation);
+            } else {
+                path.post(invokeOperation);
+            }
+
+            final ModelImpl bodyParam =
+                    new ModelImpl()
+                            .type("object");
+            for (final ObjectActionParameter parameter : parameters) {
+
+                final Property valueProperty;
+                // TODO: need to switch on parameter's type and create appropriate impl of valueProperty
+                // if(parameter.getSpecification().isValue()) ...
+                valueProperty = stringProperty();
+
+                bodyParam
+                        .property(parameter.getId(),
+                                new ObjectProperty()
+                                        .property("value", valueProperty)
+                        );
+            }
+
+            invokeOperation
+                    .consumes("application/json")
+                    .parameter(
+                            new BodyParameter()
+                                    .name("body")
+                                    .schema(bodyParam));
+
+        }
+
+        invokeOperation
+                .response(
+                        200, new Response()
+                                .description(roSpecForResponseOf(serviceAction) + ": (invoke) representation of " + serviceId + "#" + actionId)
+                                .schema(new ObjectProperty())
+                );
     }
 
-    void appendInvokePath(
+    void appendObjectActionInvokePath(
             final Swagger swagger,
-            final ObjectAction serviceAction) {
+            final ObjectAction objectAction) {
 
-        final ObjectSpecification serviceSpec = serviceAction.getOnType();
-        final String serviceId = serviceIdFor(serviceSpec);
-        final String serviceActionId = serviceAction.getId();
+        final ObjectSpecification objectSpec = objectAction.getOnType();
+        final String objectType = objectTypeFor(objectSpec);
+        final String actionId = objectAction.getId();
 
-        final List<ObjectActionParameter> parameters = serviceAction.getParameters();
-        final Path serviceActionInvokePath = new Path();
-        swagger.path(String.format("/services/%s/actions/%s/invoke", serviceId, serviceActionId), serviceActionInvokePath);
+        final List<ObjectActionParameter> parameters = objectAction.getParameters();
+        final Path path = new Path();
+        swagger.path(String.format("/objects/%s/{objectId}/actions/%s/invoke", objectType, actionId), path);
 
         final Operation invokeOperation =
                 new Operation()
-                        .tag(serviceId)
-                        .description(roSpec("19.1") + ": (invoke) resource of " + serviceId + "#" + serviceActionId)
+                        .tag(objectType)
+                        .description(roSpec("19.1") + ": (invoke) resource of " + objectType + "#" + actionId)
+                        .parameter(
+                                new PathParameter()
+                                        .name("objectId")
+                                        .type("string"))
                         .produces("application/json")
                         .produces("application/json;profile=urn:org.restfulobjects:repr-types/action-result")
                         .produces("application/json;profile=urn:org.apache.isis/v1")
                         .produces("application/json;profile=urn:org.apache.isis/v1;suppress=true");
 
-        final ActionSemantics.Of semantics = serviceAction.getSemantics();
+        final ActionSemantics.Of semantics = objectAction.getSemantics();
         if(semantics.isSafeInNature()) {
-            serviceActionInvokePath.get(invokeOperation);
+            path.get(invokeOperation);
 
             for (final ObjectActionParameter parameter : parameters) {
                 invokeOperation
@@ -340,9 +503,9 @@ public class SwaggerSpecGenerator {
 
         } else {
             if (semantics.isIdempotentInNature()) {
-                serviceActionInvokePath.put(invokeOperation);
+                path.put(invokeOperation);
             } else {
-                serviceActionInvokePath.post(invokeOperation);
+                path.post(invokeOperation);
             }
 
             final ModelImpl bodyParam =
@@ -374,7 +537,7 @@ public class SwaggerSpecGenerator {
         invokeOperation
                 .response(
                         200, new Response()
-                                .description(roSpecForResponseOf(serviceAction) + ": (invoke) representation of " + serviceId + "#" + serviceActionId)
+                                .description(roSpecForResponseOf(objectAction) + ": (invoke) representation of " + objectType + "#" + actionId)
                                 .schema(new ObjectProperty())
                 );
     }
@@ -394,15 +557,39 @@ public class SwaggerSpecGenerator {
         }
     }
 
-    boolean isVisible(final SwaggerService.Visibility visibility, final DomainServiceFacet domainServiceFacet) {
-        if (domainServiceFacet.getNatureOfService() == NatureOfService.VIEW_REST_ONLY) {
+    private boolean isVisibleForPublic(final ObjectAction objectAction) {
+        final ObjectSpecification specification = objectAction.getReturnType();
+        boolean visible = isVisibleForPublic(specification);
+        if(!visible) {
+            return false;
+        }
+        List<ObjectSpecification> parameterTypes = objectAction.getParameterTypes();
+        for (ObjectSpecification parameterType : parameterTypes) {
+            boolean paramVisible = isVisibleForPublic(parameterType);
+            if(!paramVisible) {
+                return false;
+            }
+        }
+        return true;
+    }
+
+    private boolean isVisibleForPublic(final ObjectSpecification specification) {
+        if (specification == null) {
             return true;
         }
-        if (visibility.isPublic()) {
-            return false;
+        if(specification.isViewModel()) {
+            return true;
+        }
+        if(specification.isValue()) {
+            return true;
+        }
+        if(specification.isParentedOrFreeCollection()) {
+            TypeOfFacet typeOfFacet = specification.getFacet(TypeOfFacet.class);
+            ObjectSpecification elementSpec = typeOfFacet.valueSpec();
+            return isVisibleForPublic(elementSpec);
         }
-        return domainServiceFacet.getNatureOfService() == NatureOfService.VIEW_MENU_ONLY ||
-               domainServiceFacet.getNatureOfService() == NatureOfService.VIEW;
+        final Class<?> correspondingClass = specification.getCorrespondingClass();
+        return correspondingClass == void.class || correspondingClass == Void.class;
     }
 
     private ModelImpl newModel(final String description) {


[34/52] [abbrv] isis git commit: ISIS-1243: adding faq on i18n for wicket labels

Posted by mg...@apache.org.
ISIS-1243: adding faq on i18n for wicket labels


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/2d9b2ee2
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/2d9b2ee2
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/2d9b2ee2

Branch: refs/heads/ISIS-1224-select2-v4
Commit: 2d9b2ee2f11bf453efcbacfabd8c4c5c21857c95
Parents: 8817ac9
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Sun Dec 6 11:53:27 2015 +0000
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Mon Dec 7 07:15:43 2015 +0000

----------------------------------------------------------------------
 .../src/main/asciidoc/guides/_ugfun_faqs.adoc       |  1 +
 .../_ugfun_faqs_i18n-label-in-wicket-viewer.adoc    | 16 ++++++++++++++++
 2 files changed, 17 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/2d9b2ee2/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs.adoc
index b35409e..49d0882 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs.adoc
@@ -15,3 +15,4 @@ include::_ugfun_faqs_subtype-entity-not-fully-populated.adoc[leveloffset=+1]
 include::_ugfun_faqs_restful-image-property.adoc[leveloffset=+1]
 include::_ugfun_faqs_enhance-only.adoc[leveloffset=+1]
 include::_ugfun_faqs_per-user-themes.adoc[leveloffset=+1]
+include::_ugfun_faqs_i18n-label-in-wicket-viewer.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/2d9b2ee2/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_i18n-label-in-wicket-viewer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_i18n-label-in-wicket-viewer.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_i18n-label-in-wicket-viewer.adoc
new file mode 100644
index 0000000..4429ecb
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_i18n-label-in-wicket-viewer.adoc
@@ -0,0 +1,16 @@
+[[_ugfun_faqs_i18n-label-in-wicket-viewer]]
+= How i18n Labels in Wicket Viewer?
+: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/
+
+From the Apache Isis mailing list is:
+
+* _I am trying to internationalize the label descriptions of form actions, eg those in `ActionParametersFormPanel`.  Referencing those via their message id inside a .po file didn't work either.  Can this be done?_
+
+At the moment (`1.10.0`) we have a bit of a hybrid story when it comes to i18n.  Most of the i18n does indeed come from the .po files, however certain bits of the UI are "hard-coded", which is to say they rely upon link:https://ci.apache.org/projects/wicket/guide/6.x/guide/i18n.html#i18n_3[ Wicket's internationalization support], namely resource bundles.
+
+So, you can internationalize the labels from this class using the regular resource bundle approach; this is just "vanilla" Wicket: create a directory structure inside the webapp resource folder following that pattern `org.apache.isis.viewer.wicket.ui.components.actions`.  Inside there create an equivalent `ActionParametersFormPanel_xx_XX.properties` or `ActionParametersFormPanel_xx.properties` file for the various locales that you want to support (eg `ActionParametersFormPanel_en_UK.properties`, `ActionParametersFormPanel_en_US.properties`, `ActionParametersFormPanel_de.properties` and so on).
+
+We do have a ticket link:https://issues.apache.org/jira/browse/ISIS-1093[ISIS-1093] to simplify this so that all i18n labels are read from the .po files.
+


[29/52] [abbrv] isis git commit: ISIS-1243: fixing links to fundamentals guide; updating asciidoc live templates; updating contributors guide that documents the asciidoc live templates

Posted by mg...@apache.org.
ISIS-1243: fixing links to fundamentals guide; updating asciidoc live templates; updating contributors guide that documents the asciidoc live templates


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/f6f60c70
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/f6f60c70
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/f6f60c70

Branch: refs/heads/ISIS-1224-select2-v4
Commit: f6f60c7038fb12cb706e58b500b7d06cfad11da3
Parents: 1ad8247
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Fri Dec 4 10:11:17 2015 +0000
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Fri Dec 4 10:11:17 2015 +0000

----------------------------------------------------------------------
 ...o-1.9.0_bootstrapping-using-AppManifest.adoc |   2 +-
 ...n-notes_1.8.0-to-1.9.0_upgrading-to-dn4.adoc |   2 +-
 ...tion-notes_1.8.0-to-1.9.0_war-packaging.adoc |   4 +-
 .../src/main/asciidoc/documentation.adoc        |   2 +-
 .../asciidoc/guides/_cg_asciidoc-templates.adoc | 205 ++++++-------------
 .../main/asciidoc/guides/_cg_ide_eclipse.adoc   |   2 +-
 .../asciidoc/guides/_cg_isis-maven-plugin.adoc  |   2 +-
 .../guides/_cg_isis-maven-plugin_validate.adoc  |   2 +-
 .../asciidoc/guides/_rgant-ActionLayout.adoc    |   2 +-
 .../guides/_rgant-ActionLayout_bookmarking.adoc |   2 +-
 .../_rgant-ActionLayout_contributedAs.adoc      |   2 +-
 .../guides/_rgant-ActionLayout_cssClass.adoc    |   2 +-
 .../guides/_rgant-ActionLayout_cssClassFa.adoc  |   2 +-
 .../guides/_rgant-ActionLayout_describedAs.adoc |   2 +-
 .../guides/_rgant-ActionLayout_hidden.adoc      |   2 +-
 .../guides/_rgant-ActionLayout_named.adoc       |   2 +-
 .../guides/_rgant-ActionLayout_position.adoc    |   2 +-
 .../asciidoc/guides/_rgant-Action_hidden.adoc   |   2 +-
 .../guides/_rgant-CollectionLayout.adoc         |   2 +-
 .../_rgant-CollectionLayout_cssClass.adoc       |   2 +-
 .../_rgant-CollectionLayout_defaultView.adoc    |   2 +-
 .../_rgant-CollectionLayout_describedAs.adoc    |   2 +-
 .../guides/_rgant-CollectionLayout_hidden.adoc  |   2 +-
 .../guides/_rgant-CollectionLayout_named.adoc   |   2 +-
 .../guides/_rgant-CollectionLayout_paged.adoc   |   2 +-
 .../guides/_rgant-CollectionLayout_render.adoc  |   4 +-
 .../_rgant-CollectionLayout_sortedBy.adoc       |   2 +-
 .../guides/_rgant-Collection_hidden.adoc        |   2 +-
 .../guides/_rgant-DomainObjectLayout.adoc       |   2 +-
 .../guides/_rgant-DomainServiceLayout.adoc      |   4 +-
 .../main/asciidoc/guides/_rgant-HomePage.adoc   |   2 +-
 .../src/main/asciidoc/guides/_rgant-Inject.adoc |   2 +-
 .../guides/_rgant-MemberGroupLayout.adoc        |   2 +-
 .../asciidoc/guides/_rgant-MemberOrder.adoc     |   2 +-
 .../asciidoc/guides/_rgant-ParameterLayout.adoc |   2 +-
 .../asciidoc/guides/_rgant-PropertyLayout.adoc  |   2 +-
 .../guides/_rgant-PropertyLayout_cssClass.adoc  |   2 +-
 .../_rgant-PropertyLayout_describedAs.adoc      |   2 +-
 .../guides/_rgant-PropertyLayout_hidden.adoc    |   4 +-
 .../_rgant-PropertyLayout_labelPosition.adoc    |   2 +-
 .../guides/_rgant-PropertyLayout_multiLine.adoc |   2 +-
 .../guides/_rgant-PropertyLayout_named.adoc     |   2 +-
 ...gant-PropertyLayout_renderedAsDayBefore.adoc |   2 +-
 .../asciidoc/guides/_rgant-ViewModelLayout.adoc |   2 +-
 .../asciidoc/guides/_rgant_aaa_deprecated.adoc  |   2 +-
 .../main/asciidoc/guides/_rgant_aaa_jee.adoc    |   2 +-
 .../main/asciidoc/guides/_rgant_aaa_main.adoc   |   4 +-
 .../main/asciidoc/guides/_rgant_aaa_other.adoc  |   2 +-
 .../guides/_rgcfg_configuring-core.adoc         |   6 +-
 ...s_disabling-persistence-by-reachability.adoc |   2 +-
 .../guides/_rgcfg_specifying-components.adoc    |   2 +-
 .../main/asciidoc/guides/_rgcms_classes.adoc    |   2 +-
 ...rgcms_classes_AppManifest-bootstrapping.adoc |   2 +-
 .../guides/_rgcms_methods_prefixes_choices.adoc |   2 +-
 .../guides/_rgcms_methods_prefixes_default.adoc |   2 +-
 .../asciidoc/guides/_rgcms_schema-common.adoc   |   2 +-
 .../_rgsvc-api_ActionInvocationContext.adoc     |   2 +-
 .../guides/_rgsvc-api_BackgroundService.adoc    |   2 +-
 .../guides/_rgsvc-api_BookmarkService.adoc      |   2 +-
 .../guides/_rgsvc-api_CommandContext.adoc       |   2 +-
 .../guides/_rgsvc-api_DeepLinkService.adoc      |   2 +-
 .../guides/_rgsvc-api_EmailService.adoc         |   2 +-
 .../guides/_rgsvc-api_EventBusService.adoc      |   2 +-
 .../guides/_rgsvc-api_GuiceBeanProvider.adoc    |   2 +-
 .../guides/_rgsvc-api_IsisJdoSupport.adoc       |   2 +-
 .../asciidoc/guides/_rgsvc-api_JaxbService.adoc |   2 +-
 .../guides/_rgsvc-api_MementoService.adoc       |   2 +-
 .../guides/_rgsvc-api_MetamodelService.adoc     |   2 +-
 .../guides/_rgsvc-api_QueryResultsCache.adoc    |   2 +-
 .../asciidoc/guides/_rgsvc-api_Scratchpad.adoc  |   2 +-
 .../asciidoc/guides/_rgsvc-api_SudoService.adoc |   2 +-
 .../guides/_rgsvc-api_WrapperFactory.adoc       |   2 +-
 .../guides/_rgsvc-api_XmlSnapshotService.adoc   |   2 +-
 .../_rgsvc-spi_ClassDiscoveryService.adoc       |   4 +-
 .../_rgsvc-spi_ContentNegotiationService.adoc   |   2 +-
 .../_rgsvc-spi_EmailNotificationService.adoc    |   2 +-
 ...spi_FixtureScriptsSpecificationProvider.adoc |   2 +-
 .../guides/_rgsvc-spi_LocaleProvider.adoc       |   2 +-
 .../_rgsvc-spi_RepresentationService.adoc       |   2 +-
 .../guides/_rgsvc-spi_TranslationService.adoc   |   2 +-
 .../guides/_rgsvc-spi_TranslationsResolver.adoc |   2 +-
 .../guides/_rgsvc-spi_UrlEncodingService.adoc   |   2 +-
 .../main/asciidoc/guides/_tg_pet-clinic.adoc    |   2 +-
 .../_tg_stop-scaffolding-start-coding.adoc      |  24 +--
 .../guides/_ugbtb_deployment_neo4j.adoc         |   6 +-
 ..._more-advanced_decoupling_contributions.adoc |   2 +-
 .../guides/_ugbtb_more-advanced_i18n.adoc       |   2 +-
 ...btb_more-advanced_view-models_use-cases.adoc |   2 +-
 ...gbtb_programming-model_custom-validator.adoc |   2 +-
 ...rogramming-model_layout-metadata-reader.adoc |   2 +-
 .../_ugfun_core-concepts_building-blocks.adoc   |   4 +-
 ..._core-concepts_other-deployment-options.adoc |   2 +-
 .../_ugfun_core-concepts_philosophy_aop.adoc    |   4 +-
 ..._core-concepts_philosophy_how-eases-ddd.adoc |   2 +-
 ...bjects-pattern_object-interface-mapping.adoc |   2 +-
 ...concepts_principles_apache-isis-vs_cqrs.adoc |   2 +-
 ...ts_principles_apache-isis-vs_metawidget.adoc |   2 +-
 .../guides/_ugfun_faqs_enabling-logging.adoc    |   2 +-
 .../asciidoc/guides/_ugfun_getting-started.adoc |   6 +-
 ...un_getting-started_datanucleus-enhancer.adoc |   6 +-
 ...fun_getting-started_simpleapp-archetype.adoc |   2 +-
 .../_ugfun_how-tos_class-structure_actions.adoc |   2 +-
 ...fun_how-tos_class-structure_collections.adoc |   2 +-
 ...gfun_how-tos_class-structure_properties.adoc |   4 +-
 .../guides/_ugfun_how-tos_domain-services.adoc  |   6 +-
 ...n_how-tos_ui-hints_action-icons-and-css.adoc |   2 +-
 .../guides/_ugfun_how-tos_ui-hints_layout.adoc  |   2 +-
 .../guides/_ugfun_object-layout_dynamic.adoc    |   2 +-
 .../_ugfun_object-layout_static-vs-dynamic.adoc |   4 +-
 .../_ugsec_configuring-isis-to-use-shiro.adoc   |   2 +-
 .../asciidoc/guides/_ugsec_shiro-ini-realm.adoc |   2 +-
 ...st_bdd-spec-support_maven-configuration.adoc |   2 +-
 ...tst_bdd-spec-support_writing-a-bdd-spec.adoc |   6 +-
 .../_ugtst_fixture-scripts_api-and-usage.adoc   |  12 +-
 ..._ugtst_integ-test-support_bootstrapping.adoc |   2 +-
 ..._integ-test-support_maven-configuration.adoc |   2 +-
 ..._ugtst_unit-test-support_contract-tests.adoc |   4 +-
 ...t_unit-test-support_maven-configuration.adoc |   2 +-
 .../guides/_ugvw_customisation_about-page.adoc  |   2 +-
 ...ugvw_customisation_tweaking-css-classes.adoc |   2 +-
 .../src/main/asciidoc/guides/_ugvw_layout.adoc  |   6 +-
 .../src/main/asciidoc/guides/cg.adoc            |   2 +-
 .../src/main/asciidoc/guides/rg.adoc            |   2 +-
 .../src/main/asciidoc/guides/rgant.adoc         |   3 +-
 .../src/main/asciidoc/guides/rgcfg.adoc         |  24 ++-
 .../src/main/asciidoc/guides/rgcms.adoc         |   6 +-
 .../src/main/asciidoc/guides/rgsvc.adoc         |   3 +-
 .../src/main/asciidoc/guides/tg.adoc            |   1 +
 .../src/main/asciidoc/guides/ug.adoc            |   2 +-
 .../src/main/asciidoc/guides/ugbtb.adoc         |   2 +-
 .../src/main/asciidoc/guides/ugfun.adoc         |  12 +-
 .../src/main/asciidoc/guides/ugsec.adoc         |   5 +-
 .../src/main/asciidoc/guides/ugtst.adoc         |   3 +-
 .../src/main/asciidoc/guides/ugvro.adoc         |   4 +-
 .../src/main/asciidoc/guides/ugvw.adoc          |   2 +-
 .../templates/isis-asciidoc-templates-idea.xml  | 115 ++++-------
 136 files changed, 306 insertions(+), 407 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_bootstrapping-using-AppManifest.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_bootstrapping-using-AppManifest.adoc b/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_bootstrapping-using-AppManifest.adoc
index 0617439..121bb73 100644
--- a/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_bootstrapping-using-AppManifest.adoc
+++ b/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_bootstrapping-using-AppManifest.adoc
@@ -8,7 +8,7 @@
 
 Apache Isis 1.9.0 provides a simplified programmatic way of bootstrapping the application, that also unifies bootstrapping for integration tests.
 
-For now this new bootstrapping mechanism is optional (you don't have to change your code), but it may become mandatory in future releases.  The xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] has been updated to use this new mechanism.
+For now this new bootstrapping mechanism is optional (you don't have to change your code), but it may become mandatory in future releases.  The xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] has been updated to use this new mechanism.
 
 The instructions below assume that your application is structured as per the simpleapp archetype.  Adjust accordingly.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_upgrading-to-dn4.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_upgrading-to-dn4.adoc b/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_upgrading-to-dn4.adoc
index 7fd697d..b868f3f 100644
--- a/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_upgrading-to-dn4.adoc
+++ b/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_upgrading-to-dn4.adoc
@@ -8,7 +8,7 @@
 
 Apache Isis 1.9.0 updates to DataNucleus 4.0.0, which requires some changes (simplifications) to the Maven configuration.
 
-If you starting a new app then you can start from the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]; its Maven configuration has been updated.
+If you starting a new app then you can start from the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]; its Maven configuration has been updated.
 
 If you have an existing Apache Isis app that you want to upgrade, then you'll need to make some changes.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_war-packaging.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_war-packaging.adoc b/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_war-packaging.adoc
index 5e72ba0..e137657 100644
--- a/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_war-packaging.adoc
+++ b/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_war-packaging.adoc
@@ -6,7 +6,7 @@
 
 
 
-As discussed in xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] and elsewhere, the `org.apache.isis.WebServer` provides the ability to run your app from an embedded jetty.  This is great for prototyping.  The class resides in the `isis-core-webserver` module, which also has the dependency on jetty.
+As discussed in xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] and elsewhere, the `org.apache.isis.WebServer` provides the ability to run your app from an embedded jetty.  This is great for prototyping.  The class resides in the `isis-core-webserver` module, which also has the dependency on jetty.
 
 In 1.9.0 we have upgraded the jetty dependency to use Jetty 9.2.0 (`org.eclipse.jetty.aggregate:jetty-all:9.2.11.v20150529`, to be precise).  One consequence of this is that the packaged WAR file will not boot on Tomcat.
 
@@ -31,4 +31,4 @@ Alternatively you can change your webapp's `pom.xml` so that when the war is pac
 ----
 
 
-For future projects the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] has been updated with this change.
+For future projects the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] has been updated with this change.

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/documentation.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/documentation.adoc b/adocs/documentation/src/main/asciidoc/documentation.adoc
index 5e1b2d8..272e919 100644
--- a/adocs/documentation/src/main/asciidoc/documentation.adoc
+++ b/adocs/documentation/src/main/asciidoc/documentation.adoc
@@ -79,7 +79,7 @@ pass:[<br/>]
 
 |*Contributors' Guide*
 
-* *link:./guides/cg.html[Contributors Guide^]*
+* *link:./guides/cg.html[Contributors' Guide^]*
 
 including:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_cg_asciidoc-templates.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_asciidoc-templates.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_asciidoc-templates.adoc
index 6a97968..81c4597 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_cg_asciidoc-templates.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_asciidoc-templates.adoc
@@ -92,9 +92,9 @@ where:
 
 
 
-== Xref to Contributors' Guide
+== Xref to Guides
 
-Cross-references (links) to the xref:cg.adoc#_cg[Contributors' Guide] (this document).
+Cross-references (links) to the various guides
 
 [cols="1,4a,2a", options="header"]
 |===
@@ -104,115 +104,34 @@ Cross-references (links) to the xref:cg.adoc#_cg[Contributors' Guide] (this docu
 
 
 |`adcg`
-|pass:[<pre>xref:cg.adoc#_cg[Contributors' Guide\]</pre>] +
+|pass:[<pre>xref:cg.adoc#xxx[ttt\]</pre>]
 
-a hyperlink to the contributors guide.
-|xref:cg.adoc#_cg[Contributors' Guide]
+a hyperlink to a bookmark within the contributors guide, where:
 
-|`adcg1`
-|pass:[<pre>xref:cg.adoc#_cg_xxx[ttt\]</pre>]
-
-a hyperlink to a level 1 (chapter) within the contributors guide, where:
-
-* `xxx` is the chapter's anchor
+* `xxx` is the bookmark's anchor
 * `ttt` is the text to display as the hyperlink
 
 for example:
 
-pass:[<pre>xref:cg.adoc#_cg_asciidoc-templates[Asciidoc templates/]</pre>]
+pass:[<pre>xref:cg.adoc#_cg_asciidoc-templates[Asciidoc templates\]</pre>]
 
 |xref:cg.adoc#_cg_asciidoc-templates[Asciidoc templates]
 
 
-|`adcg2`
-|pass:[<pre>xref:cg.adoc#_cg_xxx_yyy[ttt\]</pre>]
-
-a hyperlink to a level 2 (chapter and section) within the contributors guide, where:
-
-* `xxx` and `yyy` make up the anchor to the section within the chapter
-* `ttt` is the text to display as the hyperlink
-
-for example:
-
-pass:[<pre>xref:cg.adoc#_cg_committers_release-process[Release process/]</pre>]
-
-|xref:cg.adoc#_cg_committers_release-process[Release process]
-
-|===
-
-
-
-== Xref to Reference Guide
-
-Cross-references (links) to the xref:rg.adoc#_rg[Reference Guide].
-
-[cols="1,4a,2a", options="header"]
-|===
-| Abbrev.
-| Produces
-| Example
-
-|`adrg`
-|pass:[<pre>xref:rg.adoc#_rg[Reference Guide\]</pre>]
-
-a hyperlink to the Reference Guide.
-
-|xref:rg.adoc#_rg[Reference Guide]
-
-|`adrg1`
-|pass:[<pre>xref:rg.adoc#_rg_xxx[ttt\]</pre>]
-
-a hyperlink to a level 1 (chapter) within the reference guide, where:
-
-* `xxx` is the chapter's anchor
-* `ttt` is the text to display as the hyperlink
-
-for example:
-
-pass:[<pre>xref:rgant.adoc#_rgant[Annotations\]</pre>]
-
-|xref:rgant.adoc#_rgant[Annotations]
-
-
-
-|`adrg2`
-|pass:[<pre>xref:rg.adoc#_rg_xxx_yyy[ttt\]</pre>]
-
-a hyperlink to a level 2 (chapter and section) within the reference guide, where:
-
-* `xxx` and `yyy` make up the anchor to the section within the chapter
-* `ttt` is the text to display as the hyperlink
-
-for example:
-
-pass:[<pre>xref:ug.adoc#_ugfun_object-layout_dynamic_[Dynamic object layout]</pre>]
-
-|xref:ug.adoc#_ugfun_object-layout_dynamic[Dynamic object layout]
-
-
 
-|`adrg3`
-|pass:[<pre>xref:rg.adoc#_rg_xxx_yyy_zzz[ttt\]</pre>]
+|`adrgcfg`
+|pass:[<pre>xref:rgcfg.adoc#xxx[ttt\]</pre>]
 
-a hyperlink to a level 3 (chapter, section, subsection) within the reference guide, where:
+a hyperlink to a bookmark within configuration properties guide, where:
 
-* `xxx`, `yyy`, `zzz` make up the anchor to the subsection within the chapter
+* `xxx` is the bookmark
 * `ttt` is the text to display as the hyperlink
 
 for example:
 
-pass:[<pre>xref:rgcfg.adoc#_rgcfg_application-specific_application-css[Application-specific CSS\]</pre>]
-
-|xref:rgcfg.adoc#_rgcfg_application-specific_application-css[Application-specific CSS]
-
-
-
-|`adrgcfg`
-|pass:[<pre>xref:rgcfg.adoc#_rgcfg_configuring-core[configuration properties]</pre>]
-
-a hyperlink to the reference guide's catalogue of the Apache Isis configuration properties.
+pass:[<pre>xref:rgcfg.adoc#_rgcfg_configuring-core[Configuring Core\]</pre>]
 
-|xref:rgcfg.adoc#_rgcfg_configuring-core[configuration properties]
+|xref:rgcfg.adoc#_rgcfg_configuring-core[Configuring Core]
 
 
 
@@ -352,102 +271,108 @@ pass:[<pre>xref:rgsvc.adoc#_rgsvc-spi_ContentMappingService[`ContentMappingServi
 
 
 
-|===
 
+|`adugfun`
+|pass:[<pre>xref:ugfun.adoc#xxx[ttt\]</pre>]
 
+a hyperlink to a bookmark within the fundamentals users' guide, where:
 
-== Xref to the Users' Guide
-
-Cross-references (links) to the xref:ug.adoc#_ug[Users' Guide].
+* `xxx` is the bookmark's anchor
+* `ttt` is the text to display as the hyperlink
 
-[cols="1,4a,2a", options="header"]
-|===
-| Abbrev.
-| Produces
-| Example
+for example:
 
-|`adug`
-|pass:[<pre>xref:ug.adoc#_ug[Users' Guide\]</pre>]
+pass:[<pre>xref:ugfun.adoc#_ugfun_core-concepts[Core concepts\]</pre>]
 
-a hyperlink to the Users' Guide.
+|xref:ugfun.adoc#_ugfun_core-concepts[Core concepts]
 
-|xref:ug.adoc#_ug[Users' Guide]
 
 
 
-|`adug1`
-|pass:[<pre>xref:ug.adoc#xxx[ttt\]</pre>]
+|`adugvw`
+|pass:[<pre>xref:ugvw.adoc#xxx[ttt\]</pre>]
 
-a hyperlink to a level 1 (chapter) within the users' guide, where:
+A hyperlink to a bookmark within the Wicket viewer guide, where:
 
-* `xxx` is the chapter's anchor
-* `ttt` is the text to display as the hyperlink
+* `xxx` is the bookmark's anchor
+* `ttt` is the text to display as the hyperlink.
 
 for example:
 
-pass:[<pre>xref:ug.adoc#_ugfun_core-concepts[Core concepts\]</pre>]
+pass:[<pre>xref:ugvw.adoc#_ugvw_customisation[Customisation\]</pre>]
 
-|xref:ug.adoc#_ugfun_core-concepts[Core concepts]
+|xref:ugvw.adoc#_ugvw_customisation[Customisation]
 
 
+|`adugvro`
+|pass:[<pre>xref:ugvro.adoc#xxx[ttt\]</pre>]
 
-|`adug2`
-|pass:[<pre>xref:ug.adoc#xxx_yyy[ttt\]</pre>]
-
-a hyperlink to a level 2 (chapter and section) within the users' guide, where:
+A hyperlink to a bookmark within the Restful Objects viewer guide, where:
 
-* `xxx` and `yyy` make up the anchor to the section within the chapter
-* `ttt` is the text to display as the hyperlink
+* `xxx` is the bookmark's anchor
+* `ttt` is the text to display as the hyperlink.
 
 for example:
 
-pass:[<pre>xref:ug.adoc#core-concepts_philosophy[Philosophy\]</pre>]
+pass:[<pre>xref:ugvro.adoc#_ugvro_ro-spec[RestfulObjects specification\]</pre>]
 
+|xref:ugvro.adoc#_ugvro_ro-spec[RestfulObjects specification]
 
-|xref:ug.adoc#core-concepts_philosophy[Philosophy]
 
 
 
-|`adug3`
-|pass:[<pre>xref:ug.adoc#xxx_yyy_zzz[ttt\]</pre>]
+|`adugsec`
+|pass:[<pre>xref:ugsec.adoc#xxx[ttt\]</pre>]
 
-a hyperlink to a level 3 (chapter, section, subsection) within the users' guide, where:
+A hyperlink to a bookmark within the Secrurity guide, where:
 
-* `xxx`, `yyy`, `zzz` make up the anchor to the subsection within the chapter
-* `ttt` is the text to display as the hyperlink
+* `xxx` is the bookmark's anchor
+* `ttt` is the text to display as the hyperlink.
 
 for example:
 
-pass:[<pre>xref:ug.adoc#_ugfun_core-concepts_philosophy_naked-objects-pattern[Naked objects pattern\]</pre>]
+pass:[<pre>xref:ugsec.adoc#_ugsec_shiro-caching[Caching and other Shiro Features\]</pre>]
 
-|xref:ug.adoc#_ugfun_core-concepts_philosophy_naked-objects-pattern[Naked objects pattern]
+|xref:ugsec.adoc#_ugsec_shiro-caching[Caching and other Shiro Features]
 
 
+|`adugtst`
+|pass:[<pre>xref:ugtst.adoc#xxx[ttt\]</pre>]
 
+A hyperlink to a bookmark within the Testing guide, where:
 
-|`adugsimpleapp`
-|pass:[<pre>xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype\]</pre>]
+* `xxx` is the bookmark's anchor
+* `ttt` is the text to display as the hyperlink.
 
-A hyperlink to the `simpleapp` archetype in the "getting started" chapter.
+for example:
 
-|xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]
+pass:[<pre>xref:ugtst.adoc#_ugtst_bdd-spec-support[BDD Spec Support\]</pre>]
 
+|xref:ugtst.adoc#_ugtst_bdd-spec-support[BDD Spec Support]
 
-|`adugvro`
-|pass:[<pre>xref:ugvro.adoc#[RestfulObjects viewer\]</pre>]
 
-A hyperlink to the Restful Objects viewer chapter.
+|`adugbtb`
+|pass:[<pre>xref:ugbtb.adoc#xxx[ttt\]</pre>]
 
-|xref:ugvro.adoc#[RestfulObjects viewer]
+A hyperlink to a bookmark within the 'Beyond the Basics' user guide, where:
 
+* `xxx` is the bookmark's anchor
+* `ttt` is the text to display as the hyperlink.
 
+for example:
+
+pass:[<pre>xref:ugbtb.adoc#_ugbtb_deployment_externalized-configuration[Externalized Configuration\]</pre>]
+
+|xref:ugbtb.adoc#_ugbtb_deployment_externalized-configuration[Externalized Configuration]
 
-|`adugvw`
-|pass:[<pre>xref:ugvw.adoc#[Wicket viewer\]</pre>]
 
-A hyperlink to the Wicket viewer chapter.
 
-|xref:ugvw.adoc#[Wicket viewer]
+|`adugsimpleapp`
+|pass:[<pre>xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype\]</pre>]
+
+A hyperlink to the `simpleapp` archetype in the "getting started" chapter.
+
+|xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_cg_ide_eclipse.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_ide_eclipse.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_ide_eclipse.adoc
index bbf0d98..51a2c27 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_cg_ide_eclipse.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_ide_eclipse.adoc
@@ -62,7 +62,7 @@ image::{_imagesdir}appendices/dev-env/eclipse/eclipse-110-project-support.png[wi
 
 DataNucleus' enhancer uses the domain object model's own classpath to reference DataNucleus JARs. So, even though your domain objects are unlikely to depend on DataNucleus, these references must still be present.
 
-See the earlier section on xref:ug.adoc#_ugfun_getting-started_datanucleus-enhancer[DataNucleus enhancer] for details of the contents of the `pom.xml`.  Chances are it is already set up from running the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
+See the earlier section on xref:ugfun.adoc#_ugfun_getting-started_datanucleus-enhancer[DataNucleus enhancer] for details of the contents of the `pom.xml`.  Chances are it is already set up from running the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
 
 
 Then, tell DataNucleus to use the project classpath:

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin.adoc
index 6b9a13d..e08c844 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin.adoc
@@ -29,7 +29,7 @@ it knows how to bootstrap an Isis runtime.  This is discussed below, followed by
 As noted in the introduction, both goals require an xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`]
 to point the plugin at, so that it knows how to bootstrap an Isis runtime.
 
-This can be extremely minimal.  For example, the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp]'s
+This can be extremely minimal.  For example, the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp]'s
 manifest is:
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin_validate.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin_validate.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin_validate.adoc
index 9771752..f480034 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin_validate.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin_validate.adoc
@@ -110,7 +110,7 @@ mvn test -Dskip.isis-validate
 
 == Example of failure
 
-In the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp] application the `SimpleObject` defines an `updateName` action.  This has a supporting method:
+In the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp] application the `SimpleObject` defines an `updateName` action.  This has a supporting method:
 
 
 [source,java]

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout.adoc
index cc16e56..c2537a1 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout.adoc
@@ -100,7 +100,7 @@ public class ToDoItems {
 
 
 
-As an alternative to using the `@ActionLayout` annotation, a dynamic layout using  xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`] file can be specified; for example:
+As an alternative to using the `@ActionLayout` annotation, a dynamic layout using  xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`] file can be specified; for example:
 
 [source,javascript]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_bookmarking.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_bookmarking.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_bookmarking.adoc
index 6a646dc..d7d7157 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_bookmarking.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_bookmarking.adoc
@@ -50,7 +50,7 @@ The enum value `AS_CHILD` has no meaning for actions; it relates only to bookmar
 
 
 
-As an alternative to using the annotation, the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_contributedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_contributedAs.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_contributedAs.adoc
index 13b1fe8..ce3d5e2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_contributedAs.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_contributedAs.adoc
@@ -49,6 +49,6 @@ In such cases, though, it would probably make more sense to annotate the action
 
 [NOTE]
 ====
-Unlike other `@ActionLayout` attributes, this attribute _cannot_ be specified dynamically in the `.layout.json` xref:ug.adoc#_ugfun_object-layout_dynamic[dynamic layout file] because it relates to the contributor domain service, not the contributee domain object.
+Unlike other `@ActionLayout` attributes, this attribute _cannot_ be specified dynamically in the `.layout.json` xref:ugfun.adoc#_ugfun_object-layout_dynamic[dynamic layout file] because it relates to the contributor domain service, not the contributee domain object.
 ====
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_cssClass.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_cssClass.adoc
index e2f0bac..50663ba 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_cssClass.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_cssClass.adoc
@@ -30,7 +30,7 @@ to apply CSS, specifically to add http://fortawesome.github.io/Font-Awesome/icon
 
 
 
-As an alternative to using the annotation, the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_cssClassFa.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_cssClassFa.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_cssClassFa.adoc
index 3e393c7..97e4640 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_cssClassFa.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_cssClassFa.adoc
@@ -31,7 +31,7 @@ public class ToDoItem {
 There can be multiple "fa-" classes, eg to mirror or rotate the icon. There is no need to include the mandatory `fa` "marker" CSS class; it will be automatically added to the list.  The `fa-` prefix can also be omitted from the class names; it will be prepended to each if required.
 
 
-As an alternative to using the annotation, the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_describedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_describedAs.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_describedAs.adoc
index f1543f8..ff07b6b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_describedAs.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_describedAs.adoc
@@ -24,7 +24,7 @@ public class Customer {
 
 
 
-As an alternative to using the annotation, the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_hidden.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_hidden.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_hidden.adoc
index bb28835..8b24d47 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_hidden.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_hidden.adoc
@@ -37,7 +37,7 @@ The action should not be hidden.
 The other values of the `Where` enum have no meaning for a collection.
 
 
-As an alternative to using the annotation, the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_named.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_named.adoc
index 7813dca..2c6952c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_named.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_named.adoc
@@ -25,7 +25,7 @@ public class Customer {
 ----
 
 
-As an alternative to using the annotation, the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_position.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_position.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_position.adoc
index c3d09c0..2338f5e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_position.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_position.adoc
@@ -67,7 +67,7 @@ image::{_imagesdir}reference-annotations/ActionLayout/position-PANEL_DROPDOWN.pn
 If there are multiple actions associated with a single property then the positioning can be mix'ed-and-match'ed as required.  If the `PANEL` or `PANEL_DROPDOWN` are used, then (as the screenshots above show) the actions from potentially multiple properties grouped by that panel will be shown together.
 
 
-As an alternative to using the annotation, the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgant-Action_hidden.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-Action_hidden.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-Action_hidden.adoc
index f65b28c..fb9876a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-Action_hidden.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-Action_hidden.adoc
@@ -11,7 +11,7 @@ Actions can be hidden at the domain-level, indicating that they are not visible
 
 [TIP]
 ====
-It is also possible to use xref:rgant.adoc#_rgant-ActionLayout_hidden[`@ActionLayout#hidden()`] or xref:ug.adoc#_ugfun_object-layout_dynamic[dynamic layouts] such that the action can be hidden at the view layer. Both options are provided with a view that in the future the view-layer semantics may be under the control of (expert) users, whereas domain-layer semantics should never be overridden or modified by the user.
+It is also possible to use xref:rgant.adoc#_rgant-ActionLayout_hidden[`@ActionLayout#hidden()`] or xref:ugfun.adoc#_ugfun_object-layout_dynamic[dynamic layouts] such that the action can be hidden at the view layer. Both options are provided with a view that in the future the view-layer semantics may be under the control of (expert) users, whereas domain-layer semantics should never be overridden or modified by the user.
 ====
 
 For example:

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout.adoc
index 0ff2f80..0d0500e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout.adoc
@@ -94,7 +94,7 @@ public class ToDoItem {
 
 
 
-As an alternative to using the `@CollectionLayout` annotation, a dynamic layout using  xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`] file can be specified; for example:
+As an alternative to using the `@CollectionLayout` annotation, a dynamic layout using  xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`] file can be specified; for example:
 
 [source,javascript]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_cssClass.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_cssClass.adoc
index e18e3e1..58b7d0d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_cssClass.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_cssClass.adoc
@@ -24,7 +24,7 @@ public class ToDoItem {
 ----
 
 
-As an alternative to using the annotation, the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_defaultView.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_defaultView.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_defaultView.adoc
index 9641d78..5b77688 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_defaultView.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_defaultView.adoc
@@ -24,7 +24,7 @@ public class BusRoute {
 ----
 
 
-As an alternative to using the annotation, the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_describedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_describedAs.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_describedAs.adoc
index effc006..26b329a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_describedAs.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_describedAs.adoc
@@ -24,7 +24,7 @@ public class ToDoItem {
 ----
 
 
-As an alternative to using the annotation, the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_hidden.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_hidden.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_hidden.adoc
index ad906c3..c85db7e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_hidden.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_hidden.adoc
@@ -47,7 +47,7 @@ The collection should not be hidden.
 The other values of the `Where` enum have no meaning for a collection.
 
 
-As an alternative to using the annotation, the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_named.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_named.adoc
index 9fe50e2..2ab0b68 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_named.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_named.adoc
@@ -33,7 +33,7 @@ public class ToDoItem {
 
 
 
-As an alternative to using the annotation, the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_paged.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_paged.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_paged.adoc
index 2551458..256efa4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_paged.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_paged.adoc
@@ -31,7 +31,7 @@ It is also possible to specify a global default for the page size of standalone
 
 
 
-As an alternative to using the annotation, the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_render.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_render.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_render.adoc
index 121e185..ae076bc 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_render.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_render.adoc
@@ -20,7 +20,7 @@ public class Order {
 ----
 
 
-As an alternative to using the annotation, the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]
@@ -35,7 +35,7 @@ can be used instead, eg:
 
 [NOTE]
 ====
-Note that xref:ug.adoc#_ugfun_how-tos_contributed-members[contributed collections] (which, under the covers are just action invocations against a domain service) are always rendered eagerly.
+Note that xref:ugfun.adoc#_ugfun_how-tos_contributed-members[contributed collections] (which, under the covers are just action invocations against a domain service) are always rendered eagerly.
 
 Also, if a xref:rgant.adoc#_rgant-CollectionLayout_defaultView[`@CollectionLayout#defaultView()`] attribute has been specified then that will take precedence over the value of the `render()` attribute.
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_sortedBy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_sortedBy.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_sortedBy.adoc
index 2083be4..73da475 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_sortedBy.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_sortedBy.adoc
@@ -46,7 +46,7 @@ Without this annotation, the order would have been inverted (because the natural
 
 
 
-As an alternative to using the annotation, the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgant-Collection_hidden.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-Collection_hidden.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-Collection_hidden.adoc
index c16c14a..59d51d5 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-Collection_hidden.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-Collection_hidden.adoc
@@ -9,7 +9,7 @@ Collections can be hidden at the domain-level, indicating that they are not visi
 
 [TIP]
 ====
-It is also possible to use xref:rgant.adoc#_rgant-CollectionLayout_hidden[`@CollectionLayout#hidden()`] or xref:ug.adoc#_ugfun_object-layout_dynamic[dynamic layouts] such that the collection can be hidden at the view layer. Both options are provided with a view that in the future the view-layer semantics may be under the control of (expert) users, whereas domain-layer semantics should never be overridden or modified by the user.
+It is also possible to use xref:rgant.adoc#_rgant-CollectionLayout_hidden[`@CollectionLayout#hidden()`] or xref:ugfun.adoc#_ugfun_object-layout_dynamic[dynamic layouts] such that the collection can be hidden at the view layer. Both options are provided with a view that in the future the view-layer semantics may be under the control of (expert) users, whereas domain-layer semantics should never be overridden or modified by the user.
 ====
 
 For example:

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout.adoc
index e49a5f5..5948b59 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout.adoc
@@ -109,7 +109,7 @@ public class ToDoItem {
 
 [NOTE]
 ====
-Note that there is (currently) no support for specifying UI hints for domain objects through the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`] file (only for properties, collections and actions are supported).
+Note that there is (currently) no support for specifying UI hints for domain objects through the dynamic xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`] file (only for properties, collections and actions are supported).
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainServiceLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainServiceLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainServiceLayout.adoc
index 240951e..effc805 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainServiceLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainServiceLayout.adoc
@@ -10,7 +10,7 @@ The `@DomainServiceLayout` annotation applies to domain services, collecting tog
 
 [TIP]
 ====
-You will also find some additional material in the xref:ug.adoc#_ugfun_object-layout_application-menu[object layout] chapter.
+You will also find some additional material in the xref:ugfun.adoc#_ugfun_object-layout_application-menu[object layout] chapter.
 ====
 
 
@@ -64,7 +64,7 @@ public class ToDoItems {
 
 [NOTE]
 ====
-Note that there is (currently) no support for specifying UI hints for domain services through the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`] file (only for properties, collections and actions are supported).
+Note that there is (currently) no support for specifying UI hints for domain services through the dynamic xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`] file (only for properties, collections and actions are supported).
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgant-HomePage.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-HomePage.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-HomePage.adoc
index 159caae..ade4095 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-HomePage.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-HomePage.adoc
@@ -45,7 +45,7 @@ public class ToDoAppDashboard {
     public Blob exportToWordDoc() { ... }  // <1>
 }
 ----
-<1> associated using xref:ug.adoc#_ugfun_object-layout_dynamic[dynamic layouts] with the `notYetComplete` collection.
+<1> associated using xref:ugfun.adoc#_ugfun_object-layout_dynamic[dynamic layouts] with the `notYetComplete` collection.
 
 The other two actions shown in the above screenshot -- `exportAsXml` and `downloadLayout` -- are actually contributed to the `ToDoAppDashboard` through various domain services, as is the `downloadLayout` action.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgant-Inject.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-Inject.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-Inject.adoc
index 77dc434..7025e43 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-Inject.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-Inject.adoc
@@ -27,7 +27,7 @@ public class Customer {
     OrderRepository orders;                    // <2>
 }
 ----
-<1> an alternative implementation would be to implement `findRecentOrders()` as a xref:ug.adoc#_ugfun_how-tos_contributed-members[contributed action].
+<1> an alternative implementation would be to implement `findRecentOrders()` as a xref:ugfun.adoc#_ugfun_how-tos_contributed-members[contributed action].
 <2> we recommend default (rather than `private`) visibility so that unit tests can easily mock out the service
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgant-MemberGroupLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-MemberGroupLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-MemberGroupLayout.adoc
index f93af0d..acb285a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-MemberGroupLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-MemberGroupLayout.adoc
@@ -16,5 +16,5 @@ The annotation defines two attributes, `name()` and `sequence()`.  Broadly speak
 
 [IMPORTANT]
 ====
-As this is an important topic, there is a xref:ug.adoc#_ugfun_object-layout[separate chapter] that discussed object layout in full.
+As this is an important topic, there is a xref:ugfun.adoc#_ugfun_object-layout[separate chapter] that discussed object layout in full.
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgant-MemberOrder.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-MemberOrder.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-MemberOrder.adoc
index c642d84..f09c574 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-MemberOrder.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-MemberOrder.adoc
@@ -21,7 +21,7 @@ Collections are always rendered in the "last" column.  This can appear either be
 
 [IMPORTANT]
 ====
-As this is an important topic, there is a xref:ug.adoc#_ugfun_object-layout[separate chapter] that discussed object layout in full.
+As this is an important topic, there is a xref:ugfun.adoc#_ugfun_object-layout[separate chapter] that discussed object layout in full.
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgant-ParameterLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-ParameterLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-ParameterLayout.adoc
index fd7cc1c..1592b2c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-ParameterLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-ParameterLayout.adoc
@@ -96,7 +96,7 @@ public class ToDoItem {
 
 [NOTE]
 ====
-Note that there is (currently) no support for specifying UI hints for domain services through the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`] file (only for properties, collections and actions are supported).
+Note that there is (currently) no support for specifying UI hints for domain services through the dynamic xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`] file (only for properties, collections and actions are supported).
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout.adoc
index 9687634..68d4518 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout.adoc
@@ -102,7 +102,7 @@ It is also possible to apply the annotation to actions of domain services that a
 
 
 
-As an alternative to using the `@PropertyLayout` annotation, a dynamic layout using  xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`] file can be specified; for example:
+As an alternative to using the `@PropertyLayout` annotation, a dynamic layout using  xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`] file can be specified; for example:
 
 [source,javascript]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_cssClass.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_cssClass.adoc
index 0c31226..1ffe390 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_cssClass.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_cssClass.adoc
@@ -23,7 +23,7 @@ public class ToDoItem {
 
 
 
-As an alternative to using the annotation, the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_describedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_describedAs.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_describedAs.adoc
index 8c63f37..401fb46 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_describedAs.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_describedAs.adoc
@@ -20,7 +20,7 @@ public class Customer {
 ----
 
 
-As an alternative to using the annotation, the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_hidden.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_hidden.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_hidden.adoc
index 2e83211..7743805 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_hidden.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_hidden.adoc
@@ -10,7 +10,7 @@ The `hidden()` attribute indicates where (in the UI) the property should be hidd
 
 [TIP]
 ====
-It is also possible to use xref:rgant.adoc#_rgant-PropertyLayout_hidden[`@PropertyLayout#hidden()`] or xref:ug.adoc#_ugfun_object-layout_dynamic[dynamic layouts] such that the property can be hidden at the view layer. Both options are provided with a view that in the future the view-layer semantics may be under the control of (expert) users, whereas domain-layer semantics should never be overridden or modified by the user.
+It is also possible to use xref:rgant.adoc#_rgant-PropertyLayout_hidden[`@PropertyLayout#hidden()`] or xref:ugfun.adoc#_ugfun_object-layout_dynamic[dynamic layouts] such that the property can be hidden at the view layer. Both options are provided with a view that in the future the view-layer semantics may be under the control of (expert) users, whereas domain-layer semantics should never be overridden or modified by the user.
 ====
 
 
@@ -67,7 +67,7 @@ The xref:ugvro.adoc#[RestfulObjects viewer] has only partial support for these `
 ====
 
 
-As an alternative to using the annotation, the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_labelPosition.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_labelPosition.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_labelPosition.adoc
index 7eef03e..508b2cb 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_labelPosition.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_labelPosition.adoc
@@ -58,7 +58,7 @@ image::{_imagesdir}reference-annotations/PropertyLayout/labelPosition-boolean-RI
 
 
 
-As an alternative to using the annotation, the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_multiLine.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_multiLine.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_multiLine.adoc
index f506d24..758f765 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_multiLine.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_multiLine.adoc
@@ -25,7 +25,7 @@ Here the `stepsToReproduce` will be displayed in a text area of 10 rows.
 
 
 
-As an alternative to using the annotation, the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_named.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_named.adoc
index 43fc46d..9aece74 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_named.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_named.adoc
@@ -31,7 +31,7 @@ public class ToDoItem {
 
 
 
-As an alternative to using the annotation, the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_renderedAsDayBefore.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_renderedAsDayBefore.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_renderedAsDayBefore.adoc
index d041d5a..60e89cb 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_renderedAsDayBefore.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_renderedAsDayBefore.adoc
@@ -32,7 +32,7 @@ public class Tenancy {
 
 
 
-As an alternative to using the annotation, the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgant-ViewModelLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-ViewModelLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-ViewModelLayout.adoc
index a7406c1..34c1389 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-ViewModelLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-ViewModelLayout.adoc
@@ -82,7 +82,7 @@ public class CategoryPieChart { ... }
 
 [NOTE]
 ====
-Note that there is (currently) no support for specifying UI hints for view models through the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`] file (only for properties, collections and actions are supported).
+Note that there is (currently) no support for specifying UI hints for view models through the dynamic xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`] file (only for properties, collections and actions are supported).
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgant_aaa_deprecated.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant_aaa_deprecated.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant_aaa_deprecated.adoc
index b40bdeb..3a52807 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant_aaa_deprecated.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant_aaa_deprecated.adoc
@@ -19,7 +19,7 @@ The annotations listed in the table below are still supported by Apache Isis, bu
 |Purpose
 |Use instead
 |Layer
-|xref:ug.adoc#_ugfun_object-layout_dynamic[Dynamic layout]?
+|xref:ugfun.adoc#_ugfun_object-layout_dynamic[Dynamic layout]?
 
 |`@ActionOrder`
 |Order of buttons and menu items representing actions.

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgant_aaa_jee.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant_aaa_jee.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant_aaa_jee.adoc
index a68682c..9ad9522 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant_aaa_jee.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant_aaa_jee.adoc
@@ -16,7 +16,7 @@ The table below lists the JEE annotations currently recognized.  Expect to see m
 |Annotation
 |Purpose
 |Layer
-|xref:ug.adoc#_ugfun_object-layout_dynamic[Dynamic layout]?
+|xref:ugfun.adoc#_ugfun_object-layout_dynamic[Dynamic layout]?
 
 |xref:rgant.adoc#_rgant-Digits[`@javax.validation.` +
 `constraints.` +

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgant_aaa_main.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant_aaa_main.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant_aaa_main.adoc
index 42a19f5..013c0b8 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant_aaa_main.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant_aaa_main.adoc
@@ -11,7 +11,7 @@ For each of these domain types and members there are two annotations.  One cover
 
 [TIP]
 ====
-Most UI semantics can also be specified using xref:ug.adoc#_ugfun_object-layout_dynamic[dynamic object layout].
+Most UI semantics can also be specified using xref:ugfun.adoc#_ugfun_object-layout_dynamic[dynamic object layout].
 ====
 
 
@@ -24,7 +24,7 @@ The table below summarizes these most commonly used annotations in Apache Isis.
 |Annotation
 |Purpose
 |Layer
-|xref:ug.adoc#_ugfun_object-layout_dynamic[Dynamic layout]?
+|xref:ugfun.adoc#_ugfun_object-layout_dynamic[Dynamic layout]?
 
 |xref:rgant.adoc#_rgant-Action[`@Action`]
 |Domain semantics for actions

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgant_aaa_other.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant_aaa_other.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant_aaa_other.adoc
index 824d77b..2c15a7a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant_aaa_other.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant_aaa_other.adoc
@@ -13,7 +13,7 @@ These annotations are also commonly used, but relate _not_ to objects or object
 |Annotation
 |Purpose
 |Layer
-|xref:ug.adoc#_ugfun_object-layout_dynamic[Dynamic layout]?
+|xref:ugfun.adoc#_ugfun_object-layout_dynamic[Dynamic layout]?
 
 |xref:rgant.adoc#_rgant-Facets[`@Facets`]
 |Install arbitrary facets within the Apache Isis metamodel.

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-core.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-core.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-core.adoc
index 224be40..0d675e4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-core.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-core.adoc
@@ -55,14 +55,14 @@ Only intended for "emergency use" as a workaround while pending fix/patch to Apa
 |regex:css1, regex2:css2,...
 |Comma separated list of key:value pairs, where the key is a regex matching action names (eg `delete.*`) and the value is a link:http://getbootstrap.com/css/[Bootstrap] CSS button class (eg `btn-warning) to be applied (as per `@CssClass()`) to all action members matching the regex. +
 
-See xref:ug.adoc#_ugfun_how-tos_ui-hints_action-icons-and-css[UI hints] for more details.
+See xref:ugfun.adoc#_ugfun_how-tos_ui-hints_action-icons-and-css[UI hints] for more details.
 
 |`isis.reflector.facet.` +
 `cssClassFa.patterns`
 |regex:fa-icon,regex2:fa-icon2,...
 |Comma separated list of key:value pairs, where the key is a regex matching action names (eg `create.*`) and the value is a link:http://fortawesome.github.io/Font-Awesome/icons/[font-awesome] icon name (eg `fa-plus`) to be applied (as per `@CssClassFa()`) to all action members matching the regex. +
 
-See xref:ug.adoc#_ugfun_how-tos_ui-hints_action-icons-and-css[UI hints] for more details.
+See xref:ugfun.adoc#_ugfun_how-tos_ui-hints_action-icons-and-css[UI hints] for more details.
 
 |`isis.reflector.facet.` +
 `domainObjectAnnotation.` +
@@ -189,7 +189,7 @@ See xref:ugbtb.adoc#_ugbtb_programming-model_finetuning[finetuning the programmi
 |`isis.reflector.` +
 `layoutMetadataReaders`
 |`FQCN`,`FQCN2`,...
-|Fully qualified class names of classes to be instantiated to read layout metadata, as used in for xref:ug.adoc#_ugfun_object-layout_dynamic[dynamic layout]s. +
+|Fully qualified class names of classes to be instantiated to read layout metadata, as used in for xref:ugfun.adoc#_ugfun_object-layout_dynamic[dynamic layout]s. +
 
 See xref:ugbtb.adoc#_ugbtb_programming-model_layout-metadata-reader[Layout Metadata Reader] for more information.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_disabling-persistence-by-reachability.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_disabling-persistence-by-reachability.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_disabling-persistence-by-reachability.adoc
index fa994ce..40f5f89 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_disabling-persistence-by-reachability.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_disabling-persistence-by-reachability.adoc
@@ -23,7 +23,7 @@ We therefore recommend that you disable persistence-by-reachability by adding th
 isis.persistor.datanucleus.impl.datanucleus.persistenceByReachabilityAtCommit=false
 ----
 
-This change has been made to the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]
+This change has been made to the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]
 
 If you do disable this feature, then you will (of course) need to ensure that you explicitly persist all entities using the `DomainObjectContainer#persist(.)` or `DomainObjectContainer#persistIfNotAlready(.)` methods.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgcfg_specifying-components.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_specifying-components.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_specifying-components.adoc
index ad20bb1..3205a5b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_specifying-components.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_specifying-components.adoc
@@ -27,7 +27,7 @@ To specify the `AppManifest` as a configuration property, use:
 |`FQCN`
 |`o.a.i.applib.AppManifest` +
 
-By convention this implementation resides in an `myapp-app` Maven module (as opposed to `myapp-dom` or `myapp-fixture`).  See the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] for details.
+By convention this implementation resides in an `myapp-app` Maven module (as opposed to `myapp-dom` or `myapp-fixture`).  See the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] for details.
 
 |===
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes.adoc
index 071d8b6..1e8649d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-This chapter describes the usage of various classes and interfaces that are not otherwise associated with xref:rgsvc.adoc#_rgsvc-api[domain] xref:rgsvc.adoc#_rgsvc-spi[services], xref:ug.adoc#_ugfun_object-layout[object layout] or xref:rgcfg.adoc#_rgcfg[configuration].
+This chapter describes the usage of various classes and interfaces that are not otherwise associated with xref:rgsvc.adoc#_rgsvc-api[domain] xref:rgsvc.adoc#_rgsvc-spi[services], xref:ugfun.adoc#_ugfun_object-layout[object layout] or xref:rgcfg.adoc#_rgcfg[configuration].
 
 
 include::_rgcms_classes_AppManifest-bootstrapping.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_AppManifest-bootstrapping.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_AppManifest-bootstrapping.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_AppManifest-bootstrapping.adoc
index 19a4e4f..71ba5da 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_AppManifest-bootstrapping.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_AppManifest-bootstrapping.adoc
@@ -183,7 +183,7 @@ What then remains is to update the bootstrapping code itself.
 
 Bootstrapping integration tests is still performed using the `IsisSystemForTest.Builder`, but very often the bootstrapping code can be substantially simplified (compared to not using an `AppManifest`, that is).
 
-For example, this is the bootstrapping code for the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] looks something like:
+For example, this is the bootstrapping code for the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] looks something like:
 
 [source,java]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_choices.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_choices.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_choices.adoc
index eefc9ba..42de401 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_choices.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_choices.adoc
@@ -60,7 +60,7 @@ image::{_imagesdir}reference-methods/prefixes/choices/dependent.png[width="800px
 
 
 
-This functionality is actually implemented as a xref:ug.adoc#_ugfun_how-tos_contributed-members[contributed action], so the code for this is:
+This functionality is actually implemented as a xref:ugfun.adoc#_ugfun_how-tos_contributed-members[contributed action], so the code for this is:
 
 [source,java]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_default.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_default.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_default.adoc
index 037538a..635cf6e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_default.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_default.adoc
@@ -58,7 +58,7 @@ public class ShoppingCartItem {
 
 
 
-Defaults are also supported (of course) for xref:ug.adoc#_ugfun_how-tos_contributed-members[contributed actions].  For example, here is a contributed action for updating category/subcategory of the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp]:
+Defaults are also supported (of course) for xref:ugfun.adoc#_ugfun_how-tos_contributed-members[contributed actions].  For example, here is a contributed action for updating category/subcategory of the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp]:
 
 [source,java]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-common.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-common.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-common.adoc
index 211f064..def83e7 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-common.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-common.adoc
@@ -12,7 +12,7 @@ xref:rgsvc.adoc#_rgsvc-api_BookmarkService[`BookmarkService`].
 
 Although simple, this is an enormously powerful concept, in that it represents a URI to any domain object managed by
 a given Apache Isis application.  With it, we have the ability to lookup any arbitrary object.  Further discussion and
-examples can be found xref:ug.adoc#_ugfun_core-concepts_building-blocks_oid[here].
+examples can be found xref:ugfun.adoc#_ugfun_core-concepts_building-blocks_oid[here].
 
 
 [source,xml]

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_ActionInvocationContext.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_ActionInvocationContext.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_ActionInvocationContext.adoc
index 2ab1258..6b501a1 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_ActionInvocationContext.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_ActionInvocationContext.adoc
@@ -71,7 +71,7 @@ so no further configuration is required.
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ugfun.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_BackgroundService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_BackgroundService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_BackgroundService.adoc
index 25706eb..f3c4fce 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_BackgroundService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_BackgroundService.adoc
@@ -100,7 +100,7 @@ further configuration is required.
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ugfun.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_BookmarkService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_BookmarkService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_BookmarkService.adoc
index 4ff46db..a31ba85 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_BookmarkService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_BookmarkService.adoc
@@ -111,6 +111,6 @@ configuration is required.
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ugfun.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_CommandContext.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_CommandContext.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_CommandContext.adoc
index 8994a5c..2bcdddb 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_CommandContext.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_CommandContext.adoc
@@ -203,7 +203,7 @@ implementation of `CommandContext` service is automatically registered and injec
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ugfun.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DeepLinkService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DeepLinkService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DeepLinkService.adoc
index 363b0c7..a635b05 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DeepLinkService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DeepLinkService.adoc
@@ -53,4 +53,4 @@ automatically registered and injected (it is annotated with `@DomainService`) so
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ugfun.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_EmailService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_EmailService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_EmailService.adoc
index 2042983..ea86c0c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_EmailService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_EmailService.adoc
@@ -87,7 +87,7 @@ implementation of `EmailService` service is automatically registered and injecte
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ugfun.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
 
 
 == Related Services

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_EventBusService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_EventBusService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_EventBusService.adoc
index 1e3ecbb..940ed87 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_EventBusService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_EventBusService.adoc
@@ -393,7 +393,7 @@ implementation of `EventBusService` service is automatically registered and inje
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ugfun.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_GuiceBeanProvider.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_GuiceBeanProvider.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_GuiceBeanProvider.adoc
index 261195f..87004c1 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_GuiceBeanProvider.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_GuiceBeanProvider.adoc
@@ -86,6 +86,6 @@ automatically registered and injected (it is annotated with `@DomainService`) so
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ugfun.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_IsisJdoSupport.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_IsisJdoSupport.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_IsisJdoSupport.adoc
index 9553542..e5395c9 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_IsisJdoSupport.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_IsisJdoSupport.adoc
@@ -273,4 +273,4 @@ implementation of `IsisJdoSupport` service is automatically registered and injec
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ugfun.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).


[50/52] [abbrv] isis git commit: Merge branch 'master' into ISIS-1223-upgrade-to-wicket-7

Posted by mg...@apache.org.
Merge branch 'master' into ISIS-1223-upgrade-to-wicket-7


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/803fbc14
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/803fbc14
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/803fbc14

Branch: refs/heads/ISIS-1224-select2-v4
Commit: 803fbc14c825de91204d2ba5a73712c963f56322
Parents: d483b2c 4e21fbc
Author: Martin Tzvetanov Grigorov <mg...@apache.org>
Authored: Sun Dec 13 10:37:12 2015 +0100
Committer: Martin Tzvetanov Grigorov <mg...@apache.org>
Committed: Sun Dec 13 10:37:12 2015 +0100

----------------------------------------------------------------------
 README.adoc                                     |    8 +-
 STATUS                                          |    3 +
 adocs/documentation/Gemfile                     |    3 +
 adocs/documentation/Gemfile.lock                |    2 +
 adocs/documentation/monitor.rb                  |   70 +-
 adocs/documentation/publish.sh                  |    8 +-
 .../_migration-notes_1.10.0-to-1.11.0.adoc      |   58 +
 .../_migration-notes_1.7.0-to-1.8.0.adoc        |    5 +-
 ...o-1.9.0_bootstrapping-using-AppManifest.adoc |    4 +-
 ...tes_1.8.0-to-1.9.0_exception-recognizer.adoc |    6 +-
 ..._fixture-scripts-specification-provider.adoc |    4 +-
 ...1.8.0-to-1.9.0_specify-all-dom-packages.adoc |    6 +-
 ...n-notes_1.8.0-to-1.9.0_upgrading-to-dn4.adoc |    2 +-
 ...tion-notes_1.8.0-to-1.9.0_war-packaging.adoc |    4 +-
 .../_migration-notes_1.9.0-to-1.10.0.adoc       |  136 ++
 .../src/main/asciidoc/_powered-by_commapp.adoc  |   45 +
 .../src/main/asciidoc/_powered-by_estatio.adoc  |   41 +
 .../asciidoc/_powered-by_gesconsultor-grc.adoc  |  109 ++
 .../asciidoc/_powered-by_transport-planner.adoc |   55 +
 .../src/main/asciidoc/_release-notes_1.0.0.adoc |  126 ++
 .../src/main/asciidoc/_release-notes_1.0.1.adoc |   22 +
 .../src/main/asciidoc/_release-notes_1.1.0.adoc |  141 ++
 .../main/asciidoc/_release-notes_1.10.0.adoc    |   93 ++
 .../src/main/asciidoc/_release-notes_1.2.0.adoc |  136 ++
 .../src/main/asciidoc/_release-notes_1.3.0.adoc |  256 +++
 .../src/main/asciidoc/_release-notes_1.3.1.adoc |   30 +
 .../src/main/asciidoc/_release-notes_1.4.0.adoc |  238 +++
 .../src/main/asciidoc/_release-notes_1.4.1.adoc |   30 +
 .../src/main/asciidoc/_release-notes_1.5.0.adoc |  125 ++
 .../src/main/asciidoc/_release-notes_1.6.0.adoc |   93 ++
 .../src/main/asciidoc/_release-notes_1.7.0.adoc |  122 ++
 .../src/main/asciidoc/_release-notes_1.8.0.adoc |  127 ++
 .../src/main/asciidoc/_release-notes_1.9.0.adoc |  140 ++
 .../src/main/asciidoc/common-use-cases.adoc     |    4 +-
 .../documentation/src/main/asciidoc/demos.adoc  |   18 -
 .../src/main/asciidoc/doap_isis.rdf             |   19 +-
 .../src/main/asciidoc/documentation.adoc        |   73 +-
 .../src/main/asciidoc/downloads.adoc            |   10 +-
 .../asciidoc/guides/_cg_asciidoc-templates.adoc |  257 ++-
 .../main/asciidoc/guides/_cg_building-isis.adoc |   28 +-
 .../_cg_committers_cutting-a-release.adoc       |   64 +-
 .../_cg_committers_post-release-successful.adoc |   70 +-
 ...cg_committers_post-release-unsuccessful.adoc |   16 +-
 ...ommitters_release-process-for-snapshots.adoc |   26 +-
 .../_cg_committers_verifying-releases.adoc      |    2 +-
 .../main/asciidoc/guides/_cg_ide-templates.adoc |   62 +-
 .../src/main/asciidoc/guides/_cg_ide.adoc       |    1 +
 .../main/asciidoc/guides/_cg_ide_agilej.adoc    |   55 +
 .../main/asciidoc/guides/_cg_ide_eclipse.adoc   |   28 +-
 .../main/asciidoc/guides/_cg_ide_intellij.adoc  |   65 +-
 .../asciidoc/guides/_cg_ide_project-lombok.adoc |    4 +-
 .../asciidoc/guides/_cg_isis-maven-plugin.adoc  |  231 +--
 .../guides/_cg_isis-maven-plugin_validate.adoc  |  241 +++
 .../guides/_cg_isis-maven-plugin_xsd.adoc       |  329 ++++
 .../main/asciidoc/guides/_rg_annotations.adoc   |   63 -
 .../asciidoc/guides/_rg_annotations_aaa.adoc    |   17 -
 .../guides/_rg_annotations_aaa_deprecated.adoc  |  342 ----
 .../guides/_rg_annotations_aaa_jdo.adoc         |  113 --
 .../guides/_rg_annotations_aaa_jee.adoc         |   59 -
 .../guides/_rg_annotations_aaa_main.adoc        |  103 --
 .../guides/_rg_annotations_aaa_other.adoc       |   57 -
 .../guides/_rg_annotations_aaa_partial.adoc     |   92 --
 .../guides/_rg_annotations_manpage-Action.adoc  |  137 --
 .../_rg_annotations_manpage-ActionLayout.adoc   |  133 --
 ...ations_manpage-ActionLayout_bookmarking.adoc |   64 -
 ...ions_manpage-ActionLayout_contributedAs.adoc |   54 -
 ...notations_manpage-ActionLayout_cssClass.adoc |   41 -
 ...tations_manpage-ActionLayout_cssClassFa.adoc |   59 -
 ...ations_manpage-ActionLayout_describedAs.adoc |   37 -
 ...annotations_manpage-ActionLayout_hidden.adoc |   57 -
 ..._annotations_manpage-ActionLayout_named.adoc |   45 -
 ...notations_manpage-ActionLayout_position.adoc |   80 -
 .../_rg_annotations_manpage-Action_command.adoc |  134 --
 ..._annotations_manpage-Action_domainEvent.adoc |  160 --
 .../_rg_annotations_manpage-Action_hidden.adoc  |   49 -
 ..._rg_annotations_manpage-Action_invokeOn.adoc |   64 -
 ...g_annotations_manpage-Action_publishing.adoc |   53 -
 ...g_annotations_manpage-Action_restrictTo.adoc |   30 -
 ...rg_annotations_manpage-Action_semantics.adoc |   91 --
 .../_rg_annotations_manpage-Action_typeOf.adoc  |   31 -
 .../_rg_annotations_manpage-Collection.adoc     |  105 --
 ...rg_annotations_manpage-CollectionLayout.adoc |  128 --
 ...tions_manpage-CollectionLayout_cssClass.adoc |   36 -
 ...ns_manpage-CollectionLayout_describedAs.adoc |   37 -
 ...tations_manpage-CollectionLayout_hidden.adoc |   58 -
 ...otations_manpage-CollectionLayout_named.adoc |   53 -
 ...otations_manpage-CollectionLayout_paged.adoc |   45 -
 ...tations_manpage-CollectionLayout_render.adoc |   40 -
 ...tions_manpage-CollectionLayout_sortedBy.adoc |   59 -
 ...otations_manpage-Collection_domainEvent.adoc |  178 --
 ..._annotations_manpage-Collection_editing.adoc |   48 -
 ...g_annotations_manpage-Collection_hidden.adoc |   54 -
 ...tations_manpage-Collection_notPersisted.adoc |   57 -
 ...g_annotations_manpage-Collection_typeOf.adoc |   26 -
 .../guides/_rg_annotations_manpage-Column.adoc  |  154 --
 .../guides/_rg_annotations_manpage-Digits.adoc  |   35 -
 .../_rg_annotations_manpage-Discriminator.adoc  |   59 -
 .../_rg_annotations_manpage-DomainObject.adoc   |  105 --
 ..._annotations_manpage-DomainObjectLayout.adoc |  115 --
 ..._manpage-DomainObjectLayout_bookmarking.adoc |   66 -
 ...ons_manpage-DomainObjectLayout_cssClass.adoc |   34 -
 ...s_manpage-DomainObjectLayout_cssClassFa.adoc |   40 -
 ..._manpage-DomainObjectLayout_describedAs.adoc |   22 -
 ...ations_manpage-DomainObjectLayout_named.adoc |   37 -
 ...ations_manpage-DomainObjectLayout_paged.adoc |   33 -
 ...tions_manpage-DomainObjectLayout_plural.adoc |   28 -
 ...notations_manpage-DomainObject_auditing.adoc |   38 -
 ...age-DomainObject_autoCompleteRepository.adoc |   81 -
 ...nnotations_manpage-DomainObject_bounded.adoc |   36 -
 ...nnotations_manpage-DomainObject_editing.adoc |   61 -
 ...annotations_manpage-DomainObject_nature.adoc |   66 -
 ...tations_manpage-DomainObject_objectType.adoc |   46 -
 ...tations_manpage-DomainObject_publishing.adoc |   49 -
 .../_rg_annotations_manpage-DomainService.adoc  |   64 -
 ...annotations_manpage-DomainServiceLayout.adoc |   78 -
 ...ons_manpage-DomainServiceLayout_menuBar.adoc |   43 -
 ...s_manpage-DomainServiceLayout_menuOrder.adoc |   74 -
 ...tions_manpage-DomainServiceLayout_named.adoc |   29 -
 ...nnotations_manpage-DomainService_nature.adoc |   89 -
 ...ons_manpage-DomainService_repositoryFor.adoc |   26 -
 .../guides/_rg_annotations_manpage-Facets.adoc  |   15 -
 .../_rg_annotations_manpage-HomePage.adoc       |   52 -
 .../guides/_rg_annotations_manpage-Inject.adoc  |  154 --
 ...g_annotations_manpage-MemberGroupLayout.adoc |   20 -
 .../_rg_annotations_manpage-MemberOrder.adoc    |   35 -
 .../_rg_annotations_manpage-MinLength.adoc      |   32 -
 .../guides/_rg_annotations_manpage-Mixin.adoc   |   40 -
 .../_rg_annotations_manpage-NotPersistent.adoc  |   18 -
 .../_rg_annotations_manpage-Parameter.adoc      |   96 --
 ..._rg_annotations_manpage-ParameterLayout.adoc |  112 --
 ...ations_manpage-ParameterLayout_cssClass.adoc |   29 -
 ...ons_manpage-ParameterLayout_describedAs.adoc |   38 -
 ...s_manpage-ParameterLayout_labelPosition.adoc |   41 -
 ...tions_manpage-ParameterLayout_multiLine.adoc |   32 -
 ...notations_manpage-ParameterLayout_named.adoc |   44 -
 ...age-ParameterLayout_renderedAsDayBefore.adoc |   35 -
 ...s_manpage-ParameterLayout_typicalLength.adoc |   36 -
 ...annotations_manpage-Parameter_maxLength.adoc |   35 -
 ...notations_manpage-Parameter_mustSatisfy.adoc |   65 -
 ...notations_manpage-Parameter_optionality.adoc |   36 -
 ...otations_manpage-Parameter_regexPattern.adoc |   31 -
 ..._annotations_manpage-PersistenceCapable.adoc |   90 -
 .../_rg_annotations_manpage-PostConstruct.adoc  |   71 -
 .../_rg_annotations_manpage-PreDestroy.adoc     |   53 -
 .../_rg_annotations_manpage-PrimaryKey.adoc     |   19 -
 .../_rg_annotations_manpage-Programmatic.adoc   |   27 -
 .../_rg_annotations_manpage-Property.adoc       |  134 --
 .../_rg_annotations_manpage-PropertyLayout.adoc |  142 --
 ...tations_manpage-PropertyLayout_cssClass.adoc |   36 -
 ...ions_manpage-PropertyLayout_describedAs.adoc |   33 -
 ...notations_manpage-PropertyLayout_hidden.adoc |   78 -
 ...ns_manpage-PropertyLayout_labelPosition.adoc |   96 --
 ...ations_manpage-PropertyLayout_multiLine.adoc |   44 -
 ...nnotations_manpage-PropertyLayout_named.adoc |   51 -
 ...page-PropertyLayout_renderedAsDayBefore.adoc |   45 -
 ...ns_manpage-PropertyLayout_typicalLength.adoc |   25 -
 ...nnotations_manpage-Property_domainEvent.adoc |  164 --
 ...rg_annotations_manpage-Property_editing.adoc |   43 -
 ..._rg_annotations_manpage-Property_hidden.adoc |   66 -
 ..._annotations_manpage-Property_maxLength.adoc |   49 -
 ...nnotations_manpage-Property_mustSatisfy.adoc |   57 -
 ...notations_manpage-Property_notPersisted.adoc |   61 -
 ...nnotations_manpage-Property_optionality.adoc |  129 --
 ...notations_manpage-Property_regexPattern.adoc |   28 -
 .../_rg_annotations_manpage-RequestScoped.adoc  |   50 -
 .../guides/_rg_annotations_manpage-Title.adoc   |   38 -
 .../_rg_annotations_manpage-ViewModel.adoc      |   44 -
 ..._rg_annotations_manpage-ViewModelLayout.adoc |  102 --
 ...ations_manpage-ViewModelLayout_cssClass.adoc |   30 -
 ...ions_manpage-ViewModelLayout_cssClassFa.adoc |   41 -
 ...ons_manpage-ViewModelLayout_describedAs.adoc |   23 -
 ...notations_manpage-ViewModelLayout_named.adoc |   35 -
 ...notations_manpage-ViewModelLayout_paged.adoc |   34 -
 ...otations_manpage-ViewModelLayout_plural.adoc |   24 -
 .../src/main/asciidoc/guides/_rg_classes.adoc   |   22 -
 .../_rg_classes_AppManifest-bootstrapping.adoc  |  282 ----
 .../guides/_rg_classes_contributee.adoc         |   13 -
 ...es_contributee_manpage-HasTransactionId.adoc |   31 -
 ...classes_contributee_manpage-HasUserName.adoc |   27 -
 .../guides/_rg_classes_domainevent.adoc         |   76 -
 ...domainevent_manpage-AbstractDomainEvent.adoc |   20 -
 ...s_domainevent_manpage-ActionDomainEvent.adoc |   20 -
 ...mainevent_manpage-CollectionDomainEvent.adoc |   21 -
 ...domainevent_manpage-PropertyDomainEvent.adoc |   17 -
 .../main/asciidoc/guides/_rg_classes_i18n.adoc  |   11 -
 ...classes_i18n_manpage-TranslatableString.adoc |   13 -
 .../guides/_rg_classes_lifecycleevent.adoc      |  130 --
 ...cleevent_manpage-AbstractLifecycleEvent.adoc |   27 -
 ...fecycleevent_manpage-ObjectCreatedEvent.adoc |   20 -
 ...ifecycleevent_manpage-ObjectLoadedEvent.adoc |   17 -
 ...cycleevent_manpage-ObjectPersistedEvent.adoc |   19 -
 ...ycleevent_manpage-ObjectPersistingEvent.adoc |   21 -
 ...ecycleevent_manpage-ObjectRemovingEvent.adoc |   20 -
 ...fecycleevent_manpage-ObjectUpdatedEvent.adoc |   21 -
 ...ecycleevent_manpage-ObjectUpdatingEvent.adoc |   22 -
 .../main/asciidoc/guides/_rg_classes_roles.adoc |   15 -
 ...rg_classes_roles_manpage-HoldsUpdatedAt.adoc |   45 -
 ...rg_classes_roles_manpage-HoldsUpdatedBy.adoc |   19 -
 ..._rg_classes_roles_manpage-Timestampable.adoc |   23 -
 .../main/asciidoc/guides/_rg_classes_spec.adoc  |  108 --
 .../main/asciidoc/guides/_rg_classes_super.adoc |  105 --
 ...s_super_manpage-AbstractContainedObject.adoc |   32 -
 ...sses_super_manpage-AbstractDomainObject.adoc |   14 -
 ...er_manpage-AbstractFactoryAndRepository.adoc |   15 -
 ...g_classes_super_manpage-AbstractService.adoc |   10 -
 ...lasses_super_manpage-AbstractSubscriber.adoc |    8 -
 ...classes_super_manpage-AbstractViewModel.adoc |   15 -
 ..._rg_classes_super_manpage-FixtureScript.adoc |   21 -
 ...rg_classes_super_manpage-FixtureScripts.adoc |   12 -
 .../asciidoc/guides/_rg_classes_utility.adoc    |   16 -
 .../_rg_classes_utility_manpage-Enums.adoc      |    8 -
 ...classes_utility_manpage-ObjectContracts.adoc |  107 --
 .../_rg_classes_utility_manpage-Reasons.adoc    |   31 -
 ..._rg_classes_utility_manpage-TitleBuffer.adoc |   13 -
 .../guides/_rg_classes_value-types.adoc         |  119 --
 .../_rg_classes_value-types_manpage-Blob.adoc   |    8 -
 .../_rg_classes_value-types_manpage-Clob.adoc   |    8 -
 .../_rg_classes_value-types_manpage-Color.adoc  |    9 -
 .../_rg_classes_value-types_manpage-Money.adoc  |    8 -
 ...rg_classes_value-types_manpage-Password.adoc |    8 -
 .../src/main/asciidoc/guides/_rg_methods.adoc   |   17 -
 .../asciidoc/guides/_rg_methods_lifecycle.adoc  |  102 --
 .../guides/_rg_methods_lifecycle_jdo-api.adoc   |   53 -
 .../_rg_methods_lifecycle_manpage-created.adoc  |   17 -
 .../_rg_methods_lifecycle_manpage-loaded.adoc   |   15 -
 ..._rg_methods_lifecycle_manpage-persisted.adoc |   16 -
 ...rg_methods_lifecycle_manpage-persisting.adoc |   16 -
 .../_rg_methods_lifecycle_manpage-removed.adoc  |   16 -
 .../_rg_methods_lifecycle_manpage-removing.adoc |   16 -
 .../_rg_methods_lifecycle_manpage-updated.adoc  |   18 -
 .../_rg_methods_lifecycle_manpage-updating.adoc |   15 -
 .../asciidoc/guides/_rg_methods_prefixes.adoc   |  219 ---
 .../_rg_methods_prefixes_manpage-addTo.adoc     |   37 -
 ...g_methods_prefixes_manpage-autoComplete.adoc |   96 --
 .../_rg_methods_prefixes_manpage-choices.adoc   |  143 --
 .../_rg_methods_prefixes_manpage-clear.adoc     |   32 -
 .../_rg_methods_prefixes_manpage-default.adoc   |  129 --
 .../_rg_methods_prefixes_manpage-disable.adoc   |   93 --
 .../_rg_methods_prefixes_manpage-get.adoc       |   19 -
 .../_rg_methods_prefixes_manpage-hide.adoc      |   82 -
 .../_rg_methods_prefixes_manpage-modify.adoc    |   37 -
 ..._rg_methods_prefixes_manpage-removeFrom.adoc |   37 -
 .../_rg_methods_prefixes_manpage-set.adoc       |   13 -
 .../_rg_methods_prefixes_manpage-validate.adoc  |  113 --
 ..._methods_prefixes_manpage-validateAddTo.adoc |   45 -
 ...ods_prefixes_manpage-validateRemoveFrom.adoc |   45 -
 .../asciidoc/guides/_rg_methods_reserved.adoc   |   58 -
 .../_rg_methods_reserved_manpage-cssClass.adoc  |   46 -
 .../_rg_methods_reserved_manpage-disable.adoc   |  102 --
 .../_rg_methods_reserved_manpage-getId.adoc     |   19 -
 .../_rg_methods_reserved_manpage-hide.adoc      |   39 -
 .../_rg_methods_reserved_manpage-iconName.adoc  |   36 -
 .../_rg_methods_reserved_manpage-title.adoc     |   65 -
 .../_rg_methods_reserved_manpage-validate.adoc  |   27 -
 .../main/asciidoc/guides/_rg_object-layout.adoc |   18 -
 .../_rg_object-layout_application-menu.adoc     |  171 --
 .../guides/_rg_object-layout_dynamic.adoc       |  113 --
 .../_rg_object-layout_static-vs-dynamic.adoc    |   26 -
 .../guides/_rg_object-layout_static.adoc        |  159 --
 .../src/main/asciidoc/guides/_rg_runtime.adoc   |   28 -
 .../_rg_runtime_application-specific.adoc       |   13 -
 ...me_application-specific_application-css.adoc |    8 -
 ...ime_application-specific_application-js.adoc |    9 -
 .../guides/_rg_runtime_configuration-files.adoc |   40 -
 .../guides/_rg_runtime_configuring-core.adoc    |  333 ----
 .../_rg_runtime_configuring-datanucleus.adoc    |   18 -
 ...s_disabling-persistence-by-reachability.adoc |   88 -
 ...atanucleus_eagerly-registering-entities.adoc |   23 -
 ...configuring-datanucleus_persistence-xml.adoc |   10 -
 ...time_configuring-datanucleus_properties.adoc |   66 -
 ...ring-datanucleus_using-jndi-data-source.adoc |   75 -
 .../guides/_rg_runtime_deployment-types.adoc    |  111 --
 .../_rg_runtime_specifying-components.adoc      |  110 --
 .../main/asciidoc/guides/_rg_services-api.adoc  |  295 ----
 ...ces-api_manpage-ActionInvocationContext.adoc |   99 --
 ..._services-api_manpage-BackgroundService.adoc |  124 --
 ...roundService_BackgroundCommandExecution.adoc |   25 -
 ...es-api_manpage-BackgroundService_Quartz.adoc |  162 --
 ...rg_services-api_manpage-BookmarkService.adoc |  118 --
 ...ices-api_manpage-BulkInteractionContext.adoc |    9 -
 .../_rg_services-api_manpage-ClockService.adoc  |  105 --
 ..._rg_services-api_manpage-CommandContext.adoc |  218 ---
 ...rg_services-api_manpage-DeepLinkService.adoc |   58 -
 ...vices-api_manpage-DomainObjectContainer.adoc |   44 -
 ...nObjectContainer_generic-repository-api.adoc |   89 -
 ...page-DomainObjectContainer_messages-api.adoc |   50 -
 ...mainObjectContainer_object-creation-api.adoc |   49 -
 ...nObjectContainer_object-persistence-api.adoc |   62 -
 ...-DomainObjectContainer_presentation-api.adoc |   46 -
 ...ge-DomainObjectContainer_properties-api.adoc |   54 -
 ...page-DomainObjectContainer_security-api.adoc |   48 -
 ...page-DomainObjectContainer_services-api.adoc |   37 -
 ...ge-DomainObjectContainer_validation-api.adoc |   26 -
 .../_rg_services-api_manpage-EmailService.adoc  |   99 --
 ...rg_services-api_manpage-EventBusService.adoc |  392 -----
 ...vices-api_manpage-FixtureScriptsDefault.adoc |   50 -
 ..._services-api_manpage-GuiceBeanProvider.adoc |   91 --
 ..._rg_services-api_manpage-IsisJdoSupport.adoc |  277 ----
 ..._rg_services-api_manpage-MementoService.adoc |  132 --
 ...g_services-api_manpage-MetamodelService.adoc |   43 -
 ..._services-api_manpage-QueryResultsCache.adoc |  128 --
 .../_rg_services-api_manpage-Scratchpad.adoc    |  130 --
 .../_rg_services-api_manpage-SudoService.adoc   |   69 -
 ..._rg_services-api_manpage-WrapperFactory.adoc |  163 --
 ...services-api_manpage-XmlSnapshotService.adoc |  215 ---
 .../main/asciidoc/guides/_rg_services-spi.adoc  |  287 ----
 ...rg_services-spi_manpage-AuditingService.adoc |   85 -
 ...es-spi_manpage-BackgroundCommandService.adoc |  130 --
 ...vices-spi_manpage-ClassDiscoveryService.adoc |   84 -
 ..._rg_services-spi_manpage-CommandService.adoc |  100 --
 ...vices-spi_manpage-ContentMappingService.adoc |  106 --
 ...s-spi_manpage-ContentNegotiationService.adoc |  206 ---
 ...es-spi_manpage-EmailNotificationService.adoc |   81 -
 ...vices-spi_manpage-ErrorReportingService.adoc |  105 --
 ...rg_services-spi_manpage-EventSerializer.adoc |   73 -
 ...ervices-spi_manpage-ExceptionRecognizer.adoc |  126 --
 ...age-FixtureScriptsSpecificationProvider.adoc |   70 -
 ..._rg_services-spi_manpage-LocaleProvider.adoc |   72 -
 ..._services-spi_manpage-PublishingService.adoc |  164 --
 ...vices-spi_manpage-RepresentationService.adoc |  107 --
 ...services-spi_manpage-TranslationService.adoc |   80 -
 ...rvices-spi_manpage-TranslationsResolver.adoc |   68 -
 ...services-spi_manpage-UserProfileService.adoc |   44 -
 ...ces-spi_manpage-UserRegistrationService.adoc |   82 -
 .../src/main/asciidoc/guides/_rg_web-xml.adoc   |  458 ------
 .../src/main/asciidoc/guides/_rgant-Action.adoc |  133 ++
 .../asciidoc/guides/_rgant-ActionLayout.adoc    |  133 ++
 .../guides/_rgant-ActionLayout_bookmarking.adoc |   64 +
 .../_rgant-ActionLayout_contributedAs.adoc      |   54 +
 .../guides/_rgant-ActionLayout_cssClass.adoc    |   41 +
 .../guides/_rgant-ActionLayout_cssClassFa.adoc  |   59 +
 .../guides/_rgant-ActionLayout_describedAs.adoc |   37 +
 .../guides/_rgant-ActionLayout_hidden.adoc      |   57 +
 .../guides/_rgant-ActionLayout_named.adoc       |   45 +
 .../guides/_rgant-ActionLayout_position.adoc    |   80 +
 .../asciidoc/guides/_rgant-Action_command.adoc  |  134 ++
 .../guides/_rgant-Action_domainEvent.adoc       |  164 ++
 .../asciidoc/guides/_rgant-Action_hidden.adoc   |   49 +
 .../asciidoc/guides/_rgant-Action_invokeOn.adoc |   64 +
 .../guides/_rgant-Action_publishing.adoc        |   53 +
 .../guides/_rgant-Action_restrictTo.adoc        |   30 +
 .../guides/_rgant-Action_semantics.adoc         |   91 ++
 .../asciidoc/guides/_rgant-Action_typeOf.adoc   |   31 +
 .../main/asciidoc/guides/_rgant-Collection.adoc |  105 ++
 .../guides/_rgant-CollectionLayout.adoc         |  137 ++
 .../_rgant-CollectionLayout_cssClass.adoc       |   36 +
 .../_rgant-CollectionLayout_defaultView.adoc    |   43 +
 .../_rgant-CollectionLayout_describedAs.adoc    |   38 +
 .../guides/_rgant-CollectionLayout_hidden.adoc  |   58 +
 .../guides/_rgant-CollectionLayout_named.adoc   |   53 +
 .../guides/_rgant-CollectionLayout_paged.adoc   |   45 +
 .../guides/_rgant-CollectionLayout_render.adoc  |   42 +
 .../_rgant-CollectionLayout_sortedBy.adoc       |   59 +
 .../guides/_rgant-Collection_domainEvent.adoc   |  174 ++
 .../guides/_rgant-Collection_editing.adoc       |   48 +
 .../guides/_rgant-Collection_hidden.adoc        |   54 +
 .../guides/_rgant-Collection_notPersisted.adoc  |   57 +
 .../guides/_rgant-Collection_typeOf.adoc        |   26 +
 .../src/main/asciidoc/guides/_rgant-Column.adoc |  154 ++
 .../src/main/asciidoc/guides/_rgant-Digits.adoc |   35 +
 .../asciidoc/guides/_rgant-Discriminator.adoc   |   59 +
 .../asciidoc/guides/_rgant-DomainObject.adoc    |  154 ++
 .../guides/_rgant-DomainObjectLayout.adoc       |  132 ++
 .../_rgant-DomainObjectLayout_bookmarking.adoc  |   66 +
 .../_rgant-DomainObjectLayout_cssClass.adoc     |   34 +
 .../_rgant-DomainObjectLayout_cssClassFa.adoc   |   40 +
 ...gant-DomainObjectLayout_cssClassUiEvent.adoc |  126 ++
 .../_rgant-DomainObjectLayout_describedAs.adoc  |   22 +
 .../_rgant-DomainObjectLayout_iconUiEvent.adoc  |  122 ++
 .../guides/_rgant-DomainObjectLayout_named.adoc |   37 +
 .../guides/_rgant-DomainObjectLayout_paged.adoc |   33 +
 .../_rgant-DomainObjectLayout_plural.adoc       |   28 +
 .../_rgant-DomainObjectLayout_titleUiEvent.adoc |  120 ++
 .../guides/_rgant-DomainObject_auditing.adoc    |   38 +
 ...ant-DomainObject_autoCompleteRepository.adoc |   81 +
 .../guides/_rgant-DomainObject_bounded.adoc     |   36 +
 ...gant-DomainObject_createdLifecycleEvent.adoc |  108 ++
 .../guides/_rgant-DomainObject_editing.adoc     |   61 +
 ...rgant-DomainObject_loadedLifecycleEvent.adoc |  105 ++
 .../guides/_rgant-DomainObject_nature.adoc      |   66 +
 .../guides/_rgant-DomainObject_objectType.adoc  |   46 +
 ...nt-DomainObject_persistedLifecycleEvent.adoc |  111 ++
 ...t-DomainObject_persistingLifecycleEvent.adoc |  114 ++
 .../guides/_rgant-DomainObject_publishing.adoc  |   49 +
 ...ant-DomainObject_removingLifecycleEvent.adoc |  114 ++
 ...gant-DomainObject_updatedLifecycleEvent.adoc |  110 ++
 ...ant-DomainObject_updatingLifecycleEvent.adoc |  114 ++
 .../asciidoc/guides/_rgant-DomainService.adoc   |   64 +
 .../guides/_rgant-DomainServiceLayout.adoc      |   78 +
 .../_rgant-DomainServiceLayout_menuBar.adoc     |   43 +
 .../_rgant-DomainServiceLayout_menuOrder.adoc   |   74 +
 .../_rgant-DomainServiceLayout_named.adoc       |   29 +
 .../guides/_rgant-DomainService_nature.adoc     |   89 +
 .../_rgant-DomainService_repositoryFor.adoc     |   26 +
 .../src/main/asciidoc/guides/_rgant-Facets.adoc |   15 +
 .../main/asciidoc/guides/_rgant-HomePage.adoc   |   52 +
 .../src/main/asciidoc/guides/_rgant-Inject.adoc |  154 ++
 .../guides/_rgant-MemberGroupLayout.adoc        |   20 +
 .../asciidoc/guides/_rgant-MemberOrder.adoc     |   35 +
 .../main/asciidoc/guides/_rgant-MinLength.adoc  |   32 +
 .../src/main/asciidoc/guides/_rgant-Mixin.adoc  |   40 +
 .../asciidoc/guides/_rgant-NotPersistent.adoc   |   18 +
 .../main/asciidoc/guides/_rgant-Parameter.adoc  |   96 ++
 .../asciidoc/guides/_rgant-ParameterLayout.adoc |  112 ++
 .../guides/_rgant-ParameterLayout_cssClass.adoc |   29 +
 .../_rgant-ParameterLayout_describedAs.adoc     |   38 +
 .../_rgant-ParameterLayout_labelPosition.adoc   |   41 +
 .../_rgant-ParameterLayout_multiLine.adoc       |   32 +
 .../guides/_rgant-ParameterLayout_named.adoc    |   44 +
 ...ant-ParameterLayout_renderedAsDayBefore.adoc |   35 +
 .../_rgant-ParameterLayout_typicalLength.adoc   |   36 +
 .../guides/_rgant-Parameter_maxLength.adoc      |   35 +
 .../guides/_rgant-Parameter_mustSatisfy.adoc    |   65 +
 .../guides/_rgant-Parameter_optionality.adoc    |   36 +
 .../guides/_rgant-Parameter_regexPattern.adoc   |   37 +
 .../guides/_rgant-PersistenceCapable.adoc       |   90 +
 .../asciidoc/guides/_rgant-PostConstruct.adoc   |   71 +
 .../main/asciidoc/guides/_rgant-PreDestroy.adoc |   53 +
 .../main/asciidoc/guides/_rgant-PrimaryKey.adoc |   19 +
 .../asciidoc/guides/_rgant-Programmatic.adoc    |   27 +
 .../main/asciidoc/guides/_rgant-Property.adoc   |  134 ++
 .../asciidoc/guides/_rgant-PropertyLayout.adoc  |  142 ++
 .../guides/_rgant-PropertyLayout_cssClass.adoc  |   36 +
 .../_rgant-PropertyLayout_describedAs.adoc      |   33 +
 .../guides/_rgant-PropertyLayout_hidden.adoc    |   78 +
 .../_rgant-PropertyLayout_labelPosition.adoc    |   96 ++
 .../guides/_rgant-PropertyLayout_multiLine.adoc |   44 +
 .../guides/_rgant-PropertyLayout_named.adoc     |   51 +
 ...gant-PropertyLayout_renderedAsDayBefore.adoc |   45 +
 .../_rgant-PropertyLayout_typicalLength.adoc    |   25 +
 .../guides/_rgant-Property_domainEvent.adoc     |  154 ++
 .../guides/_rgant-Property_editing.adoc         |   43 +
 .../asciidoc/guides/_rgant-Property_hidden.adoc |   66 +
 .../guides/_rgant-Property_maxLength.adoc       |   49 +
 .../guides/_rgant-Property_mustSatisfy.adoc     |   57 +
 .../guides/_rgant-Property_notPersisted.adoc    |   61 +
 .../guides/_rgant-Property_optionality.adoc     |  129 ++
 .../guides/_rgant-Property_regexPattern.adoc    |   35 +
 .../asciidoc/guides/_rgant-RequestScoped.adoc   |   50 +
 .../src/main/asciidoc/guides/_rgant-Title.adoc  |   62 +
 .../main/asciidoc/guides/_rgant-ViewModel.adoc  |   44 +
 .../asciidoc/guides/_rgant-ViewModelLayout.adoc |  102 ++
 .../guides/_rgant-ViewModelLayout_cssClass.adoc |   30 +
 .../_rgant-ViewModelLayout_cssClassFa.adoc      |   41 +
 .../_rgant-ViewModelLayout_describedAs.adoc     |   23 +
 .../guides/_rgant-ViewModelLayout_named.adoc    |   35 +
 .../guides/_rgant-ViewModelLayout_paged.adoc    |   34 +
 .../guides/_rgant-ViewModelLayout_plural.adoc   |   24 +
 .../guides/_rgant-XmlJavaTypeAdapter.adoc       |   27 +
 .../asciidoc/guides/_rgant-XmlRootElement.adoc  |   83 +
 .../src/main/asciidoc/guides/_rgant_aaa.adoc    |   17 +
 .../asciidoc/guides/_rgant_aaa_deprecated.adoc  |  342 ++++
 .../main/asciidoc/guides/_rgant_aaa_jdo.adoc    |  113 ++
 .../main/asciidoc/guides/_rgant_aaa_jee.adoc    |   73 +
 .../main/asciidoc/guides/_rgant_aaa_main.adoc   |  103 ++
 .../main/asciidoc/guides/_rgant_aaa_other.adoc  |   57 +
 .../asciidoc/guides/_rgant_aaa_partial.adoc     |   92 ++
 .../guides/_rgcfg_configuration-files.adoc      |   40 +
 .../guides/_rgcfg_configuring-core.adoc         |  455 ++++++
 .../guides/_rgcfg_configuring-datanucleus.adoc  |   18 +
 ...s_disabling-persistence-by-reachability.adoc |   88 +
 ...atanucleus_eagerly-registering-entities.adoc |   23 +
 ...configuring-datanucleus_persistence-xml.adoc |   10 +
 ...gcfg_configuring-datanucleus_properties.adoc |   66 +
 ...ring-datanucleus_using-jndi-data-source.adoc |   75 +
 .../guides/_rgcfg_deployment-types.adoc         |  111 ++
 .../guides/_rgcfg_specifying-components.adoc    |  110 ++
 .../main/asciidoc/guides/_rgcms_classes.adoc    |   23 +
 ...rgcms_classes_AppManifest-bootstrapping.adoc |  282 ++++
 .../guides/_rgcms_classes_contributee.adoc      |   13 +
 ...ms_classes_contributee_HasTransactionId.adoc |   31 +
 .../_rgcms_classes_contributee_HasUserName.adoc |   27 +
 .../guides/_rgcms_classes_domainevent.adoc      |   76 +
 ...classes_domainevent_AbstractDomainEvent.adoc |   20 +
 ...s_classes_domainevent_ActionDomainEvent.adoc |   20 +
 ...asses_domainevent_CollectionDomainEvent.adoc |   21 +
 ...classes_domainevent_PropertyDomainEvent.adoc |   17 +
 .../asciidoc/guides/_rgcms_classes_i18n.adoc    |   11 +
 .../_rgcms_classes_i18n_TranslatableString.adoc |   13 +
 .../guides/_rgcms_classes_lifecycleevent.adoc   |  130 ++
 ...s_lifecycleevent_AbstractLifecycleEvent.adoc |   27 +
 ...asses_lifecycleevent_ObjectCreatedEvent.adoc |   20 +
 ...lasses_lifecycleevent_ObjectLoadedEvent.adoc |   17 +
 ...ses_lifecycleevent_ObjectPersistedEvent.adoc |   19 +
 ...es_lifecycleevent_ObjectPersistingEvent.adoc |   21 +
 ...sses_lifecycleevent_ObjectRemovingEvent.adoc |   20 +
 ...asses_lifecycleevent_ObjectUpdatedEvent.adoc |   21 +
 ...sses_lifecycleevent_ObjectUpdatingEvent.adoc |   22 +
 .../asciidoc/guides/_rgcms_classes_roles.adoc   |   18 +
 .../guides/_rgcms_classes_roles_Dto.adoc        |   61 +
 .../_rgcms_classes_roles_HoldsUpdatedAt.adoc    |   44 +
 .../_rgcms_classes_roles_HoldsUpdatedBy.adoc    |   19 +
 .../_rgcms_classes_roles_Persistable.adoc       |   34 +
 .../_rgcms_classes_roles_Timestampable.adoc     |   23 +
 .../asciidoc/guides/_rgcms_classes_spec.adoc    |  108 ++
 .../asciidoc/guides/_rgcms_classes_super.adoc   |  105 ++
 ...s_classes_super_AbstractContainedObject.adoc |   32 +
 ...gcms_classes_super_AbstractDomainObject.adoc |   14 +
 ...sses_super_AbstractFactoryAndRepository.adoc |   15 +
 .../_rgcms_classes_super_AbstractService.adoc   |   10 +
 ..._rgcms_classes_super_AbstractSubscriber.adoc |   18 +
 .../_rgcms_classes_super_AbstractViewModel.adoc |   15 +
 .../_rgcms_classes_super_FixtureScript.adoc     |   21 +
 .../_rgcms_classes_super_FixtureScripts.adoc    |   12 +
 .../asciidoc/guides/_rgcms_classes_uievent.adoc |   62 +
 .../_rgcms_classes_uievent_CssClassUiEvent.adoc |   22 +
 .../_rgcms_classes_uievent_IconUiEvent.adoc     |   23 +
 .../_rgcms_classes_uievent_TitleUiEvent.adoc    |   22 +
 .../asciidoc/guides/_rgcms_classes_utility.adoc |   16 +
 .../guides/_rgcms_classes_utility_Enums.adoc    |    8 +
 .../_rgcms_classes_utility_ObjectContracts.adoc |  107 ++
 .../guides/_rgcms_classes_utility_Reasons.adoc  |   31 +
 .../_rgcms_classes_utility_TitleBuffer.adoc     |   13 +
 .../guides/_rgcms_classes_value-types.adoc      |  119 ++
 .../guides/_rgcms_classes_value-types_Blob.adoc |    8 +
 .../guides/_rgcms_classes_value-types_Clob.adoc |    8 +
 .../_rgcms_classes_value-types_Color.adoc       |    8 +
 .../_rgcms_classes_value-types_Money.adoc       |    8 +
 .../_rgcms_classes_value-types_Password.adoc    |    8 +
 .../main/asciidoc/guides/_rgcms_methods.adoc    |   17 +
 .../guides/_rgcms_methods_lifecycle.adoc        |  102 ++
 .../_rgcms_methods_lifecycle_created.adoc       |   17 +
 .../_rgcms_methods_lifecycle_jdo-api.adoc       |   53 +
 .../guides/_rgcms_methods_lifecycle_loaded.adoc |   15 +
 .../_rgcms_methods_lifecycle_persisted.adoc     |   16 +
 .../_rgcms_methods_lifecycle_persisting.adoc    |   16 +
 .../_rgcms_methods_lifecycle_removed.adoc       |   16 +
 .../_rgcms_methods_lifecycle_removing.adoc      |   16 +
 .../_rgcms_methods_lifecycle_updated.adoc       |   18 +
 .../_rgcms_methods_lifecycle_updating.adoc      |   15 +
 .../guides/_rgcms_methods_prefixes.adoc         |  219 +++
 .../guides/_rgcms_methods_prefixes_addTo.adoc   |   37 +
 .../_rgcms_methods_prefixes_autoComplete.adoc   |   96 ++
 .../guides/_rgcms_methods_prefixes_choices.adoc |  143 ++
 .../guides/_rgcms_methods_prefixes_clear.adoc   |   32 +
 .../guides/_rgcms_methods_prefixes_default.adoc |  129 ++
 .../guides/_rgcms_methods_prefixes_disable.adoc |   93 ++
 .../guides/_rgcms_methods_prefixes_get.adoc     |   19 +
 .../guides/_rgcms_methods_prefixes_hide.adoc    |   82 +
 .../guides/_rgcms_methods_prefixes_modify.adoc  |   37 +
 .../_rgcms_methods_prefixes_removeFrom.adoc     |   37 +
 .../guides/_rgcms_methods_prefixes_set.adoc     |   13 +
 .../_rgcms_methods_prefixes_validate.adoc       |  113 ++
 .../_rgcms_methods_prefixes_validateAddTo.adoc  |   45 +
 ...cms_methods_prefixes_validateRemoveFrom.adoc |   45 +
 .../guides/_rgcms_methods_reserved.adoc         |   58 +
 .../_rgcms_methods_reserved_cssClass.adoc       |   46 +
 .../guides/_rgcms_methods_reserved_disable.adoc |  102 ++
 .../guides/_rgcms_methods_reserved_getId.adoc   |   19 +
 .../guides/_rgcms_methods_reserved_hide.adoc    |   39 +
 .../_rgcms_methods_reserved_iconName.adoc       |   36 +
 .../guides/_rgcms_methods_reserved_title.adoc   |   65 +
 .../_rgcms_methods_reserved_validate.adoc       |   27 +
 .../main/asciidoc/guides/_rgcms_schema-aim.adoc |   97 ++
 .../asciidoc/guides/_rgcms_schema-common.adoc   |  103 ++
 .../src/main/asciidoc/guides/_rgcms_schema.adoc |   24 +
 .../src/main/asciidoc/guides/_rgsvc-api.adoc    |  306 ++++
 .../_rgsvc-api_ActionInvocationContext.adoc     |   98 ++
 .../guides/_rgsvc-api_BackgroundService.adoc    |  123 ++
 ...roundService_BackgroundCommandExecution.adoc |   25 +
 .../_rgsvc-api_BackgroundService_Quartz.adoc    |  162 ++
 .../guides/_rgsvc-api_BookmarkService.adoc      |  116 ++
 .../_rgsvc-api_BulkInteractionContext.adoc      |    9 +
 .../guides/_rgsvc-api_ClockService.adoc         |  101 ++
 .../guides/_rgsvc-api_CommandContext.adoc       |  216 +++
 .../guides/_rgsvc-api_DeepLinkService.adoc      |   56 +
 .../_rgsvc-api_DomainObjectContainer.adoc       |   40 +
 ...nObjectContainer_generic-repository-api.adoc |   89 +
 ...-api_DomainObjectContainer_messages-api.adoc |   50 +
 ...mainObjectContainer_object-creation-api.adoc |   49 +
 ...nObjectContainer_object-persistence-api.adoc |   62 +
 ..._DomainObjectContainer_presentation-api.adoc |   46 +
 ...pi_DomainObjectContainer_properties-api.adoc |   54 +
 ...-api_DomainObjectContainer_security-api.adoc |   48 +
 ...-api_DomainObjectContainer_services-api.adoc |   37 +
 ...pi_DomainObjectContainer_validation-api.adoc |   26 +
 .../guides/_rgsvc-api_EmailService.adoc         |   95 ++
 .../guides/_rgsvc-api_EventBusService.adoc      |  405 +++++
 .../_rgsvc-api_FixtureScriptsDefault.adoc       |   50 +
 .../guides/_rgsvc-api_GuiceBeanProvider.adoc    |   91 ++
 .../guides/_rgsvc-api_IsisJdoSupport.adoc       |  276 ++++
 .../asciidoc/guides/_rgsvc-api_JaxbService.adoc |   67 +
 .../guides/_rgsvc-api_MementoService.adoc       |  131 ++
 .../guides/_rgsvc-api_MetamodelService.adoc     |   42 +
 .../guides/_rgsvc-api_QueryResultsCache.adoc    |  126 ++
 .../asciidoc/guides/_rgsvc-api_Scratchpad.adoc  |  128 ++
 .../asciidoc/guides/_rgsvc-api_SudoService.adoc |   69 +
 .../guides/_rgsvc-api_WrapperFactory.adoc       |  162 ++
 .../guides/_rgsvc-api_XmlSnapshotService.adoc   |  220 +++
 .../src/main/asciidoc/guides/_rgsvc-spi.adoc    |  299 ++++
 .../guides/_rgsvc-spi_AuditingService.adoc      |   85 +
 .../_rgsvc-spi_BackgroundCommandService.adoc    |  131 ++
 .../_rgsvc-spi_ClassDiscoveryService.adoc       |   82 +
 .../guides/_rgsvc-spi_CommandService.adoc       |  100 ++
 .../_rgsvc-spi_ContentMappingService.adoc       |  107 ++
 .../_rgsvc-spi_ContentNegotiationService.adoc   |  204 +++
 .../_rgsvc-spi_EmailNotificationService.adoc    |   81 +
 .../_rgsvc-spi_ErrorReportingService.adoc       |  106 ++
 .../guides/_rgsvc-spi_EventSerializer.adoc      |   74 +
 .../guides/_rgsvc-spi_ExceptionRecognizer.adoc  |  119 ++
 ...spi_FixtureScriptsSpecificationProvider.adoc |   76 +
 .../guides/_rgsvc-spi_LocaleProvider.adoc       |   70 +
 .../guides/_rgsvc-spi_PublishingService.adoc    |  192 +++
 .../_rgsvc-spi_RepresentationService.adoc       |  103 ++
 .../guides/_rgsvc-spi_TranslationService.adoc   |   80 +
 .../guides/_rgsvc-spi_TranslationsResolver.adoc |   67 +
 .../guides/_rgsvc-spi_UrlEncodingService.adoc   |   59 +
 .../guides/_rgsvc-spi_UserProfileService.adoc   |   47 +
 .../_rgsvc-spi_UserRegistrationService.adoc     |   98 ++
 .../main/asciidoc/guides/_tg_pet-clinic.adoc    |    4 +-
 .../_tg_stop-scaffolding-start-coding.adoc      |  136 +-
 .../main/asciidoc/guides/_ug_core-concepts.adoc |   22 -
 .../guides/_ug_core-concepts_add-ons.adoc       |   35 -
 .../_ug_core-concepts_building-blocks.adoc      |  267 ---
 ...re-concepts_framework-provided-services.adoc |   54 -
 ..._core-concepts_other-deployment-options.adoc |   81 -
 .../guides/_ug_core-concepts_philosophy.adoc    |   21 -
 .../_ug_core-concepts_philosophy_aop.adoc       |   36 -
 .../_ug_core-concepts_philosophy_dci.adoc       |    9 -
 ...oncepts_philosophy_domain-driven-design.adoc |   78 -
 ...cepts_philosophy_hexagonal-architecture.adoc |   29 -
 ..._core-concepts_philosophy_how-eases-ddd.adoc |   74 -
 ...ncepts_philosophy_naked-objects-pattern.adoc |   60 -
 ...bjects-pattern_object-interface-mapping.adoc |   18 -
 .../guides/_ug_core-concepts_principles.adoc    |   16 -
 ...core-concepts_principles_apache-isis-vs.adoc |   16 -
 ...concepts_principles_apache-isis-vs_cqrs.adoc |   28 -
 ...rinciples_apache-isis-vs_event-sourcing.adoc |   19 -
 ...ts_principles_apache-isis-vs_metawidget.adoc |   16 -
 ...ache-isis-vs_mvc-server-side-frameworks.adoc |   19 -
 ...ug_core-concepts_principles_isis-itself.adoc |   47 -
 .../_ug_core-concepts_principles_your-apps.adoc |   39 -
 .../main/asciidoc/guides/_ug_deployment.adoc    |   19 -
 .../guides/_ug_deployment_cmd-line.adoc         |  113 --
 ...g_deployment_externalized-configuration.adoc |  245 ---
 .../asciidoc/guides/_ug_deployment_gae.adoc     |   50 -
 .../guides/_ug_deployment_jvm-flags.adoc        |   52 -
 .../asciidoc/guides/_ug_deployment_neo4j.adoc   |   59 -
 .../asciidoc/guides/_ug_deployment_tomcat.adoc  |   28 -
 .../src/main/asciidoc/guides/_ug_extending.adoc |   14 -
 .../guides/_ug_extending_programming-model.adoc |   13 -
 ...ding_programming-model_custom-validator.adoc |  107 --
 ..._extending_programming-model_finetuning.adoc |   80 -
 ...rogramming-model_layout-metadata-reader.adoc |   82 -
 .../_ug_extending_restfulobjects-viewer.adoc    |   51 -
 .../guides/_ug_extending_wicket-viewer.adoc     |   25 -
 ...ng_wicket-viewer_custom-bootstrap-theme.adoc |   34 -
 ...ug_extending_wicket-viewer_custom-pages.adoc |   92 --
 ...ng_wicket-viewer_isis-addons-extensions.adoc |   17 -
 ...viewer_login-via-query-args-prototyping.adoc |   49 -
 ...g_wicket-viewer_replacing-page-elements.adoc |  167 --
 .../asciidoc/guides/_ug_getting-started.adoc    |   37 -
 ...ug_getting-started_datanucleus-enhancer.adoc |  107 --
 ..._ug_getting-started_simpleapp-archetype.adoc |  304 ----
 .../asciidoc/guides/_ug_headless-access.adoc    |   27 -
 ...less-access_AbstractIsisSessionTemplate.adoc |   40 -
 ...dless-access_BackgroundCommandExecution.adoc |   45 -
 .../src/main/asciidoc/guides/_ug_how-tos.adoc   |   20 -
 .../guides/_ug_how-tos_business-rules.adoc      |   72 -
 .../guides/_ug_how-tos_class-structure.adoc     |   38 -
 ...w-tos_class-structure_action-parameters.adoc |   26 -
 .../_ug_how-tos_class-structure_actions.adoc    |   19 -
 ...ow-tos_class-structure_class-definition.adoc |   24 -
 ..._ug_how-tos_class-structure_collections.adoc |   26 -
 ...ow-tos_class-structure_ignoring-methods.adoc |   16 -
 ...how-tos_class-structure_inject-services.adoc |   83 -
 ...lass-structure_properties-vs-parameters.adoc |   45 -
 .../_ug_how-tos_class-structure_properties.adoc |  299 ----
 .../guides/_ug_how-tos_contributed-members.adoc |   69 -
 .../main/asciidoc/guides/_ug_how-tos_crud.adoc  |   29 -
 .../guides/_ug_how-tos_derived-members.adoc     |   48 -
 .../guides/_ug_how-tos_domain-services.adoc     |  313 ----
 .../_ug_how-tos_drop-downs-and-defaults.adoc    |   65 -
 .../_ug_how-tos_entity-relationships.adoc       |   15 -
 ...aged-1-to-m-bidirectional-relationships.adoc |   58 -
 .../guides/_ug_how-tos_persisted-title.adoc     |   56 -
 .../asciidoc/guides/_ug_how-tos_ui-hints.adoc   |   15 -
 ...g_how-tos_ui-hints_action-icons-and-css.adoc |   58 -
 .../_ug_how-tos_ui-hints_eager-rendering.adoc   |   58 -
 .../guides/_ug_how-tos_ui-hints_layout.adoc     |    9 -
 ...how-tos_ui-hints_names-and-descriptions.adoc |   47 -
 ...ow-tos_ui-hints_object-titles-and-icons.adoc |   97 --
 .../main/asciidoc/guides/_ug_more-advanced.adoc |   26 -
 .../guides/_ug_more-advanced_bulk-actions.adoc  |    8 -
 .../guides/_ug_more-advanced_decoupling.adoc    |   28 -
 ..._more-advanced_decoupling_contributions.adoc |   23 -
 ..._ug_more-advanced_decoupling_db-schemas.adoc |  141 --
 .../_ug_more-advanced_decoupling_event-bus.adoc |   11 -
 .../_ug_more-advanced_decoupling_mixins.adoc    |  191 ---
 ...ore-advanced_decoupling_pushing-changes.adoc |  140 --
 ...-advanced_decoupling_vetoing-visibility.adoc |   15 -
 .../asciidoc/guides/_ug_more-advanced_i18n.adoc |  378 -----
 .../_ug_more-advanced_mapping-rdbms-views.adoc  |    9 -
 .../guides/_ug_more-advanced_multi-tenancy.adoc |    8 -
 ...ore-advanced_overriding-jdo-annotations.adoc |   55 -
 ..._ug_more-advanced_persistence-lifecycle.adoc |    8 -
 .../guides/_ug_more-advanced_tips-n-tricks.adoc |   15 -
 ...ore-advanced_tips-n-tricks_are-you-sure.adoc |   76 -
 ...ore-advanced_tips-n-tricks_enhance-only.adoc |   17 -
 ...-advanced_tips-n-tricks_per-user-themes.adoc |   85 -
 ...-tricks_render-all-properties-in-tables.adoc |   49 -
 ...tricks_simulating-collections-of-values.adoc |   23 -
 ...g_more-advanced_transactions-and-errors.adoc |   33 -
 .../guides/_ug_more-advanced_view-models.adoc   |   22 -
 .../guides/_ug_restfulobjects-viewer.adoc       |   25 -
 ...objects-viewer_configuration-properties.adoc |   72 -
 ...configuration-properties_honor-ui-hints.adoc |   27 -
 ...erties_simplified-object-representation.adoc |   68 -
 ...uration-properties_suppressing-elements.adoc |   39 -
 .../_ug_restfulobjects-viewer_features.adoc     |   23 -
 ...ug_restfulobjects-viewer_hints-and-tips.adoc |   85 -
 .../src/main/asciidoc/guides/_ug_security.adoc  |   53 -
 .../_ug_security_api-for-applications.adoc      |   63 -
 ...security_configuring-isis-to-use-bypass.adoc |   23 -
 ..._security_configuring-isis-to-use-shiro.adoc |   76 -
 .../guides/_ug_security_shiro-caching.adoc      |   41 -
 .../guides/_ug_security_shiro-ini-realm.adoc    |  133 --
 ...shiro-isis-enhanced-wildcard-permission.adoc |   61 -
 .../_ug_security_shiro-isis-ldap-realm.adoc     |  146 --
 ..._shiro-isisaddons-security-module-realm.adoc |   36 -
 .../guides/_ug_security_shiro-jdbc-realm.adoc   |  113 --
 .../_ug_security_usage-by-isis-viewers.adoc     |  208 ---
 .../src/main/asciidoc/guides/_ug_testing.adoc   |   17 -
 .../main/asciidoc/guides/_ug_testing_aaa.adoc   |  166 --
 .../guides/_ug_testing_bdd-spec-support.adoc    |   22 -
 ...ug_testing_bdd-spec-support_bdd-tooling.adoc |   14 -
 ...g_testing_bdd-spec-support_how-it-works.adoc |   20 -
 ...ug_testing_bdd-spec-support_key-classes.adoc |   59 -
 ...ng_bdd-spec-support_maven-configuration.adoc |   73 -
 ...ing_bdd-spec-support_writing-a-bdd-spec.adoc |  141 --
 .../guides/_ug_testing_fixture-scripts.adoc     |   44 -
 ...g_testing_fixture-scripts_api-and-usage.adoc |  352 ----
 ...ug_testing_fixture-scripts_sudo-service.adoc |   59 -
 .../guides/_ug_testing_integ-test-support.adoc  |   24 -
 ...esting_integ-test-support_bootstrapping.adoc |  260 ---
 ..._integ-test-support_maven-configuration.adoc |   46 -
 ...esting_integ-test-support_typical-usage.adoc |  124 --
 ...ting_integ-test-support_wrapper-factory.adoc |  162 --
 .../guides/_ug_testing_unit-test-support.adoc   |   14 -
 ...esting_unit-test-support_contract-tests.adoc |  171 --
 ...ting_unit-test-support_jmock-extensions.adoc |   59 -
 ...g_unit-test-support_maven-configuration.adoc |   46 -
 ...est-support_soap-fake-server-junit-rule.adoc |  113 --
 .../asciidoc/guides/_ug_troubleshooting.adoc    |   14 -
 .../_ug_troubleshooting_enabling-logging.adoc   |   39 -
 .../main/asciidoc/guides/_ug_wicket-viewer.adoc |   30 -
 ..._wicket-viewer_configuration-properties.adoc |  112 --
 ...guration-properties_abbreviating-titles.adoc |   33 -
 ...ration-properties_showing-theme-chooser.adoc |   43 -
 ...uration-properties_stripped-wicket-tags.adoc |   26 -
 ...n-properties_suppressing-password-reset.adoc |   47 -
 ...tion-properties_suppressing-remember-me.adoc |   35 -
 ...guration-properties_suppressing-sign-up.adoc |   49 -
 .../guides/_ug_wicket-viewer_customisation.adoc |   18 -
 ..._wicket-viewer_customisation_about-page.adoc |  121 --
 ...icket-viewer_customisation_auto-refresh.adoc |   35 -
 ..._wicket-viewer_customisation_brand-logo.adoc |   71 -
 ...er_customisation_cheap-n-cheerful-theme.adoc |   29 -
 ...-viewer_customisation_custom-javascript.adoc |   42 -
 ...cket-viewer_customisation_default-theme.adoc |   29 -
 ...ewer_customisation_tweaking-css-classes.adoc |  107 --
 ..._customisation_using-different-css-file.adoc |   36 -
 ...icket-viewer_customisation_welcome-page.adoc |   42 -
 .../guides/_ug_wicket-viewer_features.adoc      |   26 -
 ...wicket-viewer_features_blob-attachments.adoc |  121 --
 ...wicket-viewer_features_bookmarked-pages.adoc |  108 --
 ...cket-viewer_features_hints-and-copy-url.adoc |   79 -
 ..._ug_wicket-viewer_features_recent-pages.adoc |   53 -
 ...wicket-viewer_features_titles-in-tables.adoc |   76 -
 ...icket-viewer_features_user-registration.adoc |   81 -
 .../guides/_ug_wicket-viewer_isis-addons.adoc   |   33 -
 .../guides/_ug_wicket-viewer_layout.adoc        |   97 --
 .../_ug_wicket-viewer_request-parameters.adoc   |   53 -
 .../main/asciidoc/guides/_ugbtb_deployment.adoc |   19 +
 .../guides/_ugbtb_deployment_cmd-line.adoc      |  113 ++
 ...b_deployment_externalized-configuration.adoc |  245 +++
 .../asciidoc/guides/_ugbtb_deployment_gae.adoc  |   50 +
 .../guides/_ugbtb_deployment_jvm-flags.adoc     |   52 +
 .../guides/_ugbtb_deployment_neo4j.adoc         |   59 +
 .../guides/_ugbtb_deployment_tomcat.adoc        |   28 +
 .../asciidoc/guides/_ugbtb_more-advanced.adoc   |   26 +
 .../guides/_ugbtb_more-advanced_decoupling.adoc |   28 +
 ..._more-advanced_decoupling_contributions.adoc |   23 +
 ...btb_more-advanced_decoupling_db-schemas.adoc |  141 ++
 ...gbtb_more-advanced_decoupling_event-bus.adoc |   11 +
 .../_ugbtb_more-advanced_decoupling_mixins.adoc |  191 +++
 ...ore-advanced_decoupling_pushing-changes.adoc |  140 ++
 ...-advanced_decoupling_vetoing-visibility.adoc |   15 +
 .../_ugbtb_more-advanced_headless-access.adoc   |   27 +
 ...less-access_AbstractIsisSessionTemplate.adoc |   40 +
 ...dless-access_BackgroundCommandExecution.adoc |   45 +
 .../guides/_ugbtb_more-advanced_i18n.adoc       |  378 +++++
 ...ugbtb_more-advanced_mapping-rdbms-views.adoc |    9 +
 .../_ugbtb_more-advanced_multi-tenancy.adoc     |    8 +
 ...ore-advanced_overriding-jdo-annotations.adoc |   64 +
 .../_ugbtb_more-advanced_persisted-title.adoc   |   82 +
 ...placing-default-service-implementations.adoc |   64 +
 ...b_more-advanced_transactions-and-errors.adoc |   33 +
 .../_ugbtb_more-advanced_view-models.adoc       |   19 +
 .../_ugbtb_more-advanced_view-models_jaxb.adoc  |  240 +++
 ...-advanced_view-models_programming-model.adoc |   87 +
 ...btb_more-advanced_view-models_use-cases.adoc |  142 ++
 .../guides/_ugbtb_programming-model.adoc        |   14 +
 ...gbtb_programming-model_custom-validator.adoc |  107 ++
 .../_ugbtb_programming-model_finetuning.adoc    |   80 +
 ...rogramming-model_layout-metadata-reader.adoc |   82 +
 .../main/asciidoc/guides/_ugbtb_web-xml.adoc    |  473 ++++++
 .../asciidoc/guides/_ugfun_core-concepts.adoc   |   22 +
 .../guides/_ugfun_core-concepts_add-ons.adoc    |   35 +
 .../_ugfun_core-concepts_building-blocks.adoc   |  335 ++++
 ...re-concepts_framework-provided-services.adoc |   54 +
 ..._core-concepts_other-deployment-options.adoc |   81 +
 .../guides/_ugfun_core-concepts_philosophy.adoc |   21 +
 .../_ugfun_core-concepts_philosophy_aop.adoc    |   36 +
 .../_ugfun_core-concepts_philosophy_dci.adoc    |    9 +
 ...oncepts_philosophy_domain-driven-design.adoc |   79 +
 ...cepts_philosophy_hexagonal-architecture.adoc |   29 +
 ..._core-concepts_philosophy_how-eases-ddd.adoc |   74 +
 ...ncepts_philosophy_naked-objects-pattern.adoc |   60 +
 ...bjects-pattern_object-interface-mapping.adoc |   18 +
 .../guides/_ugfun_core-concepts_principles.adoc |   16 +
 ...core-concepts_principles_apache-isis-vs.adoc |   16 +
 ...concepts_principles_apache-isis-vs_cqrs.adoc |   28 +
 ...rinciples_apache-isis-vs_event-sourcing.adoc |   19 +
 ...ts_principles_apache-isis-vs_metawidget.adoc |   16 +
 ...ache-isis-vs_mvc-server-side-frameworks.adoc |   19 +
 ...un_core-concepts_principles_isis-itself.adoc |   47 +
 ...gfun_core-concepts_principles_your-apps.adoc |   39 +
 .../src/main/asciidoc/guides/_ugfun_faqs.adoc   |   18 +
 .../guides/_ugfun_faqs_enabling-logging.adoc    |   39 +
 .../guides/_ugfun_faqs_enhance-only.adoc        |   17 +
 ..._ugfun_faqs_i18n-label-in-wicket-viewer.adoc |   16 +
 .../guides/_ugfun_faqs_per-user-themes.adoc     |   85 +
 .../_ugfun_faqs_restful-image-property.adoc     |   20 +
 ...faqs_subtype-entity-not-fully-populated.adoc |   67 +
 .../asciidoc/guides/_ugfun_getting-started.adoc |   37 +
 ...un_getting-started_datanucleus-enhancer.adoc |  107 ++
 ...fun_getting-started_simpleapp-archetype.adoc |  304 ++++
 .../main/asciidoc/guides/_ugfun_how-tos.adoc    |   22 +
 .../guides/_ugfun_how-tos_bulk-actions.adoc     |    8 +
 .../guides/_ugfun_how-tos_business-rules.adoc   |   72 +
 .../guides/_ugfun_how-tos_class-structure.adoc  |   38 +
 ...w-tos_class-structure_action-parameters.adoc |   26 +
 .../_ugfun_how-tos_class-structure_actions.adoc |   19 +
 ...ow-tos_class-structure_class-definition.adoc |   24 +
 ...fun_how-tos_class-structure_collections.adoc |   26 +
 ...ow-tos_class-structure_ignoring-methods.adoc |   16 +
 ...how-tos_class-structure_inject-services.adoc |   83 +
 ...lass-structure_properties-vs-parameters.adoc |   45 +
 ...gfun_how-tos_class-structure_properties.adoc |  299 ++++
 .../_ugfun_how-tos_contributed-members.adoc     |   69 +
 .../asciidoc/guides/_ugfun_how-tos_crud.adoc    |   29 +
 .../guides/_ugfun_how-tos_derived-members.adoc  |   48 +
 .../guides/_ugfun_how-tos_domain-services.adoc  |  313 ++++
 .../_ugfun_how-tos_drop-downs-and-defaults.adoc |   65 +
 .../_ugfun_how-tos_entity-relationships.adoc    |   15 +
 ...aged-1-to-m-bidirectional-relationships.adoc |   59 +
 ...how-tos_render-all-properties-in-tables.adoc |   49 +
 ...ow-tos_simulating-collections-of-values.adoc |   23 +
 .../guides/_ugfun_how-tos_ui-hints.adoc         |   15 +
 ...n_how-tos_ui-hints_action-icons-and-css.adoc |   58 +
 ..._ugfun_how-tos_ui-hints_eager-rendering.adoc |   58 +
 .../guides/_ugfun_how-tos_ui-hints_layout.adoc  |    9 +
 ...how-tos_ui-hints_names-and-descriptions.adoc |   47 +
 ...ow-tos_ui-hints_object-titles-and-icons.adoc |   97 ++
 .../guides/_ugfun_how-tos_ui_are-you-sure.adoc  |   76 +
 .../asciidoc/guides/_ugfun_object-layout.adoc   |   18 +
 .../_ugfun_object-layout_application-menu.adoc  |  171 ++
 .../guides/_ugfun_object-layout_dynamic.adoc    |  113 ++
 .../_ugfun_object-layout_static-vs-dynamic.adoc |   26 +
 .../guides/_ugfun_object-layout_static.adoc     |  159 ++
 .../guides/_ugsec_api-for-applications.adoc     |   63 +
 .../_ugsec_configuring-isis-to-use-bypass.adoc  |   23 +
 .../_ugsec_configuring-isis-to-use-shiro.adoc   |   76 +
 .../asciidoc/guides/_ugsec_shiro-caching.adoc   |   41 +
 .../asciidoc/guides/_ugsec_shiro-ini-realm.adoc |  133 ++
 ...shiro-isis-enhanced-wildcard-permission.adoc |   61 +
 .../guides/_ugsec_shiro-isis-ldap-realm.adoc    |  146 ++
 ..._shiro-isisaddons-security-module-realm.adoc |   36 +
 .../guides/_ugsec_shiro-jdbc-realm.adoc         |  113 ++
 .../guides/_ugsec_usage-by-isis-viewers.adoc    |  208 +++
 .../src/main/asciidoc/guides/_ugtst_aaa.adoc    |  166 ++
 .../guides/_ugtst_bdd-spec-support.adoc         |   22 +
 .../_ugtst_bdd-spec-support_bdd-tooling.adoc    |   14 +
 .../_ugtst_bdd-spec-support_how-it-works.adoc   |   20 +
 .../_ugtst_bdd-spec-support_key-classes.adoc    |   59 +
 ...st_bdd-spec-support_maven-configuration.adoc |   73 +
 ...tst_bdd-spec-support_writing-a-bdd-spec.adoc |  141 ++
 .../asciidoc/guides/_ugtst_fixture-scripts.adoc |   44 +
 .../_ugtst_fixture-scripts_api-and-usage.adoc   |  352 ++++
 .../_ugtst_fixture-scripts_sudo-service.adoc    |   59 +
 .../guides/_ugtst_integ-test-support.adoc       |   24 +
 ..._ugtst_integ-test-support_bootstrapping.adoc |  260 +++
 ..._integ-test-support_maven-configuration.adoc |   46 +
 ..._ugtst_integ-test-support_typical-usage.adoc |  124 ++
 ...gtst_integ-test-support_wrapper-factory.adoc |  162 ++
 .../guides/_ugtst_unit-test-support.adoc        |   14 +
 ..._ugtst_unit-test-support_contract-tests.adoc |  171 ++
 ...gtst_unit-test-support_jmock-extensions.adoc |   59 +
 ...t_unit-test-support_maven-configuration.adoc |   46 +
 ...est-support_soap-fake-server-junit-rule.adoc |  113 ++
 .../asciidoc/guides/_ugvro_architecture.adoc    |   57 +
 .../guides/_ugvro_configuration-properties.adoc |   54 +
 .../asciidoc/guides/_ugvro_hints-and-tips.adoc  |   97 ++
 .../main/asciidoc/guides/_ugvro_ro-spec.adoc    |  201 +++
 .../_ugvro_simplified-representations.adoc      |  368 +++++
 ...epresentations_configuration-properties.adoc |  135 ++
 .../guides/_ugvw_configuration-properties.adoc  |  112 ++
 ...guration-properties_abbreviating-titles.adoc |   33 +
 ...ration-properties_showing-theme-chooser.adoc |   43 +
 ...uration-properties_stripped-wicket-tags.adoc |   26 +
 ...n-properties_suppressing-password-reset.adoc |   47 +
 ...tion-properties_suppressing-remember-me.adoc |   35 +
 ...guration-properties_suppressing-sign-up.adoc |   49 +
 .../asciidoc/guides/_ugvw_customisation.adoc    |   18 +
 .../guides/_ugvw_customisation_about-page.adoc  |  121 ++
 .../_ugvw_customisation_auto-refresh.adoc       |   35 +
 .../guides/_ugvw_customisation_brand-logo.adoc  |   71 +
 ...vw_customisation_cheap-n-cheerful-theme.adoc |   29 +
 .../_ugvw_customisation_custom-javascript.adoc  |   42 +
 .../_ugvw_customisation_default-theme.adoc      |   29 +
 ...ugvw_customisation_tweaking-css-classes.adoc |  107 ++
 ..._customisation_using-different-css-file.adoc |   36 +
 .../_ugvw_customisation_welcome-page.adoc       |   42 +
 .../main/asciidoc/guides/_ugvw_extending.adoc   |   25 +
 .../_ugvw_extending_custom-bootstrap-theme.adoc |   34 +
 .../guides/_ugvw_extending_custom-pages.adoc    |   92 ++
 .../_ugvw_extending_isis-addons-extensions.adoc |   17 +
 ...ending_login-via-query-args-prototyping.adoc |   49 +
 ..._ugvw_extending_replacing-page-elements.adoc |  167 ++
 .../main/asciidoc/guides/_ugvw_features.adoc    |   26 +
 .../guides/_ugvw_features_blob-attachments.adoc |  121 ++
 .../guides/_ugvw_features_bookmarked-pages.adoc |  108 ++
 .../_ugvw_features_hints-and-copy-url.adoc      |   79 +
 .../guides/_ugvw_features_recent-pages.adoc     |   53 +
 .../guides/_ugvw_features_titles-in-tables.adoc |   76 +
 .../_ugvw_features_user-registration.adoc       |   81 +
 .../main/asciidoc/guides/_ugvw_isis-addons.adoc |   33 +
 .../src/main/asciidoc/guides/_ugvw_layout.adoc  |   97 ++
 .../guides/_ugvw_request-parameters.adoc        |   53 +
 .../src/main/asciidoc/guides/cg.adoc            |   30 +-
 .../020-annotation-processor.png                |  Bin 57338 -> 67560 bytes
 ...10-dcevm-list-of-found-jdk-installations.png |  Bin 0 -> 44267 bytes
 .../070-advanced/020-dcevm-once-installed.png   |  Bin 0 -> 44435 bytes
 .../030-dcevm-intellij-project-structure.png    |  Bin 0 -> 62740 bytes
 .../040-dcevm-run-configuration.png             |  Bin 0 -> 47864 bytes
 .../guides/images/maven-plugin/xsd-goal.png     |  Bin 0 -> 46790 bytes
 .../guides/images/maven-plugin/xsd-goal.pptx    |  Bin 0 -> 64740 bytes
 .../service-collaborations.png                  |  Bin 10368 -> 28874 bytes
 .../service-collaborations.pptx                 |  Bin 52460 -> 51472 bytes
 .../ro-spec-resources-and-representations.png   |  Bin 0 -> 139796 bytes
 .../src/main/asciidoc/guides/rg.adoc            |   33 +-
 .../src/main/asciidoc/guides/rgant.adoc         |   96 ++
 .../src/main/asciidoc/guides/rgcfg.adoc         |   62 +
 .../src/main/asciidoc/guides/rgcms.adoc         |   46 +
 .../src/main/asciidoc/guides/rgsvc.adoc         |   40 +
 .../asciidoc/guides/simpleapp-archetype.adoc    |    6 +-
 .../src/main/asciidoc/guides/tg.adoc            |    1 +
 .../src/main/asciidoc/guides/ug.adoc            |   42 +-
 .../src/main/asciidoc/guides/ugbtb.adoc         |   44 +
 .../src/main/asciidoc/guides/ugfun.adoc         |   50 +
 .../src/main/asciidoc/guides/ugsec.adoc         |   85 +
 .../src/main/asciidoc/guides/ugtst.adoc         |   50 +
 .../src/main/asciidoc/guides/ugvro.adoc         |   55 +
 .../src/main/asciidoc/guides/ugvw.adoc          |   55 +
 .../src/main/asciidoc/how-isis-works.adoc       |    2 +-
 .../images/powered-by/commapp/screenshot-1.png  |  Bin 0 -> 670918 bytes
 .../images/powered-by/commapp/screenshot-2.png  |  Bin 0 -> 56933 bytes
 .../asciidoc/images/powered-by/estatio-1.png    |  Bin 261553 -> 0 bytes
 .../images/powered-by/estatio/estatio-1.png     |  Bin 0 -> 261553 bytes
 .../gesconsultor-grc/fig-1-custom-viewer.png    |  Bin 0 -> 1169636 bytes
 .../fig-2-custom-drag-n-drop-interface.png      |  Bin 0 -> 1495279 bytes
 ...fig-3-custom-ui-analyzing-risk-scenarios.png |  Bin 0 -> 2218476 bytes
 .../fig-4-managing-projects.png                 |  Bin 0 -> 995701 bytes
 .../documentation/src/main/asciidoc/index.html  |   19 +-
 .../src/main/asciidoc/isis-in-pictures.adoc     |   44 +-
 .../src/main/asciidoc/migration-notes.adoc      |    3 +
 .../src/main/asciidoc/powered-by.adoc           |   84 +-
 .../src/main/asciidoc/release-notes.adoc        | 1537 +-----------------
 .../asciidoc/resources/templates/.gitignore     |    1 +
 .../templates/asciidoc-templates-idea.xml       |  365 -----
 ...-settings-file-templates-for-apache-isis.jar |  Bin 0 -> 9104 bytes
 .../templates/isis-asciidoc-templates-idea.xml  |  328 ++++
 .../resources/templates/isis-template-idea.xml  |  522 ++++++
 .../resources/templates/isis-templates-idea.xml |  804 ---------
 .../resources/templates/isis-templates2.xml     |  479 ------
 adocs/template/document.html.erb                |   31 +
 core/applib/pom.xml                             |    2 +-
 .../apache/isis/applib/AbstractSubscriber.java  |   14 +-
 .../org/apache/isis/applib/AppManifest.java     |    1 +
 .../isis/applib/DomainObjectContainer.java      |   11 +
 .../applib/annotation/CollectionLayout.java     |   14 +
 .../isis/applib/annotation/DomainObject.java    |   91 ++
 .../applib/annotation/DomainObjectLayout.java   |   38 +-
 .../apache/isis/applib/annotation/Nature.java   |   30 +-
 .../isis/applib/annotation/NatureOfService.java |   22 +-
 .../isis/applib/annotation/Parameter.java       |    2 +-
 .../apache/isis/applib/annotation/Property.java |    4 +
 .../apache/isis/applib/annotation/Title.java    |    2 +-
 .../isis/applib/annotation/ViewModel.java       |   22 +
 .../apache/isis/applib/services/dto/Dto.java    |   21 +
 .../applib/services/dto/Dto_downloadXml.java    |   67 +
 .../applib/services/dto/Dto_downloadXsd.java    |  125 ++
 .../apache/isis/applib/services/dto/Util.java   |   33 +
 .../services/eventbus/AbstractUiEvent.java      |   97 ++
 .../services/eventbus/ActionDomainEvent.java    |   32 +-
 .../eventbus/ActionInteractionEvent.java        |    8 +
 .../eventbus/CollectionDomainEvent.java         |   31 +-
 .../eventbus/CollectionInteractionEvent.java    |    7 +
 .../services/eventbus/CssClassUiEvent.java      |  102 ++
 .../applib/services/eventbus/IconUiEvent.java   |  101 ++
 .../services/eventbus/ObjectCreatedEvent.java   |   30 +
 .../services/eventbus/ObjectLoadedEvent.java    |   32 +
 .../services/eventbus/ObjectPersistedEvent.java |   30 +
 .../eventbus/ObjectPersistingEvent.java         |   30 +
 .../services/eventbus/ObjectRemovingEvent.java  |   30 +
 .../services/eventbus/ObjectUpdatedEvent.java   |   30 +
 .../services/eventbus/ObjectUpdatingEvent.java  |   30 +
 .../services/eventbus/PropertyDomainEvent.java  |   30 +-
 .../eventbus/PropertyInteractionEvent.java      |    5 +
 .../applib/services/eventbus/TitleUiEvent.java  |  129 ++
 .../services/i18n/TranslatableString.java       |    1 +
 .../isis/applib/services/jaxb/JaxbService.java  |   64 +
 .../applib/services/swagger/SwaggerService.java |   72 +
 .../services/swagger/SwaggerServiceMenu.java    |   80 +
 .../isis/applib/services/swagger/Util.java      |   46 +
 .../urlencoding/UrlEncodingService.java         |   29 +
 .../UrlEncodingServiceUsingBaseEncoding.java    |   57 +
 core/integtestsupport/pom.xml                   |    2 +-
 .../IntegrationTestAbstract.java                |   16 +-
 core/log4j/pom.xml                              |    2 +-
 core/maven-plugin/pom.xml                       |    2 +-
 .../isis/tool/mavenplugin/IsisMojoAbstract.java |   24 +-
 .../isis/tool/mavenplugin/IsisMojoValidate.java |   15 +-
 .../isis/tool/mavenplugin/IsisMojoXsd.java      |  155 ++
 .../tool/mavenplugin/MetaModelProcessor.java    |    2 +-
 core/metamodel/pom.xml                          |   13 +-
 .../isis/core/commons/lang/ClassExtensions.java |    7 +-
 .../core/commons/lang/StringExtensions.java     |   12 +-
 .../isis/core/metamodel/facets/Annotations.java |  115 ++
 .../facets/ContributeeMemberFacetFactory.java   |    3 +-
 .../action/ActionAnnotationFacetFactory.java    |   10 +-
 .../ActionDomainEventFacetAbstract.java         |    3 -
 .../CollectionAnnotationFacetFactory.java       |   15 +-
 .../defaultview/DefaultViewFacet.java           |   26 +
 .../defaultview/DefaultViewFacetAbstract.java   |   35 +
 ...tViewFacetForCollectionLayoutAnnotation.java |   41 +
 ...ewFacetOnCollectionFromLayoutProperties.java |   46 +
 .../layout/CollectionLayoutFacetFactory.java    |   11 +
 .../callbacks/CreatedCallbackFacetAbstract.java |   35 +
 .../callbacks/CreatedCallbackFacetFactory.java  |   62 +
 .../CreatedCallbackFacetViaMethod.java          |   65 +
 .../callbacks/CreatedLifecycleEventFacet.java   |   30 +
 ...ycleEventFacetForDomainObjectAnnotation.java |   49 +
 .../object/callbacks/LifecycleEventFacet.java   |   28 +
 .../callbacks/LoadCallbackFacetFactory.java     |   68 +
 .../callbacks/LoadedCallbackFacetAbstract.java  |   37 +
 .../callbacks/LoadedCallbackFacetViaMethod.java |   65 +
 .../callbacks/LoadedLifecycleEventFacet.java    |   30 +
 ...ycleEventFacetForDomainObjectAnnotation.java |   49 +
 .../callbacks/LoadingCallbackFacetAbstract.java |   41 +
 .../LoadingCallbackFacetViaMethod.java          |   69 +
 .../callbacks/PersistCallbackFacetFactory.java  |   78 +
 ...ersistCallbackViaSaveMethodFacetFactory.java |   78 +
 .../PersistedCallbackFacetAbstract.java         |   37 +
 .../PersistedCallbackFacetViaMethod.java        |   65 +
 .../callbacks/PersistedLifecycleEventFacet.java |   30 +
 ...ycleEventFacetForDomainObjectAnnotation.java |   49 +
 .../PersistingCallbackFacetAbstract.java        |   37 +
 .../PersistingCallbackFacetViaMethod.java       |   65 +
 .../PersistingLifecycleEventFacet.java          |   30 +
 ...ycleEventFacetForDomainObjectAnnotation.java |   50 +
 .../callbacks/RemoveCallbackFacetFactory.java   |   78 +
 ...moveCallbackViaDeleteMethodFacetFactory.java |   78 +
 .../object/callbacks/RemovedCallbackFacet.java  |    2 +
 .../callbacks/RemovedCallbackFacetAbstract.java |   39 +
 .../RemovedCallbackFacetViaMethod.java          |   69 +
 .../RemovingCallbackFacetAbstract.java          |   37 +
 .../RemovingCallbackFacetViaMethod.java         |   65 +
 .../callbacks/RemovingLifecycleEventFacet.java  |   30 +
 ...ycleEventFacetForDomainObjectAnnotation.java |   51 +
 .../callbacks/UpdateCallbackFacetFactory.java   |   68 +
 .../callbacks/UpdatedCallbackFacetAbstract.java |   37 +
 .../UpdatedCallbackFacetViaMethod.java          |   65 +
 .../callbacks/UpdatedLifecycleEventFacet.java   |   30 +
 ...ycleEventFacetForDomainObjectAnnotation.java |   51 +
 .../UpdatingCallbackFacetAbstract.java          |   37 +
 .../UpdatingCallbackFacetViaMethod.java         |   69 +
 .../callbacks/UpdatingLifecycleEventFacet.java  |   30 +
 ...ycleEventFacetForDomainObjectAnnotation.java |   51 +
 .../create/CreatedCallbackFacetAbstract.java    |   37 -
 .../create/CreatedCallbackFacetFactory.java     |   62 -
 .../create/CreatedCallbackFacetViaMethod.java   |   65 -
 .../load/LoadCallbackFacetFactory.java          |   68 -
 .../load/LoadedCallbackFacetAbstract.java       |   37 -
 .../load/LoadedCallbackFacetViaMethod.java      |   65 -
 .../load/LoadingCallbackFacetAbstract.java      |   41 -
 .../load/LoadingCallbackFacetViaMethod.java     |   69 -
 .../persist/PersistCallbackFacetFactory.java    |   80 -
 ...ersistCallbackViaSaveMethodFacetFactory.java |   80 -
 .../persist/PersistedCallbackFacetAbstract.java |   37 -
 .../PersistedCallbackFacetViaMethod.java        |   65 -
 .../PersistingCallbackFacetAbstract.java        |   37 -
 .../PersistingCallbackFacetViaMethod.java       |   65 -
 .../remove/RemoveCallbackFacetFactory.java      |   80 -
 ...moveCallbackViaDeleteMethodFacetFactory.java |   80 -
 .../remove/RemovedCallbackFacetAbstract.java    |   37 -
 .../remove/RemovedCallbackFacetViaMethod.java   |   65 -
 .../remove/RemovingCallbackFacetAbstract.java   |   37 -
 .../remove/RemovingCallbackFacetViaMethod.java  |   65 -
 .../update/UpdateCallbackFacetFactory.java      |   68 -
 .../update/UpdatedCallbackFacetAbstract.java    |   37 -
 .../update/UpdatedCallbackFacetViaMethod.java   |   65 -
 .../update/UpdatingCallbackFacetAbstract.java   |   37 -
 .../update/UpdatingCallbackFacetViaMethod.java  |   69 -
 .../DomainObjectAnnotationFacetFactory.java     |  156 ++
 ...bleObjectFacetForDomainObjectAnnotation.java |    7 +-
 ...ectLayoutAnnotationUsingCssClassUiEvent.java |  106 ++
 .../DomainObjectLayoutFacetFactory.java         |   31 +-
 ...nObjectLayoutAnnotationUsingIconUiEvent.java |  103 ++
 ...ObjectLayoutAnnotationUsingTitleUiEvent.java |  119 ++
 .../RemoveSubscriberMethodsFacetFactory.java    |   70 +
 .../facets/object/parseable/ParseableFacet.java |    2 +-
 .../RecreatableObjectFacetAbstract.java         |   48 +-
 ...creatableObjectFacetDeclarativeAbstract.java |  166 --
 ...ectFacetDeclarativeInitializingAbstract.java |  165 ++
 .../RecreatableObjectFacetFactory.java          |   18 +-
 ...acetForRecreatableDomainObjectInterface.java |    6 +-
 ...jectFacetForRecreatableObjectAnnotation.java |    5 +-
 ...bjectFacetForRecreatableObjectInterface.java |    6 +-
 ...atableObjectFacetForViewModelAnnotation.java |   41 +
 ...eObjectFacetForXmlRootElementAnnotation.java |   65 +
 .../annotation/RegExFacetOnTypeAnnotation.java  |    4 +-
 .../RegExFacetOnTypeAnnotationFactory.java      |    3 +-
 .../annotation/TitleAnnotationFacetFactory.java |   32 +-
 .../TitleFacetViaTitleAnnotation.java           |   29 +-
 .../facets/object/viewmodel/ViewModelFacet.java |   49 +
 .../objectvalue/multiline/MultiLineFacet.java   |    4 +-
 .../facets/objectvalue/regex/RegExFacet.java    |    1 +
 .../objectvalue/regex/RegExFacetAbstract.java   |   12 +-
 .../regex/RegExFacetForParameterAnnotation.java |    7 +-
 ...egExFacetFromRegExAnnotationOnParameter.java |    7 +-
 .../PropertyAnnotationFacetFactory.java         |   14 +-
 .../regex/RegExFacetForPropertyAnnotation.java  |    8 +-
 .../RegExFacetForRegExAnnotationOnProperty.java |    7 +-
 .../CollectionLayoutFacetRepr.java              |    1 +
 .../layoutmetadata/DefaultViewFacetRepr.java    |   24 +
 .../json/LayoutMetadataReaderFromJson.java      |   18 +-
 .../metamodel/progmodel/ProgrammingModel.java   |    6 +-
 .../container/DomainObjectContainerDefault.java |   11 +
 .../Persistable_downloadJdoMetadata.java        |   80 +
 .../metamodel/services/jdosupport/Util.java     |   33 +
 .../services/swagger/SwaggerServiceDefault.java |   81 +
 .../services/swagger/internal/Caching.java      |   48 +
 .../swagger/internal/ClassExcluder.java         |   52 +
 .../services/swagger/internal/Generation.java   |  832 ++++++++++
 .../swagger/internal/SwaggerSpecGenerator.java  |   64 +
 .../services/swagger/internal/Tagger.java       |   61 +
 .../services/swagger/internal/Util.java         |  166 ++
 .../swagger/internal/ValuePropertyFactory.java  |  176 ++
 .../specloader/specimpl/ContributeeMember.java  |    2 +-
 .../specimpl/ObjectActionMixedIn.java           |    3 +-
 .../specimpl/ObjectMemberAbstract.java          |    2 +-
 .../specimpl/ObjectSpecificationAbstract.java   |    8 +-
 .../isis/core/metamodel/util/EventUtil.java     |   45 +
 .../dflt/ProgrammingModelFacetsJava5.java       |   26 +-
 .../CreatedCallbackFacetFactoryTest.java        |    4 +-
 .../DeleteCallbackFacetFactoryTest.java         |    6 +-
 .../callback/LoadCallbackFacetFactoryTest.java  |    6 +-
 .../PersistAndSaveCallbackFacetFactoryTest.java |    8 +-
 .../PersistCallbackFacetFactoryTest.java        |    6 +-
 ...RemoveAndDeleteCallbackFacetFactoryTest.java |    8 +-
 .../RemoveCallbackFacetFactoryTest.java         |    6 +-
 .../callback/SaveCallbackFacetFactoryTest.java  |    6 +-
 .../UpdateCallbackFacetFactoryTest.java         |    6 +-
 .../TitleAnnotationFacetFactoryTest.java        |   13 +-
 .../TitleFacetViaTitleAnnotationTest.java       |   27 +-
 .../regex/RegExFacetAnnotationTest.java         |   14 +-
 .../swagger/internal/GenerationTest.java        |   48 +
 .../services/swagger/internal/TaggerTest.java   |   69 +
 core/pom.xml                                    |  147 +-
 core/runtime/pom.xml                            |    7 +-
 .../eventbus/EventBusServiceDefault.java        |    5 +-
 .../i18n/po/TranslationServicePoMenu.java       |   37 +-
 .../services/memento/MementoServiceDefault.java |   38 +-
 .../system/persistence/PersistenceSession.java  |  142 +-
 .../persistence/spi/JdoObjectIdSerializer.java  |    2 +-
 .../jdo/service/RegisterEntities.java           |   10 +
 core/schema/pom.xml                             |    4 +-
 .../jaxb/CatalogingSchemaOutputResolver.java    |   85 +
 .../services/jaxb/JaxbServiceDefault.java       |  142 ++
 .../services/jaxb/StreamResultWithWriter.java   |   45 +
 .../utils/ActionInvocationMementoDtoUtils.java  |   12 +-
 ...odaLocalTimeXMLGregorianCalendarAdapter.java |    4 -
 .../jaxbadapters/PersistentEntityAdapter.java   |   67 +
 core/security-shiro/pom.xml                     |    6 +-
 ...atorOrAuthorizorTest_isVisibleInAnyRole.java |    3 -
 core/security/pom.xml                           |    2 +-
 core/specsupport/pom.xml                        |    2 +-
 core/unittestsupport/pom.xml                    |    2 +-
 core/viewer-restfulobjects-applib/pom.xml       |    2 +-
 .../ActionResultRepresentation.java             |    3 +-
 core/viewer-restfulobjects-rendering/pom.xml    |    2 +-
 .../rendering/RendererContext.java              |   18 +-
 .../rendering/RendererContext2.java             |    2 +-
 .../rendering/RendererContext4.java             |    3 +-
 .../rendering/RendererContext5.java             |    4 +-
 .../rendering/RendererContext6.java             |   33 +
 .../rendering/ReprRendererAbstract.java         |    6 +-
 .../restfulobjects/rendering/Responses.java     |   57 +-
 .../AbstractObjectMemberReprRenderer.java       |    5 +-
 .../domainobjects/ActionResultReprRenderer.java |  107 +-
 .../domainobjects/DomainObjectReprRenderer.java |   39 +-
 .../domainobjects/ListReprRenderer.java         |    8 +-
 .../domainobjects/ObjectActionReprRenderer.java |    9 +-
 .../ObjectAndActionInvocation.java              |   43 +-
 .../domainobjects/ObjectAndCollection2.java     |   39 +
 .../domainobjects/ObjectAndProperty2.java       |   36 +
 .../ObjectCollectionReprRenderer.java           |   29 +-
 .../ObjectPropertyReprRenderer.java             |   20 +-
 .../domainobjects/ScalarValueReprRenderer.java  |    5 +-
 .../AbstractTypeFeatureReprRenderer.java        |    4 +-
 .../domaintypes/DomainTypeReprRenderer.java     |    6 +-
 .../service/RepresentationService.java          |   51 +-
 .../RepresentationServiceContentNegotiator.java |  214 +++
 .../RepresentationServiceForRestfulObjects.java |  252 +--
 .../conneg/ContentNegotiationService.java       |    2 -
 .../ContentNegotiationServiceAbstract.java      |   33 +
 ...NegotiationServiceForRestfulObjectsV1_0.java |  266 +++
 ...ontentNegotiationServiceOrgApacheIsisV1.java |  404 +++++
 .../rendering/LinkFollowSpecsTest_follow.java   |   14 +
 core/viewer-restfulobjects-server/pom.xml       |   13 +-
 .../restfulobjects/server/ResourceContext.java  |   53 +-
 .../server/RestfulObjectsApplication.java       |    6 +
 ...estfulObjectsApplicationExceptionMapper.java |   12 +-
 .../conneg/RestfulObjectsJaxbWriterForXml.java  |   67 +
 .../restfulobjects/server/conneg/Util.java      |   33 +
 .../DomainObjectResourceServerside.java         |   74 +-
 .../server/resources/DomainResourceHelper.java  |   63 +-
 .../DomainServiceResourceServerside.java        |   41 +-
 .../resources/DomainTypeResourceServerside.java |   19 +-
 .../resources/HomePageResourceServerside.java   |    3 +-
 .../server/resources/ResourceAbstract.java      |   21 +-
 .../server/resources/SwaggerSpecResource.java   |  125 ++
 .../resources/UserResourceServerside.java       |    5 +-
 .../resources/VersionResourceServerside.java    |    3 +-
 ...ontextTest_ensureCompatibleAcceptHeader.java |    2 +-
 .../server/ResourceContextTest_getArg.java      |    4 +-
 core/viewer-wicket-applib/pom.xml               |    2 +-
 core/viewer-wicket-impl/pom.xml                 |    2 +-
 .../wicket/WebRequestCycleForIsis.java          |    2 -
 core/viewer-wicket-model/pom.xml                |    2 +-
 .../model/mementos/PageParameterNames.java      |    2 +-
 .../viewer/wicket/model/models/ActionModel.java |    2 -
 .../model/models/EntityCollectionModel.java     |   17 +-
 core/viewer-wicket-ui/pom.xml                   |    2 +-
 .../ActionResultResponseHandlingStrategy.java   |   13 +-
 .../entityactions/AdditionalLinksPanel.java     |   26 +-
 .../entityactions/EntityActionLinkFactory.java  |    4 +-
 .../entityactions/EntityActionUtil.java         |    2 +-
 .../actionmenu/serviceactions/CssMenuItem.java  |    4 +-
 .../ServiceActionLinkFactory.java               |    5 +-
 .../ui/components/actions/ActionPanel.java      |   72 +-
 .../actions/ActionParametersFormPanel.java      |   22 +-
 .../collection/bulk/BulkActionsLinkFactory.java |    5 +-
 .../selector/CollectionSelectorHelper.java      |   75 +-
 .../components/scalars/ScalarPanelAbstract.java |    4 +-
 .../ScalarPanelTextFieldParseableAbstract.java  |    2 +-
 .../StandaloneCollectionPanel.java              |    2 +-
 .../widgets/breadcrumbs/BreadcrumbModel.java    |   99 +-
 .../widgets/breadcrumbs/BreadcrumbPanel.java    |   29 +-
 .../widgets/linkandlabel/ActionLinkFactory.java |    5 +-
 .../linkandlabel/ActionLinkFactoryAbstract.java |    3 +
 .../widgets/themepicker/ThemeChooser.java       |   36 +-
 .../viewer/wicket/ui/pages/PageAbstract.java    |   18 +-
 .../accmngt/AccountManagementPageAbstract.java  |    9 +-
 .../wicket/ui/pages/entity/EntityPage.java      |   21 -
 .../wicket/ui/pages/mmverror/MmvErrorPage.java  |    5 +-
 .../viewer/wicket/ui/panels/PanelAbstract.java  |   40 +-
 core/webserver/pom.xml                          |    2 +-
 core/wrapper/pom.xml                            |    6 +-
 example/application/simpleapp/app/pom.xml       |    2 +-
 ...ppAppManifestWithFixturesBypassSecurity.java |   35 +
 example/application/simpleapp/dom/pom.xml       |    2 +-
 .../java/domainapp/dom/simple/SimpleObject.java |   10 +-
 .../dom/simple/SimpleObject.layout.json         |    2 +-
 example/application/simpleapp/fixture/pom.xml   |    2 +-
 .../application/simpleapp/integtests/pom.xml    |  132 +-
 example/application/simpleapp/pom.xml           |    6 +-
 example/application/simpleapp/webapp/pom.xml    |    3 +-
 .../src/main/webapp/WEB-INF/isis.properties     |   20 +
 .../webapp/src/main/webapp/WEB-INF/web.xml      |   17 +-
 .../webapp/src/main/webapp/about/index.html     |   18 +-
 .../src/main/webapp/swagger-ui/index.html       |  122 ++
 example/archetype/simpleapp/pom.xml             |    6 +-
 .../dom/simple/SimpleObject.layout.json         |    2 +-
 .../main/resources/archetype-resources/pom.xml  |    2 +-
 .../projects/basic/archetype.properties         |    2 +-
 1298 files changed, 47378 insertions(+), 36042 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/803fbc14/core/pom.xml
----------------------------------------------------------------------

http://git-wip-us.apache.org/repos/asf/isis/blob/803fbc14/core/viewer-wicket-applib/pom.xml
----------------------------------------------------------------------

http://git-wip-us.apache.org/repos/asf/isis/blob/803fbc14/core/viewer-wicket-model/pom.xml
----------------------------------------------------------------------

http://git-wip-us.apache.org/repos/asf/isis/blob/803fbc14/core/viewer-wicket-ui/src/main/java/org/apache/isis/viewer/wicket/ui/pages/mmverror/MmvErrorPage.java
----------------------------------------------------------------------

http://git-wip-us.apache.org/repos/asf/isis/blob/803fbc14/core/viewer-wicket-ui/src/main/java/org/apache/isis/viewer/wicket/ui/panels/PanelAbstract.java
----------------------------------------------------------------------


[39/52] [abbrv] isis git commit: ISIS-1237: factoring out helper methods. Also changing order of select drop-down in swagger-ui html, deleting commented out code.

Posted by mg...@apache.org.
ISIS-1237: factoring out helper methods.  Also changing order of select drop-down in swagger-ui html, deleting commented out code.


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/f9a0b43a
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/f9a0b43a
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/f9a0b43a

Branch: refs/heads/ISIS-1224-select2-v4
Commit: f9a0b43af8ee1d43498f787ef0bc40deb48e22fc
Parents: 1b202fe
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Wed Dec 9 18:56:57 2015 +0000
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Wed Dec 9 18:56:57 2015 +0000

----------------------------------------------------------------------
 .../swagger/internal/SwaggerSpecGenerator.java  | 494 +++++++++++--------
 .../webapp/src/main/webapp/api-docs/index.html  |  13 +-
 2 files changed, 279 insertions(+), 228 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/f9a0b43a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGenerator.java
----------------------------------------------------------------------
diff --git a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGenerator.java b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGenerator.java
index fb40928..07673d3 100644
--- a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGenerator.java
+++ b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGenerator.java
@@ -70,32 +70,91 @@ public class SwaggerSpecGenerator {
         swagger.basePath("/restful");
         swagger.info(new Info()
                         .version("1.0.0")
-                        .title("Restful Objects"))
-                .path("/",
-                        new Path()
-                            .get(new Operation()
-                                    .description(roSpec("5.1"))
-                                    .produces("application/json")
-                                    .produces("application/json;profile=urn:org.restfulobjects:repr-types/home-page")
-                                    .response(200,
-                                            newResponse(Caching.NON_EXPIRING)
-                                            .description("OK")
-                                            .schema(new RefProperty("#/definitions/home-page"))
-                                    )))
+                        .title("Restful Objects"));
+
+        appendBoilerplate(swagger);
+        appendLinkDefinitions(swagger);
+
+        final Collection<ObjectSpecification> allSpecs = specificationLoader.allSpecifications();
+        for (ObjectSpecification serviceSpec : allSpecs) {
+            final DomainServiceFacet domainServiceFacet = serviceSpec.getFacet(DomainServiceFacet.class);
+            if (domainServiceFacet == null) {
+                continue;
+            }
+            if (!isVisible(visibility, domainServiceFacet)) {
+                continue;
+            }
+
+            List<ActionType> actionTypes = actionTypesFor(visibility);
+            List<ObjectAction> serviceActions = serviceSpec.getObjectActions(
+                    actionTypes, Contributed.EXCLUDED, Filters.<ObjectAction>any());
+            if(serviceActions.isEmpty()) {
+                continue;
+            }
+
+            final String serviceId = serviceIdFor(serviceSpec);
+
+            final ObjectProperty serviceMembers = appendServicePath(swagger, serviceId);
+
+            for (final ObjectAction serviceAction : serviceActions) {
+                appendActionTo(serviceMembers, serviceAction);
+
+                if(false) {
+                    appendPromptPaths(swagger, serviceAction);
+                }
+
+                appendInvokePath(swagger, serviceAction);
+            }
+        }
+
+        switch (format) {
+            case JSON:
+                return Json.pretty(swagger);
+            case YAML:
+                try {
+                    return Yaml.pretty().writeValueAsString(swagger);
+                } catch (JsonProcessingException e) {
+                    throw new RuntimeException(e);
+                }
+            default:
+                throw new IllegalArgumentException("Unrecognized format: " + format);
+        }
+    }
+
+    void appendBoilerplate(final Swagger swagger) {
+        appendBoilerplatePaths(swagger);
+        appendBoilerplateDefinitions(swagger);
+    }
+
+    void appendBoilerplatePaths(final Swagger swagger) {
+        swagger.path("/",
+                new Path()
+                        .get(new Operation()
+                                .tag("boilerplate")
+                                .description(roSpec("5.1"))
+                                .produces("application/json")
+                                .produces("application/json;profile=urn:org.restfulobjects:repr-types/home-page")
+                                .response(200,
+                                        newResponse(Caching.NON_EXPIRING)
+                                                .description("OK")
+                                                .schema(new RefProperty("#/definitions/home-page"))
+                                )))
                 .path("/user",
                         new Path()
-                            .get(new Operation()
-                                    .description(roSpec("6.1"))
-                                    .produces("application/json")
-                                    .produces("application/json;profile=urn:org.restfulobjects:repr-types/user")
-                                    .response(200,
-                                            newResponse(Caching.USER_INFO)
-                                            .description("OK")
-                                            .schema(new RefProperty("#/definitions/user"))
-                                    )))
+                                .get(new Operation()
+                                        .tag("boilerplate")
+                                        .description(roSpec("6.1"))
+                                        .produces("application/json")
+                                        .produces("application/json;profile=urn:org.restfulobjects:repr-types/user")
+                                        .response(200,
+                                                newResponse(Caching.USER_INFO)
+                                                        .description("OK")
+                                                        .schema(new RefProperty("#/definitions/user"))
+                                        )))
                 .path("/services",
                         new Path()
                                 .get(new Operation()
+                                        .tag("boilerplate")
                                         .description(roSpec("7.1"))
                                         .produces("application/json")
                                         .produces("application/json;profile=urn:org.restfulobjects:repr-types/services")
@@ -107,50 +166,56 @@ public class SwaggerSpecGenerator {
 
                 .path("/version",
                         new Path()
-                            .get(new Operation()
-                                    .description(roSpec("8.1"))
-                                    .produces("application/json")
-                                    .produces("application/json;profile=urn:org.restfulobjects:repr-types/version")
-                                    .response(200,
-                                            newResponse(Caching.NON_EXPIRING)
-                                            .description("OK")
-                                            .schema(new RefProperty("#/definitions/version"))
-                                    )));
+                                .get(new Operation()
+                                        .tag("boilerplate")
+                                        .description(roSpec("8.1"))
+                                        .produces("application/json")
+                                        .produces("application/json;profile=urn:org.restfulobjects:repr-types/version")
+                                        .response(200,
+                                                newResponse(Caching.NON_EXPIRING)
+                                                        .description("OK")
+                                                        .schema(new RefProperty("#/definitions/version"))
+                                        )));
+    }
 
+    void appendBoilerplateDefinitions(final Swagger swagger) {
         swagger.addDefinition("home-page",
                 newModel(roSpec("5.2")));
 
         swagger.addDefinition("user",
                 newModel(roSpec("6.2"))
-                    .property("userName", stringProperty())
-                    .property("roles", arrayOfStrings())
-                    .property("links", arrayOfLinksGetOnly())
-                    .required("userName")
-                    .required("roles")
-                );
+                        .property("userName", stringProperty())
+                        .property("roles", arrayOfStrings())
+                        .property("links", arrayOfLinksGetOnly())
+                        .required("userName")
+                        .required("roles")
+        );
 
         swagger.addDefinition("services",
                 newModel(roSpec("7.2"))
-                    .property("value", arrayOfLinksGetOnly())
-                    .required("userName")
-                    .required("roles")
-                );
+                        .property("value", arrayOfLinksGetOnly())
+                        .required("userName")
+                        .required("roles")
+        );
 
         swagger.addDefinition("version",
                 newModel(roSpec("8.2"))
-                    .property("specVersion", stringProperty())
-                    .property("implVersion", stringProperty())
-                    .property("optionalCapabilities",
-                            new ObjectProperty()
-                                .property("blobsClobs", stringProperty())
-                                .property("deleteObjects", stringProperty())
-                                .property("domainModel", stringProperty())
-                                .property("validateOnly", stringProperty())
-                                .property("protoPersistentObjects", stringProperty())
-                            )
-                    .required("userName")
-                    .required("roles")
-                );
+                        .property("specVersion", stringProperty())
+                        .property("implVersion", stringProperty())
+                        .property("optionalCapabilities",
+                                new ObjectProperty()
+                                        .property("blobsClobs", stringProperty())
+                                        .property("deleteObjects", stringProperty())
+                                        .property("domainModel", stringProperty())
+                                        .property("validateOnly", stringProperty())
+                                        .property("protoPersistentObjects", stringProperty())
+                        )
+                        .required("userName")
+                        .required("roles")
+        );
+    }
+
+    void appendLinkDefinitions(final Swagger swagger) {
 
         swagger.addDefinition("link",
                 new ModelImpl()
@@ -178,195 +243,192 @@ public class SwaggerSpecGenerator {
                     .required("href")
                     .required("method")
         );
+    }
 
+    void appendActionTo(final ObjectProperty serviceMembers, final ObjectAction serviceAction) {
+        String serviceActionId = serviceAction.getId();
+
+        // within the services representation itself
+        serviceMembers.property(serviceActionId,
+                new ObjectProperty()
+                        .property("id", stringPropertyEnum(serviceActionId))
+                        .property("memberType", stringPropertyEnum("action"))
+                        .property("links",
+                                new ObjectProperty()
+                                        .property("rel", stringPropertyEnum( String.format(
+                                                "urn:org.restfulobjects:rels/details;action=%s", serviceActionId)))
+                                        .property("href", stringPropertyEnum(String.format(
+                                                "actions/%s", serviceActionId))))
+                        .property("method", stringPropertyEnum("GET"))
+                        .property("type", stringPropertyEnum(
+                                "application/json;profile=urn:org.restfulobjects:repr-types/object-action"))
+        );
+    }
 
-        final Collection<ObjectSpecification> allSpecs = specificationLoader.allSpecifications();
-        for (ObjectSpecification serviceSpec : allSpecs) {
-            final DomainServiceFacet domainServiceFacet = serviceSpec.getFacet(DomainServiceFacet.class);
-            if (domainServiceFacet == null) {
-                continue;
-            }
-            if (!isVisible(visibility, domainServiceFacet)) {
-                continue;
-            }
-
-            List<ObjectAction> serviceActions = serviceSpec
-                    .getObjectActions(actionTypesFor(visibility), Contributed.EXCLUDED, Filters.<ObjectAction>any());
-            if(serviceActions.isEmpty()) {
-                continue;
-            }
+    ObjectProperty appendServicePath(
+            final Swagger swagger,
+            final String serviceId) {
 
-            String serviceId = serviceIdFor(serviceSpec);
-            final String serviceDefinitionId = "service-" + serviceId;
+        final String serviceDefinitionId = "service-" + serviceId;
+        final String servicePathStr = "/services/" + serviceId;
 
-            final Path servicePath = new Path();
-            final String servicePathStr = "/services/" + serviceId;
-            swagger.path(servicePathStr, servicePath);
+        final Path servicePath = new Path();
+        swagger.path(servicePathStr, servicePath);
 
-            servicePath.get(
-                    new Operation()
+        servicePath.get(
+                new Operation()
+                        .tag(serviceId)
                         .description(roSpec("15.1"))
                         .produces("application/json")
                         .produces("application/json;profile=urn:org.restfulobjects:repr-types/object")
                         .response(200,
                                 newResponse(Caching.TRANSACTIONAL)
-                                    .description("OK")
-                                    .schema(new RefProperty("#/definitions/"
-                                            + serviceDefinitionId)))
-            );
+                                        .description("OK")
+                                        .schema(new RefProperty("#/definitions/"
+                                                + serviceDefinitionId)))
+        );
 
-            final ObjectProperty serviceMembers = new ObjectProperty();
-            ModelImpl serviceRepr =
-                    newModel(roSpec("15.1.2") + ": representation of " + serviceId)
-                    .property("title", stringProperty())
-                    .property("serviceId", stringProperty()._default(serviceId))
-                    .property("members", serviceMembers);
+        final ObjectProperty serviceMembers = new ObjectProperty();
+        ModelImpl serviceRepr =
+                newModel(roSpec("15.1.2") + ": representation of " + serviceId)
+                        .property("title", stringProperty())
+                        .property("serviceId", stringProperty()._default(serviceId))
+                        .property("members", serviceMembers);
 
-            swagger.addDefinition(serviceDefinitionId, serviceRepr);
+        swagger.addDefinition(serviceDefinitionId, serviceRepr);
+        return serviceMembers;
+    }
 
-            for (final ObjectAction serviceAction : serviceActions) {
-                String serviceActionId = serviceAction.getId();
-
-                // within the services representation itself
-                final String serviceActionPromptPathRelStr = "actions/" + serviceActionId;
-                serviceMembers.property(serviceActionId,
-                        new ObjectProperty()
-                            .property("id", stringPropertyEnum(serviceActionId))
-                            .property("memberType", stringPropertyEnum("action"))
-                            .property("links",
-                                    new ObjectProperty()
-                                        .property("rel", stringPropertyEnum("urn:org.restfulobjects:rels/details;action=" + serviceActionId + ""))
-                                        .property("href", stringPropertyEnum(serviceActionPromptPathRelStr)))
-                            .property("method", stringPropertyEnum("GET"))
-                            .property("type", stringPropertyEnum("application/json;profile=urn:org.restfulobjects:repr-types/object-action"))
-                );
+    void appendPromptPaths(
+            final Swagger swagger,
+            final ObjectAction serviceAction) {
+
+        final ObjectSpecification serviceSpec = serviceAction.getOnType();
+        final String serviceId = serviceIdFor(serviceSpec);
+        final String servicePathStr = "/services/" + serviceId;
+        final String serviceActionId = serviceAction.getId();
+        final String serviceActionPromptPathRelStr = "actions/" + serviceActionId;
+
+        final ObjectProperty actionParametersRepr = new ObjectProperty();
+        swagger.path(servicePathStr + "/" + serviceActionPromptPathRelStr,
+                new Path()
+                        .get(
+                                new Operation()
+                                        .tag(serviceId)
+                                        .description(roSpec("18.1") + ": (prompt) resource for " + serviceId + "#" + serviceActionId)
+                                        .produces("application/json")
+                                        .produces("application/json;profile=urn:org.restfulobjects:repr-types/object-action")
+                                        .response(200,
+                                                new Response()
+                                                        .description(roSpec("18.2") + ": (prompt) representation of " + serviceId + "#" + serviceActionId)
+                                                        .schema(new ObjectProperty()
+                                                                .property("id",
+                                                                        stringPropertyEnum(serviceActionId))
+                                                                .property("memberType",
+                                                                        stringPropertyEnum("action"))
+                                                                .property("links", arrayOfLinksGetOnly())
+                                                                .property("parameters", actionParametersRepr)
+                                                        ))));
+        final List<ObjectActionParameter> parameters = serviceAction.getParameters();
+
+        int i = 0;
+        for (final ObjectActionParameter parameter : parameters) {
+            final String parameterId = parameter.getId();
+            actionParametersRepr.property(parameterId,
+                    new ObjectProperty()
+                        .property("num", new IntegerProperty()._default(i++))
+                        .property("id", stringPropertyEnum(parameterId))
+                        .property("name", stringPropertyEnum(parameter.getName()))
+                        .property("description", stringPropertyEnum(parameter.getDescription()))
+            );
+        }
+    }
 
-                // and for the service action's own resources (prompt and invoke)
-                final ObjectProperty actionParametersRepr = new ObjectProperty();
-                swagger.path(servicePathStr + "/" + serviceActionPromptPathRelStr,
-                        new Path()
-                                .get(
-                                        new Operation()
-                                                .description(roSpec("18.1") + ": (prompt) resource for " + serviceId + "#" + serviceActionId)
-                                                .produces("application/json")
-                                                .produces("application/json;profile=urn:org.restfulobjects:repr-types/object-action")
-                                                .response(200,
-                                                        new Response()
-                                                                .description(roSpec("18.2") + ": (prompt) representation of " + serviceId + "#" + serviceActionId)
-                                                                .schema(new ObjectProperty()
-                                                                        .property("id",
-                                                                                stringPropertyEnum(serviceActionId))
-                                                                        .property("memberType",
-                                                                                stringPropertyEnum("action"))
-                                                                        .property("links", arrayOfLinksGetOnly())
-                                                                        .property("parameters", actionParametersRepr)
-                                                                ))));
-                final List<ObjectActionParameter> parameters = serviceAction.getParameters();
-
-                int i = 0;
-                for (final ObjectActionParameter parameter : parameters) {
-                    final String parameterId = parameter.getId();
-                    actionParametersRepr.property(parameterId,
-                            new ObjectProperty()
-                                .property("num", new IntegerProperty()._default(i++))
-                                .property("id", stringPropertyEnum(parameterId))
-                                .property("name", stringPropertyEnum(parameter.getName()))
-                                .property("description", stringPropertyEnum(parameter.getDescription()))
-                    );
-                }
+    void appendInvokePath(
+            final Swagger swagger,
+            final ObjectAction serviceAction) {
 
-                // invoke path
-                final Path serviceActionInvokePath = new Path();
-                swagger.path( servicePathStr + "/" + serviceActionPromptPathRelStr + "/invoke", serviceActionInvokePath);
-
-                final Operation invokeOperation =
-                        new Operation()
-                            .description(roSpec("19.1") + ": (invoke) resource of " + serviceId + "#" + serviceActionId)
-                            .produces("application/json")
-                            .produces("application/json;profile=urn:org.restfulobjects:repr-types/action-result")
-                            .produces("application/json;profile=urn:org.apache.isis/v1")
-                            .produces("application/json;profile=urn:org.apache.isis/v1;suppress=true");
-
-                final ActionSemantics.Of semantics = serviceAction.getSemantics();
-                if(semantics.isSafeInNature()) {
-                    serviceActionInvokePath.get(invokeOperation);
-
-                    for (final ObjectActionParameter parameter : parameters) {
-                        invokeOperation
-                                .parameter(
-                                        new QueryParameter()
-                                                .name(parameter.getId())
-                                                .description(roSpec("2.9.1") + (!Strings.isNullOrEmpty(parameter.getDescription())? (": " + parameter.getDescription()) : ""))
-                                                .required(false)
-                                                .type("string")
-                                );
-                    }
-                    if(!parameters.isEmpty()) {
-                        invokeOperation.parameter(new QueryParameter()
-                                .name("x-isis-querystring")
-                                .description(roSpec("2.10") + ": all (formal) arguments as base64 encoded string")
-                                .required(false)
-                                .type("string"));
-                    }
-
-                } else {
-                    if (semantics.isIdempotentInNature()) {
-                        serviceActionInvokePath.put(invokeOperation);
-                    } else {
-                        serviceActionInvokePath.post(invokeOperation);
-                    }
-
-                    final ModelImpl bodyParam =
-                            new ModelImpl()
-                                .type("object");
-                    for (final ObjectActionParameter parameter : parameters) {
-
-                        final Property valueProperty;
-                        // TODO: need to switch on parameter's type and create appopriate impl of valueProperty
-                        // if(parameter.getSpecification().isValue()) ...
-                        valueProperty = stringProperty();
-
-                        bodyParam
-                                .property(parameter.getId(),
-                                        new ObjectProperty()
-                                                .property("value", valueProperty)
-                                );
-                    }
-
-                    invokeOperation
-                            .consumes("application/json")
-                            .parameter(
-                                    new BodyParameter()
-                                            .name("body")
-                                            .schema(bodyParam));
+        final ObjectSpecification serviceSpec = serviceAction.getOnType();
+        final String serviceId = serviceIdFor(serviceSpec);
+        final String serviceActionId = serviceAction.getId();
 
-                }
+        final List<ObjectActionParameter> parameters = serviceAction.getParameters();
+        final Path serviceActionInvokePath = new Path();
+        swagger.path(String.format("/services/%s/actions/%s/invoke", serviceId, serviceActionId), serviceActionInvokePath);
 
+        final Operation invokeOperation =
+                new Operation()
+                        .tag(serviceId)
+                        .description(roSpec("19.1") + ": (invoke) resource of " + serviceId + "#" + serviceActionId)
+                        .produces("application/json")
+                        .produces("application/json;profile=urn:org.restfulobjects:repr-types/action-result")
+                        .produces("application/json;profile=urn:org.apache.isis/v1")
+                        .produces("application/json;profile=urn:org.apache.isis/v1;suppress=true");
+
+        final ActionSemantics.Of semantics = serviceAction.getSemantics();
+        if(semantics.isSafeInNature()) {
+            serviceActionInvokePath.get(invokeOperation);
 
+            for (final ObjectActionParameter parameter : parameters) {
                 invokeOperation
-                        .response(
-                                200, new Response()
-                                        .description(roSpecForResponseOf(serviceAction) + ": (invoke) representation of " + serviceId + "#" + serviceActionId)
-                                    .schema(new ObjectProperty())
+                        .parameter(
+                                new QueryParameter()
+                                        .name(parameter.getId())
+                                        .description(roSpec("2.9.1") + (!Strings.isNullOrEmpty(parameter.getDescription())? (": " + parameter.getDescription()) : ""))
+                                        .required(false)
+                                        .type("string")
                         );
             }
+            if(!parameters.isEmpty()) {
+                invokeOperation.parameter(new QueryParameter()
+                        .name("x-isis-querystring")
+                        .description(roSpec("2.10") + ": all (formal) arguments as base64 encoded string")
+                        .required(false)
+                        .type("string"));
+            }
 
-        }
+        } else {
+            if (semantics.isIdempotentInNature()) {
+                serviceActionInvokePath.put(invokeOperation);
+            } else {
+                serviceActionInvokePath.post(invokeOperation);
+            }
+
+            final ModelImpl bodyParam =
+                    new ModelImpl()
+                            .type("object");
+            for (final ObjectActionParameter parameter : parameters) {
+
+                final Property valueProperty;
+                // TODO: need to switch on parameter's type and create appopriate impl of valueProperty
+                // if(parameter.getSpecification().isValue()) ...
+                valueProperty = stringProperty();
+
+                bodyParam
+                        .property(parameter.getId(),
+                                new ObjectProperty()
+                                        .property("value", valueProperty)
+                        );
+            }
+
+            invokeOperation
+                    .consumes("application/json")
+                    .parameter(
+                            new BodyParameter()
+                                    .name("body")
+                                    .schema(bodyParam));
 
-        switch (format) {
-            case JSON:
-                return Json.pretty(swagger);
-            case YAML:
-                try {
-                    return Yaml.pretty().writeValueAsString(swagger);
-                } catch (JsonProcessingException e) {
-                    throw new RuntimeException(e);
-                }
-            default:
-                throw new IllegalArgumentException("Unrecognized format: " + format);
         }
+
+        invokeOperation
+                .response(
+                        200, new Response()
+                                .description(roSpecForResponseOf(serviceAction) + ": (invoke) representation of " + serviceId + "#" + serviceActionId)
+                                .schema(new ObjectProperty())
+                );
     }
 
+
     private String roSpecForResponseOf(final ObjectAction action) {
         final ActionSemantics.Of semantics = action.getSemantics();
         switch (semantics) {

http://git-wip-us.apache.org/repos/asf/isis/blob/f9a0b43a/example/application/simpleapp/webapp/src/main/webapp/api-docs/index.html
----------------------------------------------------------------------
diff --git a/example/application/simpleapp/webapp/src/main/webapp/api-docs/index.html b/example/application/simpleapp/webapp/src/main/webapp/api-docs/index.html
index d7e3f47..7ecbcb1 100644
--- a/example/application/simpleapp/webapp/src/main/webapp/api-docs/index.html
+++ b/example/application/simpleapp/webapp/src/main/webapp/api-docs/index.html
@@ -30,14 +30,6 @@
 
     <script type="text/javascript">
     $(function () {
-      /*
-      var url = window.location.search.match(/url=([^&]+)/);
-      if (url && url.length > 1) {
-        url = decodeURIComponent(url[1]);
-      } else {
-        url = "/restful/swagger/private"
-      }
-      */
       var url = document.getElementById("input_baseUrl").selectedOptions[0].value;
 
       // Pre load translate...
@@ -113,13 +105,10 @@
         <form id='api_selector'>
             <div class='input'>
                 <select id="input_baseUrl" name="baseUrl">
-                    <option id="public" label="public" value="/restful/swagger/public"/>
                     <option id="private" label="private" value="/restful/swagger/private"/>
+                    <option id="public" label="public" value="/restful/swagger/public"/>
                     <option id="prototyping" label="prototyping" value="/restful/swagger/prototyping"/>
                 </select>
-<!--
-                <input placeholder="http://example.com/api" id="input_baseUrl" name="baseUrl" type="text" value="/restful/swagger/public">
--->
             </div>
             <div class='input' style="display:none;"><input placeholder="api_key" id="input_apiKey" name="apiKey" type="text"/></div>
             <div class='input'><a id="explore" href="#" data-sw-translate>Explore</a></div>


[09/52] [abbrv] isis git commit: ISIS-1243: renamed rg.adoc to rgcms.adoc

Posted by mg...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/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
deleted file mode 100644
index ecb5988..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_jdo-api.adoc
+++ /dev/null
@@ -1,53 +0,0 @@
-[[_rg_methods_lifecycle_jdo-api]]
-= Using the JDO API
-: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/
-
-
-
-As an alternative to relying on Apache Isis to call lifecycle callback methods, you could instead use the JDO link:http://www.datanucleus.org/products/datanucleus/jdo/lifecycle_callbacks.html[lifecycle listener] API directly.
-
-[NOTE]
-====
-We may decide to deprecate the Apache Isis callbacks in the future because they merely duplicate this functionality already available in JDO.
-====
-
-You can gain access to the relevant JDO API using the xref:rgsvc.adoc#_rgsvc-api_IsisJdoSupport[`IsisJdoSupport`] domain service.
-
-For example:
-
-[source,java]
-----
-@RequestScoped                                                   // <1>
-@DomainService(nature=NatureOfService.DOMAIN)
-public class ObjectChangedListenerService
-        implements javax.jdo.listener.StoreLifecycleListener {   // <2>
-    @Programmatic
-    @PostConstruct
-    public void init() {
-        getPmFactory().addInstanceLifecycleListener(this);
-    }
-    @Programmatic
-    @PreDestroy
-    public void tidyUp() {
-        getPmFactory().removeInstanceLifecycleListener(this);
-    }
-    private PersistenceManager getPersistenceManager() {
-        return jdoSupport.getPersistenceManager();               // <3>
-    }
-    @Programmatic
-    public void preStore (InstanceLifecycleEvent event) { ... }
-    @Programmatic
-    public void postStore (InstanceLifecycleEvent event) { ... }
-    @Inject
-    IsisJdoSupport jdoSupport;
-}
-----
-<1> must be `@RequestScoped` because we register on the `PersistenceManager`, which is different for each request.
-<2> implement whichever callback lifecycle listeners are of interest
-<3> use the injected xref:rgsvc.adoc#_rgsvc-api_IsisJdoSupport[`IsisJdoSupport`] service to obtain the `PersistenceManager`.
-
-Note that it isn't possible to register on the `PersistenceManagerFactory` because listeners cannot be attached once a persistence session has been created (which it will have been when the service's `@PostConstruct` method is called).
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_manpage-created.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_manpage-created.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_manpage-created.adoc
deleted file mode 100644
index b3cfe6d..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_manpage-created.adoc
+++ /dev/null
@@ -1,17 +0,0 @@
-[[_rg_methods_reserved_manpage-created]]
-= `created()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-The `created()` lifecycle callback method is called when an object has just been created using xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer[`newTransientInstance()`]
-
-
-[TIP]
-====
-Alternatively, consider using a xref:rgsvc.adoc#_rgsvc-api_EventBusService[event bus] xref:rg.adoc#_rg_classes_super_manpage-AbstractSubscriber[subscriber] on the xref:rg.adoc#_rg_classes_lifecycleevent_manpage-ObjectCreatedEvent[`ObjectCreatedEvent`].
-====
-
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_manpage-loaded.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_manpage-loaded.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_manpage-loaded.adoc
deleted file mode 100644
index 381bbfe..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_manpage-loaded.adoc
+++ /dev/null
@@ -1,15 +0,0 @@
-[[_rg_methods_reserved_manpage-loaded]]
-= `loaded()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `loaded()` lifecycle callback method is called when a (persistent) object has just been loaded from the object store.
-
-
-[TIP]
-====
-Alternatively, consider using a xref:rgsvc.adoc#_rgsvc-api_EventBusService[event bus] xref:rg.adoc#_rg_classes_super_manpage-AbstractSubscriber[subscriber] on the xref:rg.adoc#_rg_classes_lifecycleevent_manpage-ObjectLoadedEvent[`ObjectLoadedEvent`].
-====

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_manpage-persisted.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_manpage-persisted.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_manpage-persisted.adoc
deleted file mode 100644
index 4b063fa..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_manpage-persisted.adoc
+++ /dev/null
@@ -1,16 +0,0 @@
-[[_rg_methods_reserved_manpage-persisted]]
-= `persisted()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `persisted()` lifecycle callback method is called when object has just been persisted from the object store.
-
-See also xref:rg.adoc#_rg_methods_lifecycle_manpage-persisting[`persisting()`].
-
-[TIP]
-====
-Alternatively, consider using a xref:rgsvc.adoc#_rgsvc-api_EventBusService[event bus] xref:rg.adoc#_rg_classes_super_manpage-AbstractSubscriber[subscriber] on the xref:rg.adoc#_rg_classes_lifecycleevent_manpage-ObjectPersistedEvent[`ObjectPersistedEvent`].
-====

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_manpage-persisting.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_manpage-persisting.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_manpage-persisting.adoc
deleted file mode 100644
index 0ab88c0..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_manpage-persisting.adoc
+++ /dev/null
@@ -1,16 +0,0 @@
-[[_rg_methods_reserved_manpage-persisting]]
-= `persisting()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `persisting()` lifecycle callback method is called when a (not-yet-persistent) object is just about to be persisted from the object store
-
-See also xref:rg.adoc#_rg_methods_lifecycle_manpage-persisted[`persisted()`].
-
-[TIP]
-====
-Alternatively, consider using a xref:rgsvc.adoc#_rgsvc-api_EventBusService[event bus] xref:rg.adoc#_rg_classes_super_manpage-AbstractSubscriber[subscriber] on the xref:rg.adoc#_rg_classes_lifecycleevent_manpage-ObjectPersistingEvent[`ObjectPersistingEvent`].
-====

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_manpage-removed.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_manpage-removed.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_manpage-removed.adoc
deleted file mode 100644
index 8d7e7da..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_manpage-removed.adoc
+++ /dev/null
@@ -1,16 +0,0 @@
-[[_rg_methods_reserved_manpage-removed]]
-= `removed()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `removed()` lifecycle callback method is called when a (persistent) object has just been deleted from the object store
-
-See also xref:rg.adoc#_rg_methods_lifecycle_manpage-removing[`removing()`].
-
-[TIP]
-====
-Alternatively, consider using a xref:rgsvc.adoc#_rgsvc-api_EventBusService[event bus] xref:rg.adoc#_rg_classes_super_manpage-AbstractSubscriber[subscriber] on the xref:rg.adoc#_rg_classes_lifecycleevent_manpage-ObjectRemovedEvent[`ObjectRemovedEvent`].
-====

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_manpage-removing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_manpage-removing.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_manpage-removing.adoc
deleted file mode 100644
index ad1af38..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_manpage-removing.adoc
+++ /dev/null
@@ -1,16 +0,0 @@
-[[_rg_methods_reserved_manpage-removing]]
-= `removing()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `removing()` lifecycle callback method is called when a (persistent) object is just about to be deleted from the object store
-
-See also xref:rg.adoc#_rg_methods_lifecycle_manpage-removed[`removed()`].
-
-[TIP]
-====
-Alternatively, consider using a xref:rgsvc.adoc#_rgsvc-api_EventBusService[event bus] xref:rg.adoc#_rg_classes_super_manpage-AbstractSubscriber[subscriber] on the xref:rg.adoc#_rg_classes_lifecycleevent_manpage-ObjectRemovingEvent[`ObjectRemovingEvent`].
-====

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_manpage-updated.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_manpage-updated.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_manpage-updated.adoc
deleted file mode 100644
index 54d5680..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_manpage-updated.adoc
+++ /dev/null
@@ -1,18 +0,0 @@
-[[_rg_methods_reserved_manpage-updated]]
-= `updated()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-
-
-The `updated()` lifecycle callback method is called when a (persistent) object has just been updated in the object store
-
-See also xref:rg.adoc#_rg_methods_lifecycle_manpage-updating[`updating()`].
-
-[TIP]
-====
-Alternatively, consider using a xref:rgsvc.adoc#_rgsvc-api_EventBusService[event bus] xref:rg.adoc#_rg_classes_super_manpage-AbstractSubscriber[subscriber] on the xref:rg.adoc#_rg_classes_lifecycleevent_manpage-ObjectUpdatedEvent[`ObjectUpdatedEvent`].
-====

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_manpage-updating.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_manpage-updating.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_manpage-updating.adoc
deleted file mode 100644
index 3d8a1d5..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_manpage-updating.adoc
+++ /dev/null
@@ -1,15 +0,0 @@
-[[_rg_methods_reserved_manpage-updating]]
-= `updating()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-The `updating()` lifecycle callback method is called when a (persistent) object is just about to be updated in the object store
-
-See also xref:rg.adoc#_rg_methods_lifecycle_manpage-updated[`updated()`].
-
-[TIP]
-====
-Alternatively, consider using a xref:rgsvc.adoc#_rgsvc-api_EventBusService[event bus] xref:rg.adoc#_rg_classes_super_manpage-AbstractSubscriber[subscriber] on the xref:rg.adoc#_rg_classes_lifecycleevent_manpage-ObjectUpdatingEvent[`ObjectUpdatingEvent`].
-====

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes.adoc
deleted file mode 100644
index a88bf41..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes.adoc
+++ /dev/null
@@ -1,219 +0,0 @@
-[[_rg_methods_prefixes]]
-= Supporting Method Prefixes
-: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/
-
-
-
-Supporting methods are those that are associated with properties, collections and actions, providing additional imperative business rule checking and behaviour to be performed when the user interacts with those object members.
-
-This association is performed by name matching.  Thus, a property called "firstName", derived from a method `getFirstName()` may have supporting methods `hideFirstName()`, `disableFirstName()` and `validateFirstName()`.  Supporting methods are, therefore, each characterized by their own particular prefix.
-
-
-[NOTE]
-====
-Using name matching to associate supporting methods generally works very well, but of course if an object member's method is renamed, there's always the risk that the developer forgets to rename the supporting method; the supporting methods become "orphaned".
-
-Apache Isis checks for this automatically, and will fail-fast (fail to boot) if any orphaned methods are located.  A suitable error message is logged so that the issue can be easily diagnosed.
-====
-
-
-The table below lists the method prefixes that are recognized as part of Apache Isis' default programming model.
-
-.Recognized Method Prefixes
-[cols="2,1,1,1,1,1,4a", options="header"]
-|===
-
-|Prefix
-|Object
-|Property
-|Collection
-|Action
-|Action +
-Param
-|Description
-
-|xref:rg.adoc#_rg_methods_prefixes_manpage-addTo[`addTo...()`]
-|
-|
-|Y
-|
-|
-|add object to a collection  +
-
-[NOTE]
-====
-Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer].
-====
-
-See also xref:rg.adoc#_rg_methods_prefixes_manpage-removeFrom[`removeFrom...()`]`
-
-
-|xref:rg.adoc#_rg_methods_prefixes_manpage-autoComplete[`autoComplete...()`]
-|
-|Y
-|
-|
-|Y
-|Return a list of matching elements for a property or an action parameter. +
-
-Alternatively, can specify for a class using xref:rgant.adoc#_rgant-DomainObject_autoCompleteRepository[`@DomainObject` +
-`#autoCompleteRepository`] +
-
-See also xref:rg.adoc#_rg_methods_prefixes_manpage-choices[`choices...()`]
-
-|xref:rg.adoc#_rg_methods_prefixes_manpage-choices[`choices...()`]
-|
-|Y
-|
-|
-|Y
-|Provide list of choices for a property or action parameter. +
-
-See also xref:rg.adoc#_rg_methods_prefixes_manpage-autoComplete[`autoComplete...()`].
-
-|xref:rg.adoc#_rg_methods_prefixes_manpage-clear[`clear...()`]
-|
-|Y
-|
-|
-|
-|Clear a property (set it to null). +
-
-Allows business logic to be placed apart from the setter. +
-
-See also xref:rg.adoc#_rg_methods_prefixes_manpage-modify[`modify...()`]
-
-
-|xref:rg.adoc#_rg_methods_prefixes_manpage-default[`default...()`]
-|
-|Y
-|
-|
-|Y
-|Default value for a property or an action parameter.
-
-|xref:rg.adoc#_rg_methods_prefixes_manpage-disable[`disable...()`]
-|Y
-|Y
-|Y
-|Y
-|
-|Disables (makes read-only) a property, a collection or an action.
-
-|xref:rg.adoc#_rg_methods_prefixes_manpage-get[`get...()`]
-|
-|Y
-|Y
-|
-|
-|Access the value of a property or collection. +
-
-See also xref:rg.adoc#_rg_methods_prefixes_manpage-set[`set...()`].
-
-|xref:rg.adoc#_rg_methods_prefixes_manpage-hide[`hide...()`]
-|
-|Y
-|Y
-|Y
-|
-|Hides a property, a collection or an action.
-
-|xref:rg.adoc#_rg_methods_prefixes_manpage-modify[`modify...()`]
-|
-|Y
-|
-|
-|
-|Modify a property (set it to a non-null) value. +
-
-Allows business logic to be placed apart from the setter. +
-
-See also xref:rg.adoc#_rg_methods_prefixes_manpage-clear[`clear...()`]`.
-
-|xref:rg.adoc#_rg_methods_prefixes_manpage-removeFrom[`removeFrom...()`]
-|
-|
-|Y
-|
-|
-|remove object from a collection. +
-
-[NOTE]
-====
-Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer].
-====
-
-See also xref:rg.adoc#_rg_methods_prefixes_manpage-addTo[`addTo...()`]`
-
-
-|xref:rg.adoc#_rg_methods_prefixes_manpage-set[`set...()`]
-|
-|Y
-|Y
-|
-|
-|Sets the value of a property or a collection.
-
-|xref:rg.adoc#_rg_methods_prefixes_manpage-validate[`validate...()`]
-|Y
-|
-|
-|Y
-|Y
-|Check that a proposed value of a property or a set of action parameters or a single action parameter is valid. +
-
-See also xref:rg.adoc#_rg_methods_prefixes_manpage-validateAddTo[`validateAddTo...()`] and xref:rg.adoc#_rg_methods_prefixes_manpage-validateRemoveFrom[`validateRemoveFrom...()`] to validate modifications to collections.
-
-|xref:rg.adoc#_rg_methods_prefixes_manpage-validateAddTo[`validate +
-AddTo...()`]
-|
-|Y
-|
-|
-|
-|Check that a proposed object to add to a collection is valid. +
-
-[NOTE]
-====
-Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer].
-====
-
-See also xref:rg.adoc#_rg_methods_prefixes_manpage-validateRemoveFrom[`validateRemoveFrom...()`], and xref:rg.adoc#_rg_methods_prefixes_manpage-validate[`validate...()`] for properties and actions.
-
-|xref:rg.adoc#_rg_methods_prefixes_manpage-validateRemoveFrom[`validate +
-RemoveFrom...()`]
-|
-|Y
-|
-|
-|
-|Check that a proposed object to remove from a collection is valid. +
-
-[NOTE]
-====
-Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer].
-====
-
-See also xref:rg.adoc#_rg_methods_prefixes_manpage-validateAddTo[`validateAddTo...()`], and xref:rg.adoc#_rg_methods_prefixes_manpage-validate[`validate...()`] for properties and actions.
-
-|===
-
-
-
-include::_rg_methods_prefixes_manpage-addTo.adoc[leveloffset=+1]
-include::_rg_methods_prefixes_manpage-autoComplete.adoc[leveloffset=+1]
-include::_rg_methods_prefixes_manpage-choices.adoc[leveloffset=+1]
-include::_rg_methods_prefixes_manpage-clear.adoc[leveloffset=+1]
-include::_rg_methods_prefixes_manpage-default.adoc[leveloffset=+1]
-include::_rg_methods_prefixes_manpage-disable.adoc[leveloffset=+1]
-include::_rg_methods_prefixes_manpage-get.adoc[leveloffset=+1]
-include::_rg_methods_prefixes_manpage-hide.adoc[leveloffset=+1]
-include::_rg_methods_prefixes_manpage-modify.adoc[leveloffset=+1]
-include::_rg_methods_prefixes_manpage-removeFrom.adoc[leveloffset=+1]
-include::_rg_methods_prefixes_manpage-set.adoc[leveloffset=+1]
-include::_rg_methods_prefixes_manpage-validate.adoc[leveloffset=+1]
-include::_rg_methods_prefixes_manpage-validateAddTo.adoc[leveloffset=+1]
-include::_rg_methods_prefixes_manpage-validateRemoveFrom.adoc[leveloffset=+1]
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-addTo.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-addTo.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-addTo.adoc
deleted file mode 100644
index 0469548..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-addTo.adoc
+++ /dev/null
@@ -1,37 +0,0 @@
-[[_rg_methods_prefixes_manpage-addTo]]
-= `addTo...()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `addTo...()` supporting method is called whenever an object is added to a collection. Its purpose is to allow additional business logic to be performed.
-
-
-[NOTE]
-====
-Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer].  The suggested workaround is to simply define an action.
-====
-
-
-For example:
-
-[source,java]
-----
-public class LibraryMember {
-    public SortedSet<Book> getBorrowed() { ... }
-    public void setBorrowed(SortedSet<Book> borrowed) { ... }
-    public void addToBorrowed(Book book) {
-        getBorrowed().add(book);                                              // <1>
-        reminderService.addReminder(this, book, clock.today().plusDays(21));  // <2>
-    }
-    public void removeFromBorrowed(Book book) { ... }
-    ...
-}
-----
-<1> update the collection
-<2> perform some additional business logic
-
-
-See also xref:rg.adoc#_rg_methods_prefixes_manpage-removeFrom[`removeFrom...()`]`

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-autoComplete.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-autoComplete.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-autoComplete.adoc
deleted file mode 100644
index 22f0d2e..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-autoComplete.adoc
+++ /dev/null
@@ -1,96 +0,0 @@
-[[_rg_methods_prefixes_manpage-autoComplete]]
-= `autoComplete...()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `autoComplete...()` supporting method is called for action parameters and for properties to find objects from a drop-down list box.  The use case is when the number of candidate objects is expected to be large, so the user is required to enter some characters to narrow the search down.
-
-[TIP]
-====
-If the number of candidate objects is comparatively small, then use xref:rg.adoc#_rg_methods_prefixes_manpage-choices[`choices...()`] supporting method instead.
-====
-
-The signature of the supporting method depends on whether it is for a parameter or a property.
-
-
-== Parameters
-
-For an action parameter in (0-based) position _N_, and of type `T`, the signature is:
-
-[source,java]
-----
-public List<T> autoCompleteNXxx(String search) { ... }
-----
-
-It is also valid to return `T[]`, a `Set<T>` or a `Collection<T>`.
-
-
-For example:
-
-[source,java]
-----
-public class ShoppingCartItem {
-    @Property(editing=Editing.DISABLED)
-    public Product getProduct() { ... }
-    public void setProduct(Product product) { ... }
-
-    @Property(editing=Editing.DISABLED)
-    public int getQuantity() { ... }
-    public void setQuantity(int quantity) { ... }
-
-    @Action(semantics=SemanticsOf.IDEMPOTENT)
-    public ShoppingCartItem updateProduct(
-        Product product,
-        @ParameterLayout(named="Quantity")
-        final int quantity) {
-        setProduct(product);
-        setQuantity(quantity);
-    }
-    public Collection<Product> autoComplete0UpdateProduct(  // <1>
-        @MinLength(3) String search                         // <2>
-    ) {
-        ...
-    }
-    ...
-}
-----
-<1> `product` is the 0th argument of the action.
-<2> the xref:rgant.adoc#_rgant-MinLength[`@MinLength`] annotation specifies the minimum number of characters that must be entered before a search is performed for matching objects
-
-
-
-
-
-== Properties
-
-For a property of type `T`, the signature is:
-
-[source,java]
-----
-public List<T> autoCompleteXxx(String search) { ... }
-----
-
-(As for action parameters) it is also valid to return `T[]`, a `Set<T>` or a `Collection<T>`.
-
-For example:
-
-[source,java]
-----
-public class ShoppingCartItem {
-    public Product getProduct() { ... }
-    public void setProduct(Product product) { ... }
-
-    public Collection<Product> autoCompleteProduct(
-        @MinLength(3) String search                     // <1>
-    ) {
-        ...
-    }
-    ...
-}
-----
-<1> the xref:rgant.adoc#_rgant-MinLength[`@MinLength`] annotation specifies the minimum number of characters that must be entered before a search is performed for matching objects
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-choices.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-choices.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-choices.adoc
deleted file mode 100644
index c333132..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-choices.adoc
+++ /dev/null
@@ -1,143 +0,0 @@
-[[_rg_methods_prefixes_manpage-choices]]
-= `choices...()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `choices...()` supporting method is called for both action parameters and for properties, to find objects from a drop-down list box.  Unlike xref:rg.adoc#_rg_methods_prefixes_manpage-autoComplete[`autoComplete...()`], the use case is when the number of objects is comparatively small and can be selected from a drop-down without any additional filtering.
-
-The signature of the supporting method depends on whether it is for an action parameter or a property.
-
-
-== Parameters
-
-For an action parameter in (0-based) position _N_, and of type `T`, the signature is:
-
-[source,java]
-----
-public Collection<T> choicesNXxx() { ... }
-----
-
-
-For example:
-
-[source,java]
-----
-public class ShoppingCartItem {
-    @Property(editing=Editing.DISABLED)
-    public Product getProduct() { ... }
-    public void setProduct(Product product) { ... }
-
-    @Property(editing=Editing.DISABLED)
-    public int getQuantity() { ... }
-    public void setQuantity(int quantity) { ... }
-
-    @Action(semantics=SemanticsOf.IDEMPOTENT)
-    public ShoppingCartItem updateProduct(
-        Product product,
-        @ParameterLayout(named="Quantity")
-        final Integer quantity) {
-        setProduct(product);
-        setQuantity(quantity);
-    }
-    public Collection<Integer> choices1UpdateProduct() {
-        return Arrays.asList(1,2,3,5,10,25,50,100);
-    }
-    ...
-}
-----
-
-
-=== Dependent Choices
-
-Action parameters also support the notion of dependent choices, whereby the list of choices is dependent upon the value of some other argument.
-
-An example can be found in the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp], whereby `ToDoItem`s are categorized and then can also be subcategorized:
-
-image::{_imagesdir}reference-methods/prefixes/choices/dependent.png[width="800px",link="{_imagesdir}reference-methods/prefixes/choices/dependent.png"]
-
-
-
-This functionality is actually implemented as a xref:ug.adoc#_ug_how-tos_contributed-members[contributed action], so the code for this is:
-
-[source,java]
-----
-@DomainService(nature = NatureOfService.VIEW_CONTRIBUTIONS_ONLY)
-public class UpdateCategoryContributions ... {
-    @ActionLayout(
-            describedAs = "Update category and subcategory"
-    )
-    @Action(semantics = SemanticsOf.IDEMPOTENT)
-    public Categorized updateCategory(
-            final Categorized item,                              // <1>
-            final Category category,
-            @Parameter(optionality = Optionality.OPTIONAL)
-            final Subcategory subcategory) {
-        item.setCategory(category);
-        item.setSubcategory(subcategory);
-        return item;
-    }
-    public List<Subcategory> choices2UpdateCategory(             // <2>
-            final Categorized item,                              // <3>
-            final Category category) {                           // <4>
-        return Subcategory.listFor(category);
-    }
-    ...
-}
-----
-<1> `ToDoItem` implements `Categorized`
-<2> subcategory is the 2-th argument (0-based)
-<3> the item contributed to
-<4> the category selected
-
-
-Dependent choices are not restricted to enums, however.  Going back to the shopping cart example shown above, the choices for the `quantity` parameter could be dependent upon the selected `Product`:
-
-
-[source,java]
-----
-public class ShoppingCartItem {
-    ...
-    @Action(semantics=SemanticsOf.IDEMPOTENT)
-    public ShoppingCartItem updateProduct(
-        Product product,
-        @ParameterLayout(named="Quantity")
-        final Integer quantity) {
-        setProduct(product);
-        setQuantity(quantity);
-    }
-    public Collection<Integer> choices1UpdateProduct(Product product) {
-        return productService.quantityChoicesFor(product);                 // <1>
-    }
-    ...
-}
-----
-<1> `productService` is a (fictitous) injected service that knows what the quantity choices should be for any given product
-
-
-== Properties
-
-For a property of type `T`, the signature is:
-
-[source,java]
-----
-public Collection<T> choicesXxx() { ... }
-----
-
-
-For example:
-
-[source,java]
-----
-public class ShoppingCartItem {
-    public Product getProduct() { ... }
-    public void setProduct(Product product) { ... }
-
-    public Collection<Product> choicesProduct() {
-        ...
-    }
-----
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-clear.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-clear.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-clear.adoc
deleted file mode 100644
index 1c8646a..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-clear.adoc
+++ /dev/null
@@ -1,32 +0,0 @@
-[[_rg_methods_prefixes_manpage-clear]]
-= `clear...()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `clear...()` supporting method is called -- instead of the setter -- whenever an (optional) property is to be set to `null`.  Its purpose is to allow additional business logic to be performed.
-
-
-For example:
-
-[source,java]
-----
-public class LibraryMember {
-    public Title getFavoriteTitle() { ... }
-    public void setFavoriteTitle(Title title) { ... }
-    public void modifyFavoriteTitle(Title title) { ... }
-    public void clearFavoriteTitle() {
-        if(getTitle() == null) { return; }
-        setFavoriteTitle(null);                         // <1>
-        titleFavoritesService.decrement(title);         // <2>
-    }
-    ...
-}
-----
-<1> update the property
-<2> perform some additional business logic
-
-
-See also xref:rg.adoc#_rg_methods_prefixes_manpage-modify[`modify...()`]`

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-default.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-default.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-default.adoc
deleted file mode 100644
index 1ef19b5..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-default.adoc
+++ /dev/null
@@ -1,129 +0,0 @@
-[[_rg_methods_prefixes_manpage-default]]
-= `default...()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `default...()` supporting method is called for action parameters to return the initial argument value.  This may be some sensible default (eg today's date, or 0 or 1), or -- for an action that is modifying the state of an object -- might default to the current value of a corresponding property.
-
-The method is _also_ called for properties in the case when an object is newly instantiated using xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer[`DomainObjectContainer#newTransientInstance(...)`].  This is a much less common use case.  If a default is not specified then properties are initialized to a default based on their type (eg 0 or `false`).
-
-The signature of the supporting method depends on whether it is for an action parameter or a property.
-
-
-== Parameters
-
-For an action parameter in (0-based position n), and of type `T`, the signature is:
-
-[source,java]
-----
-public T defaultNXxx() { ... }
-----
-
-
-For example:
-
-[source,java]
-----
-public class ShoppingCartItem {
-    @Property(editing=Editing.DISABLED)
-    public Product getProduct() { ... }
-    public void setProduct(Product product) { ... }
-
-    @Property(editing=Editing.DISABLED)
-    public int getQuantity() { ... }
-    public void setQuantity(int quantity) { ... }
-
-    @Action(semantics=SemanticsOf.IDEMPOTENT)
-    public ShoppingCartItem updateProduct(
-        Product product,
-        @ParameterLayout(named="Quantity")
-        final Integer quantity) {
-        setProduct(product);
-        setQuantity(quantity);
-    }
-    public Product default0UpdateProduct() {    // <1>
-        return getProduct();
-    }
-    public int default1UpdateProduct() {        // <2>
-        return getQuantity();
-    }
-    ...
-}
-----
-<1> default the 0-th parameter using the current value of the `product` property
-<2> default the 1-th parameter using the current value of the `quantity` property
-
-
-
-Defaults are also supported (of course) for xref:ug.adoc#_ug_how-tos_contributed-members[contributed actions].  For example, here is a contributed action for updating category/subcategory of the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp]:
-
-[source,java]
-----
-@DomainService(nature = NatureOfService.VIEW_CONTRIBUTIONS_ONLY)
-public class UpdateCategoryContributions ... {
-    @ActionLayout(
-            describedAs = "Update category and subcategory"
-    )
-    @Action(semantics = SemanticsOf.IDEMPOTENT)
-    public Categorized updateCategory(
-            final Categorized item,                              // <1>
-            final Category category,
-            @Parameter(optionality = Optionality.OPTIONAL)
-            final Subcategory subcategory) {
-        item.setCategory(category);
-        item.setSubcategory(subcategory);
-        return item;
-    }
-    public Category default1UpdateCategory(                     // <2>
-            final Categorized item) {
-        return item != null? item.getCategory(): null;
-    }
-    public Subcategory default2UpdateCategory(                  // <3>
-            final Categorized item) {
-        return item != null? item.getSubcategory(): null;
-    }
-}
-----
-<1> `ToDoItem` implements `Categorized`
-<2> defaults the 1-th parameter using the item's `category` property
-<3> defaults the 2-th parameter using the item's `subcategory` property
-
-
-
-
-
-== Properties
-
-For a property of type `T`, the signature is:
-
-[source,java]
-----
-public T defaultXxx() { ... }
-----
-
-
-For example:
-
-[source,java]
-----
-public class ShoppingCartItem {
-    public int getQuantity() { ... }
-    public void setQuantity(int quantity) { ... }
-
-    public int defaultProduct() {
-        return 1;
-    }
-----
-
-
-=== Alternatives
-
-There are, in fact, two other ways to set properties of a newly instantiated object to default values.
-
-The first is to use the xref:rg.adoc#_rg_methods_lifecycle_manpage-created[`created()`] callback, called by the framework when xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer[`DomainObjectContainer#newTransientInstance(...)`] is called.  This method is called after any dependencies have been injected into the service.
-
-The second is more straightforward: simply initialize properties in the constructor.  However, this cannot use any injected services as they will not have been initialized.
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-disable.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-disable.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-disable.adoc
deleted file mode 100644
index 88b2a52..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-disable.adoc
+++ /dev/null
@@ -1,93 +0,0 @@
-[[_rg_methods_prefixes_manpage-disable]]
-= `disable...()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-
-The `disable...()` supporting method is called for properties, collections and actions.  It allows the modification of the property/collection to be vetoed (ie made read-only) and to prevent the invocation of the action ("grey it out").
-
-[NOTE]
-====
-Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer]; they are always implicitly disabled.
-====
-
-Typically modification/invocation is vetoed based on the state of the domain object being interacted with, though it could be any reason at all (eg the current date/time of the interaction, or the state of some other related data such as stock levels, or the identity of the calling user).
-
-
-The reason for vetoing a modification/invocation is normally returned as a string.  However, Apache Isis' xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[i18n support] extends this so that reasons can be internationalized.
-
-
-
-== Actions
-
-For an action the signature of the supporting method is:
-
-[source,java]
-----
-public String disableXxx(...) { ... }
-----
-
-where the returned string is the reason the action invocation is vetoed (or `null` if not vetoed), and the supporting method takes the same parameter types as the action itself.
-
-
-
-For example:
-
-[source,java]
-----
-public class Customer {
-    public boolean isBlacklisted() { ... }
-
-    public Order placeOrder(
-            final Product product,
-            @ParameterLayout(named="Quantity")
-            final int quantity) {
-        ...
-    }
-    public String disablePlaceOrder(
-            final Product product,
-            final int quantity
-            ) {
-        return isBlacklisted()
-                    ? "Blacklisted customers cannot place orders"
-                    : null;
-    }
-    ...
-}
-----
-
-
-
-== Properties and Collections
-
-For both properties and collections the signature of the supporting method is:
-
-[source,java]
-----
-public String disableXxx() { ... }
-----
-
-where the returned string is the reason the modification is vetoed (or `null` if not vetoed).
-
-
-
-For example:
-
-[source,java]
-----
-public class Customer {
-    public boolean isBlacklisted() { ... }
-
-    public BigDecimal getCreditLimit() { ... }
-    public void setCreditLimit(BigDecimal creditLimit) { ... }
-    public String disableCreditLimit() {
-        return isBlacklisted()
-                    ? "Cannot change credit limit for blacklisted customers"
-                    : null;
-    }
-    ...
-}
-----

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-get.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-get.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-get.adoc
deleted file mode 100644
index 63bd1a1..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-get.adoc
+++ /dev/null
@@ -1,19 +0,0 @@
-[[_rg_methods_prefixes_manpage-get]]
-= `get...()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `get...()` prefix is simply the normal JavaBean getter prefix that denotes properties or collections.
-
-When Apache Isis builds its metamodel, it first searches for the getter methods, characterizing them as either properties or collections based on the return type.  It then refines the metamodel based on the presence of annotations and supporting methods.
-
-All remaining `public` methods (that do not use one of the Apache Isis prefixes) are interpreted as actions.
-
-Any methods "left over" that _do_ use one of the Apache Isis prefixes, are interpreted to be orphaned.  Apache Isis "fails-fast" and will not boot, instead printing an error message to the log so that the issue can be easily diagnosed.
-
-
-See also xref:rg.adoc#_rg_methods_prefixes_manpage-set[`set...()`].
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-hide.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-hide.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-hide.adoc
deleted file mode 100644
index 93aaaf6..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-hide.adoc
+++ /dev/null
@@ -1,82 +0,0 @@
-[[_rg_methods_prefixes_manpage-hide]]
-= `hide...()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `hide...()` supporting method is called for properties, collections and actions.  It allows the property/collection to be completely hidden from view.
-
-It's comparatively rare for properties or collections to be imperatively hidden from view, but actions are sometimes hidden or shown visible (as opposed to being just xref:rg.adoc#_rg_methods_prefixes_manpage-disable[disabled], ie greyed out).
-
-
-== Actions
-
-For an action the signature of the supporting method is either:
-
-[source,java]
-----
-public bool hideXxx(...) { ... }
-----
-
-where the supporting method takes the same parameter types as the action itself, or more simply:
-
-[source,java]
-----
-public bool hideXxx() { ... }
-----
-
-with no parameters at all.  Returning `true` will hide the action, returning `false` leaves it visible.
-
-
-For example:
-
-[source,java]
-----
-public class Customer {
-    public boolean isBlacklisted() { ... }
-
-    public Order placeOrder(
-            final Product product,
-            @ParameterLayout(named="Quantity")
-            final int quantity) {
-        ...
-    }
-    public boolean hidePlaceOrder() {
-        return isBlacklisted();
-    }
-    ...
-}
-----
-
-
-
-== Properties and Collections
-
-For both properties and collections the signature of the supporting method is:
-
-[source,java]
-----
-public boolean hideXxx() { ... }
-----
-
-where returning `true` will hide the property/collection, returning `false` leaves it visible.
-
-
-
-For example:
-
-[source,java]
-----
-public class Customer {
-    public boolean isBlacklisted() { ... }
-
-    public BigDecimal getCreditLimit() { ... }
-    public void setCreditLimit(BigDecimal creditLimit) { ... }
-    public boolean hideCreditLimit() {
-        return isBlacklisted();
-    }
-    ...
-}
-----

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-modify.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-modify.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-modify.adoc
deleted file mode 100644
index 87160a0..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-modify.adoc
+++ /dev/null
@@ -1,37 +0,0 @@
-[[_rg_methods_prefixes_manpage-modify]]
-= `modify...()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `modify...()` supporting method is called -- instead of the setter -- whenever a property has been set to be set to a new value.  Its purpose is to allow additional business logic to be performed.
-
-
-For example:
-
-[source,java]
-----
-public class LibraryMember {
-    public Title getFavoriteTitle() { ... }
-    public void setFavoriteTitle(Title title) { ... }
-    public void modifyFavoriteTitle(Title title) {
-        if(getTitle() != null) {
-            titleFavoritesService.decrement(getTitle());    // <1>
-        }
-        setFavoriteTitle(title);                            // <2>
-        titleFavoritesService.decrement(title);             // <3>
-    }
-    public void clearFavoriteTitle() { ... }
-    ...
-}
-----
-<1> perform some additional business logic
-<2> update the property
-<3> perform some additional business logic
-
-
-See also xref:rg.adoc#_rg_methods_prefixes_manpage-clear[`clear...()`]`
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-removeFrom.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-removeFrom.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-removeFrom.adoc
deleted file mode 100644
index f4c5fea..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-removeFrom.adoc
+++ /dev/null
@@ -1,37 +0,0 @@
-[[_rg_methods_prefixes_manpage-removeFrom]]
-= `removeFrom...()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `removeFrom...()` supporting method is called whenever an object is removed from a collection. Its purpose is to allow additional business logic to be performed.
-
-
-[NOTE]
-====
-Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer].  The suggested workaround is to simply define an action.
-====
-
-
-For example:
-
-[source,java]
-----
-public class LibraryMember {
-    public SortedSet<Book> getBorrowed() { ... }
-    public void setBorrowed(SortedSet<Book> borrowed) { ... }
-    public void addToBorrowed(Book book) { ... }
-    public void removeFromBorrowed(Book book) {
-        getBorrowed().remove(book);                         // <1>
-        reminderService.removeReminder(this, book);         // <2>
-    }
-    ...
-}
-----
-<1> update the collection
-<2> perform some additional business logic
-
-
-See also xref:rg.adoc#_rg_methods_prefixes_manpage-addTo[`addTo...()`]`

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-set.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-set.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-set.adoc
deleted file mode 100644
index 2e39781..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-set.adoc
+++ /dev/null
@@ -1,13 +0,0 @@
-[[_rg_methods_prefixes_manpage-set]]
-= `set...()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-
-The `set...()` prefix is simply the normal JavaBean setter prefix that denotes writeable properties or collections.
-
-
-See also xref:rg.adoc#_rg_methods_prefixes_manpage-get[`get...()`].

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-validate.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-validate.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-validate.adoc
deleted file mode 100644
index a918ea6..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-validate.adoc
+++ /dev/null
@@ -1,113 +0,0 @@
-[[_rg_methods_prefixes_manpage-validate]]
-= `validate...()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `validate...()` supporting method is called for properties, actions and action parameters.  It allows the proposed new value for a property to be rejected, or the proposed argument of an action parameter to be rejected, or to reject a whole set of action arguments for an actio invocation.
-
-
-The reason for vetoing a modification/invocation is normally returned as a string.  However, Apache Isis' xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[i18n support] extends this so that reasons can be internationalized if required.
-
-
-
-== Action Parameter
-
-For an action parameter in (0-based) position _N_, and of type `T`, the signature is:
-
-[source,java]
-----
-public String validateNXxx(T proposed) { ... }
-----
-
-where the returned string is the reason why the argument is rejected (or `null` if not vetoed).
-
-
-For example:
-
-[source,java]
-----
-public class Customer {
-    public Order placeOrder(
-            final Product product,
-            @ParameterLayout(named="Quantity")
-            final int quantity) {
-        ...
-    }
-    public String validate0PlaceOrder(
-            final Product product) {
-        return product.isDiscontinued()
-                    ? "Product has been discontinued"
-                    : null;
-    }
-    ...
-}
-----
-
-
-== Action Parameter Set
-
-In addition to validating a single single action argument, it is also possible to validate a complete set of action arguments.  The signature is:
-
-[source,java]
-----
-public String validateXxx(...) { ... }
-----
-
-where the returned string is the reason why the argument is rejected (or `null` if not vetoed), and the supporting method takes the same parameter types as the action itself.
-
-
-For example:
-
-[source,java]
-----
-public class Customer {
-    public Order placeOrder(
-            final Product product,
-            @ParameterLayout(named="Quantity")
-            final int quantity) {
-        ...
-    }
-    public String validatePlaceOrder(
-            final Product product,
-            final int quantity) {
-        return quantity > product.getOrderLimit()
-                    ? "May not order more than " + product.getOrderLimit() + " items for this product"
-                    : null;
-    }
-    ...
-}
-----
-
-
-
-== Properties
-
-For properties of type `T` the signature of the supporting method is:
-
-[source,java]
-----
-public String validateXxx(T proposed) { ... }
-----
-
-where the returned string is the reason the modification is vetoed (or `null` if not vetoed).
-
-
-
-For example:
-
-[source,java]
-----
-public class Customer {
-    public BigDecimal getCreditLimit() { ... }
-    public void setCreditLimit(BigDecimal creditLimit) { ... }
-    public validateCreditLimit(BigDecimal creditLimit) {
-        return creditLimit.compareTo(BigDecimal.ZERO) < 0
-                    ? "Credit limit cannot be negative"
-                    : null;
-    }
-    ...
-}
-----

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-validateAddTo.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-validateAddTo.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-validateAddTo.adoc
deleted file mode 100644
index 7dcac02..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-validateAddTo.adoc
+++ /dev/null
@@ -1,45 +0,0 @@
-[[_rg_methods_prefixes_manpage-validateAddTo]]
-= `validateAddTo...()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `validateAddTo...()` supporting method is called whenever an object is to be added to a collection. Its purpose is to validate the proposed object and possibly veto the change.
-
-
-[NOTE]
-====
-Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer].  The suggested workaround is to simply define an action.
-====
-
-
-The signature of the supporting method for a collection with element type `E` is:
-
-[source,java]
-----
-public String validateAddToXxx(E element) { ... }
-----
-
-where the returned string is the reason the collection modification invocation is vetoed (or `null` if not vetoed).  Apache Isis' xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[i18n support] extends this so that reasons can be internationalized if required.
-
-
-For example:
-
-[source,java]
-----
-public class LibraryMember {
-    public SortedSet<Book> getBorrowed() { ... }
-    public void setBorrowed(SortedSet<Book> borrowed) { ... }
-    public String validateAddToBorrowed(Book book) {
-        return book.isReference()? "Reference books cannot be borrowed": null;
-    }
-    public void validateRemoveFromBorrowed(Book book) { ... }
-    ...
-}
-----
-
-
-See also xref:rg.adoc#_rg_methods_prefixes_manpage-addTo[`addTo...()`] and  xref:rg.adoc#_rg_methods_prefixes_manpage-validateRemoveFrom[`validateRemoveFrom...()`]`
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-validateRemoveFrom.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-validateRemoveFrom.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-validateRemoveFrom.adoc
deleted file mode 100644
index 2e0f85d..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-validateRemoveFrom.adoc
+++ /dev/null
@@ -1,45 +0,0 @@
-[[_rg_methods_prefixes_manpage-validateRemoveFrom]]
-= `validateRemoveFrom...()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `validateRemoveFrom...()` supporting method is called whenever an object is to be removed from a collection. Its purpose is to validate the proposed object removal and possibly veto the change.
-
-
-[NOTE]
-====
-Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer].  The suggested workaround is to simply define an action.
-====
-
-
-The signature of the supporting method for a collection with element type `E` is:
-
-[source,java]
-----
-public String validateRemoveFromXxx(E element) { ... }
-----
-
-where the returned string is the reason the collection modification invocation is vetoed (or `null` if not vetoed).  Apache Isis' xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[i18n support] extends this so that reasons can be internationalized if required.
-
-
-For example:
-
-[source,java]
-----
-public class LibraryMember {
-    public SortedSet<Book> getBorrowed() { ... }
-    public void setBorrowed(SortedSet<Book> borrowed) { ... }
-    public String validateAddToBorrowed(Book book) { ... }
-    public void validateRemoveFromBorrowed(Book book) {
-        return !book.hasBeenReadBy(this)? "You didn't read this book yet": null;
-    }
-    ...
-}
-----
-
-
-See also xref:rg.adoc#_rg_methods_prefixes_manpage-removeFrom[`removeFrom...()`] and  xref:rg.adoc#_rg_methods_prefixes_manpage-validateAddTo[`validateAddTo...()`]`
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved.adoc
deleted file mode 100644
index 762a8bb..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved.adoc
+++ /dev/null
@@ -1,58 +0,0 @@
-[[_rg_methods_reserved]]
-= Reserved Methods
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The table below lists the reserved methods that are recognized as part of Apache Isis' default programming model.
-
-.Reserved Methods
-[cols="1,4a", options="header"]
-|===
-
-|Method
-|Description
-
-|xref:rg.adoc#_rg_methods_reserved_manpage-cssClass[`cssClass()`]
-|Provides a CSS class for this object instance.  In conjunction with xref:rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css`], can therefore provide custom styling of an object instance wherever it is rendered. +
-
-See also xref:rg.adoc#_rg_methods_reserved_manpage-title[`title()`] and xref:rg.adoc#_rg_methods_reserved_manpage-iconName[`iconName()`].
-
-|xref:rg.adoc#_rg_methods_reserved_manpage-disable[`disable(...)`]
-|Disable all or some of an object's properties
-
-|xref:rg.adoc#_rg_methods_reserved_manpage-getId[`getId()`]
-|Provides an optional unique identifier of a service. +
-
-If not provided, the service's fully-qualified class name is used.
-
-|xref:rg.adoc#_rg_methods_reserved_manpage-hide[`hide(...)`]
-|Hide all or some of an object's properties
-
-|xref:rg.adoc#_rg_methods_reserved_manpage-iconName[`iconName()`]
-|Provides the name of the image to render, usually alongside the title, to represent the object. If not provided, then the class name is used to locate an image. +
-
-See also xref:rg.adoc#_rg_methods_reserved_manpage-title[`title()`] and xref:rg.adoc#_rg_methods_reserved_manpage-cssClass[`cssClass()`]
-
-|xref:rg.adoc#_rg_methods_reserved_manpage-title[`title()`]
-|Provides a title for the object. +
-
-See also xref:rg.adoc#_rg_methods_reserved_manpage-iconName[`iconName()`] and xref:rg.adoc#_rg_methods_reserved_manpage-cssClass[`cssClass()`]
-
-|xref:rg.adoc#_rg_methods_reserved_manpage-validate[`validate()`]
-|Validate the object's state prior to persisting.
-
-|===
-
-
-
-
-include::_rg_methods_reserved_manpage-cssClass.adoc[leveloffset=+1]
-include::_rg_methods_reserved_manpage-disable.adoc[leveloffset=+1]
-include::_rg_methods_reserved_manpage-getId.adoc[leveloffset=+1]
-include::_rg_methods_reserved_manpage-hide.adoc[leveloffset=+1]
-include::_rg_methods_reserved_manpage-iconName.adoc[leveloffset=+1]
-include::_rg_methods_reserved_manpage-title.adoc[leveloffset=+1]
-include::_rg_methods_reserved_manpage-validate.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-cssClass.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-cssClass.adoc
deleted file mode 100644
index e0b388f..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-cssClass.adoc
+++ /dev/null
@@ -1,46 +0,0 @@
-[[_rg_methods_reserved_manpage-cssClass]]
-= `cssClass()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `cssClass()` returns a CSS class for a particular object instance.
-
-The xref:ugvw.adoc#[Wicket viewer] wraps the object's representation in a containing `<div>` with the class added.  This is done both for rendering the object either in a table or when rendering the object on its own page.
-
-In conjunction with xref:rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css`], can therefore provide custom styling of an object instance wherever it is rendered. +
-
-
-For example, the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] uses this technique to add a strikethrough for completed todo items.  This is shown on the home page:
-
-image::{_imagesdir}reference-methods/reserved/cssClass/strikethrough.png[width="800px",link="{_imagesdir}reference-methods/reserved/cssClass/strikethrough.png"]
-
-
-The code to accomplish this is straightforward:
-
-[source,java]
-----
-public class ToDoItem ... {
-    public String cssClass() {
-        return !isComplete() ? "todo" : "done";
-    }
-    ...
-}
-----
-
-In the xref:rgcfg.adoc#_rgcfg_application-specific_application-css[application.css], the following styles were then added:
-
-[source,css]
-----
-tr.todo {
-}
-tr.done {
-    text-decoration: line-through;
-    color: #d3d3d3;
-}
-----
-
-
-See also xref:rg.adoc#_rg_methods_reserved_manpage-title[`title()`] and xref:rg.adoc#_rg_methods_reserved_manpage-iconName[`iconName()`].

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-disable.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-disable.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-disable.adoc
deleted file mode 100644
index b41157c..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-disable.adoc
+++ /dev/null
@@ -1,102 +0,0 @@
-[[_rg_methods_reserved_manpage-disable]]
-= `disable()`
-: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/
-
-
-One use case that Apache Isis supports is that of a domain object with a lifecycle whereby at some stage it should become immutable: all its properties/collections should be disabled, and/or its actions become not invokable.
-
-It would be painful to have to write a separate xref:rg.adoc#_rg_methods_prefixes_manpage-disable[`disable...()`] method for each and every member, so instead Isis allows a single `disable...(...)` method to be implemented that is applied to all members.
-
-The signature of the method is:
-
-[source,java]
-----
-public String disable(Identifier.Type identifierType) { ... }
-----
-
-where `Identifier.Type` is part of the Isis applib (nested static class of `o.a.i.applib.Identifier`) to distinguish between an interaction with an action, a property or an action.
-
-Note that Apache Isis' xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[i18n support] extends this so that the returned reason can also be internationalized.
-
-For example:
-
-[source,java]
-----
-public String disable(Identifier.Type identifierType) {
-    return !calendarService.isOfficeHours(clock.today()
-            ? "Cannot modify objects outside of office hours"
-            : null;
-}
-----
-
-See also the similar methods to xref:rg.adoc#_rg_methods_reserved_manpage-hide[`hide()`] object members en-masse.
-
-
-== Alternatives
-
-An alternative design -- and one that could be easily argued is actually more flexible -- is to leverage domain events with vetoing subscribers.
-
-With this approach we define, for a given domain class, a base `PropertyDomainEvent`, `CollectionDomainEvent` and `ActionDomainEvent`.  A good pattern is to make these nested static classes.  For example:
-
-[source,java]
-----
-public class ToDoItem ... {
-    public static abstract class PropertyDomainEvent<T>
-            extends ToDoAppDomainModule.PropertyDomainEvent<ToDoItem, T> {
-        ...
-    }
-    ...
-}
-----
-
-where in turn:
-
-[source,java]
-----
-public final class ToDoAppDomainModule {
-    private ToDoAppDomainModule(){}
-    public abstract static class PropertyDomainEvent<S,T>
-            extends org.apache.isis.applib.services.eventbus.PropertyDomainEvent<S,T> {
-        ...
-    }
-    ...
-}
-----
-
-Then, each property/collection/action emits either these base domain events or their own subclass:
-
-[source,java]
-----
-public class ToDoItem ... {
-    public static class DescriptionDomainEvent
-            extends PropertyDomainEvent<String> {
-        ...
-    }
-    @Property(
-        domainEvent = DescriptionDomainEvent.class
-    )
-    public String getDescription() { ... }
-    ...
-}
-----
-
-A vetoing subscriber can then subscribe to the domain events and veto access, eg:
-
-[source,java]
-----
-@DomainObject
-public class VetoOutOfOfficeHours {
-    @Subscribe
-    public void on(ToDoItem.PropertyDomainEvent ev) {
-        if(!calendarService.isOfficeHours(clock.today()) {
-            ev.veto("Cannot modify objects outside of office hours");
-        }
-    }
-    ...
-}
-----
-
-Obviously there's an awful lot more boilerplate here, but there's also a lot more flexibility.
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-getId.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-getId.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-getId.adoc
deleted file mode 100644
index 2901060..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-getId.adoc
+++ /dev/null
@@ -1,19 +0,0 @@
-[[_rg_methods_reserved_manpage-getId]]
-= `getId()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-The `getId()` method applies only to domain services, and allows a unique identifer to be provided for that service.
-
-This identifier corresponds in many ways to the xref:rgant.adoc#_rgant-DomainObject_objectType[`objectType()`] attribute for domain objects; it is used as an internal identifier but also appears in URLs within the xref:ugvro.adoc#[RestfulObjects viewer]'s REST API.
-
-If the identifier is omitted, the services fully qualified class name is used.
-
-[TIP]
-====
-Unlike domain objects, where the use of an object type is strongly encouraged (eg using xref:rgant.adoc#_rgant-PersistenceCapable[`@PersistenceCapable`]), it matters much less if an id is specified for domain services.  The principle benefit is shorter URLs in the REST API.
-====
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-hide.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-hide.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-hide.adoc
deleted file mode 100644
index 423699a..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-hide.adoc
+++ /dev/null
@@ -1,39 +0,0 @@
-[[_rg_methods_reserved_manpage-hide]]
-= `hide()`
-: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/
-
-
-
-One use case that Apache Isis supports is that of a domain object with a lifecycle whereby at some stage some number of the object's members should be hidden.  For example, for an object that at some stage is logically immutable, we might want to make all its properties/collections unmodifiable and hide all its actions.
-
-While we could write a separate xref:rg.adoc#_rg_methods_prefixes_manpage-hide[`hide...()`] method for each and every action, this could become painful.  So instead Isis allows a single `hide...(...)` method to be implemented that is applied to all members.
-
-The signature of the method is:
-
-[source,java]
-----
-public boolean hide(Identifier.Type identifierType) { ... }
-----
-
-where `Identifier.Type` is part of the Isis applib (nested static class of `o.a.i.applib.Identifier`) to distinguish between an interaction with an action, a property or an action.
-
-For example:
-
-[source,java]
-----
-public boolean hide(Identifier.Type identifierType) {
-    return identifierType == Identifier.Type.ACTION && isFrozen();
-}
-----
-
-See also the similar method to xref:rg.adoc#_rg_methods_reserved_manpage-disable[`disable()`] object members en-masse.
-
-
-== Alternatives
-
-An alternative design -- and one that could be easily argued is actually more flexible -- is to leverage domain events with vetoing subscribers.
-
-There is further discussion on this approach in xref:rg.adoc#_rg_methods_reserved_manpage-disable[here].
-


[06/52] [abbrv] isis git commit: ISIS-1243: renamed rg.adoc to rgcms.adoc

Posted by mg...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_manpage-ObjectContracts.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_manpage-ObjectContracts.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_manpage-ObjectContracts.adoc
new file mode 100644
index 0000000..41723cb
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_manpage-ObjectContracts.adoc
@@ -0,0 +1,107 @@
+[[_rgcms_classes_utility_manpage-ObjectContracts]]
+= `ObjectContracts`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+The `ObjectContracts` test provides a series of methods to make it easy for your domain objects to:
+
+* implement `Comparable` (eg so can be stored in ``java.util.SortedSet``s)
+* implement `toString()`
+* implement `equals()`
+* implement `hashCode()`
+
+For example:
+
+[source,java]
+----
+public class ToDoItem implements Comparable<ToDoItem> {
+
+    public boolean isComplete() { ... }
+    public LocalDate getDueBy() { ... }
+    public String getDescription() { ... }
+    public String getOwnedBy() { ... }
+
+    public int compareTo(final ToDoItem other) {
+        return ObjectContracts.compare(this, other, "complete","dueBy","description");
+    }
+
+    public String toString() {
+        return ObjectContracts.toString(this, "description","complete","dueBy","ownedBy");
+    }
+}
+----
+
+[WARNING]
+====
+Note that `ObjectContracts` makes heavy use of Java Reflection.  While it's great to get going quickly in prototyping, we recommend you use your IDE to code generate implementations of these methods for production code.
+
+Moreover (and perhaps even more importantly) `ObjectContracts` implementation can cause DataNucleus to recursively rehydrate a larger number of associated entities (More detail below).
+
+We therefore recommend that you disable persistence-by-reachability by adding:
+
+[source,ini]
+.persistor_datanucleus.properties
+----
+isis.persistor.datanucleus.impl.datanucleus.persistenceByReachabilityAtCommit=false
+----
+
+====
+
+== The issue in more detail
+
+Consider the link:http://yuml.me/edit/742ad446[entities]:
+
+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.
+
+All these entities implement `Comparable` using `ObjectContracts`, so that the implementation of ``AgreementRole``'s (simplified) is:
+
+[source,java]
+----
+public class AgreementRole {
+    ...
+    public int compareTo(AgreementRole other) {
+        return ObjectContracts.compareTo(this, other, "agreement","startDate","party");
+    }
+    ...
+}
+----
+
+while ``Agreement``'s is implemented as:
+
+[source,java]
+----
+    public class Agreement {
+        ...
+        public int compareTo(Agreement other) {
+            return ObjectContracts.compareTo(this, other, "reference");
+        }
+        ...
+    }
+----
+
+and ``Party``'s is similarly implemented as:
+
+[source,java]
+----
+public class Party {
+    ...
+    public int compareTo(Party other) {
+        return ObjectContracts.compareTo(this, other, "reference");
+    }
+    ...
+}
+----
+
+DataNucleus's persistence-by-reachability algorithm adds the ``AgreementRole``s into a `SortedSet`, which causes `AgreementRole#compareTo()` to fire:
+
+* the evaluation of the "agreement" property delegates back to the `Agreement`, whose own `Agreement#compareTo()` uses the scalar `reference` property.  As the `Agreement` is already in-memory, this does not trigger any further database queries
+
+* the evaluation of the "startDate" property is just a scalar property of the `AgreementRole`, so will already in-memory
+
+* the evaluation of the "party" property delegates back to the `Party`, whose own `Party#compareTo()` requires the uses the scalar `reference` property.  However, since the `Party` is not yet in-memory, using the `reference` property triggers a database query to "rehydrate" the `Party` instance.
+
+In other words, figuring out whether `AgreementRole` is comparable requires the persistence-by-reachability algorithm to run, causing the adjacent associated entity `Party` to also be retrieved.

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_manpage-Reasons.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_manpage-Reasons.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_manpage-Reasons.adoc
new file mode 100644
index 0000000..7711542
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_manpage-Reasons.adoc
@@ -0,0 +1,31 @@
+[[_rgcms_classes_utility_manpage-Reasons]]
+= `Reasons`
+: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/
+
+
+
+There are two different classes provided to help build reasons returned
+by `disableXxX()` and `validateXxx()` methods:
+
+* the `org.apache.isis.applib.util.ReasonBuffer` helper class
+* the `org.apache.isis.applib.util.Reasons` helper class
+
+For example:
+
+[source,java]
+----
+public class Customer {
+    ...
+    public String validatePlaceOrder(Product p, int quantity) {
+        return Reasons.coalesce(
+            whetherCustomerBlacklisted(this),
+            whetherProductOutOfStock(p)
+        );
+    }
+}
+----
+
+Which you use (if any) is up to you.
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_manpage-TitleBuffer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_manpage-TitleBuffer.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_manpage-TitleBuffer.adoc
new file mode 100644
index 0000000..800f1cb
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_manpage-TitleBuffer.adoc
@@ -0,0 +1,13 @@
+[[_rgcms_classes_utility_manpage-TitleBuffer]]
+= `TitleBuffer`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+The `TitleBuffer` utility class is intended to make it easy to construct title strings (returned from the xref:rgcms.adoc#_rgcms_methods_reserved_manpage-title[`title()`] method).
+
+For example, it has overloaded versions of methods called `append()` and `concat()`.
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types.adoc
new file mode 100644
index 0000000..3c6e3d8
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types.adoc
@@ -0,0 +1,119 @@
+[[_rgcms_classes_value-types]]
+= Value Types
+: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/
+
+NOTE: TODO
+
+
+
+.JDK Classes
+[cols="1,1", options="header"]
+|===
+
+|Type
+|Description
+
+|`java.lang.Boolean`
+|
+
+|`java.lang.Character`
+|
+
+|`java.lang.Double`
+|
+
+|`java.lang.Float`
+|
+
+|`java.lang.Integer`
+|
+
+|`java.lang.Long`
+|
+
+|`java.lang.Short`
+|
+
+|`java.lang.String`
+|
+
+|`java.math.BigDecimal`
+|
+
+|`java.math.BigInteger`
+|
+
+|`java.sql.Date`
+|
+
+|`java.sql.Time`
+|
+
+|`java.sql.Timestamp`
+|
+
+|`java.util.Date`
+|
+
+|===
+
+
+.JodaTime classes
+[cols="1,1", options="header"]
+|===
+
+|Type
+|Description
+
+|`org.joda.time.DateTime`
+|
+
+|`org.joda.time.LocalDateTime`
+|
+
+|`org.joda.time.LocalDate`
+|
+
+|===
+
+
+
+
+.Isis Applib classes
+[cols="1,1", options="header"]
+|===
+
+|Type
+|Description
+
+|`o.a.i.applib.value.` +
+`Blob`
+|
+
+|`o.a.i.applib.value.` +
+`Clob`
+|
+
+|`o.a.i.applib.value.` +
+`Color`
+|
+
+|`o.a.i.applib.value.` +
+`Money`
+|
+
+|`o.a.i.applib.value.` +
+`Password`
+|
+
+|===
+
+
+
+include::_rgcms_classes_value-types_manpage-Blob.adoc[leveloffset=+1]
+include::_rgcms_classes_value-types_manpage-Clob.adoc[leveloffset=+1]
+include::_rgcms_classes_value-types_manpage-Color.adoc[leveloffset=+1]
+include::_rgcms_classes_value-types_manpage-Money.adoc[leveloffset=+1]
+include::_rgcms_classes_value-types_manpage-Password.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_manpage-Blob.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_manpage-Blob.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_manpage-Blob.adoc
new file mode 100644
index 0000000..c254bd3
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_manpage-Blob.adoc
@@ -0,0 +1,8 @@
+[[_rgcms_classes_value-types_manpage-Blob]]
+= `Blob`
+: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/
+
+
+NOTE: TODO - the `org.apache.isis.applib.value.Blob` class.

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_manpage-Clob.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_manpage-Clob.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_manpage-Clob.adoc
new file mode 100644
index 0000000..ffd405d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_manpage-Clob.adoc
@@ -0,0 +1,8 @@
+[[_rgcms_classes_value-types_manpage-Clob]]
+= `Clob`
+: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/
+
+
+NOTE: TODO - the `org.apache.isis.applib.value.Clob` class.

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_manpage-Color.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_manpage-Color.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_manpage-Color.adoc
new file mode 100644
index 0000000..7bbb02b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_manpage-Color.adoc
@@ -0,0 +1,8 @@
+[[_rgcms_classes_value-types_manpage-Color]]
+= `Color`
+: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/
+
+
+NOTE: TODO - the `org.apache.isis.applib.value.Color` class.

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_manpage-Money.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_manpage-Money.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_manpage-Money.adoc
new file mode 100644
index 0000000..aaf61cc
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_manpage-Money.adoc
@@ -0,0 +1,8 @@
+[[_rgcms_classes_value-types_manpage-Money]]
+= `Money`
+: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/
+
+
+NOTE: TODO - the `org.apache.isis.applib.value.Money` class.

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_manpage-Password.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_manpage-Password.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_manpage-Password.adoc
new file mode 100644
index 0000000..a4c11ec
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_manpage-Password.adoc
@@ -0,0 +1,8 @@
+[[_rgcms_classes_value-types_manpage-Password]]
+= `Password`
+: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/
+
+
+NOTE: TODO

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods.adoc
new file mode 100644
index 0000000..dccbf0b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods.adoc
@@ -0,0 +1,17 @@
+[[_rgcms_methods]]
+= Methods
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The Apache Isis metamodel is built up from declaratively (ie, xref:rgant.adoc#_rgant[annotations]) and imperatively, from "supporting" methods and other reserved methods.
+
+This chapter documents the supporting methods and the reserved methods.  It also documents (separately) the reserved methods that act as callback hooks into the persistence lifecycle of domain entities.
+
+
+include::_rgcms_methods_prefixes.adoc[leveloffset=+1]
+include::_rgcms_methods_reserved.adoc[leveloffset=+1]
+include::_rgcms_methods_lifecycle.adoc[leveloffset=+1]
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle.adoc
new file mode 100644
index 0000000..c1072b7
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle.adoc
@@ -0,0 +1,102 @@
+[[_rgcms_methods_lifecycle]]
+= Lifecycle Methods
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+
+The lifecycle callback methods notify a domain entity about its interaction within the persistence lifecycle.  For example, the entity is notified immediately prior to being persisted, or when it is about to be updated.
+
+[WARNING]
+====
+Note that these callbacks are fired by Apache Isis rather than JDO.  In the future we may deprecate them because there are better mechanisms available using listeners/subscribers:
+
+* in Isis 1.9.0 and earlier, you may therefore want to consider using the JDO API directly to set up a lifecycle
+listener; see xref:rgcms.adoc#_rgcms_methods_lifecycle_jdo-api[here] for further discussion.
+
+* alternatively, you can use a subscriber for the xref:rgcms.adoc#_rgcms_classes_lifecycleevent[lifecycle event]s fired in Isis.
+====
+
+The lifecycle callback methods supported by Isis are:
+
+.Lifecycle methods (partial support)
+[cols="1,4a", options="header"]
+|===
+
+|Method
+|Description
+
+|xref:rgcms.adoc#_rgcms_methods_lifecycle_manpage-created[`created()`]
+|called when an object has just been created using xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer[`newTransientInstance()`]
+
+|xref:rgcms.adoc#_rgcms_methods_lifecycle_manpage-loaded[`loaded()`]
+|called when a (persistent) object has just been loaded from the object store.
+
+|xref:rgcms.adoc#_rgcms_methods_lifecycle_manpage-persisted[`persisted()`]
+|called when object has just been persisted from the object store.
+
+|xref:rgcms.adoc#_rgcms_methods_lifecycle_manpage-persisting[`persisting()`]
+|called when a (not-yet-persistent) object is just about to be persisted from the object store
+
+|xref:rgcms.adoc#_rgcms_methods_lifecycle_manpage-removed[`removed()`]
+|called when a (persistent) object has just been deleted from the object store
+
+|xref:rgcms.adoc#_rgcms_methods_lifecycle_manpage-removing[`removing()`]
+|called when a (persistent) object is just about to be deleted from the object store
+
+|xref:rgcms.adoc#_rgcms_methods_lifecycle_manpage-updated[`updated()`]
+|called when a (persistent) object has just been updated in the object store
+
+|xref:rgcms.adoc#_rgcms_methods_lifecycle_manpage-updating[`updating()`]
+|called when a (persistent) object is just about to be updated in the object store
+
+|===
+
+
+
+Some lifecycle methods have been deprecated:
+
+.Deprecated lifecycle methods
+[cols="1,4a", options="header"]
+|===
+
+|Method
+|Notes
+
+|`deleted()`
+|Replaced by xref:rgcms.adoc#_rgcms_methods_lifecycle_manpage-removed[`removed()`]
+
+|`deleting()`
+|Replaced by xref:rgcms.adoc#_rgcms_methods_lifecycle_manpage-removing[`removing()`]
+
+|`loading()`
+|callback for when the (persistent) object is just about to be loaded from the object store. +
+
+[WARNING]
+====
+This method is never called.
+====
+
+|`saved()`
+|Replaced by xref:rgcms.adoc#_rgcms_methods_lifecycle_manpage-persisted[`persisted()`]
+
+|`saving()`
+|Replaced by xref:rgcms.adoc#_rgcms_methods_lifecycle_manpage-persisting[`persisting()`]
+
+|===
+
+
+
+
+include::_rgcms_methods_lifecycle_manpage-created.adoc[leveloffset=+1]
+include::_rgcms_methods_lifecycle_manpage-loaded.adoc[leveloffset=+1]
+include::_rgcms_methods_lifecycle_manpage-persisted.adoc[leveloffset=+1]
+include::_rgcms_methods_lifecycle_manpage-persisting.adoc[leveloffset=+1]
+include::_rgcms_methods_lifecycle_manpage-removed.adoc[leveloffset=+1]
+include::_rgcms_methods_lifecycle_manpage-removing.adoc[leveloffset=+1]
+include::_rgcms_methods_lifecycle_manpage-updated.adoc[leveloffset=+1]
+include::_rgcms_methods_lifecycle_manpage-updating.adoc[leveloffset=+1]
+
+include::_rgcms_methods_lifecycle_jdo-api.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_jdo-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_jdo-api.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_jdo-api.adoc
new file mode 100644
index 0000000..407487d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_jdo-api.adoc
@@ -0,0 +1,53 @@
+[[_rgcms_methods_lifecycle_jdo-api]]
+= Using the JDO API
+: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/
+
+
+
+As an alternative to relying on Apache Isis to call lifecycle callback methods, you could instead use the JDO link:http://www.datanucleus.org/products/datanucleus/jdo/lifecycle_callbacks.html[lifecycle listener] API directly.
+
+[NOTE]
+====
+We may decide to deprecate the Apache Isis callbacks in the future because they merely duplicate this functionality already available in JDO.
+====
+
+You can gain access to the relevant JDO API using the xref:rgsvc.adoc#_rgsvc-api_IsisJdoSupport[`IsisJdoSupport`] domain service.
+
+For example:
+
+[source,java]
+----
+@RequestScoped                                                   // <1>
+@DomainService(nature=NatureOfService.DOMAIN)
+public class ObjectChangedListenerService
+        implements javax.jdo.listener.StoreLifecycleListener {   // <2>
+    @Programmatic
+    @PostConstruct
+    public void init() {
+        getPmFactory().addInstanceLifecycleListener(this);
+    }
+    @Programmatic
+    @PreDestroy
+    public void tidyUp() {
+        getPmFactory().removeInstanceLifecycleListener(this);
+    }
+    private PersistenceManager getPersistenceManager() {
+        return jdoSupport.getPersistenceManager();               // <3>
+    }
+    @Programmatic
+    public void preStore (InstanceLifecycleEvent event) { ... }
+    @Programmatic
+    public void postStore (InstanceLifecycleEvent event) { ... }
+    @Inject
+    IsisJdoSupport jdoSupport;
+}
+----
+<1> must be `@RequestScoped` because we register on the `PersistenceManager`, which is different for each request.
+<2> implement whichever callback lifecycle listeners are of interest
+<3> use the injected xref:rgsvc.adoc#_rgsvc-api_IsisJdoSupport[`IsisJdoSupport`] service to obtain the `PersistenceManager`.
+
+Note that it isn't possible to register on the `PersistenceManagerFactory` because listeners cannot be attached once a persistence session has been created (which it will have been when the service's `@PostConstruct` method is called).
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-created.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-created.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-created.adoc
new file mode 100644
index 0000000..38b62a4
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-created.adoc
@@ -0,0 +1,17 @@
+[[_rgcms_methods_reserved_manpage-created]]
+= `created()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+The `created()` lifecycle callback method is called when an object has just been created using xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer[`newTransientInstance()`]
+
+
+[TIP]
+====
+Alternatively, consider using a xref:rgsvc.adoc#_rgsvc-api_EventBusService[event bus] xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractSubscriber[subscriber] on the xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-ObjectCreatedEvent[`ObjectCreatedEvent`].
+====
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-loaded.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-loaded.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-loaded.adoc
new file mode 100644
index 0000000..0c339b4
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-loaded.adoc
@@ -0,0 +1,15 @@
+[[_rgcms_methods_reserved_manpage-loaded]]
+= `loaded()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The `loaded()` lifecycle callback method is called when a (persistent) object has just been loaded from the object store.
+
+
+[TIP]
+====
+Alternatively, consider using a xref:rgsvc.adoc#_rgsvc-api_EventBusService[event bus] xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractSubscriber[subscriber] on the xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-ObjectLoadedEvent[`ObjectLoadedEvent`].
+====

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-persisted.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-persisted.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-persisted.adoc
new file mode 100644
index 0000000..b3b832a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-persisted.adoc
@@ -0,0 +1,16 @@
+[[_rgcms_methods_reserved_manpage-persisted]]
+= `persisted()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The `persisted()` lifecycle callback method is called when object has just been persisted from the object store.
+
+See also xref:rgcms.adoc#_rgcms_methods_lifecycle_manpage-persisting[`persisting()`].
+
+[TIP]
+====
+Alternatively, consider using a xref:rgsvc.adoc#_rgsvc-api_EventBusService[event bus] xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractSubscriber[subscriber] on the xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-ObjectPersistedEvent[`ObjectPersistedEvent`].
+====

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-persisting.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-persisting.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-persisting.adoc
new file mode 100644
index 0000000..be1fe41
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-persisting.adoc
@@ -0,0 +1,16 @@
+[[_rgcms_methods_reserved_manpage-persisting]]
+= `persisting()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The `persisting()` lifecycle callback method is called when a (not-yet-persistent) object is just about to be persisted from the object store
+
+See also xref:rgcms.adoc#_rgcms_methods_lifecycle_manpage-persisted[`persisted()`].
+
+[TIP]
+====
+Alternatively, consider using a xref:rgsvc.adoc#_rgsvc-api_EventBusService[event bus] xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractSubscriber[subscriber] on the xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-ObjectPersistingEvent[`ObjectPersistingEvent`].
+====

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-removed.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-removed.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-removed.adoc
new file mode 100644
index 0000000..7f87193
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-removed.adoc
@@ -0,0 +1,16 @@
+[[_rgcms_methods_reserved_manpage-removed]]
+= `removed()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The `removed()` lifecycle callback method is called when a (persistent) object has just been deleted from the object store
+
+See also xref:rgcms.adoc#_rgcms_methods_lifecycle_manpage-removing[`removing()`].
+
+[TIP]
+====
+Alternatively, consider using a xref:rgsvc.adoc#_rgsvc-api_EventBusService[event bus] xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractSubscriber[subscriber] on the xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-ObjectRemovedEvent[`ObjectRemovedEvent`].
+====

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-removing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-removing.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-removing.adoc
new file mode 100644
index 0000000..cd57eee
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-removing.adoc
@@ -0,0 +1,16 @@
+[[_rgcms_methods_reserved_manpage-removing]]
+= `removing()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The `removing()` lifecycle callback method is called when a (persistent) object is just about to be deleted from the object store
+
+See also xref:rgcms.adoc#_rgcms_methods_lifecycle_manpage-removed[`removed()`].
+
+[TIP]
+====
+Alternatively, consider using a xref:rgsvc.adoc#_rgsvc-api_EventBusService[event bus] xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractSubscriber[subscriber] on the xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-ObjectRemovingEvent[`ObjectRemovingEvent`].
+====

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-updated.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-updated.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-updated.adoc
new file mode 100644
index 0000000..1fbc323
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-updated.adoc
@@ -0,0 +1,18 @@
+[[_rgcms_methods_reserved_manpage-updated]]
+= `updated()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+
+
+The `updated()` lifecycle callback method is called when a (persistent) object has just been updated in the object store
+
+See also xref:rgcms.adoc#_rgcms_methods_lifecycle_manpage-updating[`updating()`].
+
+[TIP]
+====
+Alternatively, consider using a xref:rgsvc.adoc#_rgsvc-api_EventBusService[event bus] xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractSubscriber[subscriber] on the xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-ObjectUpdatedEvent[`ObjectUpdatedEvent`].
+====

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-updating.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-updating.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-updating.adoc
new file mode 100644
index 0000000..455402f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-updating.adoc
@@ -0,0 +1,15 @@
+[[_rgcms_methods_reserved_manpage-updating]]
+= `updating()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+The `updating()` lifecycle callback method is called when a (persistent) object is just about to be updated in the object store
+
+See also xref:rgcms.adoc#_rgcms_methods_lifecycle_manpage-updated[`updated()`].
+
+[TIP]
+====
+Alternatively, consider using a xref:rgsvc.adoc#_rgsvc-api_EventBusService[event bus] xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractSubscriber[subscriber] on the xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-ObjectUpdatingEvent[`ObjectUpdatingEvent`].
+====

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes.adoc
new file mode 100644
index 0000000..1165905
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes.adoc
@@ -0,0 +1,219 @@
+[[_rgcms_methods_prefixes]]
+= Supporting Method Prefixes
+: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/
+
+
+
+Supporting methods are those that are associated with properties, collections and actions, providing additional imperative business rule checking and behaviour to be performed when the user interacts with those object members.
+
+This association is performed by name matching.  Thus, a property called "firstName", derived from a method `getFirstName()` may have supporting methods `hideFirstName()`, `disableFirstName()` and `validateFirstName()`.  Supporting methods are, therefore, each characterized by their own particular prefix.
+
+
+[NOTE]
+====
+Using name matching to associate supporting methods generally works very well, but of course if an object member's method is renamed, there's always the risk that the developer forgets to rename the supporting method; the supporting methods become "orphaned".
+
+Apache Isis checks for this automatically, and will fail-fast (fail to boot) if any orphaned methods are located.  A suitable error message is logged so that the issue can be easily diagnosed.
+====
+
+
+The table below lists the method prefixes that are recognized as part of Apache Isis' default programming model.
+
+.Recognized Method Prefixes
+[cols="2,1,1,1,1,1,4a", options="header"]
+|===
+
+|Prefix
+|Object
+|Property
+|Collection
+|Action
+|Action +
+Param
+|Description
+
+|xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-addTo[`addTo...()`]
+|
+|
+|Y
+|
+|
+|add object to a collection  +
+
+[NOTE]
+====
+Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer].
+====
+
+See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-removeFrom[`removeFrom...()`]`
+
+
+|xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-autoComplete[`autoComplete...()`]
+|
+|Y
+|
+|
+|Y
+|Return a list of matching elements for a property or an action parameter. +
+
+Alternatively, can specify for a class using xref:rgant.adoc#_rgant-DomainObject_autoCompleteRepository[`@DomainObject` +
+`#autoCompleteRepository`] +
+
+See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-choices[`choices...()`]
+
+|xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-choices[`choices...()`]
+|
+|Y
+|
+|
+|Y
+|Provide list of choices for a property or action parameter. +
+
+See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-autoComplete[`autoComplete...()`].
+
+|xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-clear[`clear...()`]
+|
+|Y
+|
+|
+|
+|Clear a property (set it to null). +
+
+Allows business logic to be placed apart from the setter. +
+
+See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-modify[`modify...()`]
+
+
+|xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-default[`default...()`]
+|
+|Y
+|
+|
+|Y
+|Default value for a property or an action parameter.
+
+|xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-disable[`disable...()`]
+|Y
+|Y
+|Y
+|Y
+|
+|Disables (makes read-only) a property, a collection or an action.
+
+|xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-get[`get...()`]
+|
+|Y
+|Y
+|
+|
+|Access the value of a property or collection. +
+
+See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-set[`set...()`].
+
+|xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-hide[`hide...()`]
+|
+|Y
+|Y
+|Y
+|
+|Hides a property, a collection or an action.
+
+|xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-modify[`modify...()`]
+|
+|Y
+|
+|
+|
+|Modify a property (set it to a non-null) value. +
+
+Allows business logic to be placed apart from the setter. +
+
+See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-clear[`clear...()`]`.
+
+|xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-removeFrom[`removeFrom...()`]
+|
+|
+|Y
+|
+|
+|remove object from a collection. +
+
+[NOTE]
+====
+Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer].
+====
+
+See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-addTo[`addTo...()`]`
+
+
+|xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-set[`set...()`]
+|
+|Y
+|Y
+|
+|
+|Sets the value of a property or a collection.
+
+|xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-validate[`validate...()`]
+|Y
+|
+|
+|Y
+|Y
+|Check that a proposed value of a property or a set of action parameters or a single action parameter is valid. +
+
+See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-validateAddTo[`validateAddTo...()`] and xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-validateRemoveFrom[`validateRemoveFrom...()`] to validate modifications to collections.
+
+|xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-validateAddTo[`validate +
+AddTo...()`]
+|
+|Y
+|
+|
+|
+|Check that a proposed object to add to a collection is valid. +
+
+[NOTE]
+====
+Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer].
+====
+
+See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-validateRemoveFrom[`validateRemoveFrom...()`], and xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-validate[`validate...()`] for properties and actions.
+
+|xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-validateRemoveFrom[`validate +
+RemoveFrom...()`]
+|
+|Y
+|
+|
+|
+|Check that a proposed object to remove from a collection is valid. +
+
+[NOTE]
+====
+Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer].
+====
+
+See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-validateAddTo[`validateAddTo...()`], and xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-validate[`validate...()`] for properties and actions.
+
+|===
+
+
+
+include::_rgcms_methods_prefixes_manpage-addTo.adoc[leveloffset=+1]
+include::_rgcms_methods_prefixes_manpage-autoComplete.adoc[leveloffset=+1]
+include::_rgcms_methods_prefixes_manpage-choices.adoc[leveloffset=+1]
+include::_rgcms_methods_prefixes_manpage-clear.adoc[leveloffset=+1]
+include::_rgcms_methods_prefixes_manpage-default.adoc[leveloffset=+1]
+include::_rgcms_methods_prefixes_manpage-disable.adoc[leveloffset=+1]
+include::_rgcms_methods_prefixes_manpage-get.adoc[leveloffset=+1]
+include::_rgcms_methods_prefixes_manpage-hide.adoc[leveloffset=+1]
+include::_rgcms_methods_prefixes_manpage-modify.adoc[leveloffset=+1]
+include::_rgcms_methods_prefixes_manpage-removeFrom.adoc[leveloffset=+1]
+include::_rgcms_methods_prefixes_manpage-set.adoc[leveloffset=+1]
+include::_rgcms_methods_prefixes_manpage-validate.adoc[leveloffset=+1]
+include::_rgcms_methods_prefixes_manpage-validateAddTo.adoc[leveloffset=+1]
+include::_rgcms_methods_prefixes_manpage-validateRemoveFrom.adoc[leveloffset=+1]
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-addTo.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-addTo.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-addTo.adoc
new file mode 100644
index 0000000..15f140d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-addTo.adoc
@@ -0,0 +1,37 @@
+[[_rgcms_methods_prefixes_manpage-addTo]]
+= `addTo...()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The `addTo...()` supporting method is called whenever an object is added to a collection. Its purpose is to allow additional business logic to be performed.
+
+
+[NOTE]
+====
+Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer].  The suggested workaround is to simply define an action.
+====
+
+
+For example:
+
+[source,java]
+----
+public class LibraryMember {
+    public SortedSet<Book> getBorrowed() { ... }
+    public void setBorrowed(SortedSet<Book> borrowed) { ... }
+    public void addToBorrowed(Book book) {
+        getBorrowed().add(book);                                              // <1>
+        reminderService.addReminder(this, book, clock.today().plusDays(21));  // <2>
+    }
+    public void removeFromBorrowed(Book book) { ... }
+    ...
+}
+----
+<1> update the collection
+<2> perform some additional business logic
+
+
+See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-removeFrom[`removeFrom...()`]`

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-autoComplete.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-autoComplete.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-autoComplete.adoc
new file mode 100644
index 0000000..5dbb7fb
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-autoComplete.adoc
@@ -0,0 +1,96 @@
+[[_rgcms_methods_prefixes_manpage-autoComplete]]
+= `autoComplete...()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The `autoComplete...()` supporting method is called for action parameters and for properties to find objects from a drop-down list box.  The use case is when the number of candidate objects is expected to be large, so the user is required to enter some characters to narrow the search down.
+
+[TIP]
+====
+If the number of candidate objects is comparatively small, then use xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-choices[`choices...()`] supporting method instead.
+====
+
+The signature of the supporting method depends on whether it is for a parameter or a property.
+
+
+== Parameters
+
+For an action parameter in (0-based) position _N_, and of type `T`, the signature is:
+
+[source,java]
+----
+public List<T> autoCompleteNXxx(String search) { ... }
+----
+
+It is also valid to return `T[]`, a `Set<T>` or a `Collection<T>`.
+
+
+For example:
+
+[source,java]
+----
+public class ShoppingCartItem {
+    @Property(editing=Editing.DISABLED)
+    public Product getProduct() { ... }
+    public void setProduct(Product product) { ... }
+
+    @Property(editing=Editing.DISABLED)
+    public int getQuantity() { ... }
+    public void setQuantity(int quantity) { ... }
+
+    @Action(semantics=SemanticsOf.IDEMPOTENT)
+    public ShoppingCartItem updateProduct(
+        Product product,
+        @ParameterLayout(named="Quantity")
+        final int quantity) {
+        setProduct(product);
+        setQuantity(quantity);
+    }
+    public Collection<Product> autoComplete0UpdateProduct(  // <1>
+        @MinLength(3) String search                         // <2>
+    ) {
+        ...
+    }
+    ...
+}
+----
+<1> `product` is the 0th argument of the action.
+<2> the xref:rgant.adoc#_rgant-MinLength[`@MinLength`] annotation specifies the minimum number of characters that must be entered before a search is performed for matching objects
+
+
+
+
+
+== Properties
+
+For a property of type `T`, the signature is:
+
+[source,java]
+----
+public List<T> autoCompleteXxx(String search) { ... }
+----
+
+(As for action parameters) it is also valid to return `T[]`, a `Set<T>` or a `Collection<T>`.
+
+For example:
+
+[source,java]
+----
+public class ShoppingCartItem {
+    public Product getProduct() { ... }
+    public void setProduct(Product product) { ... }
+
+    public Collection<Product> autoCompleteProduct(
+        @MinLength(3) String search                     // <1>
+    ) {
+        ...
+    }
+    ...
+}
+----
+<1> the xref:rgant.adoc#_rgant-MinLength[`@MinLength`] annotation specifies the minimum number of characters that must be entered before a search is performed for matching objects
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-choices.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-choices.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-choices.adoc
new file mode 100644
index 0000000..cf66fdc
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-choices.adoc
@@ -0,0 +1,143 @@
+[[_rgcms_methods_prefixes_manpage-choices]]
+= `choices...()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The `choices...()` supporting method is called for both action parameters and for properties, to find objects from a drop-down list box.  Unlike xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-autoComplete[`autoComplete...()`], the use case is when the number of objects is comparatively small and can be selected from a drop-down without any additional filtering.
+
+The signature of the supporting method depends on whether it is for an action parameter or a property.
+
+
+== Parameters
+
+For an action parameter in (0-based) position _N_, and of type `T`, the signature is:
+
+[source,java]
+----
+public Collection<T> choicesNXxx() { ... }
+----
+
+
+For example:
+
+[source,java]
+----
+public class ShoppingCartItem {
+    @Property(editing=Editing.DISABLED)
+    public Product getProduct() { ... }
+    public void setProduct(Product product) { ... }
+
+    @Property(editing=Editing.DISABLED)
+    public int getQuantity() { ... }
+    public void setQuantity(int quantity) { ... }
+
+    @Action(semantics=SemanticsOf.IDEMPOTENT)
+    public ShoppingCartItem updateProduct(
+        Product product,
+        @ParameterLayout(named="Quantity")
+        final Integer quantity) {
+        setProduct(product);
+        setQuantity(quantity);
+    }
+    public Collection<Integer> choices1UpdateProduct() {
+        return Arrays.asList(1,2,3,5,10,25,50,100);
+    }
+    ...
+}
+----
+
+
+=== Dependent Choices
+
+Action parameters also support the notion of dependent choices, whereby the list of choices is dependent upon the value of some other argument.
+
+An example can be found in the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp], whereby `ToDoItem`s are categorized and then can also be subcategorized:
+
+image::{_imagesdir}reference-methods/prefixes/choices/dependent.png[width="800px",link="{_imagesdir}reference-methods/prefixes/choices/dependent.png"]
+
+
+
+This functionality is actually implemented as a xref:ug.adoc#_ug_how-tos_contributed-members[contributed action], so the code for this is:
+
+[source,java]
+----
+@DomainService(nature = NatureOfService.VIEW_CONTRIBUTIONS_ONLY)
+public class UpdateCategoryContributions ... {
+    @ActionLayout(
+            describedAs = "Update category and subcategory"
+    )
+    @Action(semantics = SemanticsOf.IDEMPOTENT)
+    public Categorized updateCategory(
+            final Categorized item,                              // <1>
+            final Category category,
+            @Parameter(optionality = Optionality.OPTIONAL)
+            final Subcategory subcategory) {
+        item.setCategory(category);
+        item.setSubcategory(subcategory);
+        return item;
+    }
+    public List<Subcategory> choices2UpdateCategory(             // <2>
+            final Categorized item,                              // <3>
+            final Category category) {                           // <4>
+        return Subcategory.listFor(category);
+    }
+    ...
+}
+----
+<1> `ToDoItem` implements `Categorized`
+<2> subcategory is the 2-th argument (0-based)
+<3> the item contributed to
+<4> the category selected
+
+
+Dependent choices are not restricted to enums, however.  Going back to the shopping cart example shown above, the choices for the `quantity` parameter could be dependent upon the selected `Product`:
+
+
+[source,java]
+----
+public class ShoppingCartItem {
+    ...
+    @Action(semantics=SemanticsOf.IDEMPOTENT)
+    public ShoppingCartItem updateProduct(
+        Product product,
+        @ParameterLayout(named="Quantity")
+        final Integer quantity) {
+        setProduct(product);
+        setQuantity(quantity);
+    }
+    public Collection<Integer> choices1UpdateProduct(Product product) {
+        return productService.quantityChoicesFor(product);                 // <1>
+    }
+    ...
+}
+----
+<1> `productService` is a (fictitous) injected service that knows what the quantity choices should be for any given product
+
+
+== Properties
+
+For a property of type `T`, the signature is:
+
+[source,java]
+----
+public Collection<T> choicesXxx() { ... }
+----
+
+
+For example:
+
+[source,java]
+----
+public class ShoppingCartItem {
+    public Product getProduct() { ... }
+    public void setProduct(Product product) { ... }
+
+    public Collection<Product> choicesProduct() {
+        ...
+    }
+----
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-clear.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-clear.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-clear.adoc
new file mode 100644
index 0000000..2963210
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-clear.adoc
@@ -0,0 +1,32 @@
+[[_rgcms_methods_prefixes_manpage-clear]]
+= `clear...()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The `clear...()` supporting method is called -- instead of the setter -- whenever an (optional) property is to be set to `null`.  Its purpose is to allow additional business logic to be performed.
+
+
+For example:
+
+[source,java]
+----
+public class LibraryMember {
+    public Title getFavoriteTitle() { ... }
+    public void setFavoriteTitle(Title title) { ... }
+    public void modifyFavoriteTitle(Title title) { ... }
+    public void clearFavoriteTitle() {
+        if(getTitle() == null) { return; }
+        setFavoriteTitle(null);                         // <1>
+        titleFavoritesService.decrement(title);         // <2>
+    }
+    ...
+}
+----
+<1> update the property
+<2> perform some additional business logic
+
+
+See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-modify[`modify...()`]`

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-default.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-default.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-default.adoc
new file mode 100644
index 0000000..ec3ae75
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-default.adoc
@@ -0,0 +1,129 @@
+[[_rgcms_methods_prefixes_manpage-default]]
+= `default...()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The `default...()` supporting method is called for action parameters to return the initial argument value.  This may be some sensible default (eg today's date, or 0 or 1), or -- for an action that is modifying the state of an object -- might default to the current value of a corresponding property.
+
+The method is _also_ called for properties in the case when an object is newly instantiated using xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer[`DomainObjectContainer#newTransientInstance(...)`].  This is a much less common use case.  If a default is not specified then properties are initialized to a default based on their type (eg 0 or `false`).
+
+The signature of the supporting method depends on whether it is for an action parameter or a property.
+
+
+== Parameters
+
+For an action parameter in (0-based position n), and of type `T`, the signature is:
+
+[source,java]
+----
+public T defaultNXxx() { ... }
+----
+
+
+For example:
+
+[source,java]
+----
+public class ShoppingCartItem {
+    @Property(editing=Editing.DISABLED)
+    public Product getProduct() { ... }
+    public void setProduct(Product product) { ... }
+
+    @Property(editing=Editing.DISABLED)
+    public int getQuantity() { ... }
+    public void setQuantity(int quantity) { ... }
+
+    @Action(semantics=SemanticsOf.IDEMPOTENT)
+    public ShoppingCartItem updateProduct(
+        Product product,
+        @ParameterLayout(named="Quantity")
+        final Integer quantity) {
+        setProduct(product);
+        setQuantity(quantity);
+    }
+    public Product default0UpdateProduct() {    // <1>
+        return getProduct();
+    }
+    public int default1UpdateProduct() {        // <2>
+        return getQuantity();
+    }
+    ...
+}
+----
+<1> default the 0-th parameter using the current value of the `product` property
+<2> default the 1-th parameter using the current value of the `quantity` property
+
+
+
+Defaults are also supported (of course) for xref:ug.adoc#_ug_how-tos_contributed-members[contributed actions].  For example, here is a contributed action for updating category/subcategory of the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp]:
+
+[source,java]
+----
+@DomainService(nature = NatureOfService.VIEW_CONTRIBUTIONS_ONLY)
+public class UpdateCategoryContributions ... {
+    @ActionLayout(
+            describedAs = "Update category and subcategory"
+    )
+    @Action(semantics = SemanticsOf.IDEMPOTENT)
+    public Categorized updateCategory(
+            final Categorized item,                              // <1>
+            final Category category,
+            @Parameter(optionality = Optionality.OPTIONAL)
+            final Subcategory subcategory) {
+        item.setCategory(category);
+        item.setSubcategory(subcategory);
+        return item;
+    }
+    public Category default1UpdateCategory(                     // <2>
+            final Categorized item) {
+        return item != null? item.getCategory(): null;
+    }
+    public Subcategory default2UpdateCategory(                  // <3>
+            final Categorized item) {
+        return item != null? item.getSubcategory(): null;
+    }
+}
+----
+<1> `ToDoItem` implements `Categorized`
+<2> defaults the 1-th parameter using the item's `category` property
+<3> defaults the 2-th parameter using the item's `subcategory` property
+
+
+
+
+
+== Properties
+
+For a property of type `T`, the signature is:
+
+[source,java]
+----
+public T defaultXxx() { ... }
+----
+
+
+For example:
+
+[source,java]
+----
+public class ShoppingCartItem {
+    public int getQuantity() { ... }
+    public void setQuantity(int quantity) { ... }
+
+    public int defaultProduct() {
+        return 1;
+    }
+----
+
+
+=== Alternatives
+
+There are, in fact, two other ways to set properties of a newly instantiated object to default values.
+
+The first is to use the xref:rgcms.adoc#_rgcms_methods_lifecycle_manpage-created[`created()`] callback, called by the framework when xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer[`DomainObjectContainer#newTransientInstance(...)`] is called.  This method is called after any dependencies have been injected into the service.
+
+The second is more straightforward: simply initialize properties in the constructor.  However, this cannot use any injected services as they will not have been initialized.
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-disable.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-disable.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-disable.adoc
new file mode 100644
index 0000000..d5775cc
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-disable.adoc
@@ -0,0 +1,93 @@
+[[_rgcms_methods_prefixes_manpage-disable]]
+= `disable...()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+
+The `disable...()` supporting method is called for properties, collections and actions.  It allows the modification of the property/collection to be vetoed (ie made read-only) and to prevent the invocation of the action ("grey it out").
+
+[NOTE]
+====
+Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer]; they are always implicitly disabled.
+====
+
+Typically modification/invocation is vetoed based on the state of the domain object being interacted with, though it could be any reason at all (eg the current date/time of the interaction, or the state of some other related data such as stock levels, or the identity of the calling user).
+
+
+The reason for vetoing a modification/invocation is normally returned as a string.  However, Apache Isis' xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[i18n support] extends this so that reasons can be internationalized.
+
+
+
+== Actions
+
+For an action the signature of the supporting method is:
+
+[source,java]
+----
+public String disableXxx(...) { ... }
+----
+
+where the returned string is the reason the action invocation is vetoed (or `null` if not vetoed), and the supporting method takes the same parameter types as the action itself.
+
+
+
+For example:
+
+[source,java]
+----
+public class Customer {
+    public boolean isBlacklisted() { ... }
+
+    public Order placeOrder(
+            final Product product,
+            @ParameterLayout(named="Quantity")
+            final int quantity) {
+        ...
+    }
+    public String disablePlaceOrder(
+            final Product product,
+            final int quantity
+            ) {
+        return isBlacklisted()
+                    ? "Blacklisted customers cannot place orders"
+                    : null;
+    }
+    ...
+}
+----
+
+
+
+== Properties and Collections
+
+For both properties and collections the signature of the supporting method is:
+
+[source,java]
+----
+public String disableXxx() { ... }
+----
+
+where the returned string is the reason the modification is vetoed (or `null` if not vetoed).
+
+
+
+For example:
+
+[source,java]
+----
+public class Customer {
+    public boolean isBlacklisted() { ... }
+
+    public BigDecimal getCreditLimit() { ... }
+    public void setCreditLimit(BigDecimal creditLimit) { ... }
+    public String disableCreditLimit() {
+        return isBlacklisted()
+                    ? "Cannot change credit limit for blacklisted customers"
+                    : null;
+    }
+    ...
+}
+----

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-get.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-get.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-get.adoc
new file mode 100644
index 0000000..7ed187a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-get.adoc
@@ -0,0 +1,19 @@
+[[_rgcms_methods_prefixes_manpage-get]]
+= `get...()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The `get...()` prefix is simply the normal JavaBean getter prefix that denotes properties or collections.
+
+When Apache Isis builds its metamodel, it first searches for the getter methods, characterizing them as either properties or collections based on the return type.  It then refines the metamodel based on the presence of annotations and supporting methods.
+
+All remaining `public` methods (that do not use one of the Apache Isis prefixes) are interpreted as actions.
+
+Any methods "left over" that _do_ use one of the Apache Isis prefixes, are interpreted to be orphaned.  Apache Isis "fails-fast" and will not boot, instead printing an error message to the log so that the issue can be easily diagnosed.
+
+
+See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-set[`set...()`].
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-hide.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-hide.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-hide.adoc
new file mode 100644
index 0000000..73cce6d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-hide.adoc
@@ -0,0 +1,82 @@
+[[_rgcms_methods_prefixes_manpage-hide]]
+= `hide...()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The `hide...()` supporting method is called for properties, collections and actions.  It allows the property/collection to be completely hidden from view.
+
+It's comparatively rare for properties or collections to be imperatively hidden from view, but actions are sometimes hidden or shown visible (as opposed to being just xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-disable[disabled], ie greyed out).
+
+
+== Actions
+
+For an action the signature of the supporting method is either:
+
+[source,java]
+----
+public bool hideXxx(...) { ... }
+----
+
+where the supporting method takes the same parameter types as the action itself, or more simply:
+
+[source,java]
+----
+public bool hideXxx() { ... }
+----
+
+with no parameters at all.  Returning `true` will hide the action, returning `false` leaves it visible.
+
+
+For example:
+
+[source,java]
+----
+public class Customer {
+    public boolean isBlacklisted() { ... }
+
+    public Order placeOrder(
+            final Product product,
+            @ParameterLayout(named="Quantity")
+            final int quantity) {
+        ...
+    }
+    public boolean hidePlaceOrder() {
+        return isBlacklisted();
+    }
+    ...
+}
+----
+
+
+
+== Properties and Collections
+
+For both properties and collections the signature of the supporting method is:
+
+[source,java]
+----
+public boolean hideXxx() { ... }
+----
+
+where returning `true` will hide the property/collection, returning `false` leaves it visible.
+
+
+
+For example:
+
+[source,java]
+----
+public class Customer {
+    public boolean isBlacklisted() { ... }
+
+    public BigDecimal getCreditLimit() { ... }
+    public void setCreditLimit(BigDecimal creditLimit) { ... }
+    public boolean hideCreditLimit() {
+        return isBlacklisted();
+    }
+    ...
+}
+----

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-modify.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-modify.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-modify.adoc
new file mode 100644
index 0000000..faee86d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-modify.adoc
@@ -0,0 +1,37 @@
+[[_rgcms_methods_prefixes_manpage-modify]]
+= `modify...()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The `modify...()` supporting method is called -- instead of the setter -- whenever a property has been set to be set to a new value.  Its purpose is to allow additional business logic to be performed.
+
+
+For example:
+
+[source,java]
+----
+public class LibraryMember {
+    public Title getFavoriteTitle() { ... }
+    public void setFavoriteTitle(Title title) { ... }
+    public void modifyFavoriteTitle(Title title) {
+        if(getTitle() != null) {
+            titleFavoritesService.decrement(getTitle());    // <1>
+        }
+        setFavoriteTitle(title);                            // <2>
+        titleFavoritesService.decrement(title);             // <3>
+    }
+    public void clearFavoriteTitle() { ... }
+    ...
+}
+----
+<1> perform some additional business logic
+<2> update the property
+<3> perform some additional business logic
+
+
+See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-clear[`clear...()`]`
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-removeFrom.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-removeFrom.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-removeFrom.adoc
new file mode 100644
index 0000000..88ef934
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-removeFrom.adoc
@@ -0,0 +1,37 @@
+[[_rgcms_methods_prefixes_manpage-removeFrom]]
+= `removeFrom...()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The `removeFrom...()` supporting method is called whenever an object is removed from a collection. Its purpose is to allow additional business logic to be performed.
+
+
+[NOTE]
+====
+Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer].  The suggested workaround is to simply define an action.
+====
+
+
+For example:
+
+[source,java]
+----
+public class LibraryMember {
+    public SortedSet<Book> getBorrowed() { ... }
+    public void setBorrowed(SortedSet<Book> borrowed) { ... }
+    public void addToBorrowed(Book book) { ... }
+    public void removeFromBorrowed(Book book) {
+        getBorrowed().remove(book);                         // <1>
+        reminderService.removeReminder(this, book);         // <2>
+    }
+    ...
+}
+----
+<1> update the collection
+<2> perform some additional business logic
+
+
+See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-addTo[`addTo...()`]`

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-set.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-set.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-set.adoc
new file mode 100644
index 0000000..03d9f0d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-set.adoc
@@ -0,0 +1,13 @@
+[[_rgcms_methods_prefixes_manpage-set]]
+= `set...()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+
+The `set...()` prefix is simply the normal JavaBean setter prefix that denotes writeable properties or collections.
+
+
+See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-get[`get...()`].


[11/52] [abbrv] isis git commit: ISIS-1243: renamed rg.adoc to rgcms.adoc

Posted by mg...@apache.org.
ISIS-1243: renamed rg.adoc to rgcms.adoc


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/d0539e43
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/d0539e43
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/d0539e43

Branch: refs/heads/ISIS-1224-select2-v4
Commit: d0539e43feafd9fef12bc826962ab8a82234efdd
Parents: 1409af2
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Thu Dec 3 17:27:06 2015 +0000
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Dec 3 17:27:06 2015 +0000

----------------------------------------------------------------------
 .../_migration-notes_1.10.0-to-1.11.0.adoc      |   2 +-
 ...o-1.9.0_bootstrapping-using-AppManifest.adoc |   2 +-
 ..._fixture-scripts-specification-provider.adoc |   2 +-
 ...1.8.0-to-1.9.0_specify-all-dom-packages.adoc |   2 +-
 .../src/main/asciidoc/documentation.adoc        |   2 +-
 .../asciidoc/guides/_cg_asciidoc-templates.adoc |  28 +-
 .../asciidoc/guides/_cg_isis-maven-plugin.adoc  |   6 +-
 .../guides/_cg_isis-maven-plugin_xsd.adoc       |   8 +-
 .../src/main/asciidoc/guides/_rg_classes.adoc   |  23 --
 .../_rg_classes_AppManifest-bootstrapping.adoc  | 282 -------------------
 .../guides/_rg_classes_contributee.adoc         |  13 -
 ...es_contributee_manpage-HasTransactionId.adoc |  31 --
 ...classes_contributee_manpage-HasUserName.adoc |  27 --
 .../guides/_rg_classes_domainevent.adoc         |  76 -----
 ...domainevent_manpage-AbstractDomainEvent.adoc |  20 --
 ...s_domainevent_manpage-ActionDomainEvent.adoc |  20 --
 ...mainevent_manpage-CollectionDomainEvent.adoc |  21 --
 ...domainevent_manpage-PropertyDomainEvent.adoc |  17 --
 .../main/asciidoc/guides/_rg_classes_i18n.adoc  |  11 -
 ...classes_i18n_manpage-TranslatableString.adoc |  13 -
 .../guides/_rg_classes_lifecycleevent.adoc      | 130 ---------
 ...cleevent_manpage-AbstractLifecycleEvent.adoc |  27 --
 ...fecycleevent_manpage-ObjectCreatedEvent.adoc |  20 --
 ...ifecycleevent_manpage-ObjectLoadedEvent.adoc |  17 --
 ...cycleevent_manpage-ObjectPersistedEvent.adoc |  19 --
 ...ycleevent_manpage-ObjectPersistingEvent.adoc |  21 --
 ...ecycleevent_manpage-ObjectRemovingEvent.adoc |  20 --
 ...fecycleevent_manpage-ObjectUpdatedEvent.adoc |  21 --
 ...ecycleevent_manpage-ObjectUpdatingEvent.adoc |  22 --
 .../main/asciidoc/guides/_rg_classes_roles.adoc |  18 --
 .../guides/_rg_classes_roles_manpage-Dto.adoc   |  61 ----
 ...rg_classes_roles_manpage-HoldsUpdatedAt.adoc |  44 ---
 ...rg_classes_roles_manpage-HoldsUpdatedBy.adoc |  19 --
 .../_rg_classes_roles_manpage-Persistable.adoc  |  34 ---
 ..._rg_classes_roles_manpage-Timestampable.adoc |  23 --
 .../main/asciidoc/guides/_rg_classes_spec.adoc  | 108 -------
 .../main/asciidoc/guides/_rg_classes_super.adoc | 105 -------
 ...s_super_manpage-AbstractContainedObject.adoc |  32 ---
 ...sses_super_manpage-AbstractDomainObject.adoc |  14 -
 ...er_manpage-AbstractFactoryAndRepository.adoc |  15 -
 ...g_classes_super_manpage-AbstractService.adoc |  10 -
 ...lasses_super_manpage-AbstractSubscriber.adoc |  18 --
 ...classes_super_manpage-AbstractViewModel.adoc |  15 -
 ..._rg_classes_super_manpage-FixtureScript.adoc |  21 --
 ...rg_classes_super_manpage-FixtureScripts.adoc |  12 -
 .../asciidoc/guides/_rg_classes_uievent.adoc    |  62 ----
 ...classes_uievent_manpage-CssClassUiEvent.adoc |  22 --
 ..._rg_classes_uievent_manpage-IconUiEvent.adoc |  23 --
 ...rg_classes_uievent_manpage-TitleUiEvent.adoc |  22 --
 .../asciidoc/guides/_rg_classes_utility.adoc    |  16 --
 .../_rg_classes_utility_manpage-Enums.adoc      |   8 -
 ...classes_utility_manpage-ObjectContracts.adoc | 107 -------
 .../_rg_classes_utility_manpage-Reasons.adoc    |  31 --
 ..._rg_classes_utility_manpage-TitleBuffer.adoc |  13 -
 .../guides/_rg_classes_value-types.adoc         | 119 --------
 .../_rg_classes_value-types_manpage-Blob.adoc   |   8 -
 .../_rg_classes_value-types_manpage-Clob.adoc   |   8 -
 .../_rg_classes_value-types_manpage-Color.adoc  |   8 -
 .../_rg_classes_value-types_manpage-Money.adoc  |   8 -
 ...rg_classes_value-types_manpage-Password.adoc |   8 -
 .../src/main/asciidoc/guides/_rg_methods.adoc   |  17 --
 .../asciidoc/guides/_rg_methods_lifecycle.adoc  | 102 -------
 .../guides/_rg_methods_lifecycle_jdo-api.adoc   |  53 ----
 .../_rg_methods_lifecycle_manpage-created.adoc  |  17 --
 .../_rg_methods_lifecycle_manpage-loaded.adoc   |  15 -
 ..._rg_methods_lifecycle_manpage-persisted.adoc |  16 --
 ...rg_methods_lifecycle_manpage-persisting.adoc |  16 --
 .../_rg_methods_lifecycle_manpage-removed.adoc  |  16 --
 .../_rg_methods_lifecycle_manpage-removing.adoc |  16 --
 .../_rg_methods_lifecycle_manpage-updated.adoc  |  18 --
 .../_rg_methods_lifecycle_manpage-updating.adoc |  15 -
 .../asciidoc/guides/_rg_methods_prefixes.adoc   | 219 --------------
 .../_rg_methods_prefixes_manpage-addTo.adoc     |  37 ---
 ...g_methods_prefixes_manpage-autoComplete.adoc |  96 -------
 .../_rg_methods_prefixes_manpage-choices.adoc   | 143 ----------
 .../_rg_methods_prefixes_manpage-clear.adoc     |  32 ---
 .../_rg_methods_prefixes_manpage-default.adoc   | 129 ---------
 .../_rg_methods_prefixes_manpage-disable.adoc   |  93 ------
 .../_rg_methods_prefixes_manpage-get.adoc       |  19 --
 .../_rg_methods_prefixes_manpage-hide.adoc      |  82 ------
 .../_rg_methods_prefixes_manpage-modify.adoc    |  37 ---
 ..._rg_methods_prefixes_manpage-removeFrom.adoc |  37 ---
 .../_rg_methods_prefixes_manpage-set.adoc       |  13 -
 .../_rg_methods_prefixes_manpage-validate.adoc  | 113 --------
 ..._methods_prefixes_manpage-validateAddTo.adoc |  45 ---
 ...ods_prefixes_manpage-validateRemoveFrom.adoc |  45 ---
 .../asciidoc/guides/_rg_methods_reserved.adoc   |  58 ----
 .../_rg_methods_reserved_manpage-cssClass.adoc  |  46 ---
 .../_rg_methods_reserved_manpage-disable.adoc   | 102 -------
 .../_rg_methods_reserved_manpage-getId.adoc     |  19 --
 .../_rg_methods_reserved_manpage-hide.adoc      |  39 ---
 .../_rg_methods_reserved_manpage-iconName.adoc  |  36 ---
 .../_rg_methods_reserved_manpage-title.adoc     |  65 -----
 .../_rg_methods_reserved_manpage-validate.adoc  |  27 --
 .../main/asciidoc/guides/_rg_schema-aim.adoc    |  97 -------
 .../main/asciidoc/guides/_rg_schema-common.adoc | 103 -------
 .../src/main/asciidoc/guides/_rg_schema.adoc    |  24 --
 .../guides/_rgant-Collection_editing.adoc       |   2 +-
 .../src/main/asciidoc/guides/_rgant-Column.adoc |   2 +-
 .../_rgant-DomainObjectLayout_cssClassFa.adoc   |   2 +-
 ...gant-DomainObjectLayout_cssClassUiEvent.adoc |   2 +-
 .../_rgant-DomainObjectLayout_iconUiEvent.adoc  |   2 +-
 .../_rgant-DomainObjectLayout_titleUiEvent.adoc |   2 +-
 ...ant-DomainObject_autoCompleteRepository.adoc |   2 +-
 .../guides/_rgant-DomainObject_bounded.adoc     |   2 +-
 .../guides/_rgant-DomainObject_nature.adoc      |   2 +-
 ...t-DomainObject_persistingLifecycleEvent.adoc |   2 +-
 ...ant-DomainObject_removingLifecycleEvent.adoc |   2 +-
 ...ant-DomainObject_updatingLifecycleEvent.adoc |   2 +-
 .../main/asciidoc/guides/_rgant-MinLength.adoc  |   2 +-
 .../main/asciidoc/guides/_rgant-Parameter.adoc  |   2 +-
 .../asciidoc/guides/_rgant-PostConstruct.adoc   |   2 +-
 .../main/asciidoc/guides/_rgant-PreDestroy.adoc |   2 +-
 .../guides/_rgant-Property_editing.adoc         |   2 +-
 .../_rgant-ViewModelLayout_cssClassFa.adoc      |   2 +-
 .../asciidoc/guides/_rgant-XmlRootElement.adoc  |   6 +-
 .../guides/_rgcfg_configuring-core.adoc         |   4 +-
 ...s_disabling-persistence-by-reachability.adoc |   2 +-
 ...atanucleus_eagerly-registering-entities.adoc |   2 +-
 ...gcfg_configuring-datanucleus_properties.adoc |   2 +-
 .../guides/_rgcfg_specifying-components.adoc    |   8 +-
 .../main/asciidoc/guides/_rgcms_classes.adoc    |  23 ++
 ...rgcms_classes_AppManifest-bootstrapping.adoc | 282 +++++++++++++++++++
 .../guides/_rgcms_classes_contributee.adoc      |  13 +
 ...es_contributee_manpage-HasTransactionId.adoc |  31 ++
 ...classes_contributee_manpage-HasUserName.adoc |  27 ++
 .../guides/_rgcms_classes_domainevent.adoc      |  76 +++++
 ...domainevent_manpage-AbstractDomainEvent.adoc |  20 ++
 ...s_domainevent_manpage-ActionDomainEvent.adoc |  20 ++
 ...mainevent_manpage-CollectionDomainEvent.adoc |  21 ++
 ...domainevent_manpage-PropertyDomainEvent.adoc |  17 ++
 .../asciidoc/guides/_rgcms_classes_i18n.adoc    |  11 +
 ...classes_i18n_manpage-TranslatableString.adoc |  13 +
 .../guides/_rgcms_classes_lifecycleevent.adoc   | 130 +++++++++
 ...cleevent_manpage-AbstractLifecycleEvent.adoc |  27 ++
 ...fecycleevent_manpage-ObjectCreatedEvent.adoc |  20 ++
 ...ifecycleevent_manpage-ObjectLoadedEvent.adoc |  17 ++
 ...cycleevent_manpage-ObjectPersistedEvent.adoc |  19 ++
 ...ycleevent_manpage-ObjectPersistingEvent.adoc |  21 ++
 ...ecycleevent_manpage-ObjectRemovingEvent.adoc |  20 ++
 ...fecycleevent_manpage-ObjectUpdatedEvent.adoc |  21 ++
 ...ecycleevent_manpage-ObjectUpdatingEvent.adoc |  22 ++
 .../asciidoc/guides/_rgcms_classes_roles.adoc   |  18 ++
 .../_rgcms_classes_roles_manpage-Dto.adoc       |  61 ++++
 ...ms_classes_roles_manpage-HoldsUpdatedAt.adoc |  44 +++
 ...ms_classes_roles_manpage-HoldsUpdatedBy.adoc |  19 ++
 ...rgcms_classes_roles_manpage-Persistable.adoc |  34 +++
 ...cms_classes_roles_manpage-Timestampable.adoc |  23 ++
 .../asciidoc/guides/_rgcms_classes_spec.adoc    | 108 +++++++
 .../asciidoc/guides/_rgcms_classes_super.adoc   | 105 +++++++
 ...s_super_manpage-AbstractContainedObject.adoc |  32 +++
 ...sses_super_manpage-AbstractDomainObject.adoc |  14 +
 ...er_manpage-AbstractFactoryAndRepository.adoc |  15 +
 ...s_classes_super_manpage-AbstractService.adoc |  10 +
 ...lasses_super_manpage-AbstractSubscriber.adoc |  18 ++
 ...classes_super_manpage-AbstractViewModel.adoc |  15 +
 ...cms_classes_super_manpage-FixtureScript.adoc |  21 ++
 ...ms_classes_super_manpage-FixtureScripts.adoc |  12 +
 .../asciidoc/guides/_rgcms_classes_uievent.adoc |  62 ++++
 ...classes_uievent_manpage-CssClassUiEvent.adoc |  22 ++
 ...cms_classes_uievent_manpage-IconUiEvent.adoc |  23 ++
 ...ms_classes_uievent_manpage-TitleUiEvent.adoc |  22 ++
 .../asciidoc/guides/_rgcms_classes_utility.adoc |  16 ++
 .../_rgcms_classes_utility_manpage-Enums.adoc   |   8 +
 ...classes_utility_manpage-ObjectContracts.adoc | 107 +++++++
 .../_rgcms_classes_utility_manpage-Reasons.adoc |  31 ++
 ...cms_classes_utility_manpage-TitleBuffer.adoc |  13 +
 .../guides/_rgcms_classes_value-types.adoc      | 119 ++++++++
 ..._rgcms_classes_value-types_manpage-Blob.adoc |   8 +
 ..._rgcms_classes_value-types_manpage-Clob.adoc |   8 +
 ...rgcms_classes_value-types_manpage-Color.adoc |   8 +
 ...rgcms_classes_value-types_manpage-Money.adoc |   8 +
 ...ms_classes_value-types_manpage-Password.adoc |   8 +
 .../main/asciidoc/guides/_rgcms_methods.adoc    |  17 ++
 .../guides/_rgcms_methods_lifecycle.adoc        | 102 +++++++
 .../_rgcms_methods_lifecycle_jdo-api.adoc       |  53 ++++
 ...rgcms_methods_lifecycle_manpage-created.adoc |  17 ++
 ..._rgcms_methods_lifecycle_manpage-loaded.adoc |  15 +
 ...cms_methods_lifecycle_manpage-persisted.adoc |  16 ++
 ...ms_methods_lifecycle_manpage-persisting.adoc |  16 ++
 ...rgcms_methods_lifecycle_manpage-removed.adoc |  16 ++
 ...gcms_methods_lifecycle_manpage-removing.adoc |  16 ++
 ...rgcms_methods_lifecycle_manpage-updated.adoc |  18 ++
 ...gcms_methods_lifecycle_manpage-updating.adoc |  15 +
 .../guides/_rgcms_methods_prefixes.adoc         | 219 ++++++++++++++
 .../_rgcms_methods_prefixes_manpage-addTo.adoc  |  37 +++
 ...s_methods_prefixes_manpage-autoComplete.adoc |  96 +++++++
 ..._rgcms_methods_prefixes_manpage-choices.adoc | 143 ++++++++++
 .../_rgcms_methods_prefixes_manpage-clear.adoc  |  32 +++
 ..._rgcms_methods_prefixes_manpage-default.adoc | 129 +++++++++
 ..._rgcms_methods_prefixes_manpage-disable.adoc |  93 ++++++
 .../_rgcms_methods_prefixes_manpage-get.adoc    |  19 ++
 .../_rgcms_methods_prefixes_manpage-hide.adoc   |  82 ++++++
 .../_rgcms_methods_prefixes_manpage-modify.adoc |  37 +++
 ...cms_methods_prefixes_manpage-removeFrom.adoc |  37 +++
 .../_rgcms_methods_prefixes_manpage-set.adoc    |  13 +
 ...rgcms_methods_prefixes_manpage-validate.adoc | 113 ++++++++
 ..._methods_prefixes_manpage-validateAddTo.adoc |  45 +++
 ...ods_prefixes_manpage-validateRemoveFrom.adoc |  45 +++
 .../guides/_rgcms_methods_reserved.adoc         |  58 ++++
 ...rgcms_methods_reserved_manpage-cssClass.adoc |  46 +++
 ..._rgcms_methods_reserved_manpage-disable.adoc | 102 +++++++
 .../_rgcms_methods_reserved_manpage-getId.adoc  |  19 ++
 .../_rgcms_methods_reserved_manpage-hide.adoc   |  39 +++
 ...rgcms_methods_reserved_manpage-iconName.adoc |  36 +++
 .../_rgcms_methods_reserved_manpage-title.adoc  |  65 +++++
 ...rgcms_methods_reserved_manpage-validate.adoc |  27 ++
 .../main/asciidoc/guides/_rgcms_schema-aim.adoc |  97 +++++++
 .../asciidoc/guides/_rgcms_schema-common.adoc   | 103 +++++++
 .../src/main/asciidoc/guides/_rgcms_schema.adoc |  24 ++
 .../src/main/asciidoc/guides/_rgsvc-api.adoc    |   4 +-
 .../_rgsvc-api_ActionInvocationContext.adoc     |   2 +-
 .../guides/_rgsvc-api_BackgroundService.adoc    |   2 +-
 .../guides/_rgsvc-api_BookmarkService.adoc      |   2 +-
 .../guides/_rgsvc-api_ClockService.adoc         |   2 +-
 .../guides/_rgsvc-api_CommandContext.adoc       |   2 +-
 .../guides/_rgsvc-api_DeepLinkService.adoc      |   2 +-
 .../_rgsvc-api_DomainObjectContainer.adoc       |   2 +-
 ...mainObjectContainer_object-creation-api.adoc |   6 +-
 ..._DomainObjectContainer_presentation-api.adoc |   2 +-
 ...pi_DomainObjectContainer_validation-api.adoc |   4 +-
 .../guides/_rgsvc-api_EmailService.adoc         |   2 +-
 .../guides/_rgsvc-api_EventBusService.adoc      |   6 +-
 .../_rgsvc-api_FixtureScriptsDefault.adoc       |   6 +-
 .../guides/_rgsvc-api_GuiceBeanProvider.adoc    |   2 +-
 .../guides/_rgsvc-api_IsisJdoSupport.adoc       |   2 +-
 .../asciidoc/guides/_rgsvc-api_JaxbService.adoc |   6 +-
 .../guides/_rgsvc-api_MementoService.adoc       |   4 +-
 .../guides/_rgsvc-api_MetamodelService.adoc     |   2 +-
 .../guides/_rgsvc-api_QueryResultsCache.adoc    |   2 +-
 .../asciidoc/guides/_rgsvc-api_Scratchpad.adoc  |   2 +-
 .../asciidoc/guides/_rgsvc-api_SudoService.adoc |   2 +-
 .../guides/_rgsvc-api_WrapperFactory.adoc       |   6 +-
 .../guides/_rgsvc-api_XmlSnapshotService.adoc   |   2 +-
 .../src/main/asciidoc/guides/_rgsvc-spi.adoc    |   2 +-
 .../guides/_rgsvc-spi_AuditingService.adoc      |   6 +-
 .../_rgsvc-spi_BackgroundCommandService.adoc    |   2 +-
 .../_rgsvc-spi_ClassDiscoveryService.adoc       |   6 +-
 .../guides/_rgsvc-spi_CommandService.adoc       |   8 +-
 .../_rgsvc-spi_ContentNegotiationService.adoc   |   2 +-
 .../_rgsvc-spi_EmailNotificationService.adoc    |   2 +-
 .../_rgsvc-spi_ErrorReportingService.adoc       |   2 +-
 .../guides/_rgsvc-spi_EventSerializer.adoc      |   4 +-
 .../guides/_rgsvc-spi_ExceptionRecognizer.adoc  |   2 +-
 ...spi_FixtureScriptsSpecificationProvider.adoc |   2 +-
 .../guides/_rgsvc-spi_LocaleProvider.adoc       |   2 +-
 .../guides/_rgsvc-spi_PublishingService.adoc    |   8 +-
 .../_rgsvc-spi_RepresentationService.adoc       |   2 +-
 .../guides/_rgsvc-spi_TranslationService.adoc   |   2 +-
 .../guides/_rgsvc-spi_TranslationsResolver.adoc |   2 +-
 .../_tg_stop-scaffolding-start-coding.adoc      |  16 +-
 .../_ug_core-concepts_building-blocks.adoc      |   6 +-
 ...concepts_principles_apache-isis-vs_cqrs.adoc |   2 +-
 ...rinciples_apache-isis-vs_event-sourcing.adoc |   2 +-
 .../guides/_ug_faqs_restful-image-property.adoc |   2 +-
 .../guides/_ug_how-tos_business-rules.adoc      |   6 +-
 .../guides/_ug_how-tos_derived-members.adoc     |   4 +-
 .../guides/_ug_how-tos_domain-services.adoc     |   4 +-
 .../_ug_how-tos_drop-downs-and-defaults.adoc    |  14 +-
 ...aged-1-to-m-bidirectional-relationships.adoc |   2 +-
 ...ow-tos_ui-hints_object-titles-and-icons.adoc |   8 +-
 .../guides/_ug_how-tos_ui_are-you-sure.adoc     |   2 +-
 .../guides/_ugbtb_deployment_cmd-line.adoc      |   4 +-
 .../_ugbtb_more-advanced_decoupling_mixins.adoc |   2 +-
 ...ore-advanced_decoupling_pushing-changes.adoc |   4 +-
 .../guides/_ugbtb_more-advanced_i18n.adoc       |   2 +-
 ...ore-advanced_overriding-jdo-annotations.adoc |   2 +-
 .../_ugbtb_more-advanced_persisted-title.adoc   |   2 +-
 .../_ugbtb_more-advanced_view-models_jaxb.adoc  |   2 +-
 ...-advanced_view-models_programming-model.adoc |   2 +-
 ...btb_more-advanced_view-models_use-cases.adoc |   2 +-
 .../src/main/asciidoc/guides/_ugtst_aaa.adoc    |   2 +-
 ..._ugtst_integ-test-support_bootstrapping.adoc |   4 +-
 ..._ugtst_integ-test-support_typical-usage.adoc |   2 +-
 ..._ugtst_unit-test-support_contract-tests.adoc |   2 +-
 .../guides/_ugvw_features_blob-attachments.adoc |   2 +-
 .../src/main/asciidoc/guides/rg.adoc            |  12 +-
 277 files changed, 4097 insertions(+), 4097 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/_migration-notes_1.10.0-to-1.11.0.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/_migration-notes_1.10.0-to-1.11.0.adoc b/adocs/documentation/src/main/asciidoc/_migration-notes_1.10.0-to-1.11.0.adoc
index c2ecf93..65128a4 100644
--- a/adocs/documentation/src/main/asciidoc/_migration-notes_1.10.0-to-1.11.0.adoc
+++ b/adocs/documentation/src/main/asciidoc/_migration-notes_1.10.0-to-1.11.0.adoc
@@ -26,6 +26,6 @@ The default implementation is located in the `org.apache.isis.core:isis-core-sch
 `org.apache.isis.core.schema.services` package.
 
 If your application is bootstrapped using an `AppManifest` (recommended; ee
-xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[here]) then the `JaxbService` will automatically be discovered and
+xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[here]) then the `JaxbService` will automatically be discovered and
  registered.  However, if you are still using the older `isis.properties` configuration file to explicitly register
  services then you will need to add in this service.

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_bootstrapping-using-AppManifest.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_bootstrapping-using-AppManifest.adoc b/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_bootstrapping-using-AppManifest.adoc
index 9b09e2f..16fe795 100644
--- a/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_bootstrapping-using-AppManifest.adoc
+++ b/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_bootstrapping-using-AppManifest.adoc
@@ -124,7 +124,7 @@ public class MyAppAppManifest implements AppManifest {
 
 [TIP]
 ====
-For details of the usages of the other methods in this interface, see the xref:guides/rg.adoc#_rg_classes_AppManifest-bootstrapping[reference guide] documentation.
+For details of the usages of the other methods in this interface, see the xref:guides/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[reference guide] documentation.
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_fixture-scripts-specification-provider.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_fixture-scripts-specification-provider.adoc b/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_fixture-scripts-specification-provider.adoc
index 0b94749..21264e5 100644
--- a/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_fixture-scripts-specification-provider.adoc
+++ b/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_fixture-scripts-specification-provider.adoc
@@ -6,7 +6,7 @@
 
 
 
-The `FixtureScriptsSpecificationProvider` SPI service is an alternative to subclassing the xref:rg.adoc#_rg_classes_super_manpage-FixtureScripts[`FixtureScripts`] domain service.  The logic that would normally be in the subclass moves to the provider service instead, and the framework instantiates a fallback default instance, xref:rgsvc.adoc#_rgsvc-api_FixtureScriptsDefault[`FixtureScriptsDefault`].
+The `FixtureScriptsSpecificationProvider` SPI service is an alternative to subclassing the xref:rgcms.adoc#_rgcms_classes_super_manpage-FixtureScripts[`FixtureScripts`] domain service.  The logic that would normally be in the subclass moves to the provider service instead, and the framework instantiates a fallback default instance, xref:rgsvc.adoc#_rgsvc-api_FixtureScriptsDefault[`FixtureScriptsDefault`].
 
 This new design is optional; if you continue to provide your own subclass then everything will continue as before.  However the new design is more flexible and involves less code.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_specify-all-dom-packages.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_specify-all-dom-packages.adoc b/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_specify-all-dom-packages.adoc
index 21d71c3..7afeecc 100644
--- a/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_specify-all-dom-packages.adoc
+++ b/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_specify-all-dom-packages.adoc
@@ -10,7 +10,7 @@ Apache Isis automatically scans for certain classes on the classpath in order to
 
 * searching for classes annotated with xref:rgant.adoc#_rgant-DomainService[`@DomainService`].
 
-* searching for classes extending xref:rg.adoc#_rg_classes_super_manpage-FixtureScript[`FixtureScript`]
+* searching for classes extending xref:rgcms.adoc#_rgcms_classes_super_manpage-FixtureScript[`FixtureScript`]
 
 * searching for classes annotated with xref:rgant.adoc#_rgant-PersistenceCapable[`@PersistenceCapable`].
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/documentation.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/documentation.adoc b/adocs/documentation/src/main/asciidoc/documentation.adoc
index d119f8c..8d8b46c 100644
--- a/adocs/documentation/src/main/asciidoc/documentation.adoc
+++ b/adocs/documentation/src/main/asciidoc/documentation.adoc
@@ -72,7 +72,7 @@ pass:[<br/>]
 * link:./guides/rgant.html[Annotations^]
 * link:./guides/rgsvc.html[Domain Services^]
 * link:./guides/rgcfg.html[Configuration Properties^]
-* link:./guides/rg.html[Classes, Methods and Schema^]
+* link:./guides/rgcms.html[Classes, Methods and Schema^]
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_cg_asciidoc-templates.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_asciidoc-templates.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_asciidoc-templates.adoc
index 9b2cc8c..3366b1a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_cg_asciidoc-templates.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_asciidoc-templates.adoc
@@ -217,7 +217,7 @@ a hyperlink to the reference guide's catalogue of the Apache Isis configuration
 
 
 |`adrgcs`
-|pass:[<pre>xref:rg.adoc#_rg_classes_super_manpage-xxx[`xxx`\]</pre>]
+|pass:[<pre>xref:rgcms.adoc#_rgcms_classes_super_manpage-xxx[`xxx`\]</pre>]
 
 a hyperlink to the "man page" for a superclass, where:
 
@@ -225,14 +225,14 @@ a hyperlink to the "man page" for a superclass, where:
 
 for example:
 
-pass:[<pre>xref:rg.adoc#_rg_classes_super_manpage-AbstractService[`AbstractService`\]</pre>]
+pass:[<pre>xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractService[`AbstractService`\]</pre>]
 
-|xref:rg.adoc#_rg_classes_super_manpage-AbstractService[`AbstractService`]
+|xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractService[`AbstractService`]
 
 
 
 |`adrgcu`
-|pass:[<pre>xref:rg.adoc#_rg_classes_utility_manpage-xxx[`xxx`\]</pre>]
+|pass:[<pre>xref:rgcms.adoc#_rgcms_classes_utility_manpage-xxx[`xxx`\]</pre>]
 
 a hyperlink to the "man page" for a utility class, where:
 
@@ -240,14 +240,14 @@ a hyperlink to the "man page" for a utility class, where:
 
 for example:
 
-pass:[<pre>xref:rg.adoc#_rg_classes_utility_manpage-TitleBuffer[`TitleBuffer`\]</pre>]
+pass:[<pre>xref:rgcms.adoc#_rgcms_classes_utility_manpage-TitleBuffer[`TitleBuffer`\]</pre>]
 
-|xref:rg.adoc#_rg_classes_utility_manpage-TitleBuffer[`TitleBuffer`]
+|xref:rgcms.adoc#_rgcms_classes_utility_manpage-TitleBuffer[`TitleBuffer`]
 
 
 
 |`adrgcv`
-|pass:[<pre>xref:rg.adoc#_rg_classes_value-types_manpage-xxx[`xxx`\]</pre>]
+|pass:[<pre>xref:rgcms.adoc#_rgcms_classes_value-types_manpage-xxx[`xxx`\]</pre>]
 
 
 a hyperlink to the "man page" for an applib value class, where:
@@ -256,14 +256,14 @@ a hyperlink to the "man page" for an applib value class, where:
 
 for example:
 
-pass:[<pre>xref:rg.adoc#_rg_classes_value-types_manpage-Blob[`Blob`\]</pre>]
+pass:[<pre>xref:rgcms.adoc#_rgcms_classes_value-types_manpage-Blob[`Blob`\]</pre>]
 
-|xref:rg.adoc#_rg_classes_value-types_manpage-Blob[`Blob`]
+|xref:rgcms.adoc#_rgcms_classes_value-types_manpage-Blob[`Blob`]
 
 
 
 |`adrgmp`
-|pass:[<pre>xref:rg.adoc#_rg_methods_prefixes_manpage-xxx[`xxx...()`\]</pre>]
+|pass:[<pre>xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-xxx[`xxx...()`\]</pre>]
 
 a hyperlink to the "man page" for a prefixed method, where:
 
@@ -271,9 +271,9 @@ a hyperlink to the "man page" for a prefixed method, where:
 
 for example:
 
-pass:[<pre>xref:rg.adoc#_rg_methods_prefixes_manpage-disable[`disable...()`\]</pre>]
+pass:[<pre>xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-disable[`disable...()`\]</pre>]
 
-|xref:rg.adoc#_rg_methods_prefixes_manpage-disable[`disable...()`]
+|xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-disable[`disable...()`]
 
 
 
@@ -286,9 +286,9 @@ a hyperlink to the "man page" for a reserved method, where:
 
 for example:
 
-pass:[<pre>xref:rg.adoc#_rg_methods_reserved_manpage-title[`title()`\]</pre>]
+pass:[<pre>xref:rgcms.adoc#_rgcms_methods_reserved_manpage-title[`title()`\]</pre>]
 
-|xref:rg.adoc#_rg_methods_reserved_manpage-title[`title()`]
+|xref:rgcms.adoc#_rgcms_methods_reserved_manpage-title[`title()`]
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin.adoc
index 7af3cd5..b46dfdd 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin.adoc
@@ -15,18 +15,18 @@ Use to verify at build time that the metamodel of an application is valid.  This
 +
 Uses the xref:rgsvc.adoc#_rgsvc-api_JaxbService[`JaxbService`] to generate XSD schemas from any JAXB-annotated view models/DTOs. +
 +
-This is instead of and preferable to using the JAXB link:https://jaxb.java.net/2.2.4/docs/schemagen.html[schemagen] tool, because it uses the framework's support (via xref:rgant.adoc#_rgant-XmlJavaValueType[`@XmlJavaValueType`]) to translate any references to domain objects into ``OidDto``s (as defined by the Apache Isis xref:rg.adoc#_rg_schema-common[common schema]).
+This is instead of and preferable to using the JAXB link:https://jaxb.java.net/2.2.4/docs/schemagen.html[schemagen] tool, because it uses the framework's support (via xref:rgant.adoc#_rgant-XmlJavaValueType[`@XmlJavaValueType`]) to translate any references to domain objects into ``OidDto``s (as defined by the Apache Isis xref:rgcms.adoc#_rgcms_schema-common[common schema]).
 
 The `validate` goal is by default bound to the `test` phase of your application's `dom` sub-module, whereas the `xsd` goal defaults to the `generate-resources` phase of a completely separate `canonical` submodule.  An example can be found in the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] example app.
 
 
-Both goals require an xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[`AppManifest`] to point the plugin at, so that
+Both goals require an xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`] to point the plugin at, so that
 it knows how to bootstrap an Isis runtime.  This is discussed below, followed by sections on configuring the two goals.
 
 
 == `AppManifest`
 
-As noted in the introduction, both goals require an xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[`AppManifest`]
+As noted in the introduction, both goals require an xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`]
 to point the plugin at, so that it knows how to bootstrap an Isis runtime.
 
 This can be extremely minimal.  For example, the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp]'s

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin_xsd.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin_xsd.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin_xsd.adoc
index 6b87aca..179e4f4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin_xsd.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin_xsd.adoc
@@ -12,7 +12,7 @@ generate XSD schemas from any JAXB-annotated xref:ugbtb.adoc#_ugbtb_more-advance
 This is instead of and preferable to using the JAXB link:https://jaxb.java.net/2.2.4/docs/schemagen.html[schemagen]
 tool, because it uses the framework's support (via
 xref:rgant.adoc#_rgant-XmlJavaValueType[`@XmlJavaValueType`]) to translate any references to domain
-objects into ``OidDto``s (as defined by the Apache Isis xref:rg.adoc#_rg_schema-common[common schema]).
+objects into ``OidDto``s (as defined by the Apache Isis xref:rgcms.adoc#_rgcms_schema-common[common schema]).
 
 The `xsd` goal defines the following properties:
 
@@ -26,7 +26,7 @@ Defaults to `generated-resources/isis-xsd`
 
 * `separate` - (optional) whether to create separate directories for each JAXB-class. +
 +
-Defaults to `false`.  Most DTO classes will reference one another or the xref:rg.adoc#_rg_schema-common[common schema].  Normally it's fine to merge all these XSDs together.  This property, if set, results in each a separate directory for each generation of its XSD or XSDs.
+Defaults to `false`.  Most DTO classes will reference one another or the xref:rgcms.adoc#_rgcms_schema-common[common schema].  Normally it's fine to merge all these XSDs together.  This property, if set, results in each a separate directory for each generation of its XSD or XSDs.
 
 As a convenience to any (Java) consumers, the XSDs generated from the view models can then in turn be generated
 into DTOs.  The original view models and these DTOs are similar but not identical: while the view models can only be used
@@ -276,14 +276,14 @@ The `xjc` profile is defined as:
 <1> enabled _unless_ `skip.xjc` property specified
 <2> specifies the directory that the XSD schemas were generated to by the `isis-maven-plugin`
 <3> specify each of the XSDs to be processed
-<4> catalog file indicates the location of the referenced link:_rg_schema-common[common schema] XSDs.
+<4> catalog file indicates the location of the referenced link:_rgcms_schema-common[common schema] XSDs.
 <5> the `build-helper-maven-plugin` adds the Java source generated by the `xjc` plugin so that it can be compiled and
 packaged as any other code
 <6> the location that the `xjc` plugin generates its source code.
 
 
 The referenced `catalog.xml` file instructs the `xjc` plugin how to resolve referenced schema locations.  Only a
-reference for the Apache Isis link:_rg_schema-common[common schema] is likely to be needed:
+reference for the Apache Isis link:_rgcms_schema-common[common schema] is likely to be needed:
 
 [source,xml]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes.adoc
deleted file mode 100644
index 0479db0..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes.adoc
+++ /dev/null
@@ -1,23 +0,0 @@
-[[_rg_classes]]
-= Classes and Interfaces
-: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 chapter describes the usage of various classes and interfaces that are not otherwise associated with xref:rgsvc.adoc#_rgsvc-api[domain] xref:rgsvc.adoc#_rgsvc-spi[services], xref:ug.adoc#_ug_object-layout[object layout] or xref:rgcfg.adoc#_rgcfg[configuration].
-
-
-include::_rg_classes_AppManifest-bootstrapping.adoc[leveloffset=+1]
-include::_rg_classes_super.adoc[leveloffset=+1]
-include::_rg_classes_domainevent.adoc[leveloffset=+1]
-include::_rg_classes_uievent.adoc[leveloffset=+1]
-include::_rg_classes_lifecycleevent.adoc[leveloffset=+1]
-include::_rg_classes_value-types.adoc[leveloffset=+1]
-include::_rg_classes_utility.adoc[leveloffset=+1]
-include::_rg_classes_spec.adoc[leveloffset=+1]
-include::_rg_classes_i18n.adoc[leveloffset=+1]
-include::_rg_classes_contributee.adoc[leveloffset=+1]
-include::_rg_classes_roles.adoc[leveloffset=+1]
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_AppManifest-bootstrapping.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_AppManifest-bootstrapping.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_AppManifest-bootstrapping.adoc
deleted file mode 100644
index cbb1dae..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_AppManifest-bootstrapping.adoc
+++ /dev/null
@@ -1,282 +0,0 @@
-[[_rg_classes_AppManifest-bootstrapping]]
-= `AppManifest` (bootstrapping)
-: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 section describes how to implement the `AppManifest` interface to bootstrap both an Apache Isis web application, and also its integration tests.
-
-
-
-== API
-
-
-The `AppManifest` interface allows the constituent parts of an application to be defined programmatically, most specifically the packages that contain domain services and/or persistent entities.  Its API is defined as:
-
-[source,java]
-----
-public interface AppManifest {
-    public List<Class<?>> getModules();                         // <1>
-    public List<Class<?>> getAdditionalServices();              // <2>
-    public String getAuthenticationMechanism();                 // <3>
-    public String getAuthorizationMechanism();                  // <4>
-    public List<Class<? extends FixtureScript>> getFixtures();  // <5>
-    public Map<String,String> getConfigurationProperties();     // <6>
-}
-----
-<1> Must return a non-null list of classes, each of which representing the root of one of the modules containing services and possibly entities, which together makes up the running application.
-<2> If non-`null`, overrides the value of `isis.services` configuration property to specify a list of additional classes to be instantiated as domain services (over and above the domain services defined via `getModules()` method.
-<3> If non-`null`, overrides the value of `isis.authentication` configuration property to specify the authentication mechanism.
-<4> If non-`null`, overrides the value of `isis.authorization` configuration property to specify the authorization mechanism.
-<5> If non-`null`, overrides the value of `isis.fixtures` configuration property to specify a fixture script to be installed.
-<6> Overrides for any other configuration properties.
-
-The following sections describe each of these methods in a little more detail.
-
-
-
-
-=== `getModules()`
-
-The most significant method (the only one which must return a non-`null` value) is the `getModules()` method.  Each module is identified by a class; the framework simply uses that class' package as the root to search for domain services (annotated with xref:rgant.adoc#_rgant-DomainService[`@DomainService`]) and entities (annotated with xref:rgant.adoc#_rgant-PersistenceCapable[`@PersistenceCapable`]).  Generally there is one such module class per Maven module.
-
-A module class for a domain module might for example be defined as:
-
-[source,java]
-----
-package com.mycompany.myapp.dom;
-public final class MyAppDomainModule {
-    private MyAppDomainModule() {}
-}
-----
-
-This tells the framework that the package and subpackages under `com.mycompany.myapp.dom` should be searched for domain services and entities.
-
-As is perhaps apparent, the `getModules()` method replaces and overrides both the `isis.services.ServicesInstallerFromAnnotation.packagePrefix` key (usually found in the `isis.properties`  file) and also the`isis.persistor.datanucleus.RegisterEntities.packagePrefix` key (usually found in the `persistor_datanucleus.properties` file).  The value of the `isis.services-installer` configuration property is also ignored.
-
-For example, the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] defines the following:
-
-[source,java]
-----
-@Override
-public List<Class<?>> getModules() {
-    return Arrays.asList(
-            ToDoAppDomainModule.class,
-            ToDoAppFixtureModule.class,
-            ToDoAppAppModule.class,
-            org.isisaddons.module.audit.AuditModule.class,
-            org.isisaddons.module.command.CommandModule.class,
-            org.isisaddons.module.devutils.DevUtilsModule.class,
-            org.isisaddons.module.docx.DocxModule.class,
-            org.isisaddons.module.publishing.PublishingModule.class,
-            org.isisaddons.module.sessionlogger.SessionLoggerModule.class,
-            org.isisaddons.module.settings.SettingsModule.class,
-            org.isisaddons.wicket.gmap3.cpt.service.Gmap3ServiceModule.class
-    );
-}
-----
-
-As can be seen, the various (non-ASF) link:http://isisaddons.org[Isis Addons] modules also each provide a module class that can be easily referenced.
-
-
-=== `getAdditionalServices()`
-
-We normally we recommend that services are defined exclusively through `getModules()`, and that this method should therefore return an empty list.  However, there are certain use cases where the a service must be explicitly specified either because the service required does not (for whatever reason) have a xref:rgant.adoc#_rgant-DomainService[`@DomainService`] annotation.
-
-For example, the (non-ASF) http://github.com/isisaddons/isis-module-security[Isis addons' security] module (v1.9.0) allows the policy to evaluate conflicting permissions to be specified by explicitly registering either the `PermissionsEvaluationServiceAllowBeatsVeto` domain service or the `PermissionsEvaluationServiceVetoBeatsAllow` domain service:
-
-[source,java]
-----
-@Override
-public List<Class<?>> getAdditionalServices() {
-    return Arrays.asList(
-            org.isisaddons.module.security.dom.permission.PermissionsEvaluationServiceVetoBeatsAllow.class
-    );
-}
-----
-
-If this method returns a non-`null` value, then it overrides the value of `isis.services` configuration property.
-
-
-
-
-=== `getAuthenticationMechanism()`
-
-If non-`null`, this method specifies the authentication mechanism to use.  The valid values are currently `"shiro"`  or `"bypass"`.  If null is returned then the value of the `isis.authentication` configuration property (in `isis.properties` file) is used instead.
-
-See the xref:ugsec.adoc#[security guide] for further details on configuring shiro or bypass security.
-
-[NOTE]
-====
-This property is ignored for integration tests (which always uses the `"bypass"` mechanism).
-====
-
-
-
-=== `getAuthorizationMechanism()`
-
-If non-`null`, this method specifies the authorization mechanism to use.  The valid values are currently `"shiro"`  or `"bypass"`.  If null is returned then the value of the `isis.authorization` configuration property (in `isis.properties` file) is used instead.
-
-See the xref:ugsec.adoc#[security guide] for further details on configuring shiro or bypass security.
-
-[NOTE]
-====
-This property is ignored for integration tests (which always uses the `"bypass"` mechanism).
-====
-
-
-
-
-=== `getFixtures()`
-
-If non-`null`, this method specifies the fixture script(s) to be run on startup.  This is particularly useful when developing or demoing while using an in-memory database.
-
-For example:
-
-[source,java]
-----
-@Override
-public List<Class<? extends FixtureScript>> getFixtures() {
-    return Lists.newArrayList(todoapp.fixture.demo.DemoFixture.class);
-}
-----
-
-
-
-Note that in order for fixtures to be installed it is also necessary to set the `isis.persistor.datanucleus.install-fixtures` key to `true`.  This can most easily be done using the `getConfigurationProperties()` method, discussed below.
-
-
-
-=== `getConfigurationProperties()`
-
-This method allow arbitrary other configuration properties to be overridden.  One common use case is in conjunction with the `getFixtures()` method, discussed above:
-
-[source,java]
-----
-@Override
-public Map<String, String> getConfigurationProperties() {
-    Map<String, String> props = Maps.newHashMap();
-    props.put("isis.persistor.datanucleus.install-fixtures", "true");
-    return props;
-}
-----
-
-
-
-
-
-
-
-== Bootstrapping
-
-One of the primary goals of the `AppManifest` is to unify the bootstrapping of both integration tests and the webapp.  This requires that the integration tests and webapp can both reference the implementation.
-
-We strongly recommend using a `myapp-app` Maven module to hold the implementation of the `AppManifest`.  This Maven module can then also hold dependencies which are common to both integration tests and the webapp, specifically the `org.apache.isis.core:isis-core-runtime` and the `org.apache.isis.core:isis-core-wrapper` modules.
-
-We also strongly recommend that any application-layer domain services and view models (code that references persistent domain entities but that is not referenced back) is moved to this `myapp-app` module.  This will allow the architectural layering of the overall application to be enforced by Maven.
-
-What then remains is to update the bootstrapping code itself.
-
-
-=== Integration Tests
-
-Bootstrapping integration tests is still performed using the `IsisSystemForTest.Builder`, but very often the bootstrapping code can be substantially simplified (compared to not using an `AppManifest`, that is).
-
-For example, this is the bootstrapping code for the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype] looks something like:
-
-[source,java]
-----
-public class DomainAppSystemInitializer {
-    public static void initIsft() {
-        IsisSystemForTest isft = IsisSystemForTest.getElseNull();
-        if(isft == null) {
-            isft = new IsisSystemForTest.Builder()
-                    .withLoggingAt(org.apache.log4j.Level.INFO)
-                    .with(new MyAppAppManifest())
-                    .with(new IsisConfigurationForJdoIntegTests())
-                    .build()
-                    .setUpSystem();
-            IsisSystemForTest.set(isft);
-        }
-    }
-}
-----
-
-
-
-
-=== Webapps
-
-To bootstrap an Apache Isis webapp (using the xref:ugvw.adoc#[Wicket viewer]), there are two choices:
-
-* either specify the `AppManifest` by overriding the `IsisWicketApplication#newWicketModule()`, eg: +
-+
-[source,java]
-----
-@Override
-protected Module newIsisWicketModule() {
-    final Module isisDefaults = super.newIsisWicketModule();
-    ...
-    final Module overrides = new AbstractModule() {
-        @Override
-        protected void configure() {
-            ...
-            bind(AppManifest.class).toInstance(new MyAppAppManifest());
-        }
-    };
-    return Modules.override(isisDefaults).with(overrides);
-}
-----
-
-* alternatively update `isis.properties`, using the `isis.appManifest` key to specify the `AppManifest` implementation, eg: +
-+
-[source,ini]
-----
-isis.appManifest=domainapp.app.MyAppAppManifest
-----
-
-The first (programmatic) approach takes precedence over the second approach (configuration properties).
-
-[TIP]
-====
-If you use the `org.apache.isis.WebServer` class to launch your application from the xref:ugbtb.adoc#_ugbtb_deployment_cmd-line[command line], then note that you can specify the `AppManifest` using the `-m` (or `--manifest`) flag:
-
-[source,ini]
-----
-java org.apache.isis.WebServer -m com.mycompany.myapp.MyAppAppManifestWithFixtures
-----
-
-====
-
-
-
-
-
-
-
-
-
-
-== Subsidiary Goals
-
-There are a number of subsidiary goals of the `AppManifest` class (though as of v1.9.0 these have not yet implemented):
-
-* Allow different integration tests to run with different manifests.
-
-** Normally the running application is shared (on a thread-local) between integration tests. What the framework could do is to be intelligent enough to keep track of the manifest in use for each integration test and tear down the shared state if the "next" test uses a different manifest
-
-* Speed up bootstrapping by only scanning for classes annotated by `@DomainService` and `@PersistenceCapable` once.
-
-* Provide a programmatic way to contribute elements of `web.xml`.
-
-* Provide a programmatic way to configure Shiro security.
-
-* Anticipate the module changes forthcoming in Java 9.
-
-** Eventually we see that the `AppManifest` class acting as an "aggregator", with the list of modules will become Java 9 modules each advertising the types that they export.
-** It might even be possible for ``AppManifest``s to be switched on and off dynamically (eg if Java9 is compatible with OSGi, being one of the design goals).
-
-
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_contributee.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_contributee.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_contributee.adoc
deleted file mode 100644
index 78d9c5a..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_contributee.adoc
+++ /dev/null
@@ -1,13 +0,0 @@
-[[_rg_classes_contributee]]
-= Contributee
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-The interfaces listed in this chapter act as contributees; they allow domain services to contribute actions/properties/collections to any domain objects that implement these interfaces.
-
-
-include::_rg_classes_contributee_manpage-HasTransactionId.adoc[leveloffset=+1]
-include::_rg_classes_contributee_manpage-HasUserName.adoc[leveloffset=+1]
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_contributee_manpage-HasTransactionId.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_contributee_manpage-HasTransactionId.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_contributee_manpage-HasTransactionId.adoc
deleted file mode 100644
index c645745..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_contributee_manpage-HasTransactionId.adoc
+++ /dev/null
@@ -1,31 +0,0 @@
-[[_rg_classes_mixins_manpage-HasTransactionId]]
-= `HasTransactionId`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-The `HasTransactionId` interface is a mix-in for any domain objects that reference a transaction id, such as
-auditing entries or commands.
-
-The interface is defined is:
-
-[source,java]
-----
-public interface HasTransactionId {
-
-    public UUID getTransactionId();                             // <1>
-    public void setTransactionId(final UUID transactionId);
-}
-----
-<1> unique identifier (a GUID) of the transaction in which this interaction occurred.
-
-
-
-Modules that either have domain entity that implement and/or services that contribute this interface are:
-
-* (non-ASF) http://github.com/isisaddons/isis-module-audit[Isis addons' audit] module (`AuditEntry` entity, `AuditingServiceContributions` service)
-* (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module (`CommandJdo` entity, `CommandServiceJdoContributions` service)
-* (non-ASF) http://github.com/isisaddons/isis-module-publishing[Isis addons' publishing] module (`PublishedEvent` entity, `PublishingServiceContributions`)
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_contributee_manpage-HasUserName.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_contributee_manpage-HasUserName.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_contributee_manpage-HasUserName.adoc
deleted file mode 100644
index 1618b5c..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_contributee_manpage-HasUserName.adoc
+++ /dev/null
@@ -1,27 +0,0 @@
-[[_rg_classes_mixins_manpage-HasUserName]]
-= `HasUsername`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-The `HasUsername` interface is a mix-in for domain objects to be associated with a username.  Other services and modules can then contribute actions/collections to render such additional information relating to the activities of the user.
-
-The interface is defined is:
-
-[source,java]
-----
-public interface HasUsername {
-    public String getUsername();
-}
-----
-
-Modules that either have domain entity that implement and/or services that contribute this interface are:
-
-* (non-ASF) http://github.com/isisaddons/isis-module-security[Isis addons' security] module ( `ApplicationUser` entity, `HasUsernameContributions` service)
-* (non-ASF) http://github.com/isisaddons/isis-module-audit[Isis addons' audit] module (`AuditEntry` entity,
-* (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module's `CommandJdo` entity, `HasUsernameContributions` service)
-* (non-ASF) http://github.com/isisaddons/isis-module-publishing[Isis addons' publishing] module (`PublishedEvent` entity)
-* (non-ASF) http://github.com/isisaddons/isis-module-sessionlogger[Isis addons' sessionlogger] module (`SessionLogEntry` entity, `HasUsernameContributions` service)
-* (non-ASF) http://github.com/isisaddons/isis-module-settings[Isis addons' settings] module (`UserSettingJdo` entity)
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_domainevent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_domainevent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_domainevent.adoc
deleted file mode 100644
index 5efc7ae..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_domainevent.adoc
+++ /dev/null
@@ -1,76 +0,0 @@
-[[_rg_classes_domainevent]]
-= Domain Event Classes
-: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 section catalogues the various domain event classes defined by Apache Isis.
-
-These events are broadcast on the xref:rgsvc.adoc#_rgsvc-api_EventBusService[`EventBusService`].  The domain
-events are broadcast as a result of being specified in the xref:rgant.adoc#_rgant-Action_domainEvent[`@Action#domainEvent()`],  xref:rgant.adoc#_rgant-Property_domainEvent[`@Property#domainEvent()`] or xref:rgant.adoc#_rgant-Collection_domainEvent[`@Collection#domainEvent()`] attributes.
-
-They are listed in the table below.
-
-.Domain Event Classes
-[cols="2,4a,1,1", options="header"]
-|===
-
-|API
-|Maven Module +
-Impl'n (g: a:)
-|Implementation
-|Notes
-
-
-|xref:rg.adoc#_rg_classes_domainevent_manpage-AbstractDomainEvent[`o.a.i.applib.` +
-`AbstractDomainEvent`]
-|``o.a.i.core`` +
-``services.eventbus`` +
-``isis-core-applib``
-|(abstract class)
-|Superclass of the other domain events, listed below in this table.
-
-
-|xref:rg.adoc#_rg_classes_domainevent_manpage-ActionDomainEvent[`o.a.i.applib.` +
-`ActionDomainEvent`]
-|``o.a.i.core`` +
-``services.eventbus`` +
-``isis-core-applib``
-|(abstract class). +
-`ActionDomainEvent.Default` is the concrete implementation used if no `@Action#domainEvent` attribute is specified
-|Broadcast whenever there is an interaction (hide/disable/validate/pre-execute/post-execute) with an object's action.
-
-
-|xref:rg.adoc#_rg_classes_domainevent_manpage-CollectionDomainEvent[`o.a.i.applib.` +
-`CollectionDomainEvent`]
-|``o.a.i.core`` +
-``services.eventbus`` +
-``isis-core-applib``
-|(abstract class). +
-`CollectionDomainEvent.Default` is the concrete implementation used if no `@Collection#domainEvent` attribute
-is specified.
-|Broadcast whenever there is an interaction (hide/disable/validate/access) with an object's collection.
-
-
-|xref:rg.adoc#_rg_classes_domainevent_manpage-PropertyDomainEvent[`o.a.i.applib.` +
-`PropertyDomainEvent`]
-|``o.a.i.core`` +
-``services.eventbus`` +
-``isis-core-applib``
-|(abstract class). +
-`PropertyDomainEvent.Default` is the concrete implementation used if no `@Propert#domainEvent` attribute is specified
-|Broadcast whenever there is an interaction (hide/disable/validate/access) with an object's property.
-
-
-
-|===
-
-
-
-
-include::_rg_classes_domainevent_manpage-AbstractDomainEvent.adoc[leveloffset=+1]
-include::_rg_classes_domainevent_manpage-ActionDomainEvent.adoc[leveloffset=+1]
-include::_rg_classes_domainevent_manpage-CollectionDomainEvent.adoc[leveloffset=+1]
-include::_rg_classes_domainevent_manpage-PropertyDomainEvent.adoc[leveloffset=+1]
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_domainevent_manpage-AbstractDomainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_domainevent_manpage-AbstractDomainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_domainevent_manpage-AbstractDomainEvent.adoc
deleted file mode 100644
index ac5276f..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_domainevent_manpage-AbstractDomainEvent.adoc
+++ /dev/null
@@ -1,20 +0,0 @@
-[[_rg_classes_domainevent_manpage-AbstractDomainEvent]]
-= `AbstractDomainEvent`
-: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 class is the superclass for all domain events that are raised by the framework when interacting with actions, properties or collections.
-
-Its immediate subclasses are:
-
-* xref:rg.adoc#_rg_classes_domainevent_manpage-ActionDomainEvent[`ActionDomainEvent`]
-
-* xref:rg.adoc#_rg_classes_domainevent_manpage-PropertyDomainEvent[`PropertyDomainEvent`]
-
-* xref:rg.adoc#_rg_classes_domainevent_manpage-CollectionDomainEvent[`CollectionDomainEvent`]
-
-This class defines the `Phase` enum that is common to all domain events (hide/disable/validate/pre-execute/post-execute), and provides methods such as `veto(...)` by which subscribers can influence the interaction (eg hide a collection, disable a property, validate action arguments).
-
-It class also provides `get(...)` and `put(...)` methods that allow adhoc sharing of user data between different phases.  One event instance is used for both the hide and disable phases, and a different event instance is shared between validate/pre-execute/post-execute.

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_domainevent_manpage-ActionDomainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_domainevent_manpage-ActionDomainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_domainevent_manpage-ActionDomainEvent.adoc
deleted file mode 100644
index 289e1b6..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_domainevent_manpage-ActionDomainEvent.adoc
+++ /dev/null
@@ -1,20 +0,0 @@
-[[_rg_classes_domainevent_manpage-ActionDomainEvent]]
-= `ActionDomainEvent`
-: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/
-
-
-Subclass of xref:rg.adoc#_rg_classes_domainevent_manpage-AbstractDomainEvent[`AbstractDomainEvent`] for actions.
-
-The class has a number of responsibilities (in addition to those it inherits):
-
-* capture the target object being interacted with
-
-* capture the arguments for each of the action's parameters
-
-* provide selected metadata about the action parameters from the metamodel (names, types)
-
-* link back to the xref:rgsvc.adoc#_rgsvc-api_CommandContext[`CommandContext`] service's `Command` object
-
-The class itself is instantiated automatically by the framework whenever interacting with a rendered object's action.

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_domainevent_manpage-CollectionDomainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_domainevent_manpage-CollectionDomainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_domainevent_manpage-CollectionDomainEvent.adoc
deleted file mode 100644
index 030ba87..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_domainevent_manpage-CollectionDomainEvent.adoc
+++ /dev/null
@@ -1,21 +0,0 @@
-[[_rg_classes_domainevent_manpage-CollectionDomainEvent]]
-= `CollectionDomainEvent`
-: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/
-
-
-Subclass of xref:rg.adoc#_rg_classes_domainevent_manpage-AbstractDomainEvent[`AbstractDomainEvent`] for collections.
-
-The class has a couple of responsibilities (in addition to those it inherits):
-
-* capture the target object being interacted with
-
-* indicate whether the interaction is to add or remove an object from the collection (or simply to indicate that the collection is being accessed/read)
-
-* capture the object reference being added or removed
-
-
-The class itself is instantiated automatically by the framework whenever interacting with a rendered object's collection.
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_domainevent_manpage-PropertyDomainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_domainevent_manpage-PropertyDomainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_domainevent_manpage-PropertyDomainEvent.adoc
deleted file mode 100644
index a843152..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_domainevent_manpage-PropertyDomainEvent.adoc
+++ /dev/null
@@ -1,17 +0,0 @@
-[[_rg_classes_domainevent_manpage-PropertyDomainEvent]]
-= `PropertyDomainEvent`
-: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/
-
-
-Subclass of xref:rg.adoc#_rg_classes_domainevent_manpage-AbstractDomainEvent[`AbstractDomainEvent`] for properties.
-
-The class has a couple of responsibilities (in addition to those it inherits):
-
-* capture the target object being interacted with
-
-* capture the old and new values of the property
-
-
-The class itself is instantiated automatically by the framework whenever interacting with a rendered object's property.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_i18n.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_i18n.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_i18n.adoc
deleted file mode 100644
index 7e7c806..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_i18n.adoc
+++ /dev/null
@@ -1,11 +0,0 @@
-[[_rg_classes_i18n]]
-= i18n support
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-The `org.apache.isis.applib.services.i18n` package contains a single class to support i18n.
-
-
-include::_rg_classes_i18n_manpage-TranslatableString.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_i18n_manpage-TranslatableString.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_i18n_manpage-TranslatableString.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_i18n_manpage-TranslatableString.adoc
deleted file mode 100644
index b630b5a..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_i18n_manpage-TranslatableString.adoc
+++ /dev/null
@@ -1,13 +0,0 @@
-[[_rg_classes_i18n_manpage-TranslatableString]]
-= `TranslatableString`
-: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 - see xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[user guide, i18n].
-
-The `TranslatableString` utility class ...
-
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_lifecycleevent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_lifecycleevent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_lifecycleevent.adoc
deleted file mode 100644
index beb6341..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_lifecycleevent.adoc
+++ /dev/null
@@ -1,130 +0,0 @@
-[[_rg_classes_lifecycleevent]]
-= Lifecycle Events
-: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 section catalogues the various lifecycle event classes defined by Apache Isis.  These events
-are fired automatically when a domain object is loaded, created, updated and so forth.
-
-The lifecycle event classes are listed in the table below:
-
-
-.Lifecycle Event Classes
-[cols="2,4a,1,1", options="header"]
-|===
-
-|API
-|Maven Module +
-Impl'n (g: a:)
-|Implementation
-|Notes
-
-
-|xref:rg.adoc#_rg_classes_lifecycleevent_manpage-AbstractLifecycleEvent[`o.a.i.applib.` +
-`AbstractLifecycleEvent`]
-|``o.a.i.core`` +
-``services.eventbus`` +
-``isis-core-applib``
-|(abstract class)
-|Superclass of the other lifecycle events, listed below in this table.
-
-
-|xref:rg.adoc#_rg_classes_lifecycleevent_manpage-ObjectCreatedDomainEvent[`o.a.i.applib.` +
-`ObjectCreatedEvent`]
-|``o.a.i.core`` +
-``services.eventbus`` +
-``isis-core-applib``
-|(abstract class). +
-`ObjectCreatedEvent.Default` is the concrete implementation that is used.
-|Broadcast when an object is first instantiated
-using the xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-creation-api[`DomainObjectContainer`]'s
-`#newTransientInstance(...)` method.
-
-
-|xref:rg.adoc#_rg_classes_lifecycleevent_manpage-ObjectLoadedDomainEvent[`o.a.i.applib.` +
-`ObjectLoadedEvent`]
-|``o.a.i.core`` +
-``services.eventbus`` +
-``isis-core-applib``
-|(abstract class). +
-`ObjectLoadedEvent.Default` is the concrete implementation that is  used.
-|Broadcast when an object is retrieved from the database.
-
-
-|xref:rg.adoc#_rg_classes_lifecycleevent_manpage-ObjectPersistedDomainEvent[`o.a.i.applib.` +
-`ObjectPersistedEvent`]
-|``o.a.i.core`` +
-``services.eventbus`` +
-``isis-core-applib``
-|(abstract class). +
-`ObjectPersistedEvent.Default` is the concrete implementation that is used.
-|Broadcast when an object is first saved (inserted) into the database using the
-xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
-`#persist(...)` method.
-
-
-|xref:rg.adoc#_rg_classes_lifecycleevent_manpage-ObjectPersistingDomainEvent[`o.a.i.applib.` +
-`ObjectPersistingEvent`]
-|``o.a.i.core`` +
-``services.eventbus`` +
-``isis-core-applib``
-|(abstract class). +
-`ObjectPersistingEvent.Default` is the concrete implementation that is used.
-|Broadcast when an object is about to be saved (inserted) into the database using the
-xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
-`#persist(...)` method.
-
-
-|xref:rg.adoc#_rg_classes_lifecycleevent_manpage-ObjectRemovingDomainEvent[`o.a.i.applib.` +
-`ObjectRemovingEvent`]
-|``o.a.i.core`` +
-``services.eventbus`` +
-``isis-core-applib``
-|(abstract class). +
-`ObjectRemovingEvent.Default` is the concrete implementation that is used.
-|Broadcast when an object is about to be deleted from the database using the
-xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
-`#remove(...)` method.
-
-
-|xref:rg.adoc#_rg_classes_lifecycleevent_manpage-ObjectUpdatedDomainEvent[`o.a.i.applib.` +
-`ObjectUpdatedEvent`]
-|``o.a.i.core`` +
-``services.eventbus`` +
-``isis-core-applib``
-|(abstract class). +
-`ObjectUpdatedEvent.Default` is the concrete implementation that is used.
-|Broadcast when an object has just been updated in the database.  This is done either explicitly when the current
-transaction is flushed using the
-xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
-`#flush(...)` method, else is done implicitly when the transaction commits at the end of the user request.
-
-
-|xref:rg.adoc#_rg_classes_lifecycleevent_manpage-ObjectUpdatingDomainEvent[`o.a.i.applib.` +
-`ObjectUpdatingEvent`]
-|``o.a.i.core`` +
-``services.eventbus`` +
-``isis-core-applib``
-|(abstract class). +
-`ObjectUpdatingEvent.Default` is the concrete implementation that is used.
-|Broadcast when an object is about to be updated in the database.  This is done either explicitly when the current
-transaction is flushed using the
-xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
-`#flush(...)` method, else is done implicitly when the transaction commits at the end of the user request.
-
-
-|===
-
-
-
-include::_rg_classes_lifecycleevent_manpage-AbstractLifecycleEvent.adoc[leveloffset=+1]
-include::_rg_classes_lifecycleevent_manpage-ObjectCreatedEvent.adoc[leveloffset=+1]
-include::_rg_classes_lifecycleevent_manpage-ObjectLoadedEvent.adoc[leveloffset=+1]
-include::_rg_classes_lifecycleevent_manpage-ObjectPersistedEvent.adoc[leveloffset=+1]
-include::_rg_classes_lifecycleevent_manpage-ObjectPersistingEvent.adoc[leveloffset=+1]
-include::_rg_classes_lifecycleevent_manpage-ObjectRemovingEvent.adoc[leveloffset=+1]
-include::_rg_classes_lifecycleevent_manpage-ObjectUpdatedEvent.adoc[leveloffset=+1]
-include::_rg_classes_lifecycleevent_manpage-ObjectUpdatingEvent.adoc[leveloffset=+1]
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_lifecycleevent_manpage-AbstractLifecycleEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_lifecycleevent_manpage-AbstractLifecycleEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_lifecycleevent_manpage-AbstractLifecycleEvent.adoc
deleted file mode 100644
index e7baf30..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_lifecycleevent_manpage-AbstractLifecycleEvent.adoc
+++ /dev/null
@@ -1,27 +0,0 @@
-[[_rg_classes_lifecycleevent_manpage-AbstractLifecycleEvent]]
-= `AbstractLifecycleEvent`
-: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 class is the superclass for all lifecycle events that are raised by the framework when loading, saving, updating
-or deleting objects from the database.
-
-Its immediate subclasses are:
-
-* xref:rg.adoc#_rg_classes_lifecycleevent_manpage-ObjectCreatedEvent[`ObjectCreatedEvent`]
-
-* xref:rg.adoc#_rg_classes_lifecycleevent_manpage-ObjectLoadedEvent[`ObjectLoadedEvent`]
-
-* xref:rg.adoc#_rg_classes_lifecycleevent_manpage-ObjectPersistedEvent[`ObjectPersistedEvent`]
-
-* xref:rg.adoc#_rg_classes_lifecycleevent_manpage-ObjectPersistingEvent[`ObjectPersistingEvent`]
-
-* xref:rg.adoc#_rg_classes_lifecycleevent_manpage-ObjectRemovingEvent[`ObjectRemovingEvent`]
-
-* xref:rg.adoc#_rg_classes_lifecycleevent_manpage-ObjectUpdatedEvent[`ObjectUpdatedEvent`]
-
-* xref:rg.adoc#_rg_classes_lifecycleevent_manpage-ObjectUpdatingEvent[`ObjectUpdatingEvent`]
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_lifecycleevent_manpage-ObjectCreatedEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_lifecycleevent_manpage-ObjectCreatedEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_lifecycleevent_manpage-ObjectCreatedEvent.adoc
deleted file mode 100644
index f0a1ee2..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_lifecycleevent_manpage-ObjectCreatedEvent.adoc
+++ /dev/null
@@ -1,20 +0,0 @@
-[[_rg_classes_lifecycleevent_manpage-ObjectCreatedEvent]]
-= `ObjectCreatedEvent`
-: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/
-
-
-
-Subclass of xref:rg.adoc#_rg_classes_lifecycleevent_manpage-AbstractLifecycleEvent[`AbstractLifecycleEvent`], broadcast
-when an object is first instantiated using the
-xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-creation-api[`DomainObjectContainer`]'s
-`#newTransientInstance(...)` method.
-
-`ObjectCreatedEvent.Default` is the concrete implementation that is used.
-
-[NOTE]
-====
-In the future this may be generalized to allow arbitrary subclasses to be broadcast, see ISIS-803.
-====
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_lifecycleevent_manpage-ObjectLoadedEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_lifecycleevent_manpage-ObjectLoadedEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_lifecycleevent_manpage-ObjectLoadedEvent.adoc
deleted file mode 100644
index 627308a..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_lifecycleevent_manpage-ObjectLoadedEvent.adoc
+++ /dev/null
@@ -1,17 +0,0 @@
-[[_rg_classes_lifecycleevent_manpage-ObjectLoadedEvent]]
-= `ObjectLoadedEvent`
-: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/
-
-
-
-Subclass of xref:rg.adoc#_rg_classes_lifecycleevent_manpage-AbstractLifecycleEvent[`AbstractLifecycleEvent`], broadcast
-when an object is retrieved from the database.
-
-`ObjectLoadedEvent.Default` is the concrete implementation that is used.
-
-[NOTE]
-====
-In the future this may be generalized to allow arbitrary subclasses to be broadcast, see ISIS-803.
-====

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_lifecycleevent_manpage-ObjectPersistedEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_lifecycleevent_manpage-ObjectPersistedEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_lifecycleevent_manpage-ObjectPersistedEvent.adoc
deleted file mode 100644
index f9dcf46..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_lifecycleevent_manpage-ObjectPersistedEvent.adoc
+++ /dev/null
@@ -1,19 +0,0 @@
-[[_rg_classes_lifecycleevent_manpage-ObjectPersistedEvent]]
-= `ObjectPersistedEvent`
-: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/
-
-
-Subclass of xref:rg.adoc#_rg_classes_lifecycleevent_manpage-AbstractLifecycleEvent[`AbstractLifecycleEvent`], broadcast
-when an object is first saved (inserted) into the database using the
-xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
-`#persist(...)` method.
-
-
-`ObjectPersistedEvent.Default` is the concrete implementation that is used.
-
-[NOTE]
-====
-In the future this may be generalized to allow arbitrary subclasses to be broadcast, see ISIS-803.
-====

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_lifecycleevent_manpage-ObjectPersistingEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_lifecycleevent_manpage-ObjectPersistingEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_lifecycleevent_manpage-ObjectPersistingEvent.adoc
deleted file mode 100644
index 21ab9f6..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_lifecycleevent_manpage-ObjectPersistingEvent.adoc
+++ /dev/null
@@ -1,21 +0,0 @@
-[[_rg_classes_lifecycleevent_manpage-ObjectPersistingEvent]]
-= `ObjectPersistingEvent`
-: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/
-
-
-Subclass of xref:rg.adoc#_rg_classes_lifecycleevent_manpage-AbstractLifecycleEvent[`AbstractLifecycleEvent`], broadcast
-when an object is about to be saved (inserted) into the database using the
-xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
-`#persist(...)` method.
-
-
-`ObjectPersistingEvent.Default` is the concrete implementation that is used.
-
-[NOTE]
-====
-In the future this may be generalized to allow arbitrary subclasses to be broadcast, see ISIS-803.
-====
-
-


[16/52] [abbrv] isis git commit: ISIS-1243: removing manpage from .adoc file names.

Posted by mg...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_i18n.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_i18n.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_i18n.adoc
index c6c2fcf..65f0932 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_i18n.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_i18n.adoc
@@ -8,4 +8,4 @@
 The `org.apache.isis.applib.services.i18n` package contains a single class to support i18n.
 
 
-include::_rgcms_classes_i18n_manpage-TranslatableString.adoc[leveloffset=+1]
+include::_rgcms_classes_i18n_TranslatableString.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_i18n_TranslatableString.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_i18n_TranslatableString.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_i18n_TranslatableString.adoc
new file mode 100644
index 0000000..311cbca
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_i18n_TranslatableString.adoc
@@ -0,0 +1,13 @@
+[[_rgcms_classes_i18n_TranslatableString]]
+= `TranslatableString`
+: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 - see xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[user guide, i18n].
+
+The `TranslatableString` utility class ...
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_i18n_manpage-TranslatableString.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_i18n_manpage-TranslatableString.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_i18n_manpage-TranslatableString.adoc
deleted file mode 100644
index 9611a1e..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_i18n_manpage-TranslatableString.adoc
+++ /dev/null
@@ -1,13 +0,0 @@
-[[_rgcms_classes_i18n_manpage-TranslatableString]]
-= `TranslatableString`
-: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 - see xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[user guide, i18n].
-
-The `TranslatableString` utility class ...
-
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent.adoc
index cd99543..2ad3836 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent.adoc
@@ -22,7 +22,7 @@ Impl'n (g: a:)
 |Notes
 
 
-|xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-AbstractLifecycleEvent[`o.a.i.applib.` +
+|xref:rgcms.adoc#_rgcms_classes_lifecycleevent_AbstractLifecycleEvent[`o.a.i.applib.` +
 `AbstractLifecycleEvent`]
 |``o.a.i.core`` +
 ``services.eventbus`` +
@@ -31,7 +31,7 @@ Impl'n (g: a:)
 |Superclass of the other lifecycle events, listed below in this table.
 
 
-|xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-ObjectCreatedDomainEvent[`o.a.i.applib.` +
+|xref:rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectCreatedDomainEvent[`o.a.i.applib.` +
 `ObjectCreatedEvent`]
 |``o.a.i.core`` +
 ``services.eventbus`` +
@@ -43,7 +43,7 @@ using the xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-creation-api[`
 `#newTransientInstance(...)` method.
 
 
-|xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-ObjectLoadedDomainEvent[`o.a.i.applib.` +
+|xref:rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectLoadedDomainEvent[`o.a.i.applib.` +
 `ObjectLoadedEvent`]
 |``o.a.i.core`` +
 ``services.eventbus`` +
@@ -53,7 +53,7 @@ using the xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-creation-api[`
 |Broadcast when an object is retrieved from the database.
 
 
-|xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-ObjectPersistedDomainEvent[`o.a.i.applib.` +
+|xref:rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectPersistedDomainEvent[`o.a.i.applib.` +
 `ObjectPersistedEvent`]
 |``o.a.i.core`` +
 ``services.eventbus`` +
@@ -65,7 +65,7 @@ xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-persistence-api[`DomainO
 `#persist(...)` method.
 
 
-|xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-ObjectPersistingDomainEvent[`o.a.i.applib.` +
+|xref:rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectPersistingDomainEvent[`o.a.i.applib.` +
 `ObjectPersistingEvent`]
 |``o.a.i.core`` +
 ``services.eventbus`` +
@@ -77,7 +77,7 @@ xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-persistence-api[`DomainO
 `#persist(...)` method.
 
 
-|xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-ObjectRemovingDomainEvent[`o.a.i.applib.` +
+|xref:rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectRemovingDomainEvent[`o.a.i.applib.` +
 `ObjectRemovingEvent`]
 |``o.a.i.core`` +
 ``services.eventbus`` +
@@ -89,7 +89,7 @@ xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-persistence-api[`DomainO
 `#remove(...)` method.
 
 
-|xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-ObjectUpdatedDomainEvent[`o.a.i.applib.` +
+|xref:rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectUpdatedDomainEvent[`o.a.i.applib.` +
 `ObjectUpdatedEvent`]
 |``o.a.i.core`` +
 ``services.eventbus`` +
@@ -102,7 +102,7 @@ xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-persistence-api[`DomainO
 `#flush(...)` method, else is done implicitly when the transaction commits at the end of the user request.
 
 
-|xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-ObjectUpdatingDomainEvent[`o.a.i.applib.` +
+|xref:rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectUpdatingDomainEvent[`o.a.i.applib.` +
 `ObjectUpdatingEvent`]
 |``o.a.i.core`` +
 ``services.eventbus`` +
@@ -119,12 +119,12 @@ xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-persistence-api[`DomainO
 
 
 
-include::_rgcms_classes_lifecycleevent_manpage-AbstractLifecycleEvent.adoc[leveloffset=+1]
-include::_rgcms_classes_lifecycleevent_manpage-ObjectCreatedEvent.adoc[leveloffset=+1]
-include::_rgcms_classes_lifecycleevent_manpage-ObjectLoadedEvent.adoc[leveloffset=+1]
-include::_rgcms_classes_lifecycleevent_manpage-ObjectPersistedEvent.adoc[leveloffset=+1]
-include::_rgcms_classes_lifecycleevent_manpage-ObjectPersistingEvent.adoc[leveloffset=+1]
-include::_rgcms_classes_lifecycleevent_manpage-ObjectRemovingEvent.adoc[leveloffset=+1]
-include::_rgcms_classes_lifecycleevent_manpage-ObjectUpdatedEvent.adoc[leveloffset=+1]
-include::_rgcms_classes_lifecycleevent_manpage-ObjectUpdatingEvent.adoc[leveloffset=+1]
+include::_rgcms_classes_lifecycleevent_AbstractLifecycleEvent.adoc[leveloffset=+1]
+include::_rgcms_classes_lifecycleevent_ObjectCreatedEvent.adoc[leveloffset=+1]
+include::_rgcms_classes_lifecycleevent_ObjectLoadedEvent.adoc[leveloffset=+1]
+include::_rgcms_classes_lifecycleevent_ObjectPersistedEvent.adoc[leveloffset=+1]
+include::_rgcms_classes_lifecycleevent_ObjectPersistingEvent.adoc[leveloffset=+1]
+include::_rgcms_classes_lifecycleevent_ObjectRemovingEvent.adoc[leveloffset=+1]
+include::_rgcms_classes_lifecycleevent_ObjectUpdatedEvent.adoc[leveloffset=+1]
+include::_rgcms_classes_lifecycleevent_ObjectUpdatingEvent.adoc[leveloffset=+1]
 

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_AbstractLifecycleEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_AbstractLifecycleEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_AbstractLifecycleEvent.adoc
new file mode 100644
index 0000000..6ed5f80
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_AbstractLifecycleEvent.adoc
@@ -0,0 +1,27 @@
+[[_rgcms_classes_lifecycleevent_AbstractLifecycleEvent]]
+= `AbstractLifecycleEvent`
+: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 class is the superclass for all lifecycle events that are raised by the framework when loading, saving, updating
+or deleting objects from the database.
+
+Its immediate subclasses are:
+
+* xref:rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectCreatedEvent[`ObjectCreatedEvent`]
+
+* xref:rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectLoadedEvent[`ObjectLoadedEvent`]
+
+* xref:rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectPersistedEvent[`ObjectPersistedEvent`]
+
+* xref:rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectPersistingEvent[`ObjectPersistingEvent`]
+
+* xref:rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectRemovingEvent[`ObjectRemovingEvent`]
+
+* xref:rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectUpdatedEvent[`ObjectUpdatedEvent`]
+
+* xref:rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectUpdatingEvent[`ObjectUpdatingEvent`]
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_ObjectCreatedEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_ObjectCreatedEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_ObjectCreatedEvent.adoc
new file mode 100644
index 0000000..3db2610
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_ObjectCreatedEvent.adoc
@@ -0,0 +1,20 @@
+[[_rgcms_classes_lifecycleevent_ObjectCreatedEvent]]
+= `ObjectCreatedEvent`
+: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/
+
+
+
+Subclass of xref:rgcms.adoc#_rgcms_classes_lifecycleevent_AbstractLifecycleEvent[`AbstractLifecycleEvent`], broadcast
+when an object is first instantiated using the
+xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-creation-api[`DomainObjectContainer`]'s
+`#newTransientInstance(...)` method.
+
+`ObjectCreatedEvent.Default` is the concrete implementation that is used.
+
+[NOTE]
+====
+In the future this may be generalized to allow arbitrary subclasses to be broadcast, see ISIS-803.
+====
+

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_ObjectLoadedEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_ObjectLoadedEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_ObjectLoadedEvent.adoc
new file mode 100644
index 0000000..936e750
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_ObjectLoadedEvent.adoc
@@ -0,0 +1,17 @@
+[[_rgcms_classes_lifecycleevent_ObjectLoadedEvent]]
+= `ObjectLoadedEvent`
+: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/
+
+
+
+Subclass of xref:rgcms.adoc#_rgcms_classes_lifecycleevent_AbstractLifecycleEvent[`AbstractLifecycleEvent`], broadcast
+when an object is retrieved from the database.
+
+`ObjectLoadedEvent.Default` is the concrete implementation that is used.
+
+[NOTE]
+====
+In the future this may be generalized to allow arbitrary subclasses to be broadcast, see ISIS-803.
+====

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_ObjectPersistedEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_ObjectPersistedEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_ObjectPersistedEvent.adoc
new file mode 100644
index 0000000..1973b28
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_ObjectPersistedEvent.adoc
@@ -0,0 +1,19 @@
+[[_rgcms_classes_lifecycleevent_ObjectPersistedEvent]]
+= `ObjectPersistedEvent`
+: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/
+
+
+Subclass of xref:rgcms.adoc#_rgcms_classes_lifecycleevent_AbstractLifecycleEvent[`AbstractLifecycleEvent`], broadcast
+when an object is first saved (inserted) into the database using the
+xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
+`#persist(...)` method.
+
+
+`ObjectPersistedEvent.Default` is the concrete implementation that is used.
+
+[NOTE]
+====
+In the future this may be generalized to allow arbitrary subclasses to be broadcast, see ISIS-803.
+====

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_ObjectPersistingEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_ObjectPersistingEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_ObjectPersistingEvent.adoc
new file mode 100644
index 0000000..4828a53
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_ObjectPersistingEvent.adoc
@@ -0,0 +1,21 @@
+[[_rgcms_classes_lifecycleevent_ObjectPersistingEvent]]
+= `ObjectPersistingEvent`
+: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/
+
+
+Subclass of xref:rgcms.adoc#_rgcms_classes_lifecycleevent_AbstractLifecycleEvent[`AbstractLifecycleEvent`], broadcast
+when an object is about to be saved (inserted) into the database using the
+xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
+`#persist(...)` method.
+
+
+`ObjectPersistingEvent.Default` is the concrete implementation that is used.
+
+[NOTE]
+====
+In the future this may be generalized to allow arbitrary subclasses to be broadcast, see ISIS-803.
+====
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_ObjectRemovingEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_ObjectRemovingEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_ObjectRemovingEvent.adoc
new file mode 100644
index 0000000..7335583
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_ObjectRemovingEvent.adoc
@@ -0,0 +1,20 @@
+[[_rgcms_classes_lifecycleevent_ObjectRemovingEvent]]
+= `ObjectRemovingEvent`
+: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/
+
+
+Subclass of xref:rgcms.adoc#_rgcms_classes_lifecycleevent_AbstractLifecycleEvent[`AbstractLifecycleEvent`], broadcast
+when an object is about to be deleted from the database using the
+xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
+`#remove(...)` method.
+
+
+`ObjectRemovingEvent.Default` is the concrete implementation that is used.
+
+[NOTE]
+====
+In the future this may be generalized to allow arbitrary subclasses to be broadcast, see ISIS-803.
+====
+

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_ObjectUpdatedEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_ObjectUpdatedEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_ObjectUpdatedEvent.adoc
new file mode 100644
index 0000000..6989e72
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_ObjectUpdatedEvent.adoc
@@ -0,0 +1,21 @@
+[[_rgcms_classes_lifecycleevent_ObjectUpdatedEvent]]
+= `ObjectUpdatedEvent`
+: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/
+
+
+
+Subclass of xref:rgcms.adoc#_rgcms_classes_lifecycleevent_AbstractLifecycleEvent[`AbstractLifecycleEvent`], broadcast
+when an object has just been updated in the database.  This is done either explicitly when the current
+transaction is flushed using the
+xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
+`#flush(...)` method, else is done implicitly when the transaction commits at the end of the user request.
+
+`ObjectUpdatedEvent.Default` is the concrete implementation that is used.
+
+[NOTE]
+====
+In the future this may be generalized to allow arbitrary subclasses to be broadcast, see ISIS-803.
+====
+

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_ObjectUpdatingEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_ObjectUpdatingEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_ObjectUpdatingEvent.adoc
new file mode 100644
index 0000000..8554ff7
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_ObjectUpdatingEvent.adoc
@@ -0,0 +1,22 @@
+[[_rgcms_classes_lifecycleevent_ObjectUpdatingEvent]]
+= `ObjectUpdatingEvent`
+: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/
+
+
+
+Subclass of xref:rgcms.adoc#_rgcms_classes_lifecycleevent_AbstractLifecycleEvent[`AbstractLifecycleEvent`], broadcast
+when an object is about to be updated in the database.  This is done either explicitly when the current
+transaction is flushed using the
+xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
+`#flush(...)` method, else is done implicitly when the transaction commits at the end of the user request.
+
+
+`ObjectUpdatingEvent.Default` is the concrete implementation that is used.
+
+[NOTE]
+====
+In the future this may be generalized to allow arbitrary subclasses to be broadcast, see ISIS-803.
+====
+

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-AbstractLifecycleEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-AbstractLifecycleEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-AbstractLifecycleEvent.adoc
deleted file mode 100644
index 590c85c..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-AbstractLifecycleEvent.adoc
+++ /dev/null
@@ -1,27 +0,0 @@
-[[_rgcms_classes_lifecycleevent_manpage-AbstractLifecycleEvent]]
-= `AbstractLifecycleEvent`
-: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 class is the superclass for all lifecycle events that are raised by the framework when loading, saving, updating
-or deleting objects from the database.
-
-Its immediate subclasses are:
-
-* xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-ObjectCreatedEvent[`ObjectCreatedEvent`]
-
-* xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-ObjectLoadedEvent[`ObjectLoadedEvent`]
-
-* xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-ObjectPersistedEvent[`ObjectPersistedEvent`]
-
-* xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-ObjectPersistingEvent[`ObjectPersistingEvent`]
-
-* xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-ObjectRemovingEvent[`ObjectRemovingEvent`]
-
-* xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-ObjectUpdatedEvent[`ObjectUpdatedEvent`]
-
-* xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-ObjectUpdatingEvent[`ObjectUpdatingEvent`]
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectCreatedEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectCreatedEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectCreatedEvent.adoc
deleted file mode 100644
index 788a628..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectCreatedEvent.adoc
+++ /dev/null
@@ -1,20 +0,0 @@
-[[_rgcms_classes_lifecycleevent_manpage-ObjectCreatedEvent]]
-= `ObjectCreatedEvent`
-: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/
-
-
-
-Subclass of xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-AbstractLifecycleEvent[`AbstractLifecycleEvent`], broadcast
-when an object is first instantiated using the
-xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-creation-api[`DomainObjectContainer`]'s
-`#newTransientInstance(...)` method.
-
-`ObjectCreatedEvent.Default` is the concrete implementation that is used.
-
-[NOTE]
-====
-In the future this may be generalized to allow arbitrary subclasses to be broadcast, see ISIS-803.
-====
-

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectLoadedEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectLoadedEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectLoadedEvent.adoc
deleted file mode 100644
index 7d65cf7..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectLoadedEvent.adoc
+++ /dev/null
@@ -1,17 +0,0 @@
-[[_rgcms_classes_lifecycleevent_manpage-ObjectLoadedEvent]]
-= `ObjectLoadedEvent`
-: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/
-
-
-
-Subclass of xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-AbstractLifecycleEvent[`AbstractLifecycleEvent`], broadcast
-when an object is retrieved from the database.
-
-`ObjectLoadedEvent.Default` is the concrete implementation that is used.
-
-[NOTE]
-====
-In the future this may be generalized to allow arbitrary subclasses to be broadcast, see ISIS-803.
-====

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectPersistedEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectPersistedEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectPersistedEvent.adoc
deleted file mode 100644
index 95bd2e8..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectPersistedEvent.adoc
+++ /dev/null
@@ -1,19 +0,0 @@
-[[_rgcms_classes_lifecycleevent_manpage-ObjectPersistedEvent]]
-= `ObjectPersistedEvent`
-: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/
-
-
-Subclass of xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-AbstractLifecycleEvent[`AbstractLifecycleEvent`], broadcast
-when an object is first saved (inserted) into the database using the
-xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
-`#persist(...)` method.
-
-
-`ObjectPersistedEvent.Default` is the concrete implementation that is used.
-
-[NOTE]
-====
-In the future this may be generalized to allow arbitrary subclasses to be broadcast, see ISIS-803.
-====

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectPersistingEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectPersistingEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectPersistingEvent.adoc
deleted file mode 100644
index 376bc25..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectPersistingEvent.adoc
+++ /dev/null
@@ -1,21 +0,0 @@
-[[_rgcms_classes_lifecycleevent_manpage-ObjectPersistingEvent]]
-= `ObjectPersistingEvent`
-: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/
-
-
-Subclass of xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-AbstractLifecycleEvent[`AbstractLifecycleEvent`], broadcast
-when an object is about to be saved (inserted) into the database using the
-xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
-`#persist(...)` method.
-
-
-`ObjectPersistingEvent.Default` is the concrete implementation that is used.
-
-[NOTE]
-====
-In the future this may be generalized to allow arbitrary subclasses to be broadcast, see ISIS-803.
-====
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectRemovingEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectRemovingEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectRemovingEvent.adoc
deleted file mode 100644
index 0235513..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectRemovingEvent.adoc
+++ /dev/null
@@ -1,20 +0,0 @@
-[[_rgcms_classes_lifecycleevent_manpage-ObjectRemovingEvent]]
-= `ObjectRemovingEvent`
-: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/
-
-
-Subclass of xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-AbstractLifecycleEvent[`AbstractLifecycleEvent`], broadcast
-when an object is about to be deleted from the database using the
-xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
-`#remove(...)` method.
-
-
-`ObjectRemovingEvent.Default` is the concrete implementation that is used.
-
-[NOTE]
-====
-In the future this may be generalized to allow arbitrary subclasses to be broadcast, see ISIS-803.
-====
-

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectUpdatedEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectUpdatedEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectUpdatedEvent.adoc
deleted file mode 100644
index 58695e5..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectUpdatedEvent.adoc
+++ /dev/null
@@ -1,21 +0,0 @@
-[[_rgcms_classes_lifecycleevent_manpage-ObjectUpdatedEvent]]
-= `ObjectUpdatedEvent`
-: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/
-
-
-
-Subclass of xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-AbstractLifecycleEvent[`AbstractLifecycleEvent`], broadcast
-when an object has just been updated in the database.  This is done either explicitly when the current
-transaction is flushed using the
-xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
-`#flush(...)` method, else is done implicitly when the transaction commits at the end of the user request.
-
-`ObjectUpdatedEvent.Default` is the concrete implementation that is used.
-
-[NOTE]
-====
-In the future this may be generalized to allow arbitrary subclasses to be broadcast, see ISIS-803.
-====
-

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectUpdatingEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectUpdatingEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectUpdatingEvent.adoc
deleted file mode 100644
index e78c649..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectUpdatingEvent.adoc
+++ /dev/null
@@ -1,22 +0,0 @@
-[[_rgcms_classes_lifecycleevent_manpage-ObjectUpdatingEvent]]
-= `ObjectUpdatingEvent`
-: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/
-
-
-
-Subclass of xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-AbstractLifecycleEvent[`AbstractLifecycleEvent`], broadcast
-when an object is about to be updated in the database.  This is done either explicitly when the current
-transaction is flushed using the
-xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
-`#flush(...)` method, else is done implicitly when the transaction commits at the end of the user request.
-
-
-`ObjectUpdatingEvent.Default` is the concrete implementation that is used.
-
-[NOTE]
-====
-In the future this may be generalized to allow arbitrary subclasses to be broadcast, see ISIS-803.
-====
-

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles.adoc
index 6277ec5..7a7bfcf 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles.adoc
@@ -9,10 +9,10 @@ The interfaces listed in this chapter are role interfaces; they define a contrac
  to interact with those domain objects that implement these interfaces.
 
 
-include::_rgcms_classes_roles_manpage-HoldsUpdatedAt.adoc[leveloffset=+1]
-include::_rgcms_classes_roles_manpage-HoldsUpdatedBy.adoc[leveloffset=+1]
-include::_rgcms_classes_roles_manpage-Timestampable.adoc[leveloffset=+1]
-include::_rgcms_classes_roles_manpage-Dto.adoc[leveloffset=+1]
-include::_rgcms_classes_roles_manpage-Persistable.adoc[leveloffset=+1]
+include::_rgcms_classes_roles_HoldsUpdatedAt.adoc[leveloffset=+1]
+include::_rgcms_classes_roles_HoldsUpdatedBy.adoc[leveloffset=+1]
+include::_rgcms_classes_roles_Timestampable.adoc[leveloffset=+1]
+include::_rgcms_classes_roles_Dto.adoc[leveloffset=+1]
+include::_rgcms_classes_roles_Persistable.adoc[leveloffset=+1]
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_Dto.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_Dto.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_Dto.adoc
new file mode 100644
index 0000000..15b4293
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_Dto.adoc
@@ -0,0 +1,61 @@
+[[_rgcms_classes_mixins_Dto]]
+= `Dto` (`1.11.0-SNAPSHOT`)
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+The `Dto` role interface (`1.11.0-SNAPSHOT`) is intended to be implemented by JAXB-annotated view models, that is, annotated using
+xref:rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`].  It enables the ability to download the XML and
+XSD schema of those objects using two xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling_mixins[mixins],
+`Dto_downloadXml` and `Dto_downloadXsd`.
+
+The interface is just a marker interface (with no members), and is defined as:
+
+[source,java]
+----
+public interface Dto { }
+----
+
+The `Dto_downloadXml` mixin defines the following action:
+
+[source,java]
+----
+@Mixin
+public class Dto_downloadXml {
+    public Dto_downloadXml(final Dto dto) { ... }     // <1>
+    public Object downloadXml(final String fileName) { ... }   // <2>
+    ...
+}
+----
+<1> provided as an action to any class that (trivially) implements the `Dto` interface
+<2> actually this is '$$' in the code, a "special case" that means to use the derive the action name from the class name.
+
+This will return the XML text wrapped up in a xref:rgcms.adoc#_rgcms_classes_value-types_Clob[`Clob`].
+
+The `Dto_downloadXsd` mixin is similar:
+
+[source,java]
+----
+@Mixin
+public class Dto_downloadXsd {
+    public Dto_downloadXsd(final Dto dto) { ... }                                             // <1>
+    public Object downloadXsd(final String fileName, final IsisSchemes isisSchemas) { ... }   // <2>
+}
+----
+<1> provided as an action to any class that (trivially) implements the `Dto` interface
+<2> actually this is '$$' in the code, a "special case" that means to use the derive the action name from the class name.
+
+If the domain object's JAXB annotations reference only a single XSD schema then this will return that XML text as
+a xref:rgcms.adoc#_rgcms_classes_value-types_Clob[`Clob`] of that XSD.  If there are multiple XSD schemas referenced
+then the action will return a zip of those schemas, wrapped up in a
+xref:rgcms.adoc#_rgcms_classes_value-types_Blob[`Blob`].  The `IsisSchemas` parameter to the action can be used to
+optionally ignore the common xref:rgcms.adoc#_rgcms_schema[Apache Isis schemas] (useful if there is only one other XSD schema
+referenced by the DTO).
+
+
+
+== Related Services
+
+The `Dto_downloadXml` and `Dto_downloadXsd` delegate to the
+xref:rgsvc.adoc#_rgsvc-api_JaxbService[`JaxbService`] to actually generate the XML/XSD.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_HoldsUpdatedAt.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_HoldsUpdatedAt.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_HoldsUpdatedAt.adoc
new file mode 100644
index 0000000..0509d0f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_HoldsUpdatedAt.adoc
@@ -0,0 +1,44 @@
+[[_rgcms_classes_roles_HoldsUpdatedAt]]
+= `HoldsUpdatedAt`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+The `HoldsUpdatedAt` role interface allows the (framework-provided) `TimestampService` to update each object with
+the current timestamp whenever it is modified in a transaction.
+
+The interface is defined as:
+
+[source,java]
+----
+public interface HoldsUpdatedAt {
+    void setUpdatedAt(java.sql.Timestamp updatedAt);
+}
+----
+
+The current time is obtained from the xref:rgsvc.adoc#_rgsvc-api_ClockService[`ClockService`].
+
+Entities that implement this interface often also implement xref:rgcms.adoc#_rgcms_classes_roles_HoldsUpdatedBy[`HoldsUpdatedBy`] role interface; as a convenience the xref:rgcms.adoc#_rgcms_classes_roles_Timestampable[`Timestampable`] interface combines the two roles.
+
+
+
+== Alternative approaches
+
+An alternative way to maintain a timestamp is to use JDO's `@Version` annotation.  With this approach, it is the JDO/DataNucleus that maintains the version, rather than the framework's `TimestampService`.
+
+For example:
+
+[source,java]
+----
+@javax.jdo.annotations.Version(
+        strategy=VersionStrategy.DATE_TIME,
+        column="version")
+public class Customer {
+    ...
+    public java.sql.Timestamp getVersionSequence() {
+        return (java.sql.Timestamp) JDOHelper.getVersion(this);
+    }
+}
+----
+

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_HoldsUpdatedBy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_HoldsUpdatedBy.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_HoldsUpdatedBy.adoc
new file mode 100644
index 0000000..8c28df1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_HoldsUpdatedBy.adoc
@@ -0,0 +1,19 @@
+[[_rgcms_classes_roles_HoldsUpdatedBy]]
+= `HoldsUpdatedBy`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+The `HoldsUpdatedBy` role interface ...
+
+[source,java]
+----
+public interface HoldsUpdatedBy {
+    void setUpdatedBy(String updatedBy);
+}
+----
+
+Entities that implement this interface often also implement xref:rgcms.adoc#_rgcms_classes_roles_HoldsUpdatedAt[`HoldsUpdatedAt`] role interface; as a convenience the xref:rgcms.adoc#_rgcms_classes_roles_Timestampable[`Timestampable`] interface combines the two roles.
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_Persistable.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_Persistable.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_Persistable.adoc
new file mode 100644
index 0000000..eaaccc1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_Persistable.adoc
@@ -0,0 +1,34 @@
+[[_rgcms_classes_mixins_Persistable]]
+= `Persistable` (`1.11.0-SNAPSHOT`)
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+All domain entities automatically implement the DataNucleus `Persistable` role interface as a result of the enhancer
+process (the fully qualified class name is `org.datanucleus.enhancement.Persistable`).  So as a developer you do not
+need to write any code for this role interface.
+
+Nevertheless, the `Persistable_downloadJdoMetadata` mixin (`1.11.0-SNAPSHOT`) provides the ability to download the
+JDO link:http://www.datanucleus.org/products/datanucleus/jdo/metadata_xml.html[class metadata in XML] form.  The mixin
+defines the following action:
+
+[source,java]
+----
+@Mixin
+public class Persistable_downloadJdoMetadata {
+    public Persistable_downloadJdoMetadata(final Persistable persistable) { ... }   // <1>
+    public Object downloadJdoMetadata(final String fileName) { ... }                // <2>
+    ...
+}
+----
+<1> provided as an action to any domain entity
+<2> actually this is '$$' in the code, a "special case" that means to use the derive the action name from the class name.
+
+This will return the XML text wrapped up in a xref:rgcms.adoc#_rgcms_classes_value-types_Clob[`Clob`].
+
+
+== Related Services
+
+The mixin delegates to the xref:rgsvc.adoc#_rgsvc-api_IsisJdoSupport[`IsisJdoSupport`] service to obtain
+a reference to the JDO `PersistenceManagerFactory`.

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_Timestampable.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_Timestampable.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_Timestampable.adoc
new file mode 100644
index 0000000..27e799f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_Timestampable.adoc
@@ -0,0 +1,23 @@
+[[_rgcms_classes_roles_Timestampable]]
+= `Timestampable`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+The `Timestampable` role interface is a convenience that combines the xref:rgcms.adoc#_rgcms_classes_roles_HoldsUpdatedAt[`HoldsUpdatedAt`] and xref:rgcms.adoc#_rgcms_classes_roles_HoldsUpdatedBy[`HoldsUpdatedBy`] interfaces.  It is defined as:
+
+[source,java]
+----
+public interface Timestampable
+    extends HoldsUpdatedAt, HoldsUpdatedBy {
+}
+----
+
+The interface no additional methods of its own.
+
+
+
+== Alternatives
+
+An alternative way to maintain a timestamp is to use JDO's `@Version` annotation.  With this approach, it is the JDO/DataNucleus that maintains the version, rather than the framework's `TimestampService`.  See xref:rgcms.adoc#_rgcms_classes_roles_HoldsUpdatedBy[`HoldsUpdatedBy`] for further details.

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_manpage-Dto.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_manpage-Dto.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_manpage-Dto.adoc
deleted file mode 100644
index b7e4790..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_manpage-Dto.adoc
+++ /dev/null
@@ -1,61 +0,0 @@
-[[_rgcms_classes_mixins_Dto]]
-= `Dto` (`1.11.0-SNAPSHOT`)
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-The `Dto` role interface (`1.11.0-SNAPSHOT`) is intended to be implemented by JAXB-annotated view models, that is, annotated using
-xref:rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`].  It enables the ability to download the XML and
-XSD schema of those objects using two xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling_mixins[mixins],
-`Dto_downloadXml` and `Dto_downloadXsd`.
-
-The interface is just a marker interface (with no members), and is defined as:
-
-[source,java]
-----
-public interface Dto { }
-----
-
-The `Dto_downloadXml` mixin defines the following action:
-
-[source,java]
-----
-@Mixin
-public class Dto_downloadXml {
-    public Dto_downloadXml(final Dto dto) { ... }     // <1>
-    public Object downloadXml(final String fileName) { ... }   // <2>
-    ...
-}
-----
-<1> provided as an action to any class that (trivially) implements the `Dto` interface
-<2> actually this is '$$' in the code, a "special case" that means to use the derive the action name from the class name.
-
-This will return the XML text wrapped up in a xref:rgcms.adoc#_rgcms_classes_value-types_manpage-Clob[`Clob`].
-
-The `Dto_downloadXsd` mixin is similar:
-
-[source,java]
-----
-@Mixin
-public class Dto_downloadXsd {
-    public Dto_downloadXsd(final Dto dto) { ... }                                             // <1>
-    public Object downloadXsd(final String fileName, final IsisSchemes isisSchemas) { ... }   // <2>
-}
-----
-<1> provided as an action to any class that (trivially) implements the `Dto` interface
-<2> actually this is '$$' in the code, a "special case" that means to use the derive the action name from the class name.
-
-If the domain object's JAXB annotations reference only a single XSD schema then this will return that XML text as
-a xref:rgcms.adoc#_rgcms_classes_value-types_manpage-Clob[`Clob`] of that XSD.  If there are multiple XSD schemas referenced
-then the action will return a zip of those schemas, wrapped up in a
-xref:rgcms.adoc#_rgcms_classes_value-types_manpage-Blob[`Blob`].  The `IsisSchemas` parameter to the action can be used to
-optionally ignore the common xref:rgcms.adoc#_rgcms_schema[Apache Isis schemas] (useful if there is only one other XSD schema
-referenced by the DTO).
-
-
-
-== Related Services
-
-The `Dto_downloadXml` and `Dto_downloadXsd` delegate to the
-xref:rgsvc.adoc#_rgsvc-api_JaxbService[`JaxbService`] to actually generate the XML/XSD.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_manpage-HoldsUpdatedAt.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_manpage-HoldsUpdatedAt.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_manpage-HoldsUpdatedAt.adoc
deleted file mode 100644
index d286c5d..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_manpage-HoldsUpdatedAt.adoc
+++ /dev/null
@@ -1,44 +0,0 @@
-[[_rgcms_classes_roles_manpage-HoldsUpdatedAt]]
-= `HoldsUpdatedAt`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-The `HoldsUpdatedAt` role interface allows the (framework-provided) `TimestampService` to update each object with
-the current timestamp whenever it is modified in a transaction.
-
-The interface is defined as:
-
-[source,java]
-----
-public interface HoldsUpdatedAt {
-    void setUpdatedAt(java.sql.Timestamp updatedAt);
-}
-----
-
-The current time is obtained from the xref:rgsvc.adoc#_rgsvc-api_ClockService[`ClockService`].
-
-Entities that implement this interface often also implement xref:rgcms.adoc#_rgcms_classes_roles_manpage-HoldsUpdatedBy[`HoldsUpdatedBy`] role interface; as a convenience the xref:rgcms.adoc#_rgcms_classes_roles_manpage-Timestampable[`Timestampable`] interface combines the two roles.
-
-
-
-== Alternative approaches
-
-An alternative way to maintain a timestamp is to use JDO's `@Version` annotation.  With this approach, it is the JDO/DataNucleus that maintains the version, rather than the framework's `TimestampService`.
-
-For example:
-
-[source,java]
-----
-@javax.jdo.annotations.Version(
-        strategy=VersionStrategy.DATE_TIME,
-        column="version")
-public class Customer {
-    ...
-    public java.sql.Timestamp getVersionSequence() {
-        return (java.sql.Timestamp) JDOHelper.getVersion(this);
-    }
-}
-----
-

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_manpage-HoldsUpdatedBy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_manpage-HoldsUpdatedBy.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_manpage-HoldsUpdatedBy.adoc
deleted file mode 100644
index 9552043..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_manpage-HoldsUpdatedBy.adoc
+++ /dev/null
@@ -1,19 +0,0 @@
-[[_rgcms_classes_roles_manpage-HoldsUpdatedBy]]
-= `HoldsUpdatedBy`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-The `HoldsUpdatedBy` role interface ...
-
-[source,java]
-----
-public interface HoldsUpdatedBy {
-    void setUpdatedBy(String updatedBy);
-}
-----
-
-Entities that implement this interface often also implement xref:rgcms.adoc#_rgcms_classes_roles_manpage-HoldsUpdatedAt[`HoldsUpdatedAt`] role interface; as a convenience the xref:rgcms.adoc#_rgcms_classes_roles_manpage-Timestampable[`Timestampable`] interface combines the two roles.
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_manpage-Persistable.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_manpage-Persistable.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_manpage-Persistable.adoc
deleted file mode 100644
index 757cade..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_manpage-Persistable.adoc
+++ /dev/null
@@ -1,34 +0,0 @@
-[[_rgcms_classes_mixins_Persistable]]
-= `Persistable` (`1.11.0-SNAPSHOT`)
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-All domain entities automatically implement the DataNucleus `Persistable` role interface as a result of the enhancer
-process (the fully qualified class name is `org.datanucleus.enhancement.Persistable`).  So as a developer you do not
-need to write any code for this role interface.
-
-Nevertheless, the `Persistable_downloadJdoMetadata` mixin (`1.11.0-SNAPSHOT`) provides the ability to download the
-JDO link:http://www.datanucleus.org/products/datanucleus/jdo/metadata_xml.html[class metadata in XML] form.  The mixin
-defines the following action:
-
-[source,java]
-----
-@Mixin
-public class Persistable_downloadJdoMetadata {
-    public Persistable_downloadJdoMetadata(final Persistable persistable) { ... }   // <1>
-    public Object downloadJdoMetadata(final String fileName) { ... }                // <2>
-    ...
-}
-----
-<1> provided as an action to any domain entity
-<2> actually this is '$$' in the code, a "special case" that means to use the derive the action name from the class name.
-
-This will return the XML text wrapped up in a xref:rgcms.adoc#_rgcms_classes_value-types_manpage-Clob[`Clob`].
-
-
-== Related Services
-
-The mixin delegates to the xref:rgsvc.adoc#_rgsvc-api_IsisJdoSupport[`IsisJdoSupport`] service to obtain
-a reference to the JDO `PersistenceManagerFactory`.

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_manpage-Timestampable.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_manpage-Timestampable.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_manpage-Timestampable.adoc
deleted file mode 100644
index a69d213..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_manpage-Timestampable.adoc
+++ /dev/null
@@ -1,23 +0,0 @@
-[[_rgcms_classes_roles_manpage-Timestampable]]
-= `Timestampable`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-The `Timestampable` role interface is a convenience that combines the xref:rgcms.adoc#_rgcms_classes_roles_manpage-HoldsUpdatedAt[`HoldsUpdatedAt`] and xref:rgcms.adoc#_rgcms_classes_roles_manpage-HoldsUpdatedBy[`HoldsUpdatedBy`] interfaces.  It is defined as:
-
-[source,java]
-----
-public interface Timestampable
-    extends HoldsUpdatedAt, HoldsUpdatedBy {
-}
-----
-
-The interface no additional methods of its own.
-
-
-
-== Alternatives
-
-An alternative way to maintain a timestamp is to use JDO's `@Version` annotation.  With this approach, it is the JDO/DataNucleus that maintains the version, rather than the framework's `TimestampService`.  See xref:rgcms.adoc#_rgcms_classes_roles_manpage-HoldsUpdatedBy[`HoldsUpdatedBy`] for further details.

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_spec.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_spec.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_spec.adoc
index 01b5745..ac2da73 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_spec.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_spec.adoc
@@ -52,7 +52,7 @@ public class Customer {
 [_rgcms_classes_spec-Specification2]
 == `Specification2`
 
-The `Specification2` interface extends the `Specification` API to add support for i18n.  This is done by defining an additional method that returns a xref:rgcms.adoc#_rgcms_classes_i18n_manpage-TranslatableString[translatable string]:
+The `Specification2` interface extends the `Specification` API to add support for i18n.  This is done by defining an additional method that returns a xref:rgcms.adoc#_rgcms_classes_i18n_TranslatableString[translatable string]:
 
 [source,java]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super.adoc
index 71ea4a4..82be5d0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super.adoc
@@ -19,7 +19,7 @@ Impl'n (g: a:)
 |Notes
 
 
-|xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractContainedObject[`o.a.i.applib.` +
+|xref:rgcms.adoc#_rgcms_classes_super_AbstractContainedObject[`o.a.i.applib.` +
 `AbstractContainedObject`]
 |``o.a.i.core`` +
 ``isis-core-applib``
@@ -27,7 +27,7 @@ Impl'n (g: a:)
 |
 
 
-|xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractDomainObject[`o.a.i.applib.` +
+|xref:rgcms.adoc#_rgcms_classes_super_AbstractDomainObject[`o.a.i.applib.` +
 `AbstractDomainObject`]
 |``o.a.i.core`` +
 ``isis-core-applib``
@@ -35,7 +35,7 @@ Impl'n (g: a:)
 |
 
 
-|xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractFactoryAndRepository[`o.a.i.applib.` +
+|xref:rgcms.adoc#_rgcms_classes_super_AbstractFactoryAndRepository[`o.a.i.applib.` +
 `AbstractFactoryAndRepository`]
 |``o.a.i.core`` +
 ``isis-core-applib``
@@ -43,7 +43,7 @@ Impl'n (g: a:)
 |
 
 
-|xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractService[`o.a.i.applib.` +
+|xref:rgcms.adoc#_rgcms_classes_super_AbstractService[`o.a.i.applib.` +
 `AbstractService`]
 |``o.a.i.core`` +
 ``isis-core-applib``
@@ -51,7 +51,7 @@ Impl'n (g: a:)
 |
 
 
-|xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractSubscriber[`o.a.i.applib.` +
+|xref:rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[`o.a.i.applib.` +
 `AbstractSubscriber`]
 |``o.a.i.core`` +
 ``isis-core-applib``
@@ -59,7 +59,7 @@ Impl'n (g: a:)
 |
 
 
-|xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractViewModel[`o.a.i.applib.` +
+|xref:rgcms.adoc#_rgcms_classes_super_AbstractViewModel[`o.a.i.applib.` +
 `AbstractViewModel`]
 |``o.a.i.core`` +
 ``isis-core-applib``
@@ -67,7 +67,7 @@ Impl'n (g: a:)
 |
 
 
-|xref:rgcms.adoc#_rgcms_classes_super_manpage-FixtureScript[`o.a.i.applib.` +
+|xref:rgcms.adoc#_rgcms_classes_super_FixtureScript[`o.a.i.applib.` +
 `fixturescript` +
 `FixtureScript`]
 |``o.a.i.core`` +
@@ -76,7 +76,7 @@ Impl'n (g: a:)
 |
 
 
-|xref:rgcms.adoc#_rgcms_classes_super_manpage-FixtureScripts[`o.a.i.applib.` +
+|xref:rgcms.adoc#_rgcms_classes_super_FixtureScripts[`o.a.i.applib.` +
 `fixturescripts` +
 `FixtureScripts`]
 |``o.a.i.core`` +
@@ -93,13 +93,13 @@ Impl'n (g: a:)
 
 
 
-include::_rgcms_classes_super_manpage-AbstractContainedObject.adoc[leveloffset=+1]
-include::_rgcms_classes_super_manpage-AbstractDomainObject.adoc[leveloffset=+1]
-include::_rgcms_classes_super_manpage-AbstractFactoryAndRepository.adoc[leveloffset=+1]
-include::_rgcms_classes_super_manpage-AbstractService.adoc[leveloffset=+1]
-include::_rgcms_classes_super_manpage-AbstractSubscriber.adoc[leveloffset=+1]
-include::_rgcms_classes_super_manpage-AbstractViewModel.adoc[leveloffset=+1]
-include::_rgcms_classes_super_manpage-FixtureScript.adoc[leveloffset=+1]
-include::_rgcms_classes_super_manpage-FixtureScripts.adoc[leveloffset=+1]
+include::_rgcms_classes_super_AbstractContainedObject.adoc[leveloffset=+1]
+include::_rgcms_classes_super_AbstractDomainObject.adoc[leveloffset=+1]
+include::_rgcms_classes_super_AbstractFactoryAndRepository.adoc[leveloffset=+1]
+include::_rgcms_classes_super_AbstractService.adoc[leveloffset=+1]
+include::_rgcms_classes_super_AbstractSubscriber.adoc[leveloffset=+1]
+include::_rgcms_classes_super_AbstractViewModel.adoc[leveloffset=+1]
+include::_rgcms_classes_super_FixtureScript.adoc[leveloffset=+1]
+include::_rgcms_classes_super_FixtureScripts.adoc[leveloffset=+1]
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_AbstractContainedObject.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_AbstractContainedObject.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_AbstractContainedObject.adoc
new file mode 100644
index 0000000..806ed81
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_AbstractContainedObject.adoc
@@ -0,0 +1,32 @@
+[[_rgcms_classes_super_AbstractContainedObject]]
+= `AbstractContainedObject`
+: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 class is a convenience superclass for domain objects and services, providing general purpose methods for interacting with the framework.  These include:
+
+* `allMatches(Query)` - search for all objects matching the specified `Query`. +
++
++ Note that this, and other similar methods (eg `firstMatch(...)`, `uniqueMatch(...)`) will automatically flush the
+current transactoin.
+
+* `newTransientInstance(Class)` - to create a new instance of an object, with any services injected into it
+
+* `persistIfNotAlready(Object)` - to persist an object +
++
+In fact, the object is queued up to be persisted, and is only actually persisted either when the transaction commits, or
+when the transaction is flushed (typically when a query is performed).
+
+* `warnUser(String)` - generate a warning to the user
+
+* `getContainer()` - which returns the `DomainObjectContainer`
+
+Each of these methods simply delegates to an equivalent method in xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer[`DomainObjectContainer`].
+
+[TIP]
+====
+In practice we find that there's little to gain from subclassing; it's easier/less obscure to simply inject xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer[`DomainObjectContainer`] into a simple pojo class.
+====
+

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_AbstractDomainObject.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_AbstractDomainObject.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_AbstractDomainObject.adoc
new file mode 100644
index 0000000..a9dec97
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_AbstractDomainObject.adoc
@@ -0,0 +1,14 @@
+[[_rgcms_classes_super_AbstractDomainObject]]
+= `AbstractDomainObject`
+: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 class extends xref:rgcms.adoc#_rgcms_classes_super_AbstractContainedObject[`AbstractContainedObject`], adding
+in convenience methods for managing the persistence lifecycle of the object instance.
+
+Each of these methods, eg `isPersistent(...)`, delegates to an equivalent method in
+xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer[`DomainObjectContainer`].
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_AbstractFactoryAndRepository.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_AbstractFactoryAndRepository.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_AbstractFactoryAndRepository.adoc
new file mode 100644
index 0000000..8e662b4
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_AbstractFactoryAndRepository.adoc
@@ -0,0 +1,15 @@
+[[_rgcms_classes_super_AbstractFactoryAndRepository]]
+= `AbstractFactoryAndRepository`
+: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 class extends xref:rgcms.adoc#_rgcms_classes_super_AbstractContainedObject[`AbstractContainedObject`].  Its
+intent was to be a convenience subclass for services acting as either a repository or a factory, however note that
+ all of the methods that it defines are now deprecated.
+
+Instead, indicate that a service is repository using the xref:rgant.adoc#_rgant-DomainService_repositoryFor[`@DomainService#repositoryFor()`] attribute.
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_AbstractService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_AbstractService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_AbstractService.adoc
new file mode 100644
index 0000000..d4b01a6
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_AbstractService.adoc
@@ -0,0 +1,10 @@
+[[_rgcms_classes_super_AbstractService]]
+= `AbstractService`
+: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 class extends xref:rgcms.adoc#_rgcms_classes_super_AbstractContainedObject[`AbstractContainedObject`], adding
+in an implementation of `getId()` based upon the classes name.
+
+In practice there is little to gain from subclassing; simply inject xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer[`DomainObjectContainer`] for broadly equivalent functionality.

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_AbstractSubscriber.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_AbstractSubscriber.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_AbstractSubscriber.adoc
new file mode 100644
index 0000000..f5aa7b7
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_AbstractSubscriber.adoc
@@ -0,0 +1,18 @@
+[[_rgcms_classes_super_AbstractSubscriber]]
+= `AbstractSubscriber`
+: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 convenience superclass for creating subscriber domain services on the xref:rgsvc.adoc#_rgsvc-api_EventBusService[`EventBusService`].  It uses xref:rgant.adoc#_rgant-PostConstruct[`@PostConstruct`] and
+xref:rgant.adoc#_rgant-PreDestroy[`@PreDestroy`] callbacks to automatically register/unregister itself
+with the `EventBusService`.
+
+It's important that subscribers register before any domain services that might emit events on the
+xref:rgsvc.adoc#_rgsvc-api_EventBusService[`EventBusService`].  For example, the (non-ASF) http://github.com/isisaddons/isis-module-security[Isis addons' security] module provides a domain service that automatically
+seeds certain domain entities; these will generate xref:rgcms.adoc#_rgcms_classes_lifecycleevent[lifecycle events] and so
+any subscribers must be registered before such seed services.  The easiest way to do this is to use the
+xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] attribute.
+
+As a convenience, (as of `1.11.0-SNAPSHOT`) the `AbstractSubscriber` specifies this attribute.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_AbstractViewModel.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_AbstractViewModel.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_AbstractViewModel.adoc
new file mode 100644
index 0000000..1f6bb81
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_AbstractViewModel.adoc
@@ -0,0 +1,15 @@
+[[_rgcms_classes_super_AbstractViewModel]]
+= `AbstractViewModel`
+: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 class extends xref:rgcms.adoc#_rgcms_classes_super_AbstractContainedObject[`AbstractContainedObject`], also
+implementing the xref:rgcms.adoc#_rgcms_classes_super_ViewModel[`ViewModel`] interface.  In and of itself it provides no new behaviour.
+
+[TIP]
+====
+As an alternative, consider simply annotating the view model class with {@link org.apache.isis.applib.annotation.ViewModel}.
+====
+


[05/52] [abbrv] isis git commit: ISIS-1243: renamed rg.adoc to rgcms.adoc

Posted by mg...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-validate.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-validate.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-validate.adoc
new file mode 100644
index 0000000..74ccf58
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-validate.adoc
@@ -0,0 +1,113 @@
+[[_rgcms_methods_prefixes_manpage-validate]]
+= `validate...()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The `validate...()` supporting method is called for properties, actions and action parameters.  It allows the proposed new value for a property to be rejected, or the proposed argument of an action parameter to be rejected, or to reject a whole set of action arguments for an actio invocation.
+
+
+The reason for vetoing a modification/invocation is normally returned as a string.  However, Apache Isis' xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[i18n support] extends this so that reasons can be internationalized if required.
+
+
+
+== Action Parameter
+
+For an action parameter in (0-based) position _N_, and of type `T`, the signature is:
+
+[source,java]
+----
+public String validateNXxx(T proposed) { ... }
+----
+
+where the returned string is the reason why the argument is rejected (or `null` if not vetoed).
+
+
+For example:
+
+[source,java]
+----
+public class Customer {
+    public Order placeOrder(
+            final Product product,
+            @ParameterLayout(named="Quantity")
+            final int quantity) {
+        ...
+    }
+    public String validate0PlaceOrder(
+            final Product product) {
+        return product.isDiscontinued()
+                    ? "Product has been discontinued"
+                    : null;
+    }
+    ...
+}
+----
+
+
+== Action Parameter Set
+
+In addition to validating a single single action argument, it is also possible to validate a complete set of action arguments.  The signature is:
+
+[source,java]
+----
+public String validateXxx(...) { ... }
+----
+
+where the returned string is the reason why the argument is rejected (or `null` if not vetoed), and the supporting method takes the same parameter types as the action itself.
+
+
+For example:
+
+[source,java]
+----
+public class Customer {
+    public Order placeOrder(
+            final Product product,
+            @ParameterLayout(named="Quantity")
+            final int quantity) {
+        ...
+    }
+    public String validatePlaceOrder(
+            final Product product,
+            final int quantity) {
+        return quantity > product.getOrderLimit()
+                    ? "May not order more than " + product.getOrderLimit() + " items for this product"
+                    : null;
+    }
+    ...
+}
+----
+
+
+
+== Properties
+
+For properties of type `T` the signature of the supporting method is:
+
+[source,java]
+----
+public String validateXxx(T proposed) { ... }
+----
+
+where the returned string is the reason the modification is vetoed (or `null` if not vetoed).
+
+
+
+For example:
+
+[source,java]
+----
+public class Customer {
+    public BigDecimal getCreditLimit() { ... }
+    public void setCreditLimit(BigDecimal creditLimit) { ... }
+    public validateCreditLimit(BigDecimal creditLimit) {
+        return creditLimit.compareTo(BigDecimal.ZERO) < 0
+                    ? "Credit limit cannot be negative"
+                    : null;
+    }
+    ...
+}
+----

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-validateAddTo.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-validateAddTo.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-validateAddTo.adoc
new file mode 100644
index 0000000..3458533
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-validateAddTo.adoc
@@ -0,0 +1,45 @@
+[[_rgcms_methods_prefixes_manpage-validateAddTo]]
+= `validateAddTo...()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The `validateAddTo...()` supporting method is called whenever an object is to be added to a collection. Its purpose is to validate the proposed object and possibly veto the change.
+
+
+[NOTE]
+====
+Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer].  The suggested workaround is to simply define an action.
+====
+
+
+The signature of the supporting method for a collection with element type `E` is:
+
+[source,java]
+----
+public String validateAddToXxx(E element) { ... }
+----
+
+where the returned string is the reason the collection modification invocation is vetoed (or `null` if not vetoed).  Apache Isis' xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[i18n support] extends this so that reasons can be internationalized if required.
+
+
+For example:
+
+[source,java]
+----
+public class LibraryMember {
+    public SortedSet<Book> getBorrowed() { ... }
+    public void setBorrowed(SortedSet<Book> borrowed) { ... }
+    public String validateAddToBorrowed(Book book) {
+        return book.isReference()? "Reference books cannot be borrowed": null;
+    }
+    public void validateRemoveFromBorrowed(Book book) { ... }
+    ...
+}
+----
+
+
+See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-addTo[`addTo...()`] and  xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-validateRemoveFrom[`validateRemoveFrom...()`]`
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-validateRemoveFrom.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-validateRemoveFrom.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-validateRemoveFrom.adoc
new file mode 100644
index 0000000..dbb9979
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-validateRemoveFrom.adoc
@@ -0,0 +1,45 @@
+[[_rgcms_methods_prefixes_manpage-validateRemoveFrom]]
+= `validateRemoveFrom...()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The `validateRemoveFrom...()` supporting method is called whenever an object is to be removed from a collection. Its purpose is to validate the proposed object removal and possibly veto the change.
+
+
+[NOTE]
+====
+Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer].  The suggested workaround is to simply define an action.
+====
+
+
+The signature of the supporting method for a collection with element type `E` is:
+
+[source,java]
+----
+public String validateRemoveFromXxx(E element) { ... }
+----
+
+where the returned string is the reason the collection modification invocation is vetoed (or `null` if not vetoed).  Apache Isis' xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[i18n support] extends this so that reasons can be internationalized if required.
+
+
+For example:
+
+[source,java]
+----
+public class LibraryMember {
+    public SortedSet<Book> getBorrowed() { ... }
+    public void setBorrowed(SortedSet<Book> borrowed) { ... }
+    public String validateAddToBorrowed(Book book) { ... }
+    public void validateRemoveFromBorrowed(Book book) {
+        return !book.hasBeenReadBy(this)? "You didn't read this book yet": null;
+    }
+    ...
+}
+----
+
+
+See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-removeFrom[`removeFrom...()`] and  xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-validateAddTo[`validateAddTo...()`]`
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved.adoc
new file mode 100644
index 0000000..bae5286
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved.adoc
@@ -0,0 +1,58 @@
+[[_rgcms_methods_reserved]]
+= Reserved Methods
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The table below lists the reserved methods that are recognized as part of Apache Isis' default programming model.
+
+.Reserved Methods
+[cols="1,4a", options="header"]
+|===
+
+|Method
+|Description
+
+|xref:rgcms.adoc#_rgcms_methods_reserved_manpage-cssClass[`cssClass()`]
+|Provides a CSS class for this object instance.  In conjunction with xref:rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css`], can therefore provide custom styling of an object instance wherever it is rendered. +
+
+See also xref:rgcms.adoc#_rgcms_methods_reserved_manpage-title[`title()`] and xref:rgcms.adoc#_rgcms_methods_reserved_manpage-iconName[`iconName()`].
+
+|xref:rgcms.adoc#_rgcms_methods_reserved_manpage-disable[`disable(...)`]
+|Disable all or some of an object's properties
+
+|xref:rgcms.adoc#_rgcms_methods_reserved_manpage-getId[`getId()`]
+|Provides an optional unique identifier of a service. +
+
+If not provided, the service's fully-qualified class name is used.
+
+|xref:rgcms.adoc#_rgcms_methods_reserved_manpage-hide[`hide(...)`]
+|Hide all or some of an object's properties
+
+|xref:rgcms.adoc#_rgcms_methods_reserved_manpage-iconName[`iconName()`]
+|Provides the name of the image to render, usually alongside the title, to represent the object. If not provided, then the class name is used to locate an image. +
+
+See also xref:rgcms.adoc#_rgcms_methods_reserved_manpage-title[`title()`] and xref:rgcms.adoc#_rgcms_methods_reserved_manpage-cssClass[`cssClass()`]
+
+|xref:rgcms.adoc#_rgcms_methods_reserved_manpage-title[`title()`]
+|Provides a title for the object. +
+
+See also xref:rgcms.adoc#_rgcms_methods_reserved_manpage-iconName[`iconName()`] and xref:rgcms.adoc#_rgcms_methods_reserved_manpage-cssClass[`cssClass()`]
+
+|xref:rgcms.adoc#_rgcms_methods_reserved_manpage-validate[`validate()`]
+|Validate the object's state prior to persisting.
+
+|===
+
+
+
+
+include::_rgcms_methods_reserved_manpage-cssClass.adoc[leveloffset=+1]
+include::_rgcms_methods_reserved_manpage-disable.adoc[leveloffset=+1]
+include::_rgcms_methods_reserved_manpage-getId.adoc[leveloffset=+1]
+include::_rgcms_methods_reserved_manpage-hide.adoc[leveloffset=+1]
+include::_rgcms_methods_reserved_manpage-iconName.adoc[leveloffset=+1]
+include::_rgcms_methods_reserved_manpage-title.adoc[leveloffset=+1]
+include::_rgcms_methods_reserved_manpage-validate.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-cssClass.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-cssClass.adoc
new file mode 100644
index 0000000..ecf7f39
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-cssClass.adoc
@@ -0,0 +1,46 @@
+[[_rgcms_methods_reserved_manpage-cssClass]]
+= `cssClass()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The `cssClass()` returns a CSS class for a particular object instance.
+
+The xref:ugvw.adoc#[Wicket viewer] wraps the object's representation in a containing `<div>` with the class added.  This is done both for rendering the object either in a table or when rendering the object on its own page.
+
+In conjunction with xref:rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css`], can therefore provide custom styling of an object instance wherever it is rendered. +
+
+
+For example, the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] uses this technique to add a strikethrough for completed todo items.  This is shown on the home page:
+
+image::{_imagesdir}reference-methods/reserved/cssClass/strikethrough.png[width="800px",link="{_imagesdir}reference-methods/reserved/cssClass/strikethrough.png"]
+
+
+The code to accomplish this is straightforward:
+
+[source,java]
+----
+public class ToDoItem ... {
+    public String cssClass() {
+        return !isComplete() ? "todo" : "done";
+    }
+    ...
+}
+----
+
+In the xref:rgcfg.adoc#_rgcfg_application-specific_application-css[application.css], the following styles were then added:
+
+[source,css]
+----
+tr.todo {
+}
+tr.done {
+    text-decoration: line-through;
+    color: #d3d3d3;
+}
+----
+
+
+See also xref:rgcms.adoc#_rgcms_methods_reserved_manpage-title[`title()`] and xref:rgcms.adoc#_rgcms_methods_reserved_manpage-iconName[`iconName()`].

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-disable.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-disable.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-disable.adoc
new file mode 100644
index 0000000..a56b684
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-disable.adoc
@@ -0,0 +1,102 @@
+[[_rgcms_methods_reserved_manpage-disable]]
+= `disable()`
+: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/
+
+
+One use case that Apache Isis supports is that of a domain object with a lifecycle whereby at some stage it should become immutable: all its properties/collections should be disabled, and/or its actions become not invokable.
+
+It would be painful to have to write a separate xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-disable[`disable...()`] method for each and every member, so instead Isis allows a single `disable...(...)` method to be implemented that is applied to all members.
+
+The signature of the method is:
+
+[source,java]
+----
+public String disable(Identifier.Type identifierType) { ... }
+----
+
+where `Identifier.Type` is part of the Isis applib (nested static class of `o.a.i.applib.Identifier`) to distinguish between an interaction with an action, a property or an action.
+
+Note that Apache Isis' xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[i18n support] extends this so that the returned reason can also be internationalized.
+
+For example:
+
+[source,java]
+----
+public String disable(Identifier.Type identifierType) {
+    return !calendarService.isOfficeHours(clock.today()
+            ? "Cannot modify objects outside of office hours"
+            : null;
+}
+----
+
+See also the similar methods to xref:rgcms.adoc#_rgcms_methods_reserved_manpage-hide[`hide()`] object members en-masse.
+
+
+== Alternatives
+
+An alternative design -- and one that could be easily argued is actually more flexible -- is to leverage domain events with vetoing subscribers.
+
+With this approach we define, for a given domain class, a base `PropertyDomainEvent`, `CollectionDomainEvent` and `ActionDomainEvent`.  A good pattern is to make these nested static classes.  For example:
+
+[source,java]
+----
+public class ToDoItem ... {
+    public static abstract class PropertyDomainEvent<T>
+            extends ToDoAppDomainModule.PropertyDomainEvent<ToDoItem, T> {
+        ...
+    }
+    ...
+}
+----
+
+where in turn:
+
+[source,java]
+----
+public final class ToDoAppDomainModule {
+    private ToDoAppDomainModule(){}
+    public abstract static class PropertyDomainEvent<S,T>
+            extends org.apache.isis.applib.services.eventbus.PropertyDomainEvent<S,T> {
+        ...
+    }
+    ...
+}
+----
+
+Then, each property/collection/action emits either these base domain events or their own subclass:
+
+[source,java]
+----
+public class ToDoItem ... {
+    public static class DescriptionDomainEvent
+            extends PropertyDomainEvent<String> {
+        ...
+    }
+    @Property(
+        domainEvent = DescriptionDomainEvent.class
+    )
+    public String getDescription() { ... }
+    ...
+}
+----
+
+A vetoing subscriber can then subscribe to the domain events and veto access, eg:
+
+[source,java]
+----
+@DomainObject
+public class VetoOutOfOfficeHours {
+    @Subscribe
+    public void on(ToDoItem.PropertyDomainEvent ev) {
+        if(!calendarService.isOfficeHours(clock.today()) {
+            ev.veto("Cannot modify objects outside of office hours");
+        }
+    }
+    ...
+}
+----
+
+Obviously there's an awful lot more boilerplate here, but there's also a lot more flexibility.
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-getId.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-getId.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-getId.adoc
new file mode 100644
index 0000000..e2a46ea
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-getId.adoc
@@ -0,0 +1,19 @@
+[[_rgcms_methods_reserved_manpage-getId]]
+= `getId()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+The `getId()` method applies only to domain services, and allows a unique identifer to be provided for that service.
+
+This identifier corresponds in many ways to the xref:rgant.adoc#_rgant-DomainObject_objectType[`objectType()`] attribute for domain objects; it is used as an internal identifier but also appears in URLs within the xref:ugvro.adoc#[RestfulObjects viewer]'s REST API.
+
+If the identifier is omitted, the services fully qualified class name is used.
+
+[TIP]
+====
+Unlike domain objects, where the use of an object type is strongly encouraged (eg using xref:rgant.adoc#_rgant-PersistenceCapable[`@PersistenceCapable`]), it matters much less if an id is specified for domain services.  The principle benefit is shorter URLs in the REST API.
+====
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-hide.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-hide.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-hide.adoc
new file mode 100644
index 0000000..c069657
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-hide.adoc
@@ -0,0 +1,39 @@
+[[_rgcms_methods_reserved_manpage-hide]]
+= `hide()`
+: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/
+
+
+
+One use case that Apache Isis supports is that of a domain object with a lifecycle whereby at some stage some number of the object's members should be hidden.  For example, for an object that at some stage is logically immutable, we might want to make all its properties/collections unmodifiable and hide all its actions.
+
+While we could write a separate xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-hide[`hide...()`] method for each and every action, this could become painful.  So instead Isis allows a single `hide...(...)` method to be implemented that is applied to all members.
+
+The signature of the method is:
+
+[source,java]
+----
+public boolean hide(Identifier.Type identifierType) { ... }
+----
+
+where `Identifier.Type` is part of the Isis applib (nested static class of `o.a.i.applib.Identifier`) to distinguish between an interaction with an action, a property or an action.
+
+For example:
+
+[source,java]
+----
+public boolean hide(Identifier.Type identifierType) {
+    return identifierType == Identifier.Type.ACTION && isFrozen();
+}
+----
+
+See also the similar method to xref:rgcms.adoc#_rgcms_methods_reserved_manpage-disable[`disable()`] object members en-masse.
+
+
+== Alternatives
+
+An alternative design -- and one that could be easily argued is actually more flexible -- is to leverage domain events with vetoing subscribers.
+
+There is further discussion on this approach in xref:rgcms.adoc#_rgcms_methods_reserved_manpage-disable[here].
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-iconName.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-iconName.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-iconName.adoc
new file mode 100644
index 0000000..049151b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-iconName.adoc
@@ -0,0 +1,36 @@
+[[_rgcms_methods_reserved_manpage-iconName]]
+= `iconName()`
+: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/
+
+
+Every object is represented by an icon; this is based on the domain object's simple name.  The xref:ugvw.adoc#[Wicket viewer] searches for the image in the same package as the `.class` file for the domain object.
+
+The `iconName()` allows the icon that to be used to change for individual object instances.  These are usually quite subtle, for example to reflect the particular status of an object.  The value returned by the `iconName()` method is added as a suffix to the base icon name.
+
+For example, the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] uses this technique to add an overlay for todo items that have been completed:
+
+image::{_imagesdir}reference-methods/reserved/iconName/differing.png[width="200px",link="{_imagesdir}reference-methods/reserved/iconName/differing.png"]
+
+
+
+The screenshot below shows the location of these png icon files:
+
+image::{_imagesdir}reference-methods/reserved/iconName/png-files.png[width="200px",link="{_imagesdir}reference-methods/reserved/iconName/png-files.png"]
+
+
+
+The code to accomplish this is straightforward:
+
+[source,java]
+----
+public class ToDoItem ... {
+    public String iconName() {
+        return !isComplete() ? "todo" : "done";
+    }
+    ...
+}
+----
+
+See also xref:rgcms.adoc#_rgcms_methods_reserved_manpage-title[`title()`] and xref:rgcms.adoc#_rgcms_methods_reserved_manpage-cssClass[`cssClass()`]

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-title.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-title.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-title.adoc
new file mode 100644
index 0000000..394c9f1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-title.adoc
@@ -0,0 +1,65 @@
+[[_rgcms_methods_reserved_manpage-title]]
+= `title()`
+: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/
+
+
+
+Every object is represented by a title.  This appears both as a main header for the object when viewed as well as being used as a hyperlink within properties and collections.   It therefore must contain enough information for the end-user to distinguish the object from any others.
+
+This is most commonly done by including some unique key within the title, for example a customer's SSN, or an order number, and so forth.  However note that Apache Isis itself does _not_ require the title to be unique; it is merely recommended in most cases.
+
+An object's title can be constructed in various ways, but the most flexible is to use the `title()` method.  The signature of this method is usually:
+
+[source,java]
+----
+public String title() { ... }
+----
+
+Note that Apache Isis' xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[i18n support] extends this so that titles can also be internationalized.
+
+For example, the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] uses this technique to add an overlay for todo items that have been completed:
+
+[source,java]
+----
+public String title() {
+    final TitleBuffer buf = new TitleBuffer();                              // <1>
+    buf.append(getDescription());
+    if (isComplete()) {                                                     // <2>
+        buf.append("- Completed!");
+    } else {
+        try {
+            final LocalDate dueBy = wrapperFactory.wrap(this).getDueBy();   // <3>
+            if (dueBy != null) {
+                buf.append(" due by", dueBy);
+            }
+        } catch(final HiddenException ignored) {                            // <4>
+        }
+    }
+    return buf.toString();
+}
+----
+<1> simple xref:rgcms.adoc#_rgcms_classes_utility_manpage-TitleBuffer[tility class] to help construct the title string
+<2> imperative conditional logic
+<3> using the xref:rgsvc.adoc#_rgsvc-api_WrapperFactory[`WrapperFactory`] to determine if the `dueBy` field is visible for this user ...
+<4> ... but ignore if not
+
+As the example above shows, the implementation can be as complex as you like.
+
+In many cases, though, you may be able to use the xref:rgant.adoc#_rgant-Title[`@Title`] annotation.
+
+
+See also xref:rgcms.adoc#_rgcms_methods_reserved_manpage-iconName[`iconName()`] and xref:rgcms.adoc#_rgcms_methods_reserved_manpage-cssClass[`cssClass()`]
+
+
+
+
+
+
+
+
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-validate.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-validate.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-validate.adoc
new file mode 100644
index 0000000..24c83f9
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-validate.adoc
@@ -0,0 +1,27 @@
+[[_rgcms_methods_reserved_manpage-validate]]
+= `validate()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The `validate()` method is used to specify that invariants pertaining to an object's state are enforced.
+
+
+[WARNING]
+====
+(As of 1.8.0) there are known limitations with this functionality.  Invariants are enforced when an object is initially created and when it is edited, however invariants are currently _not_ enforced if an action is invoked.
+====
+
+
+The signature of the method is:
+
+[source,java]
+----
+public String validate() { ... }
+----
+
+where the returned string is the reason that the invocation is vetoed.
+
+Note that Apache Isis' xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[i18n support] extends this so that the returned reason can also be internationalized.

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-aim.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-aim.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-aim.adoc
new file mode 100644
index 0000000..4434846
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-aim.adoc
@@ -0,0 +1,97 @@
+[[_rgcms_schema-aim]]
+= Action Invocation Memento
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+The "aim" schema defines the serialized form (or memento) of an action invocation.
+
+Action invocations are captured (in memory rather than in serialized form) when the end-user invokes the action
+"through" the UI, by way of the xref:rgsvc.adoc#_rgsvc-api_CommandContext[CommandContext] service. Using the
+`ActionInvocationMementoDtoUtils` utility class, a service can instantiate `ActionInvocationMementoDto` which can then
+be serialized to/from using the same `ActionInvocationMementoDtoUtils` class.
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<xs:schema targetNamespace="http://isis.apache.org/schema/aim"                              <!--1-->
+           elementFormDefault="qualified"
+           xmlns:xs="http://www.w3.org/2001/XMLSchema"
+           xmlns="http://isis.apache.org/schema/aim"
+           xmlns:common="http://isis.apache.org/schema/common">
+
+    <xs:import namespace="http://isis.apache.org/schema/common"                             <!--2-->
+               schemaLocation="http://isis.apache.org/schema/common/common-1.0.xsd"/>
+
+    <xs:element name="actionInvocationMementoDto">                                          <!--3-->
+        <xs:complexType>
+            <xs:sequence>
+                <xs:element name="metadata">
+                    <xs:complexType>
+                        <xs:sequence>
+                            <xs:element name="transactionId" type="xs:string"/>             <!--4-->
+                            <xs:element name="sequence" type="xs:int"/>                     <!--5-->
+                            <xs:element name="timestamp" type="xs:dateTime"/>               <!--6-->
+                            <xs:element name="target" type="common:oidDto"/>                <!--7-->
+                            <xs:element name="targetClass" type="xs:string"/>               <!--8-->
+                            <xs:element name="targetAction" type="xs:string"/>              <!--9-->
+                            <xs:element name="actionIdentifier" type="xs:string"/>          <!--10-->
+                            <xs:element name="user" type="xs:string"/>                      <!--11-->
+                            <xs:element name="title" type="xs:string"/>                     <!--12-->
+                        </xs:sequence>
+                    </xs:complexType>
+                </xs:element>
+                <xs:element name="payload">
+                    <xs:complexType>
+                        <xs:sequence>
+                            <xs:element name="parameters">                                  <!--13-->
+                                <xs:complexType>
+                                    <xs:sequence maxOccurs="unbounded">
+                                        <xs:element name="param" type="paramDto"/>
+                                    </xs:sequence>
+                                    <xs:attribute name="num" use="required" type="xs:int"/>
+                                </xs:complexType>
+                            </xs:element>
+                            <xs:element name="return" type="common:valueDto"                <!--14-->
+                                        minOccurs="0" maxOccurs="1"/>
+                        </xs:sequence>
+                    </xs:complexType>
+                </xs:element>
+            </xs:sequence>
+        </xs:complexType>
+    </xs:element>
+
+    <xs:complexType name="paramDto">                                                        <!--15-->
+        <xs:sequence>
+            <xs:element name="value" type="common:valueDto"/>                               <!--16-->
+        </xs:sequence>
+        <xs:attribute name="parameterName" use="required" type="xs:string"/>                <!--17-->
+        <xs:attribute name="parameterType" use="required" type="common:valueType"/>
+        <xs:attribute name="null" use="optional" type="xs:boolean"/>
+    </xs:complexType>
+</xs:schema>
+----
+<1> the aim schema has a namespace URI of "http://isis.apache.org/schema/aim".  Although URIs are not the same as URLs, you will find that the schemas are also downloadable from this location.
+<2> reuses the xref:rgcms.adoc#_rgcms_schema-common[common] schema
+<3> definition of the `actionInvocationMementoDto` complex type. This consists of metadata (the transaction identifier, the target object, the initiating user) and the payload (the action parameter/arguments, the return value if known).
+<4> the unique transaction Id (a guid) allocated by the framework for each and every transaction
+<5> a sequence number within the transaction.  It is possible for there to be more than one action invocation to be
+<6> when the action was invoked
+<7> target object, as an OID (using `oidDto` from the xref:rgcms.adoc#_rgcms_schema-common[common] schema)
+<8> fully qualified class name of the target object, for information only
+<9> name of the action, for information only
+<10> Javadoc style unique identifier for the action.
+<11> User that invoked the action
+<12> title of the target object, for information only
+<13> Collection of parameter/arguments, defined in terms of the `paramDto` complex type (discussed just below)
+<14> The return value of the action, if known (and not void)
+<15> The `paramDto` defines both an action parameter and its corresponding argument values
+<16> The value of the parameter, in other words an argument value
+<17> Metadata about the parameter itself: its name, type, optionality.
+
+[NOTE]
+====
+As of `1.11.0` this schema is not used directly by the framework; in particular `Command#setMemento(...)` sets a similar
+but less formal XML structure.  This may change in the future.
+====

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-common.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-common.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-common.adoc
new file mode 100644
index 0000000..2359c4e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-common.adoc
@@ -0,0 +1,103 @@
+[[_rgcms_schema-common]]
+= Common Schema
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The main purpose of the common schema is to define the `oidDto` complex type: the object's type and its identifier.
+This is basically a formal XML equivalent to the `Bookmark` object obtained from the
+xref:rgsvc.adoc#_rgsvc-api_BookmarkService[`BookmarkService`].
+
+Although simple, this is an enormously powerful concept, in that it represents a URI to any domain object managed by
+a given Apache Isis application.  With it, we have the ability to lookup any arbitrary object.  Further discussion and
+examples can be found xref:ug.adoc#_ug_core-concepts_building-blocks_oid[here].
+
+
+[source,xml]
+----
+<xs:schema targetNamespace="http://isis.apache.org/schema/common"                           <!--1-->
+           elementFormDefault="qualified"
+           xmlns="http://isis.apache.org/schema/common"
+           xmlns:xs="http://www.w3.org/2001/XMLSchema">
+
+    <xs:complexType name="oidDto">                                                          <!--2-->
+        <xs:sequence>
+            <xs:element name="objectType" type="xs:string"/>                                <!--3-->
+            <xs:element name="objectIdentifier" type="xs:string"/>                          <!--4-->
+        </xs:sequence>
+        <xs:attribute name="objectState" type="bookmarkObjectState" default="persistent"/>
+    </xs:complexType>
+
+    <xs:simpleType name="bookmarkObjectState">                                              <!--5-->
+        <xs:restriction base="xs:string">
+            <xs:enumeration value="persistent"/>
+            <xs:enumeration value="transient"/>
+            <xs:enumeration value="viewModel"/>
+        </xs:restriction>
+    </xs:simpleType>
+    ...
+</xs:schema>
+----
+<1> the common schema has a namespace URI of "http://isis.apache.org/schema/common".  Although URIs are not the same as URLs, you will find that the schemas are also downloadable from this location.
+<2> the `oidDto` complex type defines the unique identifier for any domain object: its type, and an identifier.  The `objectState` attribute is of type `bookmarkObjectState` and will typically be "transient" or "viewModel"
+<3> the object type, corresponding to either the
+xref:rgant.adoc#_rgant-DomainObject_objectType[`@DomainObject#objectType()`] attribute, or to the (JDO)
+xref:rgant.adoc#_rgant-PersistenceCapable[`@PersistenceCapable`] annotation (`schema` and/or `table`
+attributes), or to the (JDO) xref:rgant.adoc#_rgant-Discriminator[`@Discriminator`] annotation.  If none
+is specified, then the fully
+qualified class name will be used.
+<4> the object identifier (aka primary key), converted to string form.
+<5> the `bookmarkObjectState` enumerates the possible persistence states of the referenced object.  Although "transient" is shown,
+in practice the only types of objects will be "persistent" (entities) or "viewModel".
+
+The `oidDto` complex type is used in two specific places by the framework:
+
+* first, as a means of serializing JAXB view model/DTOs (annotated with
+xref:rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`]), that reference domain entities. +
++
+These references are serialized instead into OIDs
+
+* second, as references to the target of action invocations, as described by the
+xref:rgcms.adoc#_rgcms_schema-aim[action invocation memento] schema. +
++
+They are also used to represent references to any action arguments that take domain object entities.
+
+The common schema also defines two further types: the `valueDto` complex type and the `valueType` simple type:
+
+[source,xml]
+----
+<xs:schema targetNamespace="http://isis.apache.org/schema/common"
+           elementFormDefault="qualified"
+           xmlns="http://isis.apache.org/schema/common"
+           xmlns:xs="http://www.w3.org/2001/XMLSchema">
+    ...
+    <xs:complexType name="valueDto">                              <!--1-->
+        <xs:choice minOccurs="0" maxOccurs="1">
+            <xs:element name="string" type="xs:string"/>
+            <xs:element name="byte" type="xs:byte"/>
+            <xs:element name="short" type="xs:short"/>
+            ...
+            <xs:element name="localTime" type="xs:time"/>
+            <xs:element name="reference" type="oidDto"/>
+        </xs:choice>
+    </xs:complexType>
+
+    <xs:simpleType name="valueType">                              <!--2-->
+        <xs:restriction base="xs:string">
+            <xs:enumeration value="string"/>
+            <xs:enumeration value="byte"/>
+            <xs:enumeration value="short"/>
+            ...
+            <xs:enumeration value="isisApplibClob"/>
+            <xs:enumeration value="reference"/>
+        </xs:restriction>
+    </xs:simpleType>
+</xs:schema>
+----
+
+These two type definitions are just building blocks, also used within the
+xref:rgcms.adoc#_rgcms_schema-aim[action iInvocation memento] schema.  The first, `valueDto` is intended to hold any valid
+value, eg of an argument to an action.  The second, `valueType`, enumerates the different types of vales, eg of a
+formal parameter to an action.

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema.adoc
new file mode 100644
index 0000000..65f2d1e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema.adoc
@@ -0,0 +1,24 @@
+[[_rgcms_schema]]
+= Schema
+: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/
+
+
+Most applications need to integrate with other apps in the enterprise.  To facilitate such integration scenarios,
+Apache Isis defines two standard XSD schemas:
+
+* the xref:rgcms.adoc#_rgcms_schema-common[common schema], which defines the `oidDto` complex type: the object's type and its identifier. +
++
+It also defines some two further XSD types, which are building blocks used in...
+
+* the xref:rgcms.adoc#_rgcms_schema-aim[action memento invocation] schema, which allows action invocations to be captured
+and reified. +
++
+The (non-ASF) http://github.com/isisaddons/isis-module-publishmq[Isis addons' publishmq] module uses this XML format
+to publish messages onto an link:http://activemq.apache.org[Apache ActiveMQ] message queue.
+
+The sections below discuss these schemas in more detail.
+
+include::_rgcms_schema-common.adoc[leveloffset=+1]
+include::_rgcms_schema-aim.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api.adoc
index 067752e..660f74e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api.adoc
@@ -132,7 +132,7 @@ xref:rgsvc.adoc#_rgsvc-spi_CommandService[`CommandService`] for persistent `Comm
 `services.` +
 `fixturespec` +
 `FixtureScriptsDefault`]
-|Fallback implementation of xref:rg.adoc#_rg_classes_super_manpage-FixtureScripts[`FixtureScripts`], providing the ability to execute fixture scripts.
+|Fallback implementation of xref:rgcms.adoc#_rgcms_classes_super_manpage-FixtureScripts[`FixtureScripts`], providing the ability to execute fixture scripts.
 |`FixtureScriptsDefault` +
 ``o.a.i.core`` +
 ``isis-core-applib``
@@ -214,7 +214,7 @@ SpecificationProvider`].
 |xref:rgsvc.adoc#_rgsvc-api_SudoService[`o.a.i.applib.` +
 `services.sudo` +
 `SudoService`]
-|For use in testing while running xref:rg.adoc#_rg_classes_super_manpage-FixtureScripts[fixture scripts], allows a block of code to run as a specified user account.
+|For use in testing while running xref:rgcms.adoc#_rgcms_classes_super_manpage-FixtureScripts[fixture scripts], allows a block of code to run as a specified user account.
 |`SudoServiceDefault` +
 ``o.a.i.core`` +
 ``isis-core-runtime``

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_ActionInvocationContext.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_ActionInvocationContext.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_ActionInvocationContext.adoc
index d313305..caea35d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_ActionInvocationContext.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_ActionInvocationContext.adoc
@@ -65,7 +65,7 @@ public class ToDoItem ... {
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' default
+`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' default
 implementation of `ActionInvocationContext` class is automatically registered (it is annotated with `@DomainService`)
 so no further configuration is required.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_BackgroundService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_BackgroundService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_BackgroundService.adoc
index e95e159..e56a9dc 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_BackgroundService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_BackgroundService.adoc
@@ -94,7 +94,7 @@ The user would be returned a domain object representing their action invocation.
 == Registering the Services
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `BackgroundService` is automatically registered (it is annotated with `@DomainService`) so no
 further configuration is required.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_BookmarkService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_BookmarkService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_BookmarkService.adoc
index 0f9b12a..5ce3312 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_BookmarkService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_BookmarkService.adoc
@@ -105,7 +105,7 @@ Bookmarks are also used by the (non-ASF) http://github.com/isisaddons/isis-modul
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `BookmarkService` is automatically registered (it is annotated with `@DomainService`) so no further
 configuration is required.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_ClockService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_ClockService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_ClockService.adoc
index e1073f5..c5e0e4f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_ClockService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_ClockService.adoc
@@ -93,7 +93,7 @@ public class NntpClockServiceInitializer  {
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `ClockService` is automatically registered (it is annotated with `@DomainService`) so no further
 configuration is required.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_CommandContext.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_CommandContext.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_CommandContext.adoc
index d11056a..c1c1bfc 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_CommandContext.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_CommandContext.adoc
@@ -197,7 +197,7 @@ String user = commandContext.getCommand().getUser();
 == Registering the Services
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `CommandContext` service is automatically registered and injected (it is annotated with
 `@DomainService`) so no further configuration is required.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DeepLinkService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DeepLinkService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DeepLinkService.adoc
index 2cd3639..8512b05 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DeepLinkService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DeepLinkService.adoc
@@ -47,7 +47,7 @@ The Wicket viewer core framework provides a default implementation of this API:
 == Registering the Services
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]), _and_ that the
+`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]), _and_ that the
 xref:ugvw.adoc#[Wicket viewer] is being used, then an implementation of `DeepLinkService` is
 automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer.adoc
index 9ac07cd..5b30b67 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer.adoc
@@ -34,7 +34,7 @@ include::_rgsvc-api_DomainObjectContainer_services-api.adoc[leveloffset=+1]
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `DomainObjectContainer` service is automatically registered and injected (it is annotated with
 `@DomainService`) so no further configuration is required.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_object-creation-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_object-creation-api.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_object-creation-api.adoc
index b33e8f6..d24f7fb 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_object-creation-api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_object-creation-api.adoc
@@ -21,7 +21,7 @@ public interface DomainObjectContainer {
 }
 ----
 <1> create a new non-persisted domain entity.  Any services will be automatically injected into the service
-<2> create a new view model, with the specified memento (as per xref:rg.adoc#_rg_classes_super_manpage-AbstractViewModel[ViewModel#viewModelMemento()].  In general it is easier to just annotate with xref:rgant.adoc#_rgant-ViewModel[`@ViewModel`] and let Apache Isis manage the memento automatically.
+<2> create a new view model, with the specified memento (as per xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractViewModel[ViewModel#viewModelMemento()].  In general it is easier to just annotate with xref:rgant.adoc#_rgant-ViewModel[`@ViewModel`] and let Apache Isis manage the memento automatically.
 <3> programmatically instantiate a mixin, as annotated with
 xref:rgant.adoc#_rgant-Mixin[`@Mixin`] or xref:rgant.adoc#_rgant-DomainObject_nature[`@DomainObject#nature()`].
 
@@ -40,9 +40,9 @@ Doing this will not inject any domain services, but they can be injected manuall
 
 [NOTE]
 ====
-Calling `new(...)` also this circumvents Apache Isis' xref:rg.adoc#_rg_methods_reserved_manpage-created[`created()`]
+Calling `new(...)` also this circumvents Apache Isis' xref:rgcms.adoc#_rgcms_methods_reserved_manpage-created[`created()`]
 callback, and in addition any default values for properties (either explicitly set by
-xref:rg.adoc#_rg_methods_prefixes_manpage-default[`default...()`] or defaulted implicitly according to Apache Isis'
+xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-default[`default...()`] or defaulted implicitly according to Apache Isis'
 own conventions) will not be called either.  If you don't intend to use these features, though, the net effect is code
 that has less coupling to Isis and is arguably easier to understand (has "less magic" happening).
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_presentation-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_presentation-api.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_presentation-api.adoc
index 476d6c5..a3de5d0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_presentation-api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_presentation-api.adoc
@@ -7,7 +7,7 @@
 
 
 
-A responsibility of every domain object is to return a title.  This can be done declaratively using the xref:rgant.adoc#_rgant-Title[`@Title`] annotation on property/ies, or it can be done imperatively by writing a xref:rg.adoc#_rg_methods_reserved_manpage-title[`title()`] method.
+A responsibility of every domain object is to return a title.  This can be done declaratively using the xref:rgant.adoc#_rgant-Title[`@Title`] annotation on property/ies, or it can be done imperatively by writing a xref:rgcms.adoc#_rgcms_methods_reserved_manpage-title[`title()`] method.
 
 It's quite common for titles to be built up of the titles of other objects.  If using building up the title using `@Title` then Apache Isis will automatically use the title of the objects referenced by the annotated properties.  We also need programmatic access to these titles if going the imperative route.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_validation-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_validation-api.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_validation-api.adoc
index d639c5e..30dbc15 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_validation-api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_validation-api.adoc
@@ -6,7 +6,7 @@
 
 
 
-The validation API allows a domain object to programmatically validate itself or any other domain object.  Specifically, this means the validating the current state of all properties, as well as any object-level validation defined by xref:rg.adoc#_rg_methods_reserved_manpage-validate[`validate()`].
+The validation API allows a domain object to programmatically validate itself or any other domain object.  Specifically, this means the validating the current state of all properties, as well as any object-level validation defined by xref:rgcms.adoc#_rgcms_methods_reserved_manpage-validate[`validate()`].
 
 The API provided is:
 
@@ -23,4 +23,4 @@ public interface DomainObjectContainer {
 
 If an object is changed by editing its properties, then (using the xref:ugvw.adoc#[Wicket viewer] at least) Apache Isis will check that the state of the object is valid.  There is currently however no equivalent guarantee for actions.
 
-The intent of this API was (originally at least) to provide a fallback whereby actions could at least be able to perform this validation programmatically (eg in their own xref:rg.adoc#_rg_methods_prefixes_manpage-validate[`validate...()`] or xref:rg.adoc#_rg_methods_prefixes_manpage-disable[`disable...()`] methods.  However, this feature should be considered experimental; your mileage may vary.
\ No newline at end of file
+The intent of this API was (originally at least) to provide a fallback whereby actions could at least be able to perform this validation programmatically (eg in their own xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-validate[`validate...()`] or xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-disable[`disable...()`] methods.  However, this feature should be considered experimental; your mileage may vary.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_EmailService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_EmailService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_EmailService.adoc
index df18a4f..6301e5a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_EmailService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_EmailService.adoc
@@ -81,7 +81,7 @@ To ensure that your alternative implementation takes the place of the default im
 == Registering the Services
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `EmailService` service is automatically registered and injected (it is annotated with
 `@DomainService`) so no further configuration is required.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_EventBusService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_EventBusService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_EventBusService.adoc
index 1145626..b2d620a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_EventBusService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_EventBusService.adoc
@@ -78,7 +78,7 @@ public class MySubscribingDomainService {
 <2> It's important that subscribers register before any domain services that might emit events on the event bus service.
 For example, the (non-ASF) http://github.com/isisaddons/isis-module-security[Isis addons' security] module provides a
 domain service that automatically seeds certain domain entities; these will generate
-xref:rg.adoc#_rg_classes_lifecycleevent[lifecycle events] and so any subscribers must be registered before such seed
+xref:rgcms.adoc#_rgcms_classes_lifecycleevent[lifecycle events] and so any subscribers must be registered before such seed
 services.  The easiest way to do this is to use the xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] attribute.
 <3> register with the event bus service during xref:rgant.adoc#_rgant-PostConstruct[`@PostConstruct`]
     initialization
@@ -89,7 +89,7 @@ This works for both singleton (application-scoped) and also xref:rgant.adoc#_rga
 
 [TIP]
 ====
-The xref:rg.adoc#_rg_classes_super_manpage-AbstractSubscriber[`AbstractSubscriber`] class automatically performs this
+The xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractSubscriber[`AbstractSubscriber`] class automatically performs this
 registration.  As a convenience, (as of `1.11.0-SNAPSHOT`) it is also annotated with the
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] attribute.
 ====
@@ -387,7 +387,7 @@ Late registration refers to the idea that a domain service can register itself w
 == Registering the Services
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `EventBusService` service is automatically registered and injected (it is annotated with
 `@DomainService`) so no further configuration is required.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_FixtureScriptsDefault.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_FixtureScriptsDefault.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_FixtureScriptsDefault.adoc
index 9c3d5dc..ac22f43 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_FixtureScriptsDefault.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_FixtureScriptsDefault.adoc
@@ -8,13 +8,13 @@
 
 The `FixtureScriptsDefault` service provides the ability to execute xref:ugtst.adoc#_ugtst_fixture-scripts_api-and-usage[fixture scripts] .
 
-The service extends from the xref:rg.adoc#_rg_classes_super_manpage-FixtureScripts[`FixtureScripts`], and is only instantiated by the framework if there no custom implementation of `FixtureScripts` has been otherwise provided; in other words it is a fallback.
+The service extends from the xref:rgcms.adoc#_rgcms_classes_super_manpage-FixtureScripts[`FixtureScripts`], and is only instantiated by the framework if there no custom implementation of `FixtureScripts` has been otherwise provided; in other words it is a fallback.
 
 If this service is instantiated (as a fallback) then it uses the xref:rgsvc.adoc#_rgsvc-spi_FixtureScriptsSpecificationProvider[`FixtureScriptsSpecificationProvider`] to obtain a `FixtureScriptsSpecification`.  This configures this service, telling it which package to search for `FixtureScript` classes, how to execute those classes, and hints that influence the UI.
 
 [TIP]
 ====
-We recommend using xref:rgsvc.adoc#_rgsvc-spi_FixtureScriptsSpecificationProvider[`FixtureScriptsSpecificationProvider`] rather than subclassing xref:rg.adoc#_rg_classes_super_manpage-FixtureScripts[`FixtureScripts`].
+We recommend using xref:rgsvc.adoc#_rgsvc-spi_FixtureScriptsSpecificationProvider[`FixtureScriptsSpecificationProvider`] rather than subclassing xref:rgcms.adoc#_rgcms_classes_super_manpage-FixtureScripts[`FixtureScripts`].
 ====
 
 
@@ -33,7 +33,7 @@ public class FixtureScriptsDefault ... {
 }
 ----
 
-... in other words the same as xref:rg.adoc#_rg_classes_super_manpage-FixtureScripts[`FixtureScripts`] superclass that it inherits from.
+... in other words the same as xref:rgcms.adoc#_rgcms_classes_super_manpage-FixtureScripts[`FixtureScripts`] superclass that it inherits from.
 
 
 == Configuration

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_GuiceBeanProvider.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_GuiceBeanProvider.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_GuiceBeanProvider.adoc
index e099072..cf7c5f6 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_GuiceBeanProvider.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_GuiceBeanProvider.adoc
@@ -80,7 +80,7 @@ should return "ToDo App".
 == Registering the Services
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]), _and_ that the
+`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]), _and_ that the
 xref:ugvw.adoc#[Wicket viewer] is being used, then an implementation of `GuiceBeanProvider` is
 automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_IsisJdoSupport.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_IsisJdoSupport.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_IsisJdoSupport.adoc
index cd5146f..ab53f88 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_IsisJdoSupport.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_IsisJdoSupport.adoc
@@ -267,7 +267,7 @@ public List<Order> findOrders(...) {
 == Registering the Services
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `IsisJdoSupport` service is automatically registered and injected (it is annotated with
 `@DomainService`) so no further configuration is required.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_JaxbService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_JaxbService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_JaxbService.adoc
index 598c65d..5008e43 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_JaxbService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_JaxbService.adoc
@@ -38,7 +38,7 @@ public interface JaxbService {
 
 With respect to the `IsisSchemas` enum: a JAXB-annotated domain object will live in its own XSD namespace and may
 reference multiple other XSD schemas.  In particular, many JAXB domain objects will reference the
-xref:rg.adoc#_rg_schema[common Isis schemas] (for example the `OidDto` class that represents a reference to
+xref:rgcms.adoc#_rgcms_schema[common Isis schemas] (for example the `OidDto` class that represents a reference to
 a persistent entity).  The enum indicates whether these schemas should be included or excluded from the map.
 
 Isis provides a default implementation of the service, `o.a.i.schema.services.jaxb.JaxbServiceDefault`.
@@ -50,14 +50,14 @@ Isis provides a default implementation of the service, `o.a.i.schema.services.ja
 This service is provided as a convenience for applications, but is also used internally by the framework to
 xref:rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`]-annotated
 xref:ugbtb.adoc#_ugbtb_more-advanced_view-models[view models].  The functionality to download XML and XSD schemas is also
-exposed in the UI through mixins to xref:rg.adoc#_rg_classes_roles_manpage-Dto[`Dto`] interface.
+exposed in the UI through mixins to xref:rgcms.adoc#_rgcms_classes_roles_manpage-Dto[`Dto`] interface.
 
 
 
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `JaxbService` service is automatically registered and injected (it is annotated with `@DomainService`)
 so no further configuration is required.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_MementoService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_MementoService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_MementoService.adoc
index d8718b2..3014184 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_MementoService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_MementoService.adoc
@@ -71,7 +71,7 @@ If using another implementation, the `canSet(...)` method can be used to check i
 
 == Usage
 
-As noted in the introduction, a common use case for this service is in the implementation of the xref:rg.adoc#_rg_classes_super_manpage-AbstractViewModel[`ViewModel`] interface.
+As noted in the introduction, a common use case for this service is in the implementation of the xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractViewModel[`ViewModel`] interface.
 
 [TIP]
 ====
@@ -122,7 +122,7 @@ The memento service is used by the xref:rgsvc.adoc#_rgsvc-api_CommandContext[`Co
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `MementoService` service is automatically registered and injected (it is annotated with
 `@DomainService`) so no further configuration is required.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_MetamodelService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_MetamodelService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_MetamodelService.adoc
index c67505d..6c745d6 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_MetamodelService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_MetamodelService.adoc
@@ -33,7 +33,7 @@ public interface MetaModelService {
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `MetamodelService` service is automatically registered and injected (it is annotated with
 `@DomainService`) so no further configuration is required.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_QueryResultsCache.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_QueryResultsCache.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_QueryResultsCache.adoc
index f6c3766..1182787 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_QueryResultsCache.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_QueryResultsCache.adoc
@@ -111,7 +111,7 @@ This refactoring will be worthwhile provided that enough of the orders being pro
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `QueryResultsCache` service is automatically registered and injected (it is annotated with
 `@DomainService`) so no further configuration is required.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_Scratchpad.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_Scratchpad.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_Scratchpad.adoc
index 5e6efac..bbef46d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_Scratchpad.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_Scratchpad.adoc
@@ -109,7 +109,7 @@ If using the xref:ugvw.adoc#[Wicket viewer], the `ToDoItemBulkUpdate` view model
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `Scratchpad` service is automatically registered and injected (it is annotated with `@DomainService`)
 so no further configuration is required.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_SudoService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_SudoService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_SudoService.adoc
index 5ff3e44..8bcfe26 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_SudoService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_SudoService.adoc
@@ -60,7 +60,7 @@ protected void execute(final ExecutionContext ec) {
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `SudoService` service is automatically registered and injected (it is annotated with
 `@DomainService`) so no further configuration is required.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_WrapperFactory.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_WrapperFactory.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_WrapperFactory.adoc
index c1590e6..2fc4fa4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_WrapperFactory.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_WrapperFactory.adoc
@@ -74,8 +74,8 @@ Calling any of the above methods may result in a (subclass of) `InteractionExcep
 
 In addition, the following methods may also be called:
 
-* the xref:rg.adoc#_rg_methods_reserved_manpage-title[`title()`] and `toString()` methods
-* any xref:rg.adoc#_rg_methods_prefixes_manpage-default[`default...()`], xref:rg.adoc#_rg_methods_prefixes_manpage-choices[`choices...()`] or xref:rg.adoc#_rg_methods_prefixes_manpage-autoComplete[`autoComplete...()`] methods
+* the xref:rgcms.adoc#_rgcms_methods_reserved_manpage-title[`title()`] and `toString()` methods
+* any xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-default[`default...()`], xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-choices[`choices...()`] or xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-autoComplete[`autoComplete...()`] methods
 
 An exception will be thrown if any other methods are thrown.
 
@@ -153,7 +153,7 @@ The original intent of this API was to enable test transcripts to be captured (i
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `WrapperFactory` service is automatically registered and injected (it is annotated with
 `@DomainService`) so no further configuration is required.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_XmlSnapshotService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_XmlSnapshotService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_XmlSnapshotService.adoc
index 00a47f1..3f5c84c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_XmlSnapshotService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_XmlSnapshotService.adoc
@@ -194,7 +194,7 @@ public interface XmlSnapshotService {
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `XmlSnapshotService` service is automatically registered and injected (it is annotated with
 `@DomainService`) so no further configuration is required.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi.adoc
index ae5da96..1d3f6cb 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi.adoc
@@ -60,7 +60,7 @@ The table below lists the SPIs that are defined in the Isis applib (`o.a.i.core:
 `ClassDiscoveryService`]
 |Mechanism to locate (from the classpath) classes with a specific annotation (eg xref:rgant.adoc#_rgant-DomainService[`@DomainService`])
 
-Subtypes of a given type (eg xref:rg.adoc#_rg_classes_super_manpage-FixtureScript[`FixtureScript`]).
+Subtypes of a given type (eg xref:rgcms.adoc#_rgcms_classes_super_manpage-FixtureScript[`FixtureScript`]).
 |`ClassDiscoveryService-` +
 `UsingReflections` +
 ``o.a.i.core`` +


[38/52] [abbrv] isis git commit: ISIS-1237: improving the UI of the swagger-ui html

Posted by mg...@apache.org.
ISIS-1237: improving the UI of the swagger-ui html


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/1b202fe1
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/1b202fe1
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/1b202fe1

Branch: refs/heads/ISIS-1224-select2-v4
Commit: 1b202fe1627e59fe2facdfe5c0a178ed96d0e04d
Parents: 15cd677
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Wed Dec 9 17:11:05 2015 +0000
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Wed Dec 9 17:11:05 2015 +0000

----------------------------------------------------------------------
 .../simpleapp/webapp/src/main/webapp/api-docs/index.html | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/1b202fe1/example/application/simpleapp/webapp/src/main/webapp/api-docs/index.html
----------------------------------------------------------------------
diff --git a/example/application/simpleapp/webapp/src/main/webapp/api-docs/index.html b/example/application/simpleapp/webapp/src/main/webapp/api-docs/index.html
index bc9415a..d7e3f47 100644
--- a/example/application/simpleapp/webapp/src/main/webapp/api-docs/index.html
+++ b/example/application/simpleapp/webapp/src/main/webapp/api-docs/index.html
@@ -30,12 +30,15 @@
 
     <script type="text/javascript">
     $(function () {
+      /*
       var url = window.location.search.match(/url=([^&]+)/);
       if (url && url.length > 1) {
         url = decodeURIComponent(url[1]);
       } else {
         url = "/restful/swagger/private"
       }
+      */
+      var url = document.getElementById("input_baseUrl").selectedOptions[0].value;
 
       // Pre load translate...
       if(window.SwaggerTranslator) {
@@ -109,14 +112,14 @@
         <a id="logo" href="http://swagger.io">swagger</a>
         <form id='api_selector'>
             <div class='input'>
-                <!--
-                <select name="foo">
+                <select id="input_baseUrl" name="baseUrl">
                     <option id="public" label="public" value="/restful/swagger/public"/>
                     <option id="private" label="private" value="/restful/swagger/private"/>
                     <option id="prototyping" label="prototyping" value="/restful/swagger/prototyping"/>
                 </select>
-                -->
-                <input placeholder="http://example.com/api" id="input_baseUrl" name="baseUrl" type="text">
+<!--
+                <input placeholder="http://example.com/api" id="input_baseUrl" name="baseUrl" type="text" value="/restful/swagger/public">
+-->
             </div>
             <div class='input' style="display:none;"><input placeholder="api_key" id="input_apiKey" name="apiKey" type="text"/></div>
             <div class='input'><a id="explore" href="#" data-sw-translate>Explore</a></div>


[18/52] [abbrv] isis git commit: ISIS-1243: renamed ug.adoc to ugfun.adoc. Added standard section to each of the guides so can navigate between each easily.

Posted by mg...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugtst_fixture-scripts_api-and-usage.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugtst_fixture-scripts_api-and-usage.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugtst_fixture-scripts_api-and-usage.adoc
index ad2a50d..344f32a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugtst_fixture-scripts_api-and-usage.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugtst_fixture-scripts_api-and-usage.adoc
@@ -23,7 +23,7 @@ As of 1.9.0 there is an alternative design.  Instead of subclassing `FixtureScri
 
 The actual implementation of the `FixtureScripts` service is then provided by the framework itself, namely the xref:rgsvc.adoc#_rgsvc-api_FixtureScriptsDefault[`FixtureScriptsDefault`] domain service, annotated to be rendered on the secondary "Prototyping" menu.  This uses the `FixtureScriptsSpecificationProvider` to adjust itself accordinly.
 
-For example, here's the `FixtureScriptsSpecificationProvider` service that's generated by the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype]:
+For example, here's the `FixtureScriptsSpecificationProvider` service that's generated by the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]:
 
 [source,java]
 ----
@@ -113,7 +113,7 @@ If you had defined many fixture scripts then a drop-down might become unwieldy,
 
 ----
 
-You are free, of course, to add additional "convenience" actions into it if you wish for the most commonly used/demo'd setups ; you'll find that the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype] adds this additional action:
+You are free, of course, to add additional "convenience" actions into it if you wish for the most commonly used/demo'd setups ; you'll find that the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] adds this additional action:
 
 [source,java]
 ----
@@ -139,7 +139,7 @@ Let's now look at the `FixtureScript` class, where there's a bit more going on.
 
 A fixture script is ultimately just a block of code that can be executed, so it's up to you how you implement it to set up the system.  However, we strongly recommend that you use it to invoke actions on business objects, in essence to replay what a real-life user would have done.  That way, the fixture script will remain valid even if the underlying implementation of the system changes in the future.
 
-Here's the `RecreateSimpleObjects` fixture script from the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype]:
+Here's the `RecreateSimpleObjects` fixture script from the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]:
 
 [source,java]
 ----
@@ -251,7 +251,7 @@ public class SimpleObjectCreate extends FixtureScript {       // <1>
 
 Fixture scripts can be called from integration tests just the same way that fixture scripts can call one another.
 
-For example, here's an integration test from the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype]:
+For example, here's an integration test from the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]:
 
 [source,java]
 ----
@@ -296,7 +296,7 @@ public class SimpleObjectIntegTest extends SimpleAppIntegTest {
 
 There are lots of ways to organize fixture scripts, but we've used them as either:
 
-* a fairly flat style, eg as in the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype], also as in the http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp];
+* a fairly flat style, eg as in the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype], also as in the http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp];
 
 * in a "composite pattern" style, eg as in the https://github.com/estatio/estatio/blob/ea20a6ce257acede50de6ce4fd2ff29713fcd689/estatioapp/fixture/src/main/java/org/estatio/fixture/invoice/InvoiceForLeaseItemTypeOfDiscountOneQuarterForOxfMiracle005.java#L66)[Estatio open source app].
 
@@ -318,7 +318,7 @@ image::{_imagesdir}testing/fixture-scripts/composite.png[width="550px",link="{_i
 
 Back in the earlier section we noted the `MultipleExecutionStrategy` setting.  We can now explain the meaning of this: the enum value of `EXECUTE` is designed for the flat style (where every fixture script will be called), whereas the enum value of `IGNORE` is designed for the composite style, and ensures that any fixture scripts visited more than once (eg TearDown) are only every executed the first time.
 
-As already noted , the app generated by the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype] uses the flat structure, and we feel that it's a better at separating out the "how" (how we set up some graph of domain objects into a known state, eg a customer with shipped placed orders and a newly placed order) from the "what" (what data should we actually use for the customer's name, say).
+As already noted , the app generated by the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] uses the flat structure, and we feel that it's a better at separating out the "how" (how we set up some graph of domain objects into a known state, eg a customer with shipped placed orders and a newly placed order) from the "what" (what data should we actually use for the customer's name, say).
 
 The composite style tends to combine these, which one could argue does not separate responsibilities well enough.  On the other hand, one could also make an argument that the composite style is a good way to implement precanned personas, eg "Joe", the customer who has a newly placed order, from "Mary" customer who has none.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugtst_integ-test-support_bootstrapping.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugtst_integ-test-support_bootstrapping.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugtst_integ-test-support_bootstrapping.adoc
index e7b8399..ffa31ef 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugtst_integ-test-support_bootstrapping.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugtst_integ-test-support_bootstrapping.adoc
@@ -11,7 +11,7 @@ Nevertheless, we do need to bootstrap the runtime for the very first test.
 
 As of 1.9.0 the bootstrapping of integration tests and webapps has been simplified through the xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`] class.  Since this isn't mandatory, for now we present both techniques.
 
-The example code in this section is taken from the app generated by the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype].
+The example code in this section is taken from the app generated by the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugtst_integ-test-support_maven-configuration.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugtst_integ-test-support_maven-configuration.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugtst_integ-test-support_maven-configuration.adoc
index 851da7a..587fe92 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugtst_integ-test-support_maven-configuration.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugtst_integ-test-support_maven-configuration.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-Apache Isis' integration test support is automatically configured if you use the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype].  To set it up manually, update the `pom.xml` of your domain object model module:
+Apache Isis' integration test support is automatically configured if you use the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].  To set it up manually, update the `pom.xml` of your domain object model module:
 
 [source,xml]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugtst_unit-test-support_contract-tests.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugtst_unit-test-support_contract-tests.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugtst_unit-test-support_contract-tests.adoc
index 24f7e1e..6171c86 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugtst_unit-test-support_contract-tests.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugtst_unit-test-support_contract-tests.adoc
@@ -64,11 +64,11 @@ public class SortedSetsContractTestAll extends SortedSetsContractTestAbstract {
 
 == Bidirectional
 
-This contract test automatically checks that bidirectional 1:m or 1:1 associations are being maintained correctly (assuming that they follow the xref:ug.adoc#_ug_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships[mutual registration pattern]
+This contract test automatically checks that bidirectional 1:m or 1:1 associations are being maintained correctly (assuming that they follow the xref:ug.adoc#_ugfun_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships[mutual registration pattern]
 
 [TIP]
 ====
-(If using the JDO objectstore, then) there is generally no need to programmatically maintain 1:m relationships (indeed it may introduce subtle errors). For more details, see xref:ug.adoc#_ug_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships[here].  Also check out the xref:cg.adoc#_cg_ide-templates[IDE templates] for further guidance.
+(If using the JDO objectstore, then) there is generally no need to programmatically maintain 1:m relationships (indeed it may introduce subtle errors). For more details, see xref:ug.adoc#_ugfun_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships[here].  Also check out the xref:cg.adoc#_cg_ide-templates[IDE templates] for further guidance.
 ====
 
 For example, suppose that `ParentDomainObject` and `ChildDomainObject` have a 1:m relationship (`ParentDomainObject#children` / `ChildDomainObject#parent`), and also `PeerDomainObject` has a 1:1 relationship with itself (`PeerDomainObject#next` / `PeerDomainObject#previous`).

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugtst_unit-test-support_maven-configuration.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugtst_unit-test-support_maven-configuration.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugtst_unit-test-support_maven-configuration.adoc
index 92f7ffc..9fa4881 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugtst_unit-test-support_maven-configuration.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugtst_unit-test-support_maven-configuration.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-Apache Isis' unit test support is automatically configured if you use the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype].  To set it up manually, update the `pom.xml` of your domain object model module:
+Apache Isis' unit test support is automatically configured if you use the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].  To set it up manually, update the `pom.xml` of your domain object model module:
 
 [source,xml]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugvw_customisation_about-page.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugvw_customisation_about-page.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugvw_customisation_about-page.adoc
index 6ee6f68..8a6426f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugvw_customisation_about-page.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugvw_customisation_about-page.adoc
@@ -31,7 +31,7 @@ If none of these are found, then no version is displayed.
 
 [TIP]
 ====
-This configuration is included within the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype].
+This configuration is included within the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
 ====
 
 === Adding attributes to the WAR's manifest

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugvw_customisation_tweaking-css-classes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugvw_customisation_tweaking-css-classes.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugvw_customisation_tweaking-css-classes.adoc
index 01eb3d2..5e1d869 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugvw_customisation_tweaking-css-classes.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugvw_customisation_tweaking-css-classes.adoc
@@ -92,7 +92,7 @@ div.x-myapp-highlight span.scalarName {
 }
 ----
 
-Note also that instead of using `@PropertyLayout(cssClass=...)` annotation, you can also specify the CSS style using a xref:ug.adoc#_ug_object-layout_dynamic[dynamic layout] JSON file:
+Note also that instead of using `@PropertyLayout(cssClass=...)` annotation, you can also specify the CSS style using a xref:ug.adoc#_ugfun_object-layout_dynamic[dynamic layout] JSON file:
 
 [source,javascript]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugvw_layout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugvw_layout.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugvw_layout.adoc
index 75b5e5e..322e045 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugvw_layout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugvw_layout.adoc
@@ -6,7 +6,7 @@
 
 
 
-The wicket viewer has full support for the various methods of specifying the xref:ug.adoc#_ug_object-layout[layout of objects], either statically or dynamically.
+The wicket viewer has full support for the various methods of specifying the xref:ug.adoc#_ugfun_object-layout[layout of objects], either statically or dynamically.
 
 Dynamic reloading is automatically supported when running in xref:rgcfg.adoc#_rgcfg_deployment-types[prototype (development) mode], the Wicket viewer automatically rebuilds the metamodel for each class as it is rendered.    Conversely, do note that the Wicket viewer will *not* pick up new metadata if running in production/server mode.
 
@@ -46,7 +46,7 @@ And finally, from the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Is
 image::{_imagesdir}wicket-viewer/layouts/todoapp-ToDoItem.png[width="800px",link="{_imagesdir}wicket-viewer/layouts/todoapp-ToDoItem.png"]
 
 
-To learn more about how to configure these types of layout, see the xref:ug.adoc#_ug_object-layout[object layout] chapter.
+To learn more about how to configure these types of layout, see the xref:ug.adoc#_ugfun_object-layout[object layout] chapter.
 
 
 
@@ -92,6 +92,6 @@ Therefore, make sure the following is added to the dom project's `pom.xml`:
 </resources>
 ----
 
-If using an Apache Isis xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype], then the POM is already correctly configured.
+If using an Apache Isis xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype], then the POM is already correctly configured.
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/cg.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/cg.adoc b/adocs/documentation/src/main/asciidoc/guides/cg.adoc
index 233d347..9da1818 100644
--- a/adocs/documentation/src/main/asciidoc/guides/cg.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/cg.adoc
@@ -11,13 +11,39 @@
 
 This contributors' guide has three related audiences:
 
-* programmers who want to just use Apache Isis to build applications, and want help setting up their development environment or to build their code from the command line (eg to execute within a continuous integration server such as Jenkins)
+* programmers who want to just use Apache Isis to build applications, and want help setting up their development
+environment or to build their code from the command line (eg to execute within a continuous integration server such
+as Jenkins)
 
 * programmers who want to contribute back patches (bug fixes, new features) either to the codebase or the framework's documentation
 
 * committers of Apache Isis itself who want guidance on release process, publishing documents and other related procedures.
 
-This contributors' guide is _not_ intended as a reference manual; for that see the *xref:rg.adoc#_rg[Reference Guide]*.  This guide also doesn't describe how to actually build an Apache Isis application; for that see the *xref:ug.adoc#_ug[Users' Guide]*.
+
+
+=== Other Guides
+
+Apache Isis documentation is broken out into a number of user and reference guides.
+
+The user guides available are:
+
+* xref:ugfun.adoc#[Fundamentals]
+* xref:ugvw.adoc#[Wicket viewer]
+* xref:ugvro.adoc#[Restful Objects viewer]
+* xref:ugsec.adoc#[Security]
+* xref:ugtst.adoc#[Testing]
+* xref:ugbtb.adoc#[Beyond the Basics]
+
+The reference guides are:
+
+* xref:rgant.adoc#[Annotations]
+* xref:rgsvc.adoc#[Domain Services]
+* xref:rgcfg.adoc#[Configuration Properties]
+* xref:rg.adoc#[Classes, Methods and Schema]
+
+In addition, there is (this) xref:cg.adoc#_cg[Contributors' Guide] describing development practices for contributors and committers alike.
+
+
 
 
 include::_cg_ide.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/rg.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rg.adoc b/adocs/documentation/src/main/asciidoc/guides/rg.adoc
new file mode 100644
index 0000000..4711809
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rg.adoc
@@ -0,0 +1,27 @@
+[[rg]]
+= Reference Guides
+: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/
+:numbered:
+
+
+Apache Isis documentation is broken out into a number of user and reference guides.
+
+The user guides available are:
+
+* xref:ugfun.adoc#[Fundamentals]
+* xref:ugvw.adoc#[Wicket viewer]
+* xref:ugvro.adoc#[Restful Objects viewer]
+* xref:ugsec.adoc#[Security]
+* xref:ugtst.adoc#[Testing]
+* xref:ugbtb.adoc#[Beyond the Basics] (this guide)
+
+The reference guides are:
+
+* xref:rgant.adoc#[Annotations]
+* xref:rgsvc.adoc#[Domain Services]
+* xref:rgcfg.adoc#[Configuration Properties]
+* xref:rg.adoc#[Classes, Methods and Schema]
+
+In addition, there is a xref:cg.adoc#_cg[Contributors' Guide] describing development practices for contributors and committers alike.

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/rgant.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant.adoc
index de65d2e..491e973 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant.adoc
@@ -8,9 +8,36 @@
 [[_rgant]]
 == Annotations
 
-Apache Isis uses annotations to provide additional metadata about the domain objects.
+This guide describes the various annotations used by Apache Isis to provide additional metadata about the domain objects.
+Most of these are defined by Isis itself, but some are from other libraries.  It also identifies a number of
+annotations that are now deprecated, and indicates their replacement.
 
-To give just a few examples:
+=== Other Guides
+
+Apache Isis documentation is broken out into a number of user and reference guides.
+
+The user guides available are:
+
+* xref:ugfun.adoc#[Fundamentals]
+* xref:ugvw.adoc#[Wicket viewer]
+* xref:ugvro.adoc#[Restful Objects viewer]
+* xref:ugsec.adoc#[Security]
+* xref:ugtst.adoc#[Testing]
+* xref:ugbtb.adoc#[Beyond the Basics]
+
+The reference guides are:
+
+* xref:rgant.adoc#[Annotations]
+* xref:rgsvc.adoc#[Domain Services]
+* xref:rgcfg.adoc#[Configuration Properties]
+* xref:rg.adoc#[Classes, Methods and Schema]
+
+In addition, there is a xref:cg.adoc#_cg[Contributors' Guide] describing development practices for contributors and committers alike.
+
+
+=== Examples
+
+To give just a few examples of annotations supported by Apache Isis:
 
 * if a property is read-only, then this can be annotated with `@Property(editing=EditingDISABLED)`.
 * if a class has a small fixed set of instances (eg a picklist), then it can be annotated using `@DomainObject(bounded=true)`
@@ -24,11 +51,7 @@ Some annotations act as UI hints, for example:
 * if an action has a tooltip, it can be annotated using `@ActionLayout(describedAs=...)`
 * if a domain object is bookmarkable, it can be annotated using `@DomainObjectLayout(bookmarking=BookmarkPolicy.AS_ROOT`).
 
-This guide documents all the annotations currently supported by Apache Isis.  It also identifies a number of annotations that are now deprecated, and indicates their replacement.
-
-Other guides are:
 
-* xref:rg.adoc#[Reference Guide]
 
 
 include::_rgant_aaa.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/rgcfg.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcfg.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcfg.adoc
index a1d2d07..d064cce 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcfg.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcfg.adoc
@@ -11,15 +11,41 @@
 Apache Isis' own configuration properties are simple key-value pairs, typically held in the `WEBINF/isis.properties`
 file and other related files. This guide describes how to configure an Apache Isis application.
 
+=== Other Guides
+
+Apache Isis documentation is broken out into a number of user and reference guides.
+
+The user guides available are:
+
+* xref:ugfun.adoc#[Fundamentals]
+* xref:ugvw.adoc#[Wicket viewer]
+* xref:ugvro.adoc#[Restful Objects viewer]
+* xref:ugsec.adoc#[Security]
+* xref:ugtst.adoc#[Testing]
+* xref:ugbtb.adoc#[Beyond the Basics]
+
+The reference guides are:
+
+* xref:rgant.adoc#[Annotations]
+* xref:rgsvc.adoc#[Domain Services]
+* xref:rgcfg.adoc#[Configuration Properties]
+* xref:rg.adoc#[Classes, Methods and Schema]
+
+In addition, there is a xref:cg.adoc#_cg[Contributors' Guide] describing development practices for contributors and committers alike.
+
 
 [NOTE]
 ====
-Configuration properties for the viewers can be found in the xref:ugvw.adoc#[Wicket Viewer] chapter and the xref:ugvro.adoc#[RestfulObjects viewer] chapter.  Likewise[details of configuring security (Apache Shiro) can be found in the xref:ugsec.adoc#[Security] chapter.
+Configuration properties for the viewers can be found in the xref:ugvw.adoc#[Wicket Viewer] guide and the xref:ugvro.adoc#[RestfulObjects viewer] guide.  Likewise[details of configuring security (Apache Shiro) can be found in the xref:ugsec.adoc#[Security] guide.
 
-Also, note that by default the configuration values are part of the built WAR file.  Details on how to override these configuration properties externally for different environments can be found in the xref:ugbtb.adoc#_ugbtb_deployment[Deployment] chapter.
+Also, note that by default the configuration values are part of the built WAR file.  Details on how to override these
+configuration properties externally for different environments can be found in the
+xref:ugbtb.adoc#_ugbtb_deployment[Beyond the Basics] guide, (deployment chapter).
 ====
 
 
+
+
 include::_rgcfg_deployment-types.adoc[leveloffset=+1]
 include::_rgcfg_configuration-files.adoc[leveloffset=+1]
 include::_rgcfg_specifying-components.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/rgcms.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms.adoc
index 0951d3b..b6dcc5e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms.adoc
@@ -16,8 +16,27 @@ supporting xref:rgcms.adoc#_rgcms_classes[classes].
 It also describes the xref:rgcms.adoc#_rgcms_schema[XSD schema] defined by Apache Isis.  One use case is for the
 JAXB serialization of view models (`1.11.0-SNAPSHOT`).
 
+=== Other Guides
 
-This reference guide does _not_ describe how to actually build an Apache Isis application; for that see the *xref:ug.adoc#_ug[Users' Guide]*.  The reference guide also doesn't explain how to setup your development environment; for that see the *xref:cg.adoc#_cg[Contributors' Guide]*.
+Apache Isis documentation is broken out into a number of user and reference guides.
+
+The user guides available are:
+
+* xref:ugfun.adoc#[Fundamentals]
+* xref:ugvw.adoc#[Wicket viewer]
+* xref:ugvro.adoc#[Restful Objects viewer]
+* xref:ugsec.adoc#[Security]
+* xref:ugtst.adoc#[Testing]
+* xref:ugbtb.adoc#[Beyond the Basics]
+
+The reference guides are:
+
+* xref:rgant.adoc#[Annotations]
+* xref:rgsvc.adoc#[Domain Services]
+* xref:rgcfg.adoc#[Configuration Properties]
+* xref:rg.adoc#[Classes, Methods and Schema] (this guide)
+
+In addition, there is a xref:cg.adoc#_cg[Contributors' Guide] describing development practices for contributors and committers alike.
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/rgsvc.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc.adoc
index b1a15fd..a141126 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc.adoc
@@ -12,10 +12,27 @@ This guide documents Apache Isis' domain services, both those that act as an xre
 (implemented by the framework for your domain objects to call), and those domain services that act as an
 xref:rgsvc.adoc#_rgsvc-spi[SPI] (implemented by your domain application and which are called by the framework).
 
-Other guides are:
+=== Other Guides
+
+Apache Isis documentation is broken out into a number of user and reference guides.
+
+The user guides available are:
+
+* xref:ugfun.adoc#[Fundamentals]
+* xref:ugvw.adoc#[Wicket viewer]
+* xref:ugvro.adoc#[Restful Objects viewer]
+* xref:ugsec.adoc#[Security]
+* xref:ugtst.adoc#[Testing]
+* xref:ugbtb.adoc#[Beyond the Basics]
+
+The reference guides are:
 
-* xref:rg.adoc#[Reference Guide]
 * xref:rgant.adoc#[Annotations]
+* xref:rgsvc.adoc#[Domain Services] (this guide)
+* xref:rgcfg.adoc#[Configuration Properties]
+* xref:rg.adoc#[Classes, Methods and Schema]
+
+In addition, there is a xref:cg.adoc#_cg[Contributors' Guide] describing development practices for contributors and committers alike.
 
 
 include::_rgsvc-api.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/simpleapp-archetype.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/simpleapp-archetype.adoc b/adocs/documentation/src/main/asciidoc/guides/simpleapp-archetype.adoc
index c600809..5aa2ba1 100644
--- a/adocs/documentation/src/main/asciidoc/guides/simpleapp-archetype.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/simpleapp-archetype.adoc
@@ -95,7 +95,7 @@ where `myapp` is the `artifactId` entered above.
 
 == Running the App
 
-The `simpleapp` archetype generates a single WAR file, configured to run both the link:./guides/ug.html#_ug_wicket-viewer[Wicket viewer] and the link:./guides/ug.html#_ugvro[Restful Objects viewer].   The archetype also configures the JDO/DataNucleus objectstore to use an in-memory HSQLDB connection.
+The `simpleapp` archetype generates a single WAR file, configured to run both the link:./guides/ugvw.html#[Wicket viewer] and the link:./guides/ugvro.html#[Restful Objects viewer].   The archetype also configures the JDO/DataNucleus objectstore to use an in-memory HSQLDB connection.
 
 Once you've built the app, you can run the WAR in a variety of ways. 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/ug.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ug.adoc b/adocs/documentation/src/main/asciidoc/guides/ug.adoc
index de52f80..c34ef34 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ug.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ug.adoc
@@ -1,46 +1,27 @@
 [[ug]]
-= Fundamentals
+= User Guides
 :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/
 :numbered:
 
 
-[[_ug]]
-== Fundamentals
+Apache Isis documentation is broken out into a number of user and reference guides.
 
-This guide introduces the xref:ug.adoc#_ug_core-concepts[core concepts] and ideas behind Apache Isis,
-and tells you how to xref:ug.adoc#_ug_getting-started[get started] with a Maven archetype.
-
-It also describes a number of xref:ug.adoc#_ug_how-tos[how-to]s, describes how to influence the
-xref:ug.adoc#_ug_object-layout[UI layout] of your domain objects (this is ultimately just a type of metadata), and it
- catalogues various xref:ug.adoc#_ug_faqs.adoc[FAQ]s.
-
-Other user guides are:
+The user guides available are:
 
+* xref:ugfun.adoc#[Fundamentals]
 * xref:ugvw.adoc#[Wicket viewer]
 * xref:ugvro.adoc#[Restful Objects viewer]
 * xref:ugsec.adoc#[Security]
 * xref:ugtst.adoc#[Testing]
-* xref:ugbtb.adoc#[Beyond the Basics]
+* xref:ugbtb.adoc#[Beyond the Basics] (this guide)
 
-Other reference guides are:
+The reference guides are:
 
 * xref:rgant.adoc#[Annotations]
 * xref:rgsvc.adoc#[Domain Services]
 * xref:rgcfg.adoc#[Configuration Properties]
 * xref:rg.adoc#[Classes, Methods and Schema]
 
-This users' guide is _not_ intended as a reference manual; for that see the *xref:rg.adoc#_rg[Reference Guide]*.  This
-guide also doesn't explain how to setup your development environment; for that see the *xref:cg.adoc#_cg[Contributors' Guide]*.
-
-
-
-include::_ug_core-concepts.adoc[leveloffset=+1]
-include::_ug_getting-started.adoc[leveloffset=+1]
-
-include::_ug_how-tos.adoc[leveloffset=+1]
-include::_ug_object-layout.adoc[leveloffset=+1]
-
-include::_ug_faqs.adoc[leveloffset=+1]
-
+In addition, there is a xref:cg.adoc#_cg[Contributors' Guide] describing development practices for contributors and committers alike.

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/ugbtb.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb.adoc
index 7201821..7001a58 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb.adoc
@@ -14,16 +14,27 @@ applications.
 
 Later chapters discuss how to xref:ugbtb.adoc#_ugbtb_deployment[deploy] your app, and discuss other ways in which you can xref:ugbtb.adoc#[extend] or adapt the framework itself to your particular needs.
 
-Other guides are:
+=== Other Guides
 
-* xref:ug.adoc#[Fundamentals]
+Apache Isis documentation is broken out into a number of user and reference guides.
+
+The user guides available are:
+
+* xref:ugfun.adoc#[Fundamentals]
 * xref:ugvw.adoc#[Wicket viewer]
 * xref:ugvro.adoc#[Restful Objects viewer]
-* xref:ugvro.adoc#[Security]
+* xref:ugsec.adoc#[Security]
 * xref:ugtst.adoc#[Testing]
+* xref:ugbtb.adoc#[Beyond the Basics] (this guide)
+
+The reference guides are:
 
+* xref:rgant.adoc#[Annotations]
+* xref:rgsvc.adoc#[Domain Services]
+* xref:rgcfg.adoc#[Configuration Properties]
+* xref:rg.adoc#[Classes, Methods and Schema]
 
-This users' guide is _not_ intended as a reference manual; for that see the *xref:rg.adoc#_rg[Reference Guide]*.  This guide also doesn't explain how to setup your development environment; for that see the *xref:cg.adoc#_cg[Contributors' Guide]*.
+In addition, there is a xref:cg.adoc#_cg[Contributors' Guide] describing development practices for contributors and committers alike.
 
 
 include::_ugbtb_more-advanced.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/ugfun.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun.adoc
new file mode 100644
index 0000000..00abbf2
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun.adoc
@@ -0,0 +1,50 @@
+[[ugfun]]
+= Fundamentals
+: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/
+:numbered:
+
+
+[[_ugfun]]
+== Fundamentals
+
+This guide introduces the xref:ug.adoc#_ugfun_core-concepts[core concepts] and ideas behind Apache Isis,
+and tells you how to xref:ug.adoc#_ugfun_getting-started[get started] with a Maven archetype.
+
+It also describes a number of xref:ug.adoc#_ugfun_how-tos[how-to]s, describes how to influence the
+xref:ug.adoc#_ugfun_object-layout[UI layout] of your domain objects (this is ultimately just a type of metadata), and it
+ catalogues various xref:ug.adoc#_ugfun_faqs.adoc[FAQ]s.
+
+=== Other Guides
+
+Apache Isis documentation is broken out into a number of user and reference guides.
+
+The user guides available are:
+
+* xref:ugfun.adoc#[Fundamentals] (this guide)
+* xref:ugvw.adoc#[Wicket viewer]
+* xref:ugvro.adoc#[Restful Objects viewer]
+* xref:ugsec.adoc#[Security]
+* xref:ugtst.adoc#[Testing]
+* xref:ugbtb.adoc#[Beyond the Basics]
+
+The reference guides are:
+
+* xref:rgant.adoc#[Annotations]
+* xref:rgsvc.adoc#[Domain Services]
+* xref:rgcfg.adoc#[Configuration Properties]
+* xref:rg.adoc#[Classes, Methods and Schema]
+
+In addition, there is a xref:cg.adoc#_cg[Contributors' Guide] describing development practices for contributors and committers alike.
+
+
+
+include::_ugfun_core-concepts.adoc[leveloffset=+1]
+include::_ugfun_getting-started.adoc[leveloffset=+1]
+
+include::_ugfun_how-tos.adoc[leveloffset=+1]
+include::_ugfun_object-layout.adoc[leveloffset=+1]
+
+include::_ugfun_faqs.adoc[leveloffset=+1]
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/ugsec.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugsec.adoc b/adocs/documentation/src/main/asciidoc/guides/ugsec.adoc
index e27a67a..34f9de3 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugsec.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugsec.adoc
@@ -10,14 +10,29 @@
 
 This guide describes the authentication and authorization features available to secure your Apache Isis application.
 
-Other guides are:
 
-* xref:ug.adoc#[Fundamentals]
+=== Other Guides
+
+Apache Isis documentation is broken out into a number of user and reference guides.
+
+The user guides available are:
+
+* xref:ugfun.adoc#[Fundamentals]
 * xref:ugvw.adoc#[Wicket viewer]
 * xref:ugvro.adoc#[Restful Objects viewer]
+* xref:ugsec.adoc#[Security] (this guide)
 * xref:ugtst.adoc#[Testing]
 * xref:ugbtb.adoc#[Beyond the Basics]
 
+The reference guides are:
+
+* xref:rgant.adoc#[Annotations]
+* xref:rgsvc.adoc#[Domain Services]
+* xref:rgcfg.adoc#[Configuration Properties]
+* xref:rg.adoc#[Classes, Methods and Schema]
+
+In addition, there is a xref:cg.adoc#_cg[Contributors' Guide] describing development practices for contributors and committers alike.
+
 
 === Terminology
 
@@ -31,7 +46,7 @@ Isis has two levels of permissions.  _Read_ permission means that the user can v
 
 Isis provides an API for both authentication and authorization, and provides an implementation that integrates with link:http://shiro.apache.org[Apache Shiro].  Shiro in turn uses the concept of a _realm_ as a source for both authentication and optionally authorization.
 
-Shiro ships with a simple text-based realm -- the `IniRealm` -- which reads users (and password), user roles and role permissions from the `WEB-INF/shiro.ini` file.  The xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype] is configured to use this realm.
+Shiro ships with a simple text-based realm -- the `IniRealm` -- which reads users (and password), user roles and role permissions from the `WEB-INF/shiro.ini` file.  The xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] is configured to use this realm.
 
 Shiro also ships with an implementation of an LDAP-based realm; LDAP is often used to manage user/passwords and corresponding user groups.  Apache Isis in turn extends this with its `IsisLdapRealm`, which provides more flexibility for both group/role and role/permissions management.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/ugtst.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugtst.adoc b/adocs/documentation/src/main/asciidoc/guides/ugtst.adoc
index 20f81fa..1997486 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugtst.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugtst.adoc
@@ -16,14 +16,28 @@ application frameworks.
 
 This guide describes those features available to you for testing your Apache Isis application.
 
-Other guides are:
+=== Other Guides
 
-* xref:ug.adoc#[Fundamentals]
+Apache Isis documentation is broken out into a number of user and reference guides.
+
+The user guides available are:
+
+* xref:ugfun.adoc#[Fundamentals]
 * xref:ugvw.adoc#[Wicket viewer]
 * xref:ugvro.adoc#[Restful Objects viewer]
 * xref:ugsec.adoc#[Security]
+* xref:ugtst.adoc#[Testing] (this guide)
 * xref:ugbtb.adoc#[Beyond the Basics]
 
+The reference guides are:
+
+* xref:rgant.adoc#[Annotations]
+* xref:rgsvc.adoc#[Domain Services]
+* xref:rgcfg.adoc#[Configuration Properties]
+* xref:rg.adoc#[Classes, Methods and Schema]
+
+In addition, there is a xref:cg.adoc#_cg[Contributors' Guide] describing development practices for contributors and committers alike.
+
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/ugvro.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvro.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvro.adoc
index 4d6738a..2dbdd6c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvro.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvro.adoc
@@ -14,14 +14,28 @@ which defines a generic way to expose a domain model through a REST (or more pre
 
 This user guide discuss features, configuration and how to extend the Restful Objects viewer.
 
-Other guides are:
+=== Other Guides
 
-* xref:ug.adoc#[Fundamentals]
+Apache Isis documentation is broken out into a number of user and reference guides.
+
+The user guides available are:
+
+* xref:ugfun.adoc#[Fundamentals]
 * xref:ugvw.adoc#[Wicket viewer]
+* xref:ugvro.adoc#[Restful Objects viewer] (this guide)
 * xref:ugsec.adoc#[Security]
 * xref:ugtst.adoc#[Testing]
 * xref:ugbtb.adoc#[Beyond the Basics]
 
+The reference guides are:
+
+* xref:rgant.adoc#[Annotations]
+* xref:rgsvc.adoc#[Domain Services]
+* xref:rgcfg.adoc#[Configuration Properties]
+* xref:rg.adoc#[Classes, Methods and Schema]
+
+In addition, there is a xref:cg.adoc#_cg[Contributors' Guide] describing development practices for contributors and committers alike.
+
 
 
 include::_ugvro_features.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/ugvw.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw.adoc
index 0fdda17..bfe7b43 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw.adoc
@@ -18,14 +18,28 @@ This user guide discuss end-user features, configuration and customization of th
 
 It also discusses how to extend the viewer, and the (non-ASF) link:http://isisaddons.org[Isis Addons] wicket components.
 
-Other guides are:
+=== Other Guides
 
-* xref:ug.adoc#[Fundamentals]
+Apache Isis documentation is broken out into a number of user and reference guides.
+
+The user guides available are:
+
+* xref:ugfun.adoc#[Fundamentals]
+* xref:ugvw.adoc#[Wicket viewer] (this guide)
 * xref:ugvro.adoc#[Restful Objects viewer]
 * xref:ugsec.adoc#[Security]
 * xref:ugtst.adoc#[Testing]
 * xref:ugbtb.adoc#[Beyond the Basics]
 
+The reference guides are:
+
+* xref:rgant.adoc#[Annotations]
+* xref:rgsvc.adoc#[Domain Services]
+* xref:rgcfg.adoc#[Configuration Properties]
+* xref:rg.adoc#[Classes, Methods and Schema]
+
+In addition, there is a xref:cg.adoc#_cg[Contributors' Guide] describing development practices for contributors and committers alike.
+
 
 
 


[14/52] [abbrv] isis git commit: ISIS-1243: removing manpage from .adoc file names.

Posted by mg...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-persisted.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-persisted.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-persisted.adoc
deleted file mode 100644
index b3b832a..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-persisted.adoc
+++ /dev/null
@@ -1,16 +0,0 @@
-[[_rgcms_methods_reserved_manpage-persisted]]
-= `persisted()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `persisted()` lifecycle callback method is called when object has just been persisted from the object store.
-
-See also xref:rgcms.adoc#_rgcms_methods_lifecycle_manpage-persisting[`persisting()`].
-
-[TIP]
-====
-Alternatively, consider using a xref:rgsvc.adoc#_rgsvc-api_EventBusService[event bus] xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractSubscriber[subscriber] on the xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-ObjectPersistedEvent[`ObjectPersistedEvent`].
-====

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-persisting.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-persisting.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-persisting.adoc
deleted file mode 100644
index be1fe41..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-persisting.adoc
+++ /dev/null
@@ -1,16 +0,0 @@
-[[_rgcms_methods_reserved_manpage-persisting]]
-= `persisting()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `persisting()` lifecycle callback method is called when a (not-yet-persistent) object is just about to be persisted from the object store
-
-See also xref:rgcms.adoc#_rgcms_methods_lifecycle_manpage-persisted[`persisted()`].
-
-[TIP]
-====
-Alternatively, consider using a xref:rgsvc.adoc#_rgsvc-api_EventBusService[event bus] xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractSubscriber[subscriber] on the xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-ObjectPersistingEvent[`ObjectPersistingEvent`].
-====

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-removed.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-removed.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-removed.adoc
deleted file mode 100644
index 7f87193..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-removed.adoc
+++ /dev/null
@@ -1,16 +0,0 @@
-[[_rgcms_methods_reserved_manpage-removed]]
-= `removed()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `removed()` lifecycle callback method is called when a (persistent) object has just been deleted from the object store
-
-See also xref:rgcms.adoc#_rgcms_methods_lifecycle_manpage-removing[`removing()`].
-
-[TIP]
-====
-Alternatively, consider using a xref:rgsvc.adoc#_rgsvc-api_EventBusService[event bus] xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractSubscriber[subscriber] on the xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-ObjectRemovedEvent[`ObjectRemovedEvent`].
-====

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-removing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-removing.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-removing.adoc
deleted file mode 100644
index cd57eee..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-removing.adoc
+++ /dev/null
@@ -1,16 +0,0 @@
-[[_rgcms_methods_reserved_manpage-removing]]
-= `removing()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `removing()` lifecycle callback method is called when a (persistent) object is just about to be deleted from the object store
-
-See also xref:rgcms.adoc#_rgcms_methods_lifecycle_manpage-removed[`removed()`].
-
-[TIP]
-====
-Alternatively, consider using a xref:rgsvc.adoc#_rgsvc-api_EventBusService[event bus] xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractSubscriber[subscriber] on the xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-ObjectRemovingEvent[`ObjectRemovingEvent`].
-====

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-updated.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-updated.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-updated.adoc
deleted file mode 100644
index 1fbc323..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-updated.adoc
+++ /dev/null
@@ -1,18 +0,0 @@
-[[_rgcms_methods_reserved_manpage-updated]]
-= `updated()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-
-
-The `updated()` lifecycle callback method is called when a (persistent) object has just been updated in the object store
-
-See also xref:rgcms.adoc#_rgcms_methods_lifecycle_manpage-updating[`updating()`].
-
-[TIP]
-====
-Alternatively, consider using a xref:rgsvc.adoc#_rgsvc-api_EventBusService[event bus] xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractSubscriber[subscriber] on the xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-ObjectUpdatedEvent[`ObjectUpdatedEvent`].
-====

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-updating.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-updating.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-updating.adoc
deleted file mode 100644
index 455402f..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-updating.adoc
+++ /dev/null
@@ -1,15 +0,0 @@
-[[_rgcms_methods_reserved_manpage-updating]]
-= `updating()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-The `updating()` lifecycle callback method is called when a (persistent) object is just about to be updated in the object store
-
-See also xref:rgcms.adoc#_rgcms_methods_lifecycle_manpage-updated[`updated()`].
-
-[TIP]
-====
-Alternatively, consider using a xref:rgsvc.adoc#_rgsvc-api_EventBusService[event bus] xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractSubscriber[subscriber] on the xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-ObjectUpdatingEvent[`ObjectUpdatingEvent`].
-====

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_persisted.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_persisted.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_persisted.adoc
new file mode 100644
index 0000000..6b079af
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_persisted.adoc
@@ -0,0 +1,16 @@
+[[_rgcms_methods_reserved_persisted]]
+= `persisted()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The `persisted()` lifecycle callback method is called when object has just been persisted from the object store.
+
+See also xref:rgcms.adoc#_rgcms_methods_lifecycle_persisting[`persisting()`].
+
+[TIP]
+====
+Alternatively, consider using a xref:rgsvc.adoc#_rgsvc-api_EventBusService[event bus] xref:rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscriber] on the xref:rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectPersistedEvent[`ObjectPersistedEvent`].
+====

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_persisting.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_persisting.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_persisting.adoc
new file mode 100644
index 0000000..4a22ea2
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_persisting.adoc
@@ -0,0 +1,16 @@
+[[_rgcms_methods_reserved_persisting]]
+= `persisting()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The `persisting()` lifecycle callback method is called when a (not-yet-persistent) object is just about to be persisted from the object store
+
+See also xref:rgcms.adoc#_rgcms_methods_lifecycle_persisted[`persisted()`].
+
+[TIP]
+====
+Alternatively, consider using a xref:rgsvc.adoc#_rgsvc-api_EventBusService[event bus] xref:rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscriber] on the xref:rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectPersistingEvent[`ObjectPersistingEvent`].
+====

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_removed.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_removed.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_removed.adoc
new file mode 100644
index 0000000..ef3414e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_removed.adoc
@@ -0,0 +1,16 @@
+[[_rgcms_methods_reserved_removed]]
+= `removed()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The `removed()` lifecycle callback method is called when a (persistent) object has just been deleted from the object store
+
+See also xref:rgcms.adoc#_rgcms_methods_lifecycle_removing[`removing()`].
+
+[TIP]
+====
+Alternatively, consider using a xref:rgsvc.adoc#_rgsvc-api_EventBusService[event bus] xref:rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscriber] on the xref:rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectRemovedEvent[`ObjectRemovedEvent`].
+====

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_removing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_removing.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_removing.adoc
new file mode 100644
index 0000000..6d5f880
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_removing.adoc
@@ -0,0 +1,16 @@
+[[_rgcms_methods_reserved_removing]]
+= `removing()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The `removing()` lifecycle callback method is called when a (persistent) object is just about to be deleted from the object store
+
+See also xref:rgcms.adoc#_rgcms_methods_lifecycle_removed[`removed()`].
+
+[TIP]
+====
+Alternatively, consider using a xref:rgsvc.adoc#_rgsvc-api_EventBusService[event bus] xref:rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscriber] on the xref:rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectRemovingEvent[`ObjectRemovingEvent`].
+====

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_updated.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_updated.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_updated.adoc
new file mode 100644
index 0000000..6287e54
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_updated.adoc
@@ -0,0 +1,18 @@
+[[_rgcms_methods_reserved_updated]]
+= `updated()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+
+
+The `updated()` lifecycle callback method is called when a (persistent) object has just been updated in the object store
+
+See also xref:rgcms.adoc#_rgcms_methods_lifecycle_updating[`updating()`].
+
+[TIP]
+====
+Alternatively, consider using a xref:rgsvc.adoc#_rgsvc-api_EventBusService[event bus] xref:rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscriber] on the xref:rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectUpdatedEvent[`ObjectUpdatedEvent`].
+====

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_updating.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_updating.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_updating.adoc
new file mode 100644
index 0000000..3f87a20
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_updating.adoc
@@ -0,0 +1,15 @@
+[[_rgcms_methods_reserved_updating]]
+= `updating()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+The `updating()` lifecycle callback method is called when a (persistent) object is just about to be updated in the object store
+
+See also xref:rgcms.adoc#_rgcms_methods_lifecycle_updated[`updated()`].
+
+[TIP]
+====
+Alternatively, consider using a xref:rgsvc.adoc#_rgsvc-api_EventBusService[event bus] xref:rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscriber] on the xref:rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectUpdatingEvent[`ObjectUpdatingEvent`].
+====

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes.adoc
index 1165905..3e050de 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes.adoc
@@ -34,7 +34,7 @@ The table below lists the method prefixes that are recognized as part of Apache
 Param
 |Description
 
-|xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-addTo[`addTo...()`]
+|xref:rgcms.adoc#_rgcms_methods_prefixes_addTo[`addTo...()`]
 |
 |
 |Y
@@ -47,10 +47,10 @@ Param
 Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer].
 ====
 
-See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-removeFrom[`removeFrom...()`]`
+See also xref:rgcms.adoc#_rgcms_methods_prefixes_removeFrom[`removeFrom...()`]`
 
 
-|xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-autoComplete[`autoComplete...()`]
+|xref:rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`]
 |
 |Y
 |
@@ -61,9 +61,9 @@ See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-removeFrom[`removeFrom.
 Alternatively, can specify for a class using xref:rgant.adoc#_rgant-DomainObject_autoCompleteRepository[`@DomainObject` +
 `#autoCompleteRepository`] +
 
-See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-choices[`choices...()`]
+See also xref:rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`]
 
-|xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-choices[`choices...()`]
+|xref:rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`]
 |
 |Y
 |
@@ -71,9 +71,9 @@ See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-choices[`choices...()`]
 |Y
 |Provide list of choices for a property or action parameter. +
 
-See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-autoComplete[`autoComplete...()`].
+See also xref:rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`].
 
-|xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-clear[`clear...()`]
+|xref:rgcms.adoc#_rgcms_methods_prefixes_clear[`clear...()`]
 |
 |Y
 |
@@ -83,10 +83,10 @@ See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-autoComplete[`autoCompl
 
 Allows business logic to be placed apart from the setter. +
 
-See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-modify[`modify...()`]
+See also xref:rgcms.adoc#_rgcms_methods_prefixes_modify[`modify...()`]
 
 
-|xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-default[`default...()`]
+|xref:rgcms.adoc#_rgcms_methods_prefixes_default[`default...()`]
 |
 |Y
 |
@@ -94,7 +94,7 @@ See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-modify[`modify...()`]
 |Y
 |Default value for a property or an action parameter.
 
-|xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-disable[`disable...()`]
+|xref:rgcms.adoc#_rgcms_methods_prefixes_disable[`disable...()`]
 |Y
 |Y
 |Y
@@ -102,7 +102,7 @@ See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-modify[`modify...()`]
 |
 |Disables (makes read-only) a property, a collection or an action.
 
-|xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-get[`get...()`]
+|xref:rgcms.adoc#_rgcms_methods_prefixes_get[`get...()`]
 |
 |Y
 |Y
@@ -110,9 +110,9 @@ See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-modify[`modify...()`]
 |
 |Access the value of a property or collection. +
 
-See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-set[`set...()`].
+See also xref:rgcms.adoc#_rgcms_methods_prefixes_set[`set...()`].
 
-|xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-hide[`hide...()`]
+|xref:rgcms.adoc#_rgcms_methods_prefixes_hide[`hide...()`]
 |
 |Y
 |Y
@@ -120,7 +120,7 @@ See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-set[`set...()`].
 |
 |Hides a property, a collection or an action.
 
-|xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-modify[`modify...()`]
+|xref:rgcms.adoc#_rgcms_methods_prefixes_modify[`modify...()`]
 |
 |Y
 |
@@ -130,9 +130,9 @@ See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-set[`set...()`].
 
 Allows business logic to be placed apart from the setter. +
 
-See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-clear[`clear...()`]`.
+See also xref:rgcms.adoc#_rgcms_methods_prefixes_clear[`clear...()`]`.
 
-|xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-removeFrom[`removeFrom...()`]
+|xref:rgcms.adoc#_rgcms_methods_prefixes_removeFrom[`removeFrom...()`]
 |
 |
 |Y
@@ -145,10 +145,10 @@ See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-clear[`clear...()`]`.
 Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer].
 ====
 
-See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-addTo[`addTo...()`]`
+See also xref:rgcms.adoc#_rgcms_methods_prefixes_addTo[`addTo...()`]`
 
 
-|xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-set[`set...()`]
+|xref:rgcms.adoc#_rgcms_methods_prefixes_set[`set...()`]
 |
 |Y
 |Y
@@ -156,7 +156,7 @@ See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-addTo[`addTo...()`]`
 |
 |Sets the value of a property or a collection.
 
-|xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-validate[`validate...()`]
+|xref:rgcms.adoc#_rgcms_methods_prefixes_validate[`validate...()`]
 |Y
 |
 |
@@ -164,9 +164,9 @@ See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-addTo[`addTo...()`]`
 |Y
 |Check that a proposed value of a property or a set of action parameters or a single action parameter is valid. +
 
-See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-validateAddTo[`validateAddTo...()`] and xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-validateRemoveFrom[`validateRemoveFrom...()`] to validate modifications to collections.
+See also xref:rgcms.adoc#_rgcms_methods_prefixes_validateAddTo[`validateAddTo...()`] and xref:rgcms.adoc#_rgcms_methods_prefixes_validateRemoveFrom[`validateRemoveFrom...()`] to validate modifications to collections.
 
-|xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-validateAddTo[`validate +
+|xref:rgcms.adoc#_rgcms_methods_prefixes_validateAddTo[`validate +
 AddTo...()`]
 |
 |Y
@@ -180,9 +180,9 @@ AddTo...()`]
 Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer].
 ====
 
-See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-validateRemoveFrom[`validateRemoveFrom...()`], and xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-validate[`validate...()`] for properties and actions.
+See also xref:rgcms.adoc#_rgcms_methods_prefixes_validateRemoveFrom[`validateRemoveFrom...()`], and xref:rgcms.adoc#_rgcms_methods_prefixes_validate[`validate...()`] for properties and actions.
 
-|xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-validateRemoveFrom[`validate +
+|xref:rgcms.adoc#_rgcms_methods_prefixes_validateRemoveFrom[`validate +
 RemoveFrom...()`]
 |
 |Y
@@ -196,24 +196,24 @@ RemoveFrom...()`]
 Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer].
 ====
 
-See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-validateAddTo[`validateAddTo...()`], and xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-validate[`validate...()`] for properties and actions.
+See also xref:rgcms.adoc#_rgcms_methods_prefixes_validateAddTo[`validateAddTo...()`], and xref:rgcms.adoc#_rgcms_methods_prefixes_validate[`validate...()`] for properties and actions.
 
 |===
 
 
 
-include::_rgcms_methods_prefixes_manpage-addTo.adoc[leveloffset=+1]
-include::_rgcms_methods_prefixes_manpage-autoComplete.adoc[leveloffset=+1]
-include::_rgcms_methods_prefixes_manpage-choices.adoc[leveloffset=+1]
-include::_rgcms_methods_prefixes_manpage-clear.adoc[leveloffset=+1]
-include::_rgcms_methods_prefixes_manpage-default.adoc[leveloffset=+1]
-include::_rgcms_methods_prefixes_manpage-disable.adoc[leveloffset=+1]
-include::_rgcms_methods_prefixes_manpage-get.adoc[leveloffset=+1]
-include::_rgcms_methods_prefixes_manpage-hide.adoc[leveloffset=+1]
-include::_rgcms_methods_prefixes_manpage-modify.adoc[leveloffset=+1]
-include::_rgcms_methods_prefixes_manpage-removeFrom.adoc[leveloffset=+1]
-include::_rgcms_methods_prefixes_manpage-set.adoc[leveloffset=+1]
-include::_rgcms_methods_prefixes_manpage-validate.adoc[leveloffset=+1]
-include::_rgcms_methods_prefixes_manpage-validateAddTo.adoc[leveloffset=+1]
-include::_rgcms_methods_prefixes_manpage-validateRemoveFrom.adoc[leveloffset=+1]
+include::_rgcms_methods_prefixes_addTo.adoc[leveloffset=+1]
+include::_rgcms_methods_prefixes_autoComplete.adoc[leveloffset=+1]
+include::_rgcms_methods_prefixes_choices.adoc[leveloffset=+1]
+include::_rgcms_methods_prefixes_clear.adoc[leveloffset=+1]
+include::_rgcms_methods_prefixes_default.adoc[leveloffset=+1]
+include::_rgcms_methods_prefixes_disable.adoc[leveloffset=+1]
+include::_rgcms_methods_prefixes_get.adoc[leveloffset=+1]
+include::_rgcms_methods_prefixes_hide.adoc[leveloffset=+1]
+include::_rgcms_methods_prefixes_modify.adoc[leveloffset=+1]
+include::_rgcms_methods_prefixes_removeFrom.adoc[leveloffset=+1]
+include::_rgcms_methods_prefixes_set.adoc[leveloffset=+1]
+include::_rgcms_methods_prefixes_validate.adoc[leveloffset=+1]
+include::_rgcms_methods_prefixes_validateAddTo.adoc[leveloffset=+1]
+include::_rgcms_methods_prefixes_validateRemoveFrom.adoc[leveloffset=+1]
 

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_addTo.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_addTo.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_addTo.adoc
new file mode 100644
index 0000000..23fed5c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_addTo.adoc
@@ -0,0 +1,37 @@
+[[_rgcms_methods_prefixes_addTo]]
+= `addTo...()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The `addTo...()` supporting method is called whenever an object is added to a collection. Its purpose is to allow additional business logic to be performed.
+
+
+[NOTE]
+====
+Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer].  The suggested workaround is to simply define an action.
+====
+
+
+For example:
+
+[source,java]
+----
+public class LibraryMember {
+    public SortedSet<Book> getBorrowed() { ... }
+    public void setBorrowed(SortedSet<Book> borrowed) { ... }
+    public void addToBorrowed(Book book) {
+        getBorrowed().add(book);                                              // <1>
+        reminderService.addReminder(this, book, clock.today().plusDays(21));  // <2>
+    }
+    public void removeFromBorrowed(Book book) { ... }
+    ...
+}
+----
+<1> update the collection
+<2> perform some additional business logic
+
+
+See also xref:rgcms.adoc#_rgcms_methods_prefixes_removeFrom[`removeFrom...()`]`

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_autoComplete.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_autoComplete.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_autoComplete.adoc
new file mode 100644
index 0000000..3d5e7e6
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_autoComplete.adoc
@@ -0,0 +1,96 @@
+[[_rgcms_methods_prefixes_autoComplete]]
+= `autoComplete...()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The `autoComplete...()` supporting method is called for action parameters and for properties to find objects from a drop-down list box.  The use case is when the number of candidate objects is expected to be large, so the user is required to enter some characters to narrow the search down.
+
+[TIP]
+====
+If the number of candidate objects is comparatively small, then use xref:rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`] supporting method instead.
+====
+
+The signature of the supporting method depends on whether it is for a parameter or a property.
+
+
+== Parameters
+
+For an action parameter in (0-based) position _N_, and of type `T`, the signature is:
+
+[source,java]
+----
+public List<T> autoCompleteNXxx(String search) { ... }
+----
+
+It is also valid to return `T[]`, a `Set<T>` or a `Collection<T>`.
+
+
+For example:
+
+[source,java]
+----
+public class ShoppingCartItem {
+    @Property(editing=Editing.DISABLED)
+    public Product getProduct() { ... }
+    public void setProduct(Product product) { ... }
+
+    @Property(editing=Editing.DISABLED)
+    public int getQuantity() { ... }
+    public void setQuantity(int quantity) { ... }
+
+    @Action(semantics=SemanticsOf.IDEMPOTENT)
+    public ShoppingCartItem updateProduct(
+        Product product,
+        @ParameterLayout(named="Quantity")
+        final int quantity) {
+        setProduct(product);
+        setQuantity(quantity);
+    }
+    public Collection<Product> autoComplete0UpdateProduct(  // <1>
+        @MinLength(3) String search                         // <2>
+    ) {
+        ...
+    }
+    ...
+}
+----
+<1> `product` is the 0th argument of the action.
+<2> the xref:rgant.adoc#_rgant-MinLength[`@MinLength`] annotation specifies the minimum number of characters that must be entered before a search is performed for matching objects
+
+
+
+
+
+== Properties
+
+For a property of type `T`, the signature is:
+
+[source,java]
+----
+public List<T> autoCompleteXxx(String search) { ... }
+----
+
+(As for action parameters) it is also valid to return `T[]`, a `Set<T>` or a `Collection<T>`.
+
+For example:
+
+[source,java]
+----
+public class ShoppingCartItem {
+    public Product getProduct() { ... }
+    public void setProduct(Product product) { ... }
+
+    public Collection<Product> autoCompleteProduct(
+        @MinLength(3) String search                     // <1>
+    ) {
+        ...
+    }
+    ...
+}
+----
+<1> the xref:rgant.adoc#_rgant-MinLength[`@MinLength`] annotation specifies the minimum number of characters that must be entered before a search is performed for matching objects
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_choices.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_choices.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_choices.adoc
new file mode 100644
index 0000000..e20a470
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_choices.adoc
@@ -0,0 +1,143 @@
+[[_rgcms_methods_prefixes_choices]]
+= `choices...()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The `choices...()` supporting method is called for both action parameters and for properties, to find objects from a drop-down list box.  Unlike xref:rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`], the use case is when the number of objects is comparatively small and can be selected from a drop-down without any additional filtering.
+
+The signature of the supporting method depends on whether it is for an action parameter or a property.
+
+
+== Parameters
+
+For an action parameter in (0-based) position _N_, and of type `T`, the signature is:
+
+[source,java]
+----
+public Collection<T> choicesNXxx() { ... }
+----
+
+
+For example:
+
+[source,java]
+----
+public class ShoppingCartItem {
+    @Property(editing=Editing.DISABLED)
+    public Product getProduct() { ... }
+    public void setProduct(Product product) { ... }
+
+    @Property(editing=Editing.DISABLED)
+    public int getQuantity() { ... }
+    public void setQuantity(int quantity) { ... }
+
+    @Action(semantics=SemanticsOf.IDEMPOTENT)
+    public ShoppingCartItem updateProduct(
+        Product product,
+        @ParameterLayout(named="Quantity")
+        final Integer quantity) {
+        setProduct(product);
+        setQuantity(quantity);
+    }
+    public Collection<Integer> choices1UpdateProduct() {
+        return Arrays.asList(1,2,3,5,10,25,50,100);
+    }
+    ...
+}
+----
+
+
+=== Dependent Choices
+
+Action parameters also support the notion of dependent choices, whereby the list of choices is dependent upon the value of some other argument.
+
+An example can be found in the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp], whereby `ToDoItem`s are categorized and then can also be subcategorized:
+
+image::{_imagesdir}reference-methods/prefixes/choices/dependent.png[width="800px",link="{_imagesdir}reference-methods/prefixes/choices/dependent.png"]
+
+
+
+This functionality is actually implemented as a xref:ug.adoc#_ug_how-tos_contributed-members[contributed action], so the code for this is:
+
+[source,java]
+----
+@DomainService(nature = NatureOfService.VIEW_CONTRIBUTIONS_ONLY)
+public class UpdateCategoryContributions ... {
+    @ActionLayout(
+            describedAs = "Update category and subcategory"
+    )
+    @Action(semantics = SemanticsOf.IDEMPOTENT)
+    public Categorized updateCategory(
+            final Categorized item,                              // <1>
+            final Category category,
+            @Parameter(optionality = Optionality.OPTIONAL)
+            final Subcategory subcategory) {
+        item.setCategory(category);
+        item.setSubcategory(subcategory);
+        return item;
+    }
+    public List<Subcategory> choices2UpdateCategory(             // <2>
+            final Categorized item,                              // <3>
+            final Category category) {                           // <4>
+        return Subcategory.listFor(category);
+    }
+    ...
+}
+----
+<1> `ToDoItem` implements `Categorized`
+<2> subcategory is the 2-th argument (0-based)
+<3> the item contributed to
+<4> the category selected
+
+
+Dependent choices are not restricted to enums, however.  Going back to the shopping cart example shown above, the choices for the `quantity` parameter could be dependent upon the selected `Product`:
+
+
+[source,java]
+----
+public class ShoppingCartItem {
+    ...
+    @Action(semantics=SemanticsOf.IDEMPOTENT)
+    public ShoppingCartItem updateProduct(
+        Product product,
+        @ParameterLayout(named="Quantity")
+        final Integer quantity) {
+        setProduct(product);
+        setQuantity(quantity);
+    }
+    public Collection<Integer> choices1UpdateProduct(Product product) {
+        return productService.quantityChoicesFor(product);                 // <1>
+    }
+    ...
+}
+----
+<1> `productService` is a (fictitous) injected service that knows what the quantity choices should be for any given product
+
+
+== Properties
+
+For a property of type `T`, the signature is:
+
+[source,java]
+----
+public Collection<T> choicesXxx() { ... }
+----
+
+
+For example:
+
+[source,java]
+----
+public class ShoppingCartItem {
+    public Product getProduct() { ... }
+    public void setProduct(Product product) { ... }
+
+    public Collection<Product> choicesProduct() {
+        ...
+    }
+----
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_clear.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_clear.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_clear.adoc
new file mode 100644
index 0000000..6146e7f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_clear.adoc
@@ -0,0 +1,32 @@
+[[_rgcms_methods_prefixes_clear]]
+= `clear...()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The `clear...()` supporting method is called -- instead of the setter -- whenever an (optional) property is to be set to `null`.  Its purpose is to allow additional business logic to be performed.
+
+
+For example:
+
+[source,java]
+----
+public class LibraryMember {
+    public Title getFavoriteTitle() { ... }
+    public void setFavoriteTitle(Title title) { ... }
+    public void modifyFavoriteTitle(Title title) { ... }
+    public void clearFavoriteTitle() {
+        if(getTitle() == null) { return; }
+        setFavoriteTitle(null);                         // <1>
+        titleFavoritesService.decrement(title);         // <2>
+    }
+    ...
+}
+----
+<1> update the property
+<2> perform some additional business logic
+
+
+See also xref:rgcms.adoc#_rgcms_methods_prefixes_modify[`modify...()`]`

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_default.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_default.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_default.adoc
new file mode 100644
index 0000000..36b18de
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_default.adoc
@@ -0,0 +1,129 @@
+[[_rgcms_methods_prefixes_default]]
+= `default...()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The `default...()` supporting method is called for action parameters to return the initial argument value.  This may be some sensible default (eg today's date, or 0 or 1), or -- for an action that is modifying the state of an object -- might default to the current value of a corresponding property.
+
+The method is _also_ called for properties in the case when an object is newly instantiated using xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer[`DomainObjectContainer#newTransientInstance(...)`].  This is a much less common use case.  If a default is not specified then properties are initialized to a default based on their type (eg 0 or `false`).
+
+The signature of the supporting method depends on whether it is for an action parameter or a property.
+
+
+== Parameters
+
+For an action parameter in (0-based position n), and of type `T`, the signature is:
+
+[source,java]
+----
+public T defaultNXxx() { ... }
+----
+
+
+For example:
+
+[source,java]
+----
+public class ShoppingCartItem {
+    @Property(editing=Editing.DISABLED)
+    public Product getProduct() { ... }
+    public void setProduct(Product product) { ... }
+
+    @Property(editing=Editing.DISABLED)
+    public int getQuantity() { ... }
+    public void setQuantity(int quantity) { ... }
+
+    @Action(semantics=SemanticsOf.IDEMPOTENT)
+    public ShoppingCartItem updateProduct(
+        Product product,
+        @ParameterLayout(named="Quantity")
+        final Integer quantity) {
+        setProduct(product);
+        setQuantity(quantity);
+    }
+    public Product default0UpdateProduct() {    // <1>
+        return getProduct();
+    }
+    public int default1UpdateProduct() {        // <2>
+        return getQuantity();
+    }
+    ...
+}
+----
+<1> default the 0-th parameter using the current value of the `product` property
+<2> default the 1-th parameter using the current value of the `quantity` property
+
+
+
+Defaults are also supported (of course) for xref:ug.adoc#_ug_how-tos_contributed-members[contributed actions].  For example, here is a contributed action for updating category/subcategory of the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp]:
+
+[source,java]
+----
+@DomainService(nature = NatureOfService.VIEW_CONTRIBUTIONS_ONLY)
+public class UpdateCategoryContributions ... {
+    @ActionLayout(
+            describedAs = "Update category and subcategory"
+    )
+    @Action(semantics = SemanticsOf.IDEMPOTENT)
+    public Categorized updateCategory(
+            final Categorized item,                              // <1>
+            final Category category,
+            @Parameter(optionality = Optionality.OPTIONAL)
+            final Subcategory subcategory) {
+        item.setCategory(category);
+        item.setSubcategory(subcategory);
+        return item;
+    }
+    public Category default1UpdateCategory(                     // <2>
+            final Categorized item) {
+        return item != null? item.getCategory(): null;
+    }
+    public Subcategory default2UpdateCategory(                  // <3>
+            final Categorized item) {
+        return item != null? item.getSubcategory(): null;
+    }
+}
+----
+<1> `ToDoItem` implements `Categorized`
+<2> defaults the 1-th parameter using the item's `category` property
+<3> defaults the 2-th parameter using the item's `subcategory` property
+
+
+
+
+
+== Properties
+
+For a property of type `T`, the signature is:
+
+[source,java]
+----
+public T defaultXxx() { ... }
+----
+
+
+For example:
+
+[source,java]
+----
+public class ShoppingCartItem {
+    public int getQuantity() { ... }
+    public void setQuantity(int quantity) { ... }
+
+    public int defaultProduct() {
+        return 1;
+    }
+----
+
+
+=== Alternatives
+
+There are, in fact, two other ways to set properties of a newly instantiated object to default values.
+
+The first is to use the xref:rgcms.adoc#_rgcms_methods_lifecycle_created[`created()`] callback, called by the framework when xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer[`DomainObjectContainer#newTransientInstance(...)`] is called.  This method is called after any dependencies have been injected into the service.
+
+The second is more straightforward: simply initialize properties in the constructor.  However, this cannot use any injected services as they will not have been initialized.
+

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_disable.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_disable.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_disable.adoc
new file mode 100644
index 0000000..c0c9797
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_disable.adoc
@@ -0,0 +1,93 @@
+[[_rgcms_methods_prefixes_disable]]
+= `disable...()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+
+The `disable...()` supporting method is called for properties, collections and actions.  It allows the modification of the property/collection to be vetoed (ie made read-only) and to prevent the invocation of the action ("grey it out").
+
+[NOTE]
+====
+Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer]; they are always implicitly disabled.
+====
+
+Typically modification/invocation is vetoed based on the state of the domain object being interacted with, though it could be any reason at all (eg the current date/time of the interaction, or the state of some other related data such as stock levels, or the identity of the calling user).
+
+
+The reason for vetoing a modification/invocation is normally returned as a string.  However, Apache Isis' xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[i18n support] extends this so that reasons can be internationalized.
+
+
+
+== Actions
+
+For an action the signature of the supporting method is:
+
+[source,java]
+----
+public String disableXxx(...) { ... }
+----
+
+where the returned string is the reason the action invocation is vetoed (or `null` if not vetoed), and the supporting method takes the same parameter types as the action itself.
+
+
+
+For example:
+
+[source,java]
+----
+public class Customer {
+    public boolean isBlacklisted() { ... }
+
+    public Order placeOrder(
+            final Product product,
+            @ParameterLayout(named="Quantity")
+            final int quantity) {
+        ...
+    }
+    public String disablePlaceOrder(
+            final Product product,
+            final int quantity
+            ) {
+        return isBlacklisted()
+                    ? "Blacklisted customers cannot place orders"
+                    : null;
+    }
+    ...
+}
+----
+
+
+
+== Properties and Collections
+
+For both properties and collections the signature of the supporting method is:
+
+[source,java]
+----
+public String disableXxx() { ... }
+----
+
+where the returned string is the reason the modification is vetoed (or `null` if not vetoed).
+
+
+
+For example:
+
+[source,java]
+----
+public class Customer {
+    public boolean isBlacklisted() { ... }
+
+    public BigDecimal getCreditLimit() { ... }
+    public void setCreditLimit(BigDecimal creditLimit) { ... }
+    public String disableCreditLimit() {
+        return isBlacklisted()
+                    ? "Cannot change credit limit for blacklisted customers"
+                    : null;
+    }
+    ...
+}
+----

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_get.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_get.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_get.adoc
new file mode 100644
index 0000000..4c80bbe
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_get.adoc
@@ -0,0 +1,19 @@
+[[_rgcms_methods_prefixes_get]]
+= `get...()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The `get...()` prefix is simply the normal JavaBean getter prefix that denotes properties or collections.
+
+When Apache Isis builds its metamodel, it first searches for the getter methods, characterizing them as either properties or collections based on the return type.  It then refines the metamodel based on the presence of annotations and supporting methods.
+
+All remaining `public` methods (that do not use one of the Apache Isis prefixes) are interpreted as actions.
+
+Any methods "left over" that _do_ use one of the Apache Isis prefixes, are interpreted to be orphaned.  Apache Isis "fails-fast" and will not boot, instead printing an error message to the log so that the issue can be easily diagnosed.
+
+
+See also xref:rgcms.adoc#_rgcms_methods_prefixes_set[`set...()`].
+

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_hide.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_hide.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_hide.adoc
new file mode 100644
index 0000000..101a89a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_hide.adoc
@@ -0,0 +1,82 @@
+[[_rgcms_methods_prefixes_hide]]
+= `hide...()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The `hide...()` supporting method is called for properties, collections and actions.  It allows the property/collection to be completely hidden from view.
+
+It's comparatively rare for properties or collections to be imperatively hidden from view, but actions are sometimes hidden or shown visible (as opposed to being just xref:rgcms.adoc#_rgcms_methods_prefixes_disable[disabled], ie greyed out).
+
+
+== Actions
+
+For an action the signature of the supporting method is either:
+
+[source,java]
+----
+public bool hideXxx(...) { ... }
+----
+
+where the supporting method takes the same parameter types as the action itself, or more simply:
+
+[source,java]
+----
+public bool hideXxx() { ... }
+----
+
+with no parameters at all.  Returning `true` will hide the action, returning `false` leaves it visible.
+
+
+For example:
+
+[source,java]
+----
+public class Customer {
+    public boolean isBlacklisted() { ... }
+
+    public Order placeOrder(
+            final Product product,
+            @ParameterLayout(named="Quantity")
+            final int quantity) {
+        ...
+    }
+    public boolean hidePlaceOrder() {
+        return isBlacklisted();
+    }
+    ...
+}
+----
+
+
+
+== Properties and Collections
+
+For both properties and collections the signature of the supporting method is:
+
+[source,java]
+----
+public boolean hideXxx() { ... }
+----
+
+where returning `true` will hide the property/collection, returning `false` leaves it visible.
+
+
+
+For example:
+
+[source,java]
+----
+public class Customer {
+    public boolean isBlacklisted() { ... }
+
+    public BigDecimal getCreditLimit() { ... }
+    public void setCreditLimit(BigDecimal creditLimit) { ... }
+    public boolean hideCreditLimit() {
+        return isBlacklisted();
+    }
+    ...
+}
+----

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-addTo.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-addTo.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-addTo.adoc
deleted file mode 100644
index 15f140d..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-addTo.adoc
+++ /dev/null
@@ -1,37 +0,0 @@
-[[_rgcms_methods_prefixes_manpage-addTo]]
-= `addTo...()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `addTo...()` supporting method is called whenever an object is added to a collection. Its purpose is to allow additional business logic to be performed.
-
-
-[NOTE]
-====
-Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer].  The suggested workaround is to simply define an action.
-====
-
-
-For example:
-
-[source,java]
-----
-public class LibraryMember {
-    public SortedSet<Book> getBorrowed() { ... }
-    public void setBorrowed(SortedSet<Book> borrowed) { ... }
-    public void addToBorrowed(Book book) {
-        getBorrowed().add(book);                                              // <1>
-        reminderService.addReminder(this, book, clock.today().plusDays(21));  // <2>
-    }
-    public void removeFromBorrowed(Book book) { ... }
-    ...
-}
-----
-<1> update the collection
-<2> perform some additional business logic
-
-
-See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-removeFrom[`removeFrom...()`]`

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-autoComplete.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-autoComplete.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-autoComplete.adoc
deleted file mode 100644
index 5dbb7fb..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-autoComplete.adoc
+++ /dev/null
@@ -1,96 +0,0 @@
-[[_rgcms_methods_prefixes_manpage-autoComplete]]
-= `autoComplete...()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `autoComplete...()` supporting method is called for action parameters and for properties to find objects from a drop-down list box.  The use case is when the number of candidate objects is expected to be large, so the user is required to enter some characters to narrow the search down.
-
-[TIP]
-====
-If the number of candidate objects is comparatively small, then use xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-choices[`choices...()`] supporting method instead.
-====
-
-The signature of the supporting method depends on whether it is for a parameter or a property.
-
-
-== Parameters
-
-For an action parameter in (0-based) position _N_, and of type `T`, the signature is:
-
-[source,java]
-----
-public List<T> autoCompleteNXxx(String search) { ... }
-----
-
-It is also valid to return `T[]`, a `Set<T>` or a `Collection<T>`.
-
-
-For example:
-
-[source,java]
-----
-public class ShoppingCartItem {
-    @Property(editing=Editing.DISABLED)
-    public Product getProduct() { ... }
-    public void setProduct(Product product) { ... }
-
-    @Property(editing=Editing.DISABLED)
-    public int getQuantity() { ... }
-    public void setQuantity(int quantity) { ... }
-
-    @Action(semantics=SemanticsOf.IDEMPOTENT)
-    public ShoppingCartItem updateProduct(
-        Product product,
-        @ParameterLayout(named="Quantity")
-        final int quantity) {
-        setProduct(product);
-        setQuantity(quantity);
-    }
-    public Collection<Product> autoComplete0UpdateProduct(  // <1>
-        @MinLength(3) String search                         // <2>
-    ) {
-        ...
-    }
-    ...
-}
-----
-<1> `product` is the 0th argument of the action.
-<2> the xref:rgant.adoc#_rgant-MinLength[`@MinLength`] annotation specifies the minimum number of characters that must be entered before a search is performed for matching objects
-
-
-
-
-
-== Properties
-
-For a property of type `T`, the signature is:
-
-[source,java]
-----
-public List<T> autoCompleteXxx(String search) { ... }
-----
-
-(As for action parameters) it is also valid to return `T[]`, a `Set<T>` or a `Collection<T>`.
-
-For example:
-
-[source,java]
-----
-public class ShoppingCartItem {
-    public Product getProduct() { ... }
-    public void setProduct(Product product) { ... }
-
-    public Collection<Product> autoCompleteProduct(
-        @MinLength(3) String search                     // <1>
-    ) {
-        ...
-    }
-    ...
-}
-----
-<1> the xref:rgant.adoc#_rgant-MinLength[`@MinLength`] annotation specifies the minimum number of characters that must be entered before a search is performed for matching objects
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-choices.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-choices.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-choices.adoc
deleted file mode 100644
index cf66fdc..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-choices.adoc
+++ /dev/null
@@ -1,143 +0,0 @@
-[[_rgcms_methods_prefixes_manpage-choices]]
-= `choices...()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `choices...()` supporting method is called for both action parameters and for properties, to find objects from a drop-down list box.  Unlike xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-autoComplete[`autoComplete...()`], the use case is when the number of objects is comparatively small and can be selected from a drop-down without any additional filtering.
-
-The signature of the supporting method depends on whether it is for an action parameter or a property.
-
-
-== Parameters
-
-For an action parameter in (0-based) position _N_, and of type `T`, the signature is:
-
-[source,java]
-----
-public Collection<T> choicesNXxx() { ... }
-----
-
-
-For example:
-
-[source,java]
-----
-public class ShoppingCartItem {
-    @Property(editing=Editing.DISABLED)
-    public Product getProduct() { ... }
-    public void setProduct(Product product) { ... }
-
-    @Property(editing=Editing.DISABLED)
-    public int getQuantity() { ... }
-    public void setQuantity(int quantity) { ... }
-
-    @Action(semantics=SemanticsOf.IDEMPOTENT)
-    public ShoppingCartItem updateProduct(
-        Product product,
-        @ParameterLayout(named="Quantity")
-        final Integer quantity) {
-        setProduct(product);
-        setQuantity(quantity);
-    }
-    public Collection<Integer> choices1UpdateProduct() {
-        return Arrays.asList(1,2,3,5,10,25,50,100);
-    }
-    ...
-}
-----
-
-
-=== Dependent Choices
-
-Action parameters also support the notion of dependent choices, whereby the list of choices is dependent upon the value of some other argument.
-
-An example can be found in the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp], whereby `ToDoItem`s are categorized and then can also be subcategorized:
-
-image::{_imagesdir}reference-methods/prefixes/choices/dependent.png[width="800px",link="{_imagesdir}reference-methods/prefixes/choices/dependent.png"]
-
-
-
-This functionality is actually implemented as a xref:ug.adoc#_ug_how-tos_contributed-members[contributed action], so the code for this is:
-
-[source,java]
-----
-@DomainService(nature = NatureOfService.VIEW_CONTRIBUTIONS_ONLY)
-public class UpdateCategoryContributions ... {
-    @ActionLayout(
-            describedAs = "Update category and subcategory"
-    )
-    @Action(semantics = SemanticsOf.IDEMPOTENT)
-    public Categorized updateCategory(
-            final Categorized item,                              // <1>
-            final Category category,
-            @Parameter(optionality = Optionality.OPTIONAL)
-            final Subcategory subcategory) {
-        item.setCategory(category);
-        item.setSubcategory(subcategory);
-        return item;
-    }
-    public List<Subcategory> choices2UpdateCategory(             // <2>
-            final Categorized item,                              // <3>
-            final Category category) {                           // <4>
-        return Subcategory.listFor(category);
-    }
-    ...
-}
-----
-<1> `ToDoItem` implements `Categorized`
-<2> subcategory is the 2-th argument (0-based)
-<3> the item contributed to
-<4> the category selected
-
-
-Dependent choices are not restricted to enums, however.  Going back to the shopping cart example shown above, the choices for the `quantity` parameter could be dependent upon the selected `Product`:
-
-
-[source,java]
-----
-public class ShoppingCartItem {
-    ...
-    @Action(semantics=SemanticsOf.IDEMPOTENT)
-    public ShoppingCartItem updateProduct(
-        Product product,
-        @ParameterLayout(named="Quantity")
-        final Integer quantity) {
-        setProduct(product);
-        setQuantity(quantity);
-    }
-    public Collection<Integer> choices1UpdateProduct(Product product) {
-        return productService.quantityChoicesFor(product);                 // <1>
-    }
-    ...
-}
-----
-<1> `productService` is a (fictitous) injected service that knows what the quantity choices should be for any given product
-
-
-== Properties
-
-For a property of type `T`, the signature is:
-
-[source,java]
-----
-public Collection<T> choicesXxx() { ... }
-----
-
-
-For example:
-
-[source,java]
-----
-public class ShoppingCartItem {
-    public Product getProduct() { ... }
-    public void setProduct(Product product) { ... }
-
-    public Collection<Product> choicesProduct() {
-        ...
-    }
-----
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-clear.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-clear.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-clear.adoc
deleted file mode 100644
index 2963210..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-clear.adoc
+++ /dev/null
@@ -1,32 +0,0 @@
-[[_rgcms_methods_prefixes_manpage-clear]]
-= `clear...()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `clear...()` supporting method is called -- instead of the setter -- whenever an (optional) property is to be set to `null`.  Its purpose is to allow additional business logic to be performed.
-
-
-For example:
-
-[source,java]
-----
-public class LibraryMember {
-    public Title getFavoriteTitle() { ... }
-    public void setFavoriteTitle(Title title) { ... }
-    public void modifyFavoriteTitle(Title title) { ... }
-    public void clearFavoriteTitle() {
-        if(getTitle() == null) { return; }
-        setFavoriteTitle(null);                         // <1>
-        titleFavoritesService.decrement(title);         // <2>
-    }
-    ...
-}
-----
-<1> update the property
-<2> perform some additional business logic
-
-
-See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-modify[`modify...()`]`

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-default.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-default.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-default.adoc
deleted file mode 100644
index ec3ae75..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-default.adoc
+++ /dev/null
@@ -1,129 +0,0 @@
-[[_rgcms_methods_prefixes_manpage-default]]
-= `default...()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `default...()` supporting method is called for action parameters to return the initial argument value.  This may be some sensible default (eg today's date, or 0 or 1), or -- for an action that is modifying the state of an object -- might default to the current value of a corresponding property.
-
-The method is _also_ called for properties in the case when an object is newly instantiated using xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer[`DomainObjectContainer#newTransientInstance(...)`].  This is a much less common use case.  If a default is not specified then properties are initialized to a default based on their type (eg 0 or `false`).
-
-The signature of the supporting method depends on whether it is for an action parameter or a property.
-
-
-== Parameters
-
-For an action parameter in (0-based position n), and of type `T`, the signature is:
-
-[source,java]
-----
-public T defaultNXxx() { ... }
-----
-
-
-For example:
-
-[source,java]
-----
-public class ShoppingCartItem {
-    @Property(editing=Editing.DISABLED)
-    public Product getProduct() { ... }
-    public void setProduct(Product product) { ... }
-
-    @Property(editing=Editing.DISABLED)
-    public int getQuantity() { ... }
-    public void setQuantity(int quantity) { ... }
-
-    @Action(semantics=SemanticsOf.IDEMPOTENT)
-    public ShoppingCartItem updateProduct(
-        Product product,
-        @ParameterLayout(named="Quantity")
-        final Integer quantity) {
-        setProduct(product);
-        setQuantity(quantity);
-    }
-    public Product default0UpdateProduct() {    // <1>
-        return getProduct();
-    }
-    public int default1UpdateProduct() {        // <2>
-        return getQuantity();
-    }
-    ...
-}
-----
-<1> default the 0-th parameter using the current value of the `product` property
-<2> default the 1-th parameter using the current value of the `quantity` property
-
-
-
-Defaults are also supported (of course) for xref:ug.adoc#_ug_how-tos_contributed-members[contributed actions].  For example, here is a contributed action for updating category/subcategory of the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp]:
-
-[source,java]
-----
-@DomainService(nature = NatureOfService.VIEW_CONTRIBUTIONS_ONLY)
-public class UpdateCategoryContributions ... {
-    @ActionLayout(
-            describedAs = "Update category and subcategory"
-    )
-    @Action(semantics = SemanticsOf.IDEMPOTENT)
-    public Categorized updateCategory(
-            final Categorized item,                              // <1>
-            final Category category,
-            @Parameter(optionality = Optionality.OPTIONAL)
-            final Subcategory subcategory) {
-        item.setCategory(category);
-        item.setSubcategory(subcategory);
-        return item;
-    }
-    public Category default1UpdateCategory(                     // <2>
-            final Categorized item) {
-        return item != null? item.getCategory(): null;
-    }
-    public Subcategory default2UpdateCategory(                  // <3>
-            final Categorized item) {
-        return item != null? item.getSubcategory(): null;
-    }
-}
-----
-<1> `ToDoItem` implements `Categorized`
-<2> defaults the 1-th parameter using the item's `category` property
-<3> defaults the 2-th parameter using the item's `subcategory` property
-
-
-
-
-
-== Properties
-
-For a property of type `T`, the signature is:
-
-[source,java]
-----
-public T defaultXxx() { ... }
-----
-
-
-For example:
-
-[source,java]
-----
-public class ShoppingCartItem {
-    public int getQuantity() { ... }
-    public void setQuantity(int quantity) { ... }
-
-    public int defaultProduct() {
-        return 1;
-    }
-----
-
-
-=== Alternatives
-
-There are, in fact, two other ways to set properties of a newly instantiated object to default values.
-
-The first is to use the xref:rgcms.adoc#_rgcms_methods_lifecycle_manpage-created[`created()`] callback, called by the framework when xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer[`DomainObjectContainer#newTransientInstance(...)`] is called.  This method is called after any dependencies have been injected into the service.
-
-The second is more straightforward: simply initialize properties in the constructor.  However, this cannot use any injected services as they will not have been initialized.
-

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-disable.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-disable.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-disable.adoc
deleted file mode 100644
index d5775cc..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-disable.adoc
+++ /dev/null
@@ -1,93 +0,0 @@
-[[_rgcms_methods_prefixes_manpage-disable]]
-= `disable...()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-
-The `disable...()` supporting method is called for properties, collections and actions.  It allows the modification of the property/collection to be vetoed (ie made read-only) and to prevent the invocation of the action ("grey it out").
-
-[NOTE]
-====
-Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer]; they are always implicitly disabled.
-====
-
-Typically modification/invocation is vetoed based on the state of the domain object being interacted with, though it could be any reason at all (eg the current date/time of the interaction, or the state of some other related data such as stock levels, or the identity of the calling user).
-
-
-The reason for vetoing a modification/invocation is normally returned as a string.  However, Apache Isis' xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[i18n support] extends this so that reasons can be internationalized.
-
-
-
-== Actions
-
-For an action the signature of the supporting method is:
-
-[source,java]
-----
-public String disableXxx(...) { ... }
-----
-
-where the returned string is the reason the action invocation is vetoed (or `null` if not vetoed), and the supporting method takes the same parameter types as the action itself.
-
-
-
-For example:
-
-[source,java]
-----
-public class Customer {
-    public boolean isBlacklisted() { ... }
-
-    public Order placeOrder(
-            final Product product,
-            @ParameterLayout(named="Quantity")
-            final int quantity) {
-        ...
-    }
-    public String disablePlaceOrder(
-            final Product product,
-            final int quantity
-            ) {
-        return isBlacklisted()
-                    ? "Blacklisted customers cannot place orders"
-                    : null;
-    }
-    ...
-}
-----
-
-
-
-== Properties and Collections
-
-For both properties and collections the signature of the supporting method is:
-
-[source,java]
-----
-public String disableXxx() { ... }
-----
-
-where the returned string is the reason the modification is vetoed (or `null` if not vetoed).
-
-
-
-For example:
-
-[source,java]
-----
-public class Customer {
-    public boolean isBlacklisted() { ... }
-
-    public BigDecimal getCreditLimit() { ... }
-    public void setCreditLimit(BigDecimal creditLimit) { ... }
-    public String disableCreditLimit() {
-        return isBlacklisted()
-                    ? "Cannot change credit limit for blacklisted customers"
-                    : null;
-    }
-    ...
-}
-----

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-get.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-get.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-get.adoc
deleted file mode 100644
index 7ed187a..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-get.adoc
+++ /dev/null
@@ -1,19 +0,0 @@
-[[_rgcms_methods_prefixes_manpage-get]]
-= `get...()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `get...()` prefix is simply the normal JavaBean getter prefix that denotes properties or collections.
-
-When Apache Isis builds its metamodel, it first searches for the getter methods, characterizing them as either properties or collections based on the return type.  It then refines the metamodel based on the presence of annotations and supporting methods.
-
-All remaining `public` methods (that do not use one of the Apache Isis prefixes) are interpreted as actions.
-
-Any methods "left over" that _do_ use one of the Apache Isis prefixes, are interpreted to be orphaned.  Apache Isis "fails-fast" and will not boot, instead printing an error message to the log so that the issue can be easily diagnosed.
-
-
-See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-set[`set...()`].
-


[21/52] [abbrv] isis git commit: ISIS-1243: renamed ug.adoc to ugfun.adoc. Added standard section to each of the guides so can navigate between each easily.

Posted by mg...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_other-deployment-options.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_other-deployment-options.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_other-deployment-options.adoc
new file mode 100644
index 0000000..ca69816
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_other-deployment-options.adoc
@@ -0,0 +1,81 @@
+[[_ugfun_core-concepts_other-deployment-options]]
+= Other Deployment Options
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+Apache Isis is a mature platform suitable for production deployment, with its "sweet spot" being line-of-business enterprise applications.  So if you're looking to develop that sort of application, we certainly hope you'll seriously evaluate it.
+
+But there are other ways that you can make Apache Isis work for you; in this chapter we explore a few of them.
+
+
+
+== Deploy to production
+
+Let's start though with the default use case for Apache Isis: building line-of-business enterprise applications, on top of its Wicket viewer.
+
+Apache Wicket, and therefore Apache Isis in this configuration, is a stateful architecture.  As a platform it is certainly capable of supporting user bases of several thousand (with perhaps one or two hundred concurrent); however it isn't an architecture that you should try to scale up to tens of thousands of concurrent users.
+
+The UI UI generated by the Wicket viewer is well suited to many line-of-business apps, but it's also worth knowing that (with a little knowledge of the Wicket APIs) it relatively straightforward to extend.  As described in xref:ug.adoc#_ugfun_core-concepts_add-ons[Isis addons] chapter, the viewer already has integrations with https://github.com/isisaddons/isis-wicket-gmap3[google maps], https://github.com/isisaddons/isis-wicket-fullcalendar2[a full calendar] and an https://github.com/isisaddons/isis-wicket-excel[export to Excel] component.  We are also aware of integrations with SVG images (for floor maps of shopping center) and of custom widgets displaying a catalogue (text and images) of medical diseases.
+
+Deploying on Apache Isis means that the framework also manages object persistence.  For many line-of-business applications this will mean using a relational database.  It is also possible (courtesy of its integratinon with link:http://www.datanucleus.org[DataNucleus]) to deploy an Isis app to a NoSQL store such as Neo4J or MongoDB; and it is also possible to deploy to cloud platforms such as link:https://cloud.google.com/appengine/docs[Google App Engine (GAE)].
+
+
+
+== Use for prototyping
+
+Even if you don't intend to deploy your application on top of Apache Isis, there can be a lot of value in using Apache Isis for prototyping.  Because all you need do to get an app running is write domain objects, you can very quickly explore a domain object model and validate ideas with a domain expert.
+
+By focusing just on the domain, you'll also find that you start to develop a ubiquitous language - a set of terms and concepts that the entire team (business and technologists alike) have a shared understanding.
+
+Once you've sketched out your domain model, you can then "start-over" using your preferred platform.
+
+
+
+
+
+== Deploy on your own platform
+
+The programming model defined by Apache Isis deliberately minimizes the dependencies on the rest of the framework. In fact, the only hard dependency that the domain model classes have on Apache Isis is through the `org.apache.isis.applib` classes, mostly to pick up annotations such as `@Disabled`.
+So, if you have used Apache Isis for prototyping (discussed above), then note that it's quite feasible to take your domain model a the basis of your actual development effort; Apache Isis' annotations and programming conventions will help ensure that any subtle semantics you might have captured in your prototyping are not lost.
+
+If you go this route, your deployment platform will of course need to provide similar capabilities to Apache Isis.  In particular, you'll need to figure out a way to inject domain services into domain entities (eg using a JPA listener), and you'll also need to reimplement any domain services you have used that Apache Isis provides "out-of-the-box" (eg xref:rgsvc.adoc#_rgsvc-api_QueryResultsCache[`QueryResultsCache`] domain service).
+
+
+
+
+
+== Deploy the REST API
+
+REST (Representation State Transfer) is an architectural style for building highly scalable distributed systems, using the same principles as the World Wide Web. Many commercial web APIs (twitter, facebook, Amazon) are implemented as either pure REST APIs or some approximation therein.
+
+The http://restfulobjects.org[Restful Objects specification] defines a means by a domain object model can be exposed as RESTful resources using JSON representations over HTTP. Apache Isis' xref:ugvro.adoc#[RestfulObjects viewer] is an implementation of that spec, making any Apache Isis domain object automatically available via REST.
+
+There are a number of use cases for deploying Isis as a REST API, including:
+
+* to allow a custom UI to be built against the RESTful API +
++
+For example, using AngularJS or some other RIA technology such as Flex, JavaFX, Silverlight
+
+* to enable integration between systems +
++
+REST is designed to be machine-readable, and so is an excellent choice for synchronous data interchange scenarios.
+
+* as a ready-made API for migrating data from one legacy system to its replacement.
+
+
+As for the auto-generated webapps, the framework manages object persistence. It is perfectly possible to deploy the REST API alongside an auto-generated webapp; both work from the same domain object model.
+
+
+
+
+
+== Implement your own viewer
+
+Isis' architecture was always designed to support multiple viewers; and indeed Apache Isis out-of-the-box supports two: the Wicket viewer, and the Restful Objects viewer (or three, if one includes the Wrapper Factory).
+
+While we mustn't understate the effort involved here, it is feasible to implement your own viewers too.  Indeed, one of Apache Isis' committers does indeed have a (closed source) viewer, based on http://www.wavemaker.com/[Wavemaker].
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy.adoc
new file mode 100644
index 0000000..11ed9cc
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy.adoc
@@ -0,0 +1,21 @@
+[[_ugfun_core-concepts_philosophy]]
+= Philosophy and Architecture
+: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 section describes some of the core ideas and architectural patterns upon which Apache Isis builds.
+
+include::_ugfun_core-concepts_philosophy_domain-driven-design.adoc[leveloffset=+1]
+
+include::_ugfun_core-concepts_philosophy_naked-objects-pattern.adoc[leveloffset=+1]
+
+include::_ugfun_core-concepts_philosophy_hexagonal-architecture.adoc[leveloffset=+1]
+
+include::_ugfun_core-concepts_philosophy_aop.adoc[leveloffset=+1]
+
+// include::_ugfun_core-concepts_philosophy_dci.adoc[leveloffset=+1]
+
+include::_ugfun_core-concepts_philosophy_how-eases-ddd.adoc[leveloffset=+1]
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy_aop.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy_aop.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy_aop.adoc
new file mode 100644
index 0000000..a295fba
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy_aop.adoc
@@ -0,0 +1,36 @@
+[[_ugfun_core-concepts_philosophy_aop]]
+= Aspect Oriented
+: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/
+
+
+Although not a book about object modelling, Evans' "Domain Driven Design" does use object orientation as its primary modelling tool; while xref:ug.adoc#_ugfun_core-concepts_philosophy_naked-objects-pattern[naked objects pattern] very much comes from an OO background (it even has 'object' in its name); Richard Pawson lists Alan Kay as a key influence.
+
+It's certainly true that to develop an Apache Isis application you will need to have good object oriented modelling skills.  But given that all the mainstream languages for developing business systems are object oriented (Java, C#, Ruby), that's not such a stretch.
+
+However, what you'll also find as you write your applications is that in some ways an Isis application is more aspect-oriented than it is object oriented.  Given that aspect-orientation -- as a programming paradigm at least -- hasn't caught on, that statement probably needs unpacking a little.
+
+== AOP Concepts
+
+Aspect-orientation, then, is a different way of decomposing your application, by treating _cross-cutting concerns_ as a first-class citizen.  The canonical (also rather boring) example of a cross-cutting concern is that of logging (or tracing) all method calls.  An aspect can be written that will weave in some code (a logging statement) at specified points in the code).
+
+This idea sounds rather abstract, but what it really amounts to is the idea of interceptors.  When one method calls another the AOP code is called in first.  This is actually then one bit of AOP that is quite mainstream; DI containers such as Spring provide aspect orientation in supporting annotations such as `@Transactional` or `@Secured` to java beans.
+
+Another aspect (ahem!) of aspect-oriented programming has found its way into other programming languages, that of a mix-in or trait.  In languages such as Scala these mix-ins are specified statically as part of the inheritance hierarchy, whereas with AOP the binding of a trait to some other class/type is done without the class "knowing" that additional behaviour is being mixed-in to it.
+
+== Realization within Apache Isis
+
+What has all this to do with Apache Isis, then?
+
+Well, a different way to think of the naked objects pattern is that the visualization of a domain object within a UI is a cross-cutting concern.  By following certain very standard programming conventions that represent the _Apache Isis Programming Model_ (POJOs plus annotations), the framework is able to build a metamodel and from this can render your domain objects in a standard generic fashion.  That's a rather more interesting cross-cutting concern than boring old logging!
+
+Isis also draws heavily on the AOP concept of interceptors.  Whenever an object is rendered in the UI, it is filtered with respect to the user's permissions.  That is, if a user is not authorized to either view or perhaps modify an object, then this is applied transparently by the framework.  The http://github.com/isisaddons/isis-module-security[Isis addons' security] module, mentioned previously, provides a rich user/role/permissions subdomain to use out of the box; but you can integrate with a different security mechanism if you have one already.
+
+Another example of interceptors are the http://github.com/isisaddons/isis-module-command[Isis addons' command] and http://github.com/isisaddons/isis-module-audit[Isis addons' audit] modules.  The command module captures every user interaction that modifies the state of the system (the "cause" of a change) while the audit module captures every change to every object (the "effect" of a change).  Again, this is all transparent to the user.
+
+Apache Isis also has an internal event bus (you can switch between an underlying implementation of Gauva or Axon).  A domain event is fired whenever an object is interacted with, and this allows any subscribers to influence the operation (or even veto it).  This is a key mechanism in ensuring that Isis applications are maintainable, and we discuss it in depth in the section on  xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling[Decoupling].  But fundamentally its relying on this AOP concept of interceptors.
+
+Finally, Isis also a feature that is akin to AOP mix-ins.  A "contributed action" is one that is implemented on a domain service but that appears to be a behaviour of rendered domain object.  In other words, we can dissociate behaviour from data.  That's not always the right thing to do of course.  In Richard Pawson's description of the xref:ug.adoc#_ugfun_core-concepts_philosophy_naked-objects-pattern[naked objects pattern] he talks about "behaviourally rich" objects, in other words where the business functionality encapsulated the data.   But on the other hand sometimes the behaviour and data structures change at different rates.  The link:http://en.wikipedia.org/wiki/Single_responsibility_principle[single responsibility principle] says we should only lump code together that changes at the same rate.  Apache Isis' support for contributions (not only contributed actions, but also contributed properties and contributed collections) enables this.  And again, to loop back to the topic
  of this section, it's an AOP concept that being implemented by the framework.
+
+The nice thing about aspect orientation is that for the most part you can ignore these cross-cutting concerns and - at least initially at least - just focus on implementing your domain object.  Later when your app starts to grow and you start to break it out into smaller modules, you can leverage Apache Isis' AOP support for (xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling_mixins[mixins]), (xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling_contributions[contributions]) and interceptors (the xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling_event-bus[event bus]) to ensure that your codebase remains maintainable.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy_dci.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy_dci.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy_dci.adoc
new file mode 100644
index 0000000..d70f173
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy_dci.adoc
@@ -0,0 +1,9 @@
+[[_ugfun_core-concepts_philosophy_dci]]
+= DCI
+: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/
+
+
+NOTE: TODO ... Trygve Reenskaug
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy_domain-driven-design.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy_domain-driven-design.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy_domain-driven-design.adoc
new file mode 100644
index 0000000..a2b2a36
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy_domain-driven-design.adoc
@@ -0,0 +1,79 @@
+[[_ugfun_core-concepts_philosophy_domain-driven-design]]
+= Domain-Driven Design
+: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/
+
+There's no doubt that we developers love the challenge of understanding and deploying complex technologies. But understanding the nuances and subtleties of the business domain itself is just as great a challenge, perhaps more so. If we devoted our efforts to understanding and addressing those subtleties, we could build better, cleaner, and more maintainable software that did a better job for our stakeholders. And there's no doubt that our stakeholders would thank us for it.
+
+A couple of years back Eric Evans wrote his book link:http://www.amazon.co.uk/Domain-driven-Design-Tackling-Complexity-Software/dp/0321125215[Domain-Driven Design], which is well on its way to becoming a seminal work. In fact, most if not all of the ideas in Evans' book have been expressed before, but what he did was pull those ideas together to show how predominantly object-oriented techniques can be used to develop rich, deep, insightful, and ultimately useful business applications.
+
+There are two central ideas at the heart of domain-driven design.
+
+* the *_ubiquitous language_* is about getting the whole team (both domain experts and developers) to communicate more transparently using a domain model.
+
+* Meanwhile, *_model-driven design_* is about capturing that model in a very straightforward manner in code.
+
+Let's look at each in turn.
+
+[[_ugfun_core-concepts_philosophy_domain-driven-design_ubiquitous-language]]
+== Ubiquitous Language
+
+It's no secret that the IT industry is plagued by project failures. Too often systems take longer than intended to implement, and when finally implemented, they don't address the real requirements anyway.
+
+Over the years we in IT have tried various approaches to address this failing. Using waterfall methodologies, we've asked for requirements to be fully and precisely written down before starting on anything else. Or, using agile methodologies, we've realized that requirements are likely to change anyway and have sought to deliver systems incrementally using feedback loops to refine the implementation.
+
+But let's not get distracted talking about methodologies. At the end of the day what really matters is communication between the domain experts (that is, the business) who need the system and the techies actually implementing it. If the two don't have and cannot evolve a shared understanding of what is required, then the chance of delivering a useful system will be next to nothing.
+
+Bridging this gap is traditionally what business analysts are for; they act as interpreters between the domain experts and the developers. However, this still means there are two (or more) languages in use, making it difficult to verify that the system being built is correct. If the analyst mistranslates a requirement, then neither the domain expert nor the application developer will discover this until (at best) the application is first demonstrated or (much worse) an end user sounds the alarm once the application has been deployed into production.
+
+Rather than trying to translate between a business language and a technical language, with  _DDD_ we aim to have the business and developers using the same terms for the same concepts in order to create a single *_domain model_*. This domain model identifies the relevant concepts of the domain, how they relate, and ultimately where the responsibilities are. This single domain model provides the vocabulary for the  ubiquitous language for our system.
+
+
+.Ubiquitous Language
+****
+Build a common language between the domain experts and developers by using the concepts of the domain model as the primary means of communication. Use the terms in speech, in diagrams, in writing, and when presenting.
+
+If an idea cannot be expressed using this set of concepts, then go back and extend the model. Look for and remove ambiguities and inconsistencies.
+****
+
+
+Creating a  ubiquitous language calls upon everyone involved in the system's development to express what they are doing through the vocabulary provided by the model. If this can't be done, then our model is incomplete. Finding the missing words deepens our understanding of the domain being modeled.
+
+This might sound like nothing more than me insisting that the developers shouldn't use jargon when talking to the business. Well, that's true enough, but it's not a one-way street. A  *ubiquitous language* demands that the developers work hard to understand the problem domain, but it also demands that the business works hard in being  *precise* in its naming and descriptions of those concepts. After all, ultimately the developers will have to express those concepts in a computer programming language.
+
+Also, although here I'm talking about the "domain experts" as being a homogeneous group of people, often they may come from different branches of the business. Even if we weren't building a computer system, there's a lot of value in helping the domain experts standardize their own terminology. Is the marketing department's "prospect" the same as sales' "customer," and is that the same as an after-sales "contract"?
+
+The need for precision within the  ubiquitous language also helps us scope the system. Most business processes evolve piecemeal and are often quite ill-defined. If the domain experts have a very good idea of what the business process should be, then that's a good candidate for automation, that is, including it in the scope of the system. But if the domain experts find it hard to agree, then it's probably best to leave it out. After all, human beings are rather more capable of dealing with fuzzy situations than computers.
+
+So, if the development team (business and developers together) continually searches to build their  ubiquitous language, then the domain model naturally becomes richer as the nuances of the domain are uncovered. At the same time, the knowledge of the business domain experts also deepens as edge conditions and contradictions that have previously been overlooked are explored.
+
+We use the  ubiquitous language to build up a domain model. But what do we do  *with* that model? The answer to that is the second of our central ideas.
+
+
+== Model-Driven Design
+
+Of the various methodologies that the IT industry has tried, many advocate the production of separate analysis models and implementation models. One example (from the mid 2000s) was that of the  _OMG_'s Model-Driven Architecture ( _MDA_) initiative, with its platform-independent model (the  _PIM_) and a platform-specific model (the  _PSM_).
+
+Bah and humbug! If we use our  ubiquitous language just to build up a high-level analysis model, then we will re-create the communication divide. The domain experts and business analysts will look only to the analysis model, and the developers will look only to the implementation model. Unless the mapping between the two is completely mechanical, inevitably the two will diverge.
+
+What do we mean by  *model* anyway? For some, the term will bring to mind  UML class or sequence diagrams and the like. But this isn't a model; it's a visual  *representation* of some aspect of a model. No, a domain model is a group of related concepts, identifying them, naming them, and defining how they relate. What is in the model depends on what our objective is. We're not looking to simply model everything that's out there in the real world. Instead, we want to take a relevant abstraction or simplification of it and then make it do something useful for us.  A model is neither right nor wrong, just more or less useful.
+
+For our  ubiquitous language to have value, the domain model that encodes it must have a straightforward, literal representation to the design of the software, specifically to the implementation. Our software's design should be driven by this model; we should have a model-driven design.
+
+
+.Model-Driven Design
+****
+There must be a straightforward and very literal way to represent the domain model in terms of software. The model should balance these two requirements: form the  ubiquitous language of the development team and be representable in code.
+
+Changing the code means changing the model; refining the model requires a change to the code.
+****
+
+
+Here also the word  *design* might mislead; some might be thinking of design documents and design diagrams, or perhaps of user interface (UX) design. But by  *design* we mean a way of organizing the domain concepts, which in turn leads to the way in which we organize their representation in code.
+
+Luckily, using *_object-oriented_* (_OO_) languages such as Java, this is relatively easy to do;  _OO_ is based on a modeling paradigm anyway. We can express domain concepts using classes and interfaces, and we can express the relationships between those concepts using associations.
+
+So far so good. Or maybe, so far so much motherhood and apple pie. Understanding the  _DDD_ concepts isn't the same as being able to apply them, and some of the  _DDD_ ideas can be difficult to put into practice. Time to discuss the naked objects pattern and how it eases that path by applying these central ideas of _DDD_ in a very concrete way.
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy_hexagonal-architecture.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy_hexagonal-architecture.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy_hexagonal-architecture.adoc
new file mode 100644
index 0000000..3ec1c6f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy_hexagonal-architecture.adoc
@@ -0,0 +1,29 @@
+[[_ugfun_core-concepts_philosophy_hexagonal-architecture]]
+= Hexagonal Architecture
+: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/
+
+One of the patterns that Evans discusses in his book is that of a *layered architecture*.  In it he describes why the domain model lives in its own layer within the architecture. The other layers of the application (usually presentation, application, and persistence) have their own responsibilities, and are completely separate.  Each layer is cohesive and depending only on the layers below.  In particular, we have a layer dedicated to the domain model. The code in this layer is unencumbered with the (mostly technical) responsibilities of the other layers and so can evolve to tackle complex domains as well as simple ones.
+
+This is a well-established pattern, almost a de-facto; there's very little debate that these responsibilities should be kept separate from each other.  With Apache Isis the responsibility for presentation is a framework concern, the responsibility for the domain logic is implemented by the (your) application code.
+
+A few years ago Alistair Cockburn reworked the traditional layered architecture diagram and came up with the *_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.
+====
+
+.The hexagonal architecture emphasizes multiple implementations of the different layers.
+image::{_imagesdir}core-concepts/philosophy/hexagonal-architecture.png[width="700px"]
+
+What Cockburn is emphasizing is that there's usually more than one way *into* an application (what he called the *_user-side' ports_*) and more than one way  *out of* an application too (the *_data-side ports_*). This is very similar to the concept of primary and secondary actors in use cases: a primary actor (often a human user but not always) is active and initiates an interaction, while a secondary actor (almost always an external system) is passive and waits to be interacted with.
+
+Associated with each port can be an *_adapter_* (in fact, Cockburn's alternative name for this architecture is *_ports and adapters_*). An adapter is a device (piece of software) that talks in the protocol (or  _API_) of the port. Each port could have several adapters.
+
+Apache Isis maps very nicely onto the  *hexagonal architecture*.  Apache Isis' viewers act as user-side adapters and use the Apache Isis metamodel API as a port into the domain objects.   For the data side, we are mostly concerned with persisting domain objects to some sort of object store.  Here Apache Isis delegates most of the heavy lifting to ORM implementing the JDO API.  Most of the time this will be DataNucleus configured to persist to an RDBMS, but DataNucleus can also support other object stores, for example Neo4J.  Alternatively Apache Isis can be configured to persist using some other JDO implementation, for example Google App Engine.
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy_how-eases-ddd.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy_how-eases-ddd.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy_how-eases-ddd.adoc
new file mode 100644
index 0000000..1c42f71
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy_how-eases-ddd.adoc
@@ -0,0 +1,74 @@
+[[_ugfun_core-concepts_philosophy_how-eases-ddd]]
+= How Apache Isis eases DDD
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The case for  _DDD_ might be compelling, but that doesn't necessarily make it easy to do. Let's take a look at some of the
+challenges that  _DDD_ throws up and see how Apache Isis (and its implementation of the naked objects pattern) helps address them.
+
+== DDD takes a conscious effort
+
+Here's what Eric Evans says about ubiquitous language:
+
+pass:[<div class="extended-quote-first"><p>]With a conscious effort by the [development] team the domain model can provide the backbone for [the] common [ubiquitous] language...connecting team communication to the software implementation."
+pass:[</p></div>]
+
+pass:[<div class="extended-quote-attribution"><p>]-- Eric Evans
+pass:[</p></div>]
+
+The word to pick up on here is *conscious*.  It takes a conscious effort by the entire team to develop the ubiquitous language. Everyone in the team must challenge the use of new or unfamiliar terms, must clarify concepts when used in a new context, and in general must be on the lookout for sloppy thinking. This takes willingness on the part of all involved, not to mention some practice.
+
+With Apache Isis, though, the  ubiquitous language evolves with scarcely any effort at all. For the business experts, the Apache Isis viewers show the domain concepts they identify and the relationships between those concepts in a straightforward fashion. Meanwhile, the developers can devote themselves to encoding those domain concepts directly as domain classes. There's no technology to get distracted by; there is literally nothing else for the developers to work on.
+
+
+== DDD must be grounded
+
+Employing a  model-driven design isn't necessarily straightforward, and the development processes used by some organizations positively hinder it. It's not sufficient for the business analysts or architects to come up with some idealized representation of the business domain and then chuck it over the wall for the programmers to do their best with.
+
+Instead, the concepts in the model must have a very literal representation in code. If we fail to do this, then we open up the communication divide, and our  ubiquitous language is lost. There is literally no point having a domain model that cannot be represented in code. We cannot invent our ubiquitous language in a vacuum, and the developers must ensure that the model remains grounded in the doable.
+
+In Apache Isis, we have a very pure one-to-one correspondence between the domain concepts and its implementation. Domain concepts are represented as classes and interfaces, easily demonstrated back to the business. If the model is clumsy, then the application will be clumsy too, and so the team can work together to find a better implementable model.
+
+
+
+== Model must be understandable
+
+If we are using code as the primary means of expressing the model, then we need to find a way to make this model understandable to the business.
+
+We could generate UML diagrams and the like from code. That will work for some members of the business community, but not for everyone. Or we could generate a PDF document from Javadoc comments, but comments aren't code and so the document may be inaccurate.  Anyway, even if we do create such a document, not everyone will read it.
+
+A better way to represent the model is to show it in action as a working prototype. As we show in the xref:ug.adoc#_ugfun_getting-started[Getting Started] section, Apache Isis enables this with ease. Such prototypes bring the domain model to life, engaging the audience in a way that a piece of paper never can.
+
+Moreover, with Apache Isis prototypes, the domain model will come shining through. If there are mistakes or misunderstandings in the domain model (inevitable when building any complex system), they will be obvious to all.
+
+
+
+
+== Architecture must be robust
+
+_DDD_ rightly requires that the domain model lives in its own layer within the architecture. The other layers of the application (usually presentation, application, and persistence) have their own responsibilities, and are completely separate.
+
+However, there are two immediate issues. The first is rather obvious: custom coding each of those other layers is an expensive proposition. Picking up on the previous point, this in itself can put the kibosh on using prototyping to represent the model, even if we wanted to do so.
+
+The second issue is more subtle. It takes real skill to ensure the correct separation of concerns between these layers, if indeed you can get an agreement as to what those concerns actually are. Even with the best intentions, it's all too easy for custom-written layers to blur the boundaries and put (for example) validation in the user interface layer when it should belong to the domain layer. At the other extreme, it's quite possible for custom layers to distort or completely subvert the underlying domain model.
+
+Because of Apache Isis' generic  __OOUI__s, there's no need to write the other layers of the architecture.  Of course, this reduces the development cost. But more than that, there will be no leakage of concerns outside the domain model. All the validation logic *must* be in the domain model because there is nowhere else to put it.
+
+Moreover, although Apache Isis does provide a complete runtime framework, there is no direct coupling of your domain model to the framework. That means it is very possible to take your domain model prototyped in Naked Objects and then deploy it on some other  _J(2)EE_ architecture, with a custom _UI_ if you want.  Apache Isis guarantees that your domain model is complete.
+
+
+
+
+== Extending the reach of DDD
+
+Domain-driven design is often positioned as  being applicable only to complex domains; indeed, the subtitle of Evans book is  "Tackling Complexity in the Heart of Software". The corollary is that DDD is overkill for simpler domains. The trouble is that we immediately have to make a choice: is the domain complex enough to warrant a domain-driven approach?
+
+This goes back to the previous point, building and maintaining a layered architecture. It doesn't seem cost effective to go to all the effort of a DDD approach if the underlying domain is simple.
+
+However, with Apache Isis, we don't write these other layers, so we don't have to make a call on how complex our domain is. We can start working solely on our domain, even if we suspect it will be simple. If it is indeed a simple domain, then there's no hardship, but if unexpected subtleties arise, then we're in a good position to handle them.
+
+If you're just starting out writing domain-driven applications, then Apache Isis should significantly ease your journey into applying _DDD_. On the other hand, if you've used _DDD_ for a while, then you should find Isis a very useful new tool in your arsenal.
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy_naked-objects-pattern.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy_naked-objects-pattern.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy_naked-objects-pattern.adoc
new file mode 100644
index 0000000..fbe13f1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy_naked-objects-pattern.adoc
@@ -0,0 +1,60 @@
+[[_ugfun_core-concepts_philosophy_naked-objects-pattern]]
+= Naked Objects Pattern
+: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 implements the naked objects pattern, originally formulated by Richard Pawson.  So who better than Richard to explain the origination of the idea?
+
+pass:[<div class="extended-quote-first"><p>]The Naked Objects pattern arose, at least in part, from my own frustration at the lack of success of the domain-driven approach. Good examples were hard to find--as they are still.
+pass:[</p></div>]
+
+pass:[<div class="extended-quote"><p>]A common complaint from _DDD_ practitioners was that it was hard to gain enough commitment from business stakeholders, or even to engage them at all. My own experience suggested that it was nearly impossible to engage business managers with UML diagrams.  It was much easier to engage them in rapid prototyping -- where they could see and interact with the results -- but most forms of rapid prototyping concentrate on the presentation layer, often at the expense of the underlying model and certainly at the expense of abstract thinking.
+pass:[</p></div>]
+
+pass:[<div class="extended-quote"><p>]Even if you could engage the business sponsors sufficiently to design a domain model, by the time you'd finished developing the system on top of the domain model, most of its benefits had disappeared. It's all very well creating an agile domain object model, but if any change to that model also dictates the modification of one or more layers underneath it (dealing with persistence) and multiple layers on top (dealing with presentation), then that agility is practically worthless.
+pass:[</p></div>]
+
+pass:[<div class="extended-quote"><p>]The other concern that gave rise to the birth of Naked Objects was how to make user interfaces of mainstream business systems more "expressive" -- how to make them feel more like using a drawing program or _CAD_ system. Most business systems are not at all expressive; they treat the user merely as a dumb *process-follower*, rather than as an empowered *problem-solver*.  Even the so-called usability experts had little to say on the subject: try finding the word "empowerment" or any synonym thereof in the index of any book on usability. Research had demonstrated that the best way to achieve expressiveness was to create an object-oriented user interface (_OOUI_). In practice, though, __OOUI__s were notoriously hard to develop.
+pass:[</p></div>]
+
+pass:[<div class="extended-quote"><p>]Sometime in the late 1990s, it dawned on me that if the domain model really did represent the "ubiquitous language" of the business and those domain objects were behaviorally rich (that is, business logic is encapsulated as methods on the domain objects rather than in procedural scripts on top of them), then the _UI_ could be nothing more than a reflection of the user interface. This would solve both of my concerns. It would make it easier to do domain-driven design, because one could instantly translate evolving domain modeling ideas into a working prototype. And it would deliver an expressive, object-oriented user interface for free. Thus was born the idea of Naked Objects.
+pass:[</p></div>]
+
+pass:[<div class="extended-quote-attribution"><p>]-- Richard Pawson
+pass:[</p></div>]
+
+You can learn much more about the pattern in the book, link:http://www.amazon.com/exec/obidos/ISBN=0470844205/[Naked Objects], also freely available to link:http://www.nakedobjects.org/book/[read online].  Richard co-wrote the book with one of Apache Isis' committers, Robert Matthews, who was in turn the author of the Naked Objects Framework for Java (the original codebase of of Apache Isis).
+
+You might also want to read Richard's link:resources/core-concepts/Pawson-Naked-Objects-thesis.pdf[PhD on the subject].
+
+
+[TIP]
+====
+One of the external examiners for Richard's PhD was link:http://en.wikipedia.org/wiki/Trygve_Reenskaug[Trygve Reenskaug], who originally formulated the MVC pattern at Xeroc PARC.  In his paper, link:http://heim.ifi.uio.no/~trygver/2007/2007.02.13-babyUML.pdf[Baby UML], Reenskaug describes that when implemented the first MVC, "the conventional wisdom in the group was that objects should be visible and tangible, thus bridging the gap between the human brain and the abstract data within the computer."  Sound familiar?  It's interesting to speculate what might have been if this idea had been implemented back then in the late 70s.
+
+Reenskaug then goes on to say that "this simple and powerful idea failed because ... users were used to seeing [objects] from different perspectives. The visible and tangible object would get very complex if it should be able to show itself and be manipulated in many different ways."
+
+In Apache Isis the responsibility of rendering an object is not the object itself, it is the framework.  Rather, the object inspects the object and uses that to decide how to render the object.  This is also extensible.  In the link:http://www.isisaddons.org[Isis Addons] (non-ASF) the http://github.com/isisaddons/isis-wicket-gmap3[Isis addons' gmap3] wicket extension renders any object with latitude/longitude on a map, while http://github.com/isisaddons/isis-wicket-fullcalendar2[Isis addons' fullcalendar2 wicket extension] renders any object with date(s) on a calendar.
+====
+
+
+
+include::_ugfun_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping.adoc[leveloffset=+1]
+
+
+
+
+== What this means in practice
+
+The screencast below shows what all of this means in practice, showing the relationship between a running app and the actual code underneath.
+
+.How Apache Isis builds a webapp from the underlying domain object model…
+video::ludOLyi6VyY[youtube,width="640px",height="472px"]
+
+[NOTE]
+====
+This screencast shows Apache Isis v1.0.0, Jan 2013.  The UI has been substantially refined since that release.
+====
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping.adoc
new file mode 100644
index 0000000..df40264
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping.adoc
@@ -0,0 +1,18 @@
+[[_ugfun_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping]]
+= Object Interface Mapping
+: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/
+
+
+Another -- more technical -- way to think about the naked objects pattern is as an _object interface mapper_, or `OIM`.  We sometimes use this idea to explain naked objects to a bunch of developers.
+
+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 the naked objects pattern as representing the concept of mapping domain objects to a user interface.
+
+This is the way that the link:http://metawidget.org/[MetaWidget] team, in particular Richard Kennard, the primary contributor, likes to describe their tool.  MetaWidget has a number of ideas in common with Apache Isis, specifically the runtime generation of a UI for domain objects.  You can hear more from Kennard and others on this http://devchat.tv/js-jabber/150-jsj-oims[Javascript Jabber podcast].
+
+[NOTE]
+====
+We compare Apache Isis' with MetaWidget xref:ug.adoc#_ugfun_core-concepts_principles_apache-isis-vs_metawidget[here].
+====
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_principles.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_principles.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_principles.adoc
new file mode 100644
index 0000000..6e17dbe
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_principles.adoc
@@ -0,0 +1,16 @@
+[[_ugfun_core-concepts_principles]]
+= Principles and Values
+: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 section describes some of the core principles and values that the framework aims to honour and support.
+
+The first of these relate to how we believe your domain application should be written: it should be decoupled, testable and so on).  Others relate to the implementation of the framework itself.
+
+The section concludes by contrasting the framework with some other open source frameworks commonly used.
+
+include::_ugfun_core-concepts_principles_your-apps.adoc[leveloffset=+1]
+include::_ugfun_core-concepts_principles_isis-itself.adoc[leveloffset=+1]
+include::_ugfun_core-concepts_principles_apache-isis-vs.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_principles_apache-isis-vs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_principles_apache-isis-vs.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_principles_apache-isis-vs.adoc
new file mode 100644
index 0000000..b70b4ca
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_principles_apache-isis-vs.adoc
@@ -0,0 +1,16 @@
+[[_ugfun_core-concepts_principles_apache-isis-vs]]
+= 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/
+
+Many other frameworks promise rapid application development and provide automatically generated user interfaces, so how
+do they compare to Apache Isis?
+
+
+include::_ugfun_core-concepts_principles_apache-isis-vs_mvc-server-side-frameworks.adoc[leveloffset=+1]
+include::_ugfun_core-concepts_principles_apache-isis-vs_cqrs.adoc[leveloffset=+1]
+include::_ugfun_core-concepts_principles_apache-isis-vs_event-sourcing.adoc[leveloffset=+1]
+include::_ugfun_core-concepts_principles_apache-isis-vs_metawidget.adoc[leveloffset=+1]
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_principles_apache-isis-vs_cqrs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_principles_apache-isis-vs_cqrs.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_principles_apache-isis-vs_cqrs.adoc
new file mode 100644
index 0000000..08a7d31
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_principles_apache-isis-vs_cqrs.adoc
@@ -0,0 +1,28 @@
+[[_ugfun_core-concepts_principles_apache-isis-vs_cqrs]]
+= vs CQRS
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+The CQRS architectural pattern (it stands for "Command Query Responsbility Separation") is the idea that the domain objects that mutate the state of the system - to which commands are sent and which then execute - should be separated from the mechanism by which the state of the system is queried (rendered).  The former are sometimes called the "write (domain) model", the latter the "read model".
+
+In the canonical version of this pattern there are separate datastores.  The commands act upon a command/write datastore.  The data in this datastore is then replicated in some way to the query/read datastore, usually denormalized or otherwise such that it is easy to query.  CQRS advocates recommend using very simple (almost naive) technology for the query/read model; it should be a simple projection of the query datastore.  Complexity instead lives elsewhere: business logic in the command/write model, and in the transformation logic betweeen the command/write and read/query datastores.  In particular, there is no requirement for the two datastores to use the same technology: one might be an RDBMS while the other a NoSQL datastore or even datawarehouse.
+
+In most implementations the command and query datastores are _not_ updated in the same transaction; instead there is some sort of replication mechanism.  This also means that the query datastore is eventually consistent rather than always consistent; there could be a lag of a few seconds before it is updated.  This means in turn that CQRS implementations require mechanisms to cater for offline query datastores; usually some sort of event bus.
+
+The CQRS architecture's extreme separation of responsibilities can result in a lot of boilerplate.  Any given domain concept, eg `Customer`, must be represented both in the command/write model and also in the query/read model.  Each business operation upon the command model is reified as a command object, for example `PlaceOrderCommand`.
+
+Comparing CQRS to Apache Isis, the most obvious difference is that Apache Isis does not separate out a command/write model from a query/read model, and there is usually just a single datastore.  But then again, having a separate read model just so that the querying is very straightforward is pointless with Apache Isis because, of course, Isis provides the UI "for free".
+
+There are other reasons though why a separate read model might make sense, such as to precompute particular queries, or against denormalized data.  In these cases Apache Isis can often provide a reasonable alternative, namely to map domain entities against RDBMS views, either materialized views or dynamic.  In such cases there is still only a single physical datastore, and so transactional integrity is retained.
+
+Or, the CQRS architecture can be more fully implemented with Apache Isis by introducing a separate read model, synchronized using the xref:rgsvc.adoc#_rgsvc-api_PublishingService[`PublishingService`], or using xref:rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscribers]  on the xref:rgsvc.adoc#_rgsvc-api_EventBusService[`EventBusService`].  One can then use xref:ugbtb.adoc#_ugbtb_more-advanced_view-models[view models] to surface the data in the external read datastore.
+
+With respect to commands, Apache Isis does of course support the xref:rgsvc.adoc#_rgsvc-spi_CommandService[`CommandService`] which allows each business action to be reified into a `Command`.  However, names are misleading here: Apache Isis' commands are relatively passive, merely recording the intent of the user to invoke some operation.  In a CQRS architecture, though, commands take a more active role, locating and acting upon the domain objects.  More significantly, in CQRS each command has its own class, such as `PlaceOrderCommand`, instantiated by the client and then executed.  With Apache Isis, though, the end-user merely invokes the `placeOrder(...)` action upon the domain object; the framework itself creates the `Command` as a side-effect of this.
+
+In CQRS the commands correspond to the business logic that mutates the system.  Whether this logic is part of the command class (`PlaceOrderCommand`) or whether that command delegates to methods on the domain object is an implementation detail; but it certainly is common for the business logic to be wholly within the command object and for the domain object to be merely a data holder of the data within the command/write datastore.
+
+In Apache Isis this same separation of business logic from the underlying data can be accomplished most straightforwardly using xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling_mixins[mixins] or xref:ug.adoc#_ugfun_how-tos_contributed-members[contributions].  In the UI (surfaced by the xref:ugvw.adoc#[Wicket viewer]) or in the REST API (surfaced by the xref:ugvro.adoc#[RestfulObjects viewer]) the behaviour appears to reside on the domain object; however the behaviour actually resides on separate classes and is mixed in (like a trait) only at runtime.
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_principles_apache-isis-vs_event-sourcing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_principles_apache-isis-vs_event-sourcing.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_principles_apache-isis-vs_event-sourcing.adoc
new file mode 100644
index 0000000..1d392ae
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_principles_apache-isis-vs_event-sourcing.adoc
@@ -0,0 +1,19 @@
+[[_ugfun_core-concepts_principles_apache-isis-vs_event-sourcing]]
+= vs Event Sourcing
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The link:_ugfun_core-concepts_principles_apache-isis-vs_cqrs[CQRS architecture], discussed above, is often combined with _Event Sourcing_ pattern, though they are separate ideas.
+
+With event sourcing, each business operation emits a domain event (or possibly events) that allow other objects in the system to act accordingly.  For example, if a customer places an order then this might emit the `OrderPlacedEvent`.  Most significantly, the subscribers to these events can include the datastore itself; the state of the system is in effect a transaction log of every event that has occurred since "the beginning of time": it is sometimes called an event store.   With CQRS, this event datastore corresponds to the command/write datastore (the query/read datastore is of course derived from the command datastore).
+
+Although it might seem counter-intuitive to be able store persistent state in this way (as a souped up "transaction log"), the reality is that with modern compute capabilities make it quite feasible to replay many 10s/100s of thousands of events in a second.  And the architecture supports some interesting use cases; for example it becomes quite trivial to rewind the system back to some previous point in time.
+
+When combined with CQRS we see a command that triggers a business operation, and an event that results from it.  So, a `PlaceOrderCommand` command can result in an `OrderPlacedEvent` event.  A subscriber to this event might then generate a further command to act upon some other system (eg to dispatch the system).  Note that the event might be dispatched and consumed in-process or alternatively this might occur out-of-process.  If the latter, then the subscriber will operate within a separate transaction, meaning the usual eventual consistency concerns and also compensating actions if a rollback is required.  CQRS/event sourcing advocates point out - correctly  that this is just how things are in the "real world" too.
+
+In Apache Isis every business action (and indeed, property and collection) emits domain events through the xref:rgsvc.adoc#_rgsvc-api_EventBusService[`EventBusService`] , and can optionally also be published through the xref:rgsvc.adoc#_rgsvc-spi_PublishingService[`PublishingService`].  The former are dispatched and consumed in-process and within the same transaction, and for this reason the xref:rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscribers] can also veto the events.  The latter are intended for out-of-process consumption; the (non-ASF) http://github.com/isisaddons/isis-module-publishing[Isis addons' publishing] and http://github.com/isisaddons/isis-module-publishmq[Isis addons' publishmq] modules provide implementations for dispatching either through a RDBMS database table, or directly through to an link:http://camel.apache.org[ActiveMQ] message queue (eg wired up to link:http://camel.apache.org[Apache Camel] event bus).
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_principles_apache-isis-vs_metawidget.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_principles_apache-isis-vs_metawidget.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_principles_apache-isis-vs_metawidget.adoc
new file mode 100644
index 0000000..67b02d3
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_principles_apache-isis-vs_metawidget.adoc
@@ -0,0 +1,16 @@
+[[_ugfun_core-concepts_principles_apache-isis-vs_metawidget]]
+= vs MetaWidget
+: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/
+
+
+MetaWidget (mentioned xref:ug.adoc#_ugfun_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping[earlier] has a number of ideas in common with Apache Isis, specifically the runtime generation of a UI for domain objects.  And like Apache Isis, MetaWidget builds its own metamodel of the domain objects and uses this to render the object.
+
+However, there is a difference in philosophy in that MW is not a full-stack framework and does not (in their words) try to "own the UI".  Rather they support a huge variety of UI technologies and allow the domain object to be rendered in any of them.
+
+In contrast, Apache Isis is full-stack and does generate a complete UI; we then allow you to customize or extend this UI (as per the various link:http://www.isisaddons.org[Isis Addons] (non-ASF), and we also provide a full REST API through the xref:ugvro.adoc#[Restful Objects viewer]
+
+Also, it's worth noting that MetaWidget does have an elegant pipeline architecture, with APIs to allow even its metamodel to be replaced.  It would be feasible and probably quite straightforward to use Apache Isis' own metamodel as an implementation of the MetaWidget API.  This would allow MetaWidget to be able to render an Apache Isis domain application.
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_principles_apache-isis-vs_mvc-server-side-frameworks.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_principles_apache-isis-vs_mvc-server-side-frameworks.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_principles_apache-isis-vs_mvc-server-side-frameworks.adoc
new file mode 100644
index 0000000..da53fa8
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_principles_apache-isis-vs_mvc-server-side-frameworks.adoc
@@ -0,0 +1,19 @@
+[[_ugfun_core-concepts_principles_apache-isis-vs_mvc-server-side-frameworks]]
+= vs MVC server-side frameworks
+: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/
+
+
+
+Some of most commonly used frameworks today are link:http://www.spring.io/[Spring MVC], link:http://rubyonrails.org/[Ruby on Rails] and link:http://www.grails.org[Grails], all of which implement one flavour or another of the server-side MVC pattern.  The MVC 1.0 specification (scheduled for JavaEE 8) is also similar.
+
+These frameworks all use the classic  *model-view-controller* ( _MVC_) pattern for web applications, with scaffolding, code-generation, and/or metaprogramming tools for the controllers and views, as well as convention over configuration to define how these components interact.  The views provided out of the box by these frameworks tend to be simple  _CRUD_-style interfaces. More sophisticated behavior is accomplished by customizing the generated controllers.
+
+The most obvious difference when developing an Apache Isis application is its deliberate lack of an explicit controller layer; non- _CRUD_ behavior is automatically made available in its generic object-oriented  _UI_s.  More sophisticated UIs can be built either by xref:ugvw.adoc#_ugvw_extending[extending Apache Isis' Wicket viewer] or by writing a bespoke UI leveraging the REST (hypermedia) API automatically exposed by xref:ugvro.adoc#[Isis' Restful Objects viewer].  Other frameworks can also be used to implement REST APIs, of course, but generally they require a significant amount of development to get anywhere near the level of sophistication provided automatically by Apache Isis' REST API.
+
+Although these frameworks all provide their own ecosystems of extensions, Apache Isis' equivalent link:http://www.isisaddons.org[Isis Addons] (non-ASF) tend to work at a higher-level of abstraction.  For example, each of these frameworks will integrate with various security mechanism, but the http://github.com/isisaddons/isis-module-security[Isis addons' security module] provides a full subdomain of users, roles, features and permissions that can be plugged into any Isis application.  Similarly, the http://github.com/isisaddons/isis-module-command[Isis addons' command] and http://github.com/isisaddons/isis-module-audit[Isis addons' audit] modules in combination provide a support for auditing and traceability that can also be used for out of the box profiling.  Again, these addons can be plugged into any Isis app.
+
+In terms of testing support, each of these other frameworks provide mechanisms to allow the webapp to be tested from within a JUnit test harness. Apache Isis' support is similar.  Where Apache Isis differs though is that it enables end-to-end testing without the need for slow and fragile Selenium tests. Instead, Apache Isis provides a "xref:ugtst.adoc#_ugtst_integ-test-support_wrapper-factory[WrapperFactory]" domain service that allows the generic UI provided to in essence be simulated. On a more pragmatic level, the http://github.com/isisaddons/isis-module-fakedata[Isis addons' fakedata] module does "what it says on the tin", allowing both unit- and integration-tests to focus on the salient data and fake out the rest.
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_principles_isis-itself.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_principles_isis-itself.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_principles_isis-itself.adoc
new file mode 100644
index 0000000..8c2ec14
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_principles_isis-itself.adoc
@@ -0,0 +1,47 @@
+[[_ugfun_core-concepts_principles_isis-itself]]
+= Apache Isis itself
+: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 section discusses some of the principles and values we apply to the development of the Apache Isis framework itself.
+
+== Full-stack but Extensible
+
+NOTE: TODO
+
+
+== Focuses on its USP
+
+NOTE: TODO
+
+
+add-ons
+
+* Apache 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
+
+
+
+... all code has legacy in it.... parts of the Isis codebase are well over a decade old; and back then a lot of the JEE technologies that we'd like to be using just didn't exist, so we had to invent the features we required ourselves.
+
+... also, Apache Isis today is more pragmatic than previously
+* a client/server solution, with AWT-based client
+* a HTML browser, Scimpi (JSF-like, but not using JSF), ...
+* security
+* objectstores
+
+We're working hard to remove duplication, reuse existing open source/JEE, and simplify.
+
+
+The areas of Apache Isis we consider mature are those that have been developed in support of real-world applications implemented by the committers.  Foremost among these is Estatio.
+
+
+Focus on enterprise / line-of-business applications, for use by internal staff.
+
+* problem solvers, not process followers
+
+* view models
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_principles_your-apps.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_principles_your-apps.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_principles_your-apps.adoc
new file mode 100644
index 0000000..82da9b0
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_principles_your-apps.adoc
@@ -0,0 +1,39 @@
+[[_ugfun_core-concepts_principles_your-apps]]
+= Your Applications
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+Apache Isis is primarily aimed at custom-built "enterprise" applications.  The UI exposed by the xref:ugvw.adoc#[Wicket viewer] is intended to be usable by domain experts, typically end-users within the organization.  The REST API exposed by the xref:ugvro.adoc#[RestfulObjects viewer] allows custom apps to be developed - eg using AngularJS or similar - for use by those requiring more guidance; typically end-users outside of the organization.
+
+But should your organization buy, or build?  Buying packaged software makes sense for statutory requirements, such as payroll or general ledger, or document management/retrieval.  But it makes much less sense to buy packaged software for the systems that support the core business: the software should fit the business, not the other way around.
+
+
+NOTE: TODO - flesh out the following:
+
+*  Flexible, "just enough"
+
+*  Decoupled
+
+* Long-term Cost of ownership
+
+** dependency injection of services
+** OO design techniques, eg dependency inversion principle
+** an in-memory event bus
+** applib
+
+** (no "Big Ball of Mud")
+
+* Honouring the Single Responsibility Principle
+**  behaviourally Complete vs Contributions/Mixins
+
+* Testable +
++
+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.
+
+* Reusable building blocks +
++
+Isis addons, catalog.incode.org
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs.adoc
new file mode 100644
index 0000000..ca3b9fd
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs.adoc
@@ -0,0 +1,16 @@
+[[_ugfun_faqs]]
+= FAQs
+: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 chapter has FAQs (with solutions) for problems we've encountered ourselves or have been raised on the
+Apache Isis mailing lists.
+
+
+include::_ugfun_faqs_enabling-logging.adoc[leveloffset=+1]
+include::_ugfun_faqs_subtype-entity-not-fully-populated.adoc[leveloffset=+1]
+include::_ugfun_faqs_restful-image-property.adoc[leveloffset=+1]
+include::_ugfun_faqs_enhance-only.adoc[leveloffset=+1]
+include::_ugfun_faqs_per-user-themes.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_enabling-logging.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_enabling-logging.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_enabling-logging.adoc
new file mode 100644
index 0000000..571d1be
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_enabling-logging.adoc
@@ -0,0 +1,39 @@
+[[_ugfun_faqs_enabling-logging]]
+= Enabling Logging
+: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/
+
+Sometimes you just need to see what is going on. There are various ways in which logging can be enabled, here are the ones we tend to use.
+
+* In Apache Isis +
++
+Modify `WEB-INF/logging.properties` (a log4j config file)
+
+* In DataNucleus +
++
+As per the http://www.datanucleus.org/products/accessplatform/logging.html[DN logging page]
+
+* In the JDBC Driver +
++
+Configure `log4jdbc` JDBC rather than the vanilla driver (see `WEB-INF/persistor_datanucleus.properties`) and configure log4j logging (see `WEB-INF/logging.properties`).  There are examples of both in the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
+
+* In the database +
++
+Details below.
+
+
+Database logging can be configured:
+
+* for HSQLDB +
++
+by adding`;sqllog=3` to the end of the JDBC URL.
+
+* for PostgreSQL: +
++
+Can change `postgresql\9.2\data\postgresql.conf`; see link:http://www.postgresql.org/docs/9.2/static/runtime-config-logging.html[this article] for details.
+
+* for MS SQL Server Logging: +
++
+We like to use the excellent SQL Profiler tool.
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_enhance-only.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_enhance-only.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_enhance-only.adoc
new file mode 100644
index 0000000..e01c2b5
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_enhance-only.adoc
@@ -0,0 +1,17 @@
+[[_ugfun_faqs_enhance-only]]
+= Enhance only (IntelliJ)
+: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/
+
+
+From the Apache Isis mailing list is:
+
+* _Is there a simple way to make a run configuration in IntelliJ for running the datanucleus enhancer before running integration test?_
+
+Yes, you can; here's one way:
+
+* Duplicate your run configuration for running the webapp
+** the one where the main class is `org.apache.isis.WebServer`
+** there's a button for this on the run configurations dialog.
+* then, on your copy change the main class to `org.apache.isis.Dummy`
\ No newline at end of file


[25/52] [abbrv] isis git commit: ISIS-1243: renamed ug.adoc to ugfun.adoc. Added standard section to each of the guides so can navigate between each easily.

Posted by mg...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-common.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-common.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-common.adoc
index 2359c4e..211f064 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-common.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-common.adoc
@@ -12,7 +12,7 @@ xref:rgsvc.adoc#_rgsvc-api_BookmarkService[`BookmarkService`].
 
 Although simple, this is an enormously powerful concept, in that it represents a URI to any domain object managed by
 a given Apache Isis application.  With it, we have the ability to lookup any arbitrary object.  Further discussion and
-examples can be found xref:ug.adoc#_ug_core-concepts_building-blocks_oid[here].
+examples can be found xref:ug.adoc#_ugfun_core-concepts_building-blocks_oid[here].
 
 
 [source,xml]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_ActionInvocationContext.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_ActionInvocationContext.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_ActionInvocationContext.adoc
index caea35d..2ab1258 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_ActionInvocationContext.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_ActionInvocationContext.adoc
@@ -71,7 +71,7 @@ so no further configuration is required.
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_BackgroundService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_BackgroundService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_BackgroundService.adoc
index e56a9dc..25706eb 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_BackgroundService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_BackgroundService.adoc
@@ -100,7 +100,7 @@ further configuration is required.
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_BookmarkService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_BookmarkService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_BookmarkService.adoc
index 5ce3312..4ff46db 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_BookmarkService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_BookmarkService.adoc
@@ -111,6 +111,6 @@ configuration is required.
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_CommandContext.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_CommandContext.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_CommandContext.adoc
index c1c1bfc..8994a5c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_CommandContext.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_CommandContext.adoc
@@ -203,7 +203,7 @@ implementation of `CommandContext` service is automatically registered and injec
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DeepLinkService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DeepLinkService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DeepLinkService.adoc
index 8512b05..363b0c7 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DeepLinkService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DeepLinkService.adoc
@@ -53,4 +53,4 @@ automatically registered and injected (it is annotated with `@DomainService`) so
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_EmailService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_EmailService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_EmailService.adoc
index 6301e5a..2042983 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_EmailService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_EmailService.adoc
@@ -87,7 +87,7 @@ implementation of `EmailService` service is automatically registered and injecte
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
 
 
 == Related Services

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_EventBusService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_EventBusService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_EventBusService.adoc
index 7fdde83..1e3ecbb 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_EventBusService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_EventBusService.adoc
@@ -393,7 +393,7 @@ implementation of `EventBusService` service is automatically registered and inje
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_GuiceBeanProvider.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_GuiceBeanProvider.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_GuiceBeanProvider.adoc
index cf7c5f6..261195f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_GuiceBeanProvider.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_GuiceBeanProvider.adoc
@@ -86,6 +86,6 @@ automatically registered and injected (it is annotated with `@DomainService`) so
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_IsisJdoSupport.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_IsisJdoSupport.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_IsisJdoSupport.adoc
index ab53f88..9553542 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_IsisJdoSupport.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_IsisJdoSupport.adoc
@@ -273,4 +273,4 @@ implementation of `IsisJdoSupport` service is automatically registered and injec
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_JaxbService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_JaxbService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_JaxbService.adoc
index 198534d..56c6328 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_JaxbService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_JaxbService.adoc
@@ -63,5 +63,5 @@ so no further configuration is required.
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_MementoService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_MementoService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_MementoService.adoc
index 7196374..6358231 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_MementoService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_MementoService.adoc
@@ -128,4 +128,4 @@ implementation of `MementoService` service is automatically registered and injec
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_MetamodelService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_MetamodelService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_MetamodelService.adoc
index 6c745d6..7aa8a58 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_MetamodelService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_MetamodelService.adoc
@@ -39,4 +39,4 @@ implementation of `MetamodelService` service is automatically registered and inj
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_QueryResultsCache.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_QueryResultsCache.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_QueryResultsCache.adoc
index 1182787..a5a63c3 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_QueryResultsCache.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_QueryResultsCache.adoc
@@ -117,7 +117,7 @@ implementation of `QueryResultsCache` service is automatically registered and in
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_Scratchpad.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_Scratchpad.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_Scratchpad.adoc
index bbef46d..3d091e2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_Scratchpad.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_Scratchpad.adoc
@@ -115,7 +115,7 @@ so no further configuration is required.
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_SudoService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_SudoService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_SudoService.adoc
index 8bcfe26..c1b8a84 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_SudoService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_SudoService.adoc
@@ -66,4 +66,4 @@ implementation of `SudoService` service is automatically registered and injected
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_WrapperFactory.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_WrapperFactory.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_WrapperFactory.adoc
index d83af8a..7f7eba8 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_WrapperFactory.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_WrapperFactory.adoc
@@ -159,4 +159,4 @@ implementation of `WrapperFactory` service is automatically registered and injec
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_XmlSnapshotService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_XmlSnapshotService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_XmlSnapshotService.adoc
index 3f5c84c..316f4fa 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_XmlSnapshotService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_XmlSnapshotService.adoc
@@ -200,7 +200,7 @@ implementation of `XmlSnapshotService` service is automatically registered and i
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ClassDiscoveryService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ClassDiscoveryService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ClassDiscoveryService.adoc
index 8203208..f40de54 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ClassDiscoveryService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ClassDiscoveryService.adoc
@@ -46,7 +46,7 @@ This implementation is also used to discover domain services annotated with xref
 The usage will vary depending upon the conventions of the design.  As of 1.9.0, the usage of the service has been
 centralized such that the packages to be scanned are located from the xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`]'s `#getModules()` method.
 
-For example, the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype]'s app manifest includes:
+For example, the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]'s app manifest includes:
 
 [source,java]
 ----
@@ -77,6 +77,6 @@ implementation of `ClassDiscoveryService2` service is automatically registered a
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ContentNegotiationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ContentNegotiationService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ContentNegotiationService.adoc
index 1f2f08b..4164327 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ContentNegotiationService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ContentNegotiationService.adoc
@@ -193,7 +193,7 @@ implementation of `ContentNegotiationService` service is automatically registere
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_EmailNotificationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_EmailNotificationService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_EmailNotificationService.adoc
index 9b63d8e..34553a2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_EmailNotificationService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_EmailNotificationService.adoc
@@ -70,7 +70,7 @@ implementation of `EmailNotificationService` service is automatically registered
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
 
 
 == Related Services

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_FixtureScriptsSpecificationProvider.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_FixtureScriptsSpecificationProvider.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_FixtureScriptsSpecificationProvider.adoc
index 5c9dea3..2ea5d3a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_FixtureScriptsSpecificationProvider.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_FixtureScriptsSpecificationProvider.adoc
@@ -56,7 +56,7 @@ The class is immutable but it has a builder (obtained using `FixturescriptsSpeci
 
 == Implementation
 
-The xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype] has a simple implementation of this service:
+The xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] has a simple implementation of this service:
 
 [source,java]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_LocaleProvider.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_LocaleProvider.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_LocaleProvider.adoc
index 4677e31..213b179 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_LocaleProvider.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_LocaleProvider.adoc
@@ -56,7 +56,7 @@ automatically registered and injected (it is annotated with `@DomainService`) so
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_RepresentationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_RepresentationService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_RepresentationService.adoc
index b85c8fe..5a4dd62 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_RepresentationService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_RepresentationService.adoc
@@ -87,7 +87,7 @@ As discussed in the introduction, the framework provides a default implementatio
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
 
 
 == Registering the Services

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_TranslationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_TranslationService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_TranslationService.adoc
index 5f7b1a3..21a7e64 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_TranslationService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_TranslationService.adoc
@@ -68,7 +68,7 @@ If the menu items are not required then these can be suppressed either using sec
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_TranslationsResolver.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_TranslationsResolver.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_TranslationsResolver.adoc
index 74d15b7..eb61c5b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_TranslationsResolver.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_TranslationsResolver.adoc
@@ -52,7 +52,7 @@ automatically registered and injected (it is annotated with `@DomainService`) so
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_UrlEncodingService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_UrlEncodingService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_UrlEncodingService.adoc
index 1a21aa9..39a352b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_UrlEncodingService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_UrlEncodingService.adoc
@@ -55,5 +55,5 @@ cases register an alternative implementation of this service.
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/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
index cd8a726..89c7785 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_tg_pet-clinic.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_tg_pet-clinic.adoc
@@ -5,7 +5,7 @@
 :_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 was originally written by Jeroen van der Wal.
+This is a step-by-step tutorial to build up a simple "petclinic" application, starting from the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].  It was originally written by Jeroen van der Wal.
 
 It consists of just three domain classes (http://yuml.me/edit/3db2078c[http://yuml.me/3db2078c]):
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_tg_stop-scaffolding-start-coding.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_tg_stop-scaffolding-start-coding.adoc b/adocs/documentation/src/main/asciidoc/guides/_tg_stop-scaffolding-start-coding.adoc
index f4d40a3..5a44e23 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_tg_stop-scaffolding-start-coding.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_tg_stop-scaffolding-start-coding.adoc
@@ -202,8 +202,8 @@ Most domain objects in Apache Isis applications are persistent entities. In the
 ** eg rename to `Pet`
 * if required, rename the `SimpleObject` class' `name` property
 ** for `Pet`, can leave `name` property as is
-* specify a xref:ug.adoc#_ug_how-tos_ui-hints_object-titles-and-icons[title]
-* specify an xref:ug.adoc#_ug_how-tos_ui-hints_object-titles-and-icons[icon]
+* specify a xref:ug.adoc#_ugfun_how-tos_ui-hints_object-titles-and-icons[title]
+* specify an xref:ug.adoc#_ugfun_how-tos_ui-hints_object-titles-and-icons[icon]
 * make the entity bookmarkable by adding the xref:rgant.adoc#_rgant-DomainObjectLayout_bookmarking[`@DomainObjectLayout#bookmarking()`] attribute.
 * confirm is available from bookmark panel (top-left of Wicket UI)
 
@@ -219,11 +219,11 @@ In the simpleapp archetype the `SimpleObjects` service is a factory/repository f
 * rename the `SimpleObjects` class
 ** eg rename to `Pets`
 * review `create` action (acting as a factory)
-** as per the docs describing xref:ug.adoc#_ug_how-tos_crud[how to create or delete objects]
+** as per the docs describing xref:ug.adoc#_ugfun_how-tos_crud[how to create or delete objects]
 * rename if you wish
 ** eg `newPet(...)` or `addPet(...)`
 * review `listAll` action (acting as a repository)
-* as per the docs describing xref:ug.adoc#_ug_how-tos_crud[how to write a custom repository]
+* as per the docs describing xref:ug.adoc#_ugfun_how-tos_crud[how to write a custom repository]
 * note the annotations on the corresponding domain class (originally called `SimpleObject`, though renamed by now, eg to `Pet`)
 * rename if you wish
 ** eg `listPets()`
@@ -296,7 +296,7 @@ The semantics of an action (whether it is safe/query only, whether it is idempot
 
 Domain entities have state: either values (primitives, strings) or references to other entities. In this section we explore adding some value properties
 
-* add some xref:ug.adoc#_ug_how-tos_class-structure_properties[value properties]; also:
+* add some xref:ug.adoc#_ugfun_how-tos_class-structure_properties[value properties]; also:
 * for string properties
 ** use the xref:rgant.adoc#_rgant-PropertyLayout_multiLine[`@Property(multiLine=...)`] annotation to render a text area instead of a text box
 ** use the xref:rgant.adoc#_rgant-Property_maxLength[`@Property(maxLength=...)`] annotation to specify the maximum number of characters allowable
@@ -309,7 +309,7 @@ Domain entities have state: either values (primitives, strings) or references to
 * revisit the title, consider whether to use the xref:rgant.adoc#_rgant-Title[`@Title`] annotation
 ** rather than the xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`] `title()` method
 * order the properties using the xref:rgant.adoc#_rgant-MemberOrder[`@MemberOrder`], also `@MemberGroupLayout`
-** see also the docs on xref:ug.adoc#_ug_object-layout_static[static layouts]
+** see also the docs on xref:ug.adoc#_ugfun_object-layout_static[static layouts]
 * use the xref:rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`] annotation to position property/action parameter labels either to the LEFT, TOP or NONE
 ** do the same for parameters using xref:rgant.adoc#_rgant-ParameterLayout[`@ParameterLayout`]
 
@@ -320,7 +320,7 @@ Domain entities have state: either values (primitives, strings) or references to
 
 Domain entities can also reference other domain entities. These references may be either scalar (single-valued) or vector (multi-valued). In this section we focus on scalar reference properties.
 
-* add some xref:ug.adoc#_ug_how-tos_class-structure_properties[reference properties]
+* add some xref:ug.adoc#_ugfun_how-tos_class-structure_properties[reference properties]
 * update the corresponding domain service (for creation actoin)
 * use different techniques to obtain references (shown in drop-down list box)
 ** use the xref:rgant.adoc#_rgant-DomainObject_bounded[`@DomainObjectLayout(bounded=...)`] annotation on the referenced type if there are only a small number (bounded) of instances
@@ -338,7 +338,7 @@ Domain entities can also reference other domain entities. These references may b
 
 Quick detour: often we want to set up defaults to go with choices. Sensible defaults for action parameters can really improve the usability of the app.
 
-* Add xref:ug.adoc#_ug_how-tos_drop-downs-and-defaults[defaults] for action parameters
+* Add xref:ug.adoc#_ugfun_how-tos_drop-downs-and-defaults[defaults] for action parameters
 
 
 
@@ -350,7 +350,7 @@ Returning back to references, Isis also supports vector (multi-valued) reference
 * Ensure that all domain classes implement `java.lang.Comparable`
 ** use the xref:rgcms.adoc#_rgcms_classes_utility_ObjectContracts[`ObjectContracts`] utility class to help implement `Comparable`
 *** you can also `equals()`, `hashCode()`, `toString()`
-* Add a xref:ug.adoc#_ug_how-tos_class-structure_collections[collection] to one of the entities
+* Add a xref:ug.adoc#_ugfun_how-tos_class-structure_collections[collection] to one of the entities
 ** Use `SortedSet` as the class
 ** Use the xref:rgant.adoc#_rgant-CollectionLayout_render[`@CollectionLayout(render=...)`] annotation to indicate if the collection should be visible or hidden by default
 * optional: use the xref:rgant.adoc#_rgant-CollectionLayout_sortedBy[`@CollectionLayout(sortedBy=...)`] annotation to specify a different comparator than the natural ordering
@@ -364,7 +364,7 @@ Returning back to references, Isis also supports vector (multi-valued) reference
 The Wicket UI doesn't allow collections to be modified (added to/removed from). However, we can easily write actions to accomplish the same. Moreover, these actions can provide some additional business logic. For example: it probably shouldn't be possible to add an object twice into a collection, so it should not be presented in the list of choices/autoComplete; conversely, only those objects in the collection should be offered as choices to be removed.
 
 * Add domain actions to add/remove from the collection
-* to create objects, xref:ug.adoc#_ug_how-tos_class-structure_inject-services[inject] associated domain service
+* to create objects, xref:ug.adoc#_ugfun_how-tos_class-structure_inject-services[inject] associated domain service
 ** generally we recommend using the xref:rgant.adoc#_rgant-Inject[`@Inject`] annotation with either private or default visibility
 * the service itself should use xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer[`DomainObjectContainer`]
 * use the xref:rgant.adoc#_rgant-MemberOrder[`@MemberOrder(name=...)`] annotation to associate an action with a property or with a collection
@@ -380,7 +380,7 @@ CSS classes can be associated with any class member (property, collection, actio
 
 *  the http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome] icons can be used using the xref:rgant.adoc#_rgant-ActionLayout_cssClassFa[`@ActionLayout(cssClassFa=...)`]
 
-It's also possible to use Font Awesome icons for the xref:ug.adoc#_ug_how-tos_ui-hints_object-titles-and-icons[domain object icon].
+It's also possible to use Font Awesome icons for the xref:ug.adoc#_ugfun_how-tos_ui-hints_object-titles-and-icons[domain object icon].
 
 So:
 - for some of the actions of your domain services or entities, annotate using `@ActionLayout(cssClass=...)` or `@ActionLayout(cssClassFa=...)`
@@ -392,7 +392,7 @@ So:
 
 Up to this point we've been using annotations (`@MemberOrder`, `@MemberGroupLayout`, `@Named`, `@PropertyLayout`, `@ParameterLayout`, `@ActionLayout` and so on) for UI hints. However, the feedback loop is not good: it requires us stopping the app, editing the code, recompiling and running again. So instead, all these UI hints (and more) can be specified dynamically, using a corresponding `.layout.json` file. If edited while the app is running, it will be reloaded automatically (in IntelliJ, use Run&gt;Reload Changed Classes):
 
-* Delete the various hint annotations and instead specify layout hints using a xref:ug.adoc#_ug_object-layout_dynamic[.layout.json] file.
+* Delete the various hint annotations and instead specify layout hints using a xref:ug.adoc#_ugfun_object-layout_dynamic[.layout.json] file.
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts.adoc
deleted file mode 100644
index f7b255c..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts.adoc
+++ /dev/null
@@ -1,22 +0,0 @@
-[[_ug_core-concepts]]
-= 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/
-
-This introductory chapter should give you a good about what Apache Isis actually *is*: the fundamental ideas and principles that it builds upon, how it compares with other frameworks, what the fundamental building blocks are for actually writing an Isis application, and what services and features the framework provides for you to leverage in your own apps.
-
-[TIP]
-====
-Parts of this chapter have been adapted from Dan Haywood's 2009 book, 'Domain Driven Design using Naked Objects'.  We've also added some new insights and made sure the material we've used is relevant to Apache Isis.
-====
-
-
-include::_ug_core-concepts_philosophy.adoc[leveloffset=+1]
-include::_ug_core-concepts_principles.adoc[leveloffset=+1]
-include::_ug_core-concepts_building-blocks.adoc[leveloffset=+1]
-include::_ug_core-concepts_framework-provided-services.adoc[leveloffset=+1]
-include::_ug_core-concepts_add-ons.adoc[leveloffset=+1]
-include::_ug_core-concepts_other-deployment-options.adoc[leveloffset=+1]
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_add-ons.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_add-ons.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_add-ons.adoc
deleted file mode 100644
index 0af3b56..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_add-ons.adoc
+++ /dev/null
@@ -1,35 +0,0 @@
-[[_ug_core-concepts_add-ons]]
-= Isis Add-ons
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-The link:http://www.isisaddons.org[Isis Addons] website provides a number of reusable modules and other extensions for Apache Isis.  This chapter focuses just on the modules, all of which have a name of the form `isis-module-xxx`.
-
-[WARNING]
-====
-Note that Isis addons, while maintained by Apache Isis committers, are not part of the ASF.
-====
-
-
-
-The modules themselves fall into four broad groups:
-
-* modules that provide an implementations of API defined by Apache Isis +
-+
-where Apache Isis has hooks to use the service if defined by provides no implementations of its own.  The http://github.com/isisaddons/isis-module-command[command], http://github.com/isisaddons/isis-module-audit[auditing], http://github.com/isisaddons/isis-module-publishing[publishing], http://github.com/isisaddons/isis-module-security[security]  and http://github.com/isisaddons/isis-module-sessionlogger[sessionlogger] modules fall into this category.  Typically the domain objects themselves wouldn't interact with these services
-
-* modules that provide standalone domain services with their own API and implementation +
-+
-These are simply intended to be used by domain objects.  The http://github.com/isisaddons/isis-module-docx[docx], http://github.com/isisaddons/isis-module-excel[excel], http://github.com/isisaddons/isis-module-settings[settings] and http://github.com/isisaddons/isis-module-stringinterpolator[stringinterpolator] fall into this category.
-
-* modules that provide standalone domain entities (and supporting services) for a particular subdomain +
-+
-The http://github.com/isisaddons/isis-module-tags[tags] module falls into this category
-
-* modules that provide developer utilities +
-+
-Not intended for use by either the framework or domain objects, but provide utilities that the developer themselves might use.  The http://github.com/isisaddons/isis-module-devutils[devutils] module (not suprisingly) falls into this category
-
-Each of the modules has a full README and example application demonstrating their usage.  The sections below briefly outline the capabilities of these modules.

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_building-blocks.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_building-blocks.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_building-blocks.adoc
deleted file mode 100644
index 1b7e2e5..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_building-blocks.adoc
+++ /dev/null
@@ -1,335 +0,0 @@
-[[_ug_core-concepts_building-blocks]]
-= 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/
-
-In this section we run through the main building blocks that make up an Apache Isis application.
-
-[[_ug_core-concepts_building-blocks_metamodel]]
-== A MetaModel
-
-At its core, Apache Isis is a metamodel that is built at runtime from the domain classes (eg `Customer.java`), along
-with optional supporting metadata (eg `Customer.layout.json`).
-
-The contents of this metamodel is inferred from the Java classes discovered on the classpath: the entities and
-supporting services, as well the members of those classes.  The detail of the metamodel is generally explicit, usually
-represented by Java annotations such as `@Title` or `@Action`.  Notably the metamodel is
-xref:ugbtb.adoc#_ugbtb_programming-model[extensible]; it is possible to teach Apache Isis new programming
-conventions/rules (and conversely to remove those that are built in).
-
-Most of the annotations recognized by the framework are defined by the Apache Isis framework itself.  For example the
-`@Title` annotation - which identifies how the framework should derive a human-readable label for each rendered
-domain object - is part of the `org.apache.isis.applib.annotations` package.  However the framework also recognizes
-certain other JEE annotations such as `@javax.inject.Inject` (used for dependency injection).
-
-The framework uses DataNucleus for its persistence mechanism.  This is an ORM that implements the JDO and JPA APIs, and
-which can map domain objects either to an RDBMS or to various NoSQL objectstores such as MongoDB or Neo4J.  Apache Isis
-recognizes a number of the JDO annotations such as `@javax.jdo.annotations.Column(allowNulls=...)`.
-
-In addition, the framework builds up the metamodel for each domain object using
-xref:ug.adoc#_ug_object-layout[layout hints], such as `Customer.layout.json`.  These provide metadata such as
-grouping elements of the UI together, using multi-column layouts, and so on.  The layout file can be modified while the
-application is still running, and are picked up automatically; a useful way to speed up feedback.
-
-[TIP]
-====
-At the time of writing Apache Isis only recognizes and supports the JDO API, though we expect JPA to be supported
-in the future.  We also expect to generalize support for `.layout.json` to be able to read such metadata from other
-sources.
-====
-
-
-[[_ug_core-concepts_building-blocks_types-of-domain-objects]]
-== Type of Domain Objects
-
-Most domain objects that the end-user interacts with are *domain entities*, such as `Customer`, `Order`, `Product` and
-so on.  These are persistent objects and which are mapped to a database (usually relational), using JDO/DataNucleus
-annotations.  From the end-user's perspective the UI displays a single domain object per page; they can then inspect
-and modify its state, and navigate to related objects.
-
-The next type of domain object to discuss is *domain services*.  These are (usually) singleton stateless services
-that provide additional functionality.  The behaviour of these services is rendered in various ways, though the most
-obvious is as the menu actions on the top-level menu bars in the xref:ugvw.adoc#[Wicket viewer]'s UI.
-
-Domain objects can also delegate to domain services; domain services are automatically injected into every other domain
-object; this includes domain entities as well as other services.  This injection of domain services into entities is
-significant: it allows business logic to be implemented in the domain entities, rather than have it "leach away" into
-supporting service layers.  Said another way: it is the means by which Apache Isis helps you avoid the anaemic
-domain model anti-pattern.
-
-As well as domain entities - mapped to a datastore - Apache Isis also supports *view models*.  End users interact with
-view models in the same way as a domain entity, indeed they are unlikely to distinguish one from the other.  However
-view models are _not_ mapped to the underlying database, rather they represent some aggregation of state from one or
-more underlying entities.  Their state is serialized and recreated from their internal identifier; this identifier is
-visible as the object's URL in the xref:ugvw.adoc#[Wicket viewer] or
-xref:ugvro.adoc#[RestfulObjects viewer].
-
-There's no need though for the view model to aggregate the state of regular domain entities.  A view model could also
-be used as a proxy for some externally managed entity, accessed over a web service or REST API; it could even be a
-representation of state held in-memory (such as user preferences, for example).
-
-There are also several types of domain services.  Most easily described are those domain services (discussed above)
-that are represented as the menu actions on top-level menu bars.  Another variation are *contributed services* - domain
-services that contribute behaviour or (derived) state to entities/view models.  Finally domain services may also
-simply provide additional non-UI functionality; an example being to perform an address geocoding lookup against the
-google-maps API.
-
-Also worth mentioning: domain services can also be either singletons (discussed above) or request-scoped; the latter
-being annotated with `@javax.enterprise.context.RequestScoped`.  An example of the request-scoped service is the
-xref:rgsvc.adoc#_rgsvc-api_Scratchpad[`Scratchpad`] service, for sharing arbitrary data between multiple objects.
-
-The final type of domain object is the *mixin*.  These are similar to contributed services in that they also contribute (or rather,
-mixin) both behaviour or (derived) state to entities/view models.  However, they provide a more control over contributed services,
-with a cleaner programming model similar to traits found in other languages.
-
-The diagram below summarizes the various types of domain object:
-
-image::{_imagesdir}core-concepts/building-blocks/types-of-domain-object.png[width="860px",link="{_imagesdir}core-concepts/building-blocks/types-of-domain-object.png"]
-
-
-The Apache Isis programming model uses annotations to distinguish these object types:
-
-* *view models* are annotated either with `@DomainObject(nature=VIEW_MODEL)` or using `@ViewModel`.  Which is used is
-a matter of personal preference.  +
-+
-It is also possible to implement the `ViewModel` interface, for finer-grained control.
-
-* *domain entities* that are persisted to the database (as the vast majority will) are annotated with
-`@DomainObject(nature=ENTITY)`. In addition such domain entities are annotated with the JDO/DataNucleus annotation of
-`@javax.jdo.annotations.PersistenceCapable`. +
-+
-In addition, if a domain entity is a proxy for state managed in an external system, or merely for some state held
-in-memory, then `@DomainObject(nature=EXTERNAL_ENTITY)` or `@DomainObject(nature=INMEMORY_ENTITY)` can be used.
-
-* *mixins* are annotated either with `@DomainObject(nature=MIXIN)` or using `@Mixin`.  As for view models, which is
-used is a matter of personal preference.
-
-* finally, *domain services*` are annotated with `@DomainService(nature=...)` where the nature is either
-`VIEW_MENU_ONLY` (for domain services whose actions appear on the top-level menu bars), or `VIEW_CONTRIBUTIONS_ONLY`
-(for domain services whose actions are contributed to entities or view models), or `DOMAIN` (for domain services whose
-functionality is simply for other domain objects to invoke programmatically).
-+
-It is also possible to specify a nature of simply `VIEW`, this combining `VIEW_MENU_ONLY` and `VIEW_CONTRIBUTIONS_ONLY`.
-This is in fact the default, useful for initial prototyping.  A final nature is `VIEW_REST_ONLY` which is for domain
-services whose functionality is surfaced only by the xref:ugvro.adoc#[RestfulObjects viewer].
-
-Worth emphasising is that domain entities and view models hold state, whereas domain services are generally
-stateless.  If a domain service does hold state (eg the `Scratchpad` service noted above) then it should be
-`@RequestScoped` so that this state is short-lived and usable only within a single request.
-
-
-
-[[_ug_core-concepts_building-blocks_objects-members]]
-== Object Members
-
-Every domain object in Apache Isis consists of (at most) three types of members:
-
-* properties, such as a `Customer`'s `firstName
-
-* collections, such as a `Customer`'s `orders` collection of ``Order``s
-
-* actions, such as a `Customer'`s `placeOrder(...)` method.
-
-Some domain objects - specifically domain services and mixins - only have actions.  In the case of contributing services
-and mixins these actions can (depending upon their semantics and signatures) be represented as derived properties or
-collections on the entity/view model to which they contribute/mix-in.
-
-
-=== Properties
-
-Properties follow the standard getter/setter pattern, with the return type being a scalar (a value object or another
-entity or view model).
-
-For example, with:
-
-[source,java]
-----
-public class Customer
-    private String firstName;
-    public String getFirstName() { return firstName; }
-    public void setFirstName(String firstName) { this.firstName = firstName; }
-    ...
-}
-----
-
-the framework infers the `Customer` domain entity, which in turn has a `firstName` string _property_.
-
-
-=== Collections
-
-Collections are also represented by a getter and setter, however the return type is a `Collection` or subtype.
-
-For example, with:
-
-[source,java]
-----
-public class Customer
-    private SortedSet<Order> orders = new TreeSet<Order>();
-    public SortedSet<Order> getOrders() { return orders; }
-    public void setOrders(SortedSet<Order> orders) { this.orders = orders; }
-    ...
-}
-----
-
-the framework infers the `orders` _collection_.
-
-[TIP]
-====
-The most commonly used collection type is `java.util.SortedSet`; entities are most commonly mapped to a relational
-database (ie a datastore with set semantics) and we recommend that all entities define a natural ordering so that when
-rendered in the UI they will be ordered "meaningfully" to the end-user.
-====
-
-
-=== Actions
-
-The third type of object member is actions.  (To a first approximation), actions are all public methods that do not
-represent properties or collections.
-
-For example:
-
-[source,java]
-----
-public class Customer
-    public Customer placeOrder(Product p, int quantity) { ... }
-    ...
-}
-----
-
-corresponds to the `placeOrder` _action_.
-
-[NOTE]
-====
-The above _is_ a simplification; the Apache Isis programming model also recognizes a number of other supporting methods
-each of which has its own prefix such as `hide`, `disable` or `validate`.  These can be considered as "reserved words"
-in Apache Isis, and do _not_ correspond to actions even though they have public visibility.
-====
-
-
-
-== Entities vs View Models
-
-When developing an Apache Isis application you will most likely start off with the persistent domain entities:
-`Customer`, `Order`, `Product`, and so on.  For some applications this may well suffice.  However, if the application
-needs to integrate with other systems, or if the application needs to support reasonably complex business processes,
-then you may need to look beyond just domain entities.
-
-To support these use cases we support view models.  In the same way that an (RDBMS) database view can aggregate and
-abstract from multiple underlying database tables, so a view model sits on top of one or many underlying entities.
-
-View models are not persisted, but nevertheless they can have behaviour (and titles, and icons) just like domain
-entities.  Indeed, to a user of the system there is no particular distinction (again, in the same way that when using
-an RDBMS one can use database views and database tables pretty much interchangeably).
-
-View models generally tend to be associated with supporting a particular use case; logically they are part of the
-application layer, not part of the domain layer (where entities live).
-
-We introduce view models here because they do get mentioned quite often within the users and reference guide.  However,
-we do consider them a more advanced topic; we generally recommend that you build your applications from the domain
-layer up, rather than from the view model down.
-
-For further discussion on view models, see xref:ugbtb.adoc#_ugbtb_more-advanced_view-models[this topic].
-
-
-
-
-[[_ug_core-concepts_building-blocks_domain-services]]
-== 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. Apache 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
-
-NOTE: TODO
-
-`@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:http://books.google.com/books/about/Domain_Driven_Design.html?id=hHBf4YxMnWMC[Domain Driven Design], 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.
-****
-
-
-
-[[_ug_core-concepts_building-blocks_mixins-and-contributions]]
-== Mixins & Contributions
-
-NOTE: TODO
-
-
-For more information, see xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling_contributions[this topic on contribution]s, and
-xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling_mixins[this topic on mixin]s.
-
-
-
-[[_ug_core-concepts_building-blocks_domain-events]]
-== Domain Events
-
-NOTE: TODO; see xref:rgcms.adoc#_rgcms_classes_domainevent[domain event] classes.
-
-
-
-=== UI Events (`1.11.0-SNAPSHOT`)
-
-NOTE: TODO; see xref:rgcms.adoc#_rgcms_classes_uievent[UI event] classes.
-
-
-
-
-[[_ug_core-concepts_building-blocks_oid]]
-== OIDs
-
-As well as defining a xref:ug.adoc#_ug_core-concepts_building-blocks_metamodel[metamodel] of the structure (domain
-classes) of its domain objects, Apache Isis also manages the runtime instances of said domain objects.
-
-When a domain entity is recreated from the database, the framework keeps track of its identity through an "OID": an
-object identifier.  Fundamentally this is a combination of its type (domain class), along with an identifier.  You can think
-of it as its "primary key", except across all domain entity types.
-
-For portability and resilience, though, the object type is generally an alias for the actual domain class: thus
-"customers.CUS", say, rather than "com.mycompany.myapp.customers.Customer".  This is derived from an annotation.  The
-identifier meanwhile is always converted to a string.
-
-Although simple, the OID is an enormously powerful concept: it represents a URI to any domain object managed by
-a given Apache Isis application.  With it, we have the ability to lookup any arbitrary domain objects.
-
-Some examples:
-
-* an OID allows sharing of information between users, eg as a deep link to be pasted into an email.
-
-* the information within an OID could be converted into a barcode, and stamped onto a PDF form.  When the PDF is
-scanned by the mail room, the barcode could be read to attach the correspondence to the relevant domain object.
-
-* as a handle to any object in an audit record (as used by the
-xref:rgsvc.adoc#_rgsvc-spi_AuditingService[`AuditingService`], in fact).
-
-* and of course both the xref:ugvro.adoc#[RestfulObjects viewer] and
-xref:ugvw.adoc#[Wicket viewer]
-use the oid tuple to look up, render and allow the user to interact with domain objects.
-
-Although the exact content of an OID should be considered opaque by domain objects, it is possible for domain objects
-to obtain OIDs.  These are represented as `Bookmark`s, obtained from the
-xref:rgsvc.adoc#_rgsvc-api_BookmarkService[`BookmarkService`].  Deep links meanwhile can be obtained from
-the xref:rgant.adoc#_rgant-DeepLinkService[`@DeepLinkService`].
-
-OIDs can also be converted into XML format, useful for integration scenarios.  The
-xref:rgcms.adoc#_rgcms_schema-common[common schema] XSD defines the `oidDto` complex type for precisely this purpose.
-
-
-
-[[_ug_core-concepts_building-blocks_value-objects]]
-== Value Objects (Primitives)
-
-NOTE: TODO
-
-
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_framework-provided-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_framework-provided-services.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_framework-provided-services.adoc
deleted file mode 100644
index dc63979..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_framework-provided-services.adoc
+++ /dev/null
@@ -1,54 +0,0 @@
-[[_ug_core-concepts_framework-provided-services]]
-= 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/
-
-
-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.
-
-
-General purpose:
-
-* xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer[`DomainObjectContainer`]
-* xref:rgsvc.adoc#_rgsvc-api_ClockService[`ClockService`]
-* xref:rgsvc.adoc#_rgsvc-api_IsisJdoSupport[`IsisJdoSupport`]
-* xref:rgsvc.adoc#_rgsvc-api_WrapperFactory[`WrapperFactory`]
-* xref:rgsvc.adoc#_rgsvc-api_EventBusService[`EventBusService`]
-* xref:rgsvc.adoc#_rgsvc-api_EmailService[`EmailService`]
-
-Commands/Background/Auditing:
-
-* xref:rgsvc.adoc#_rgsvc-api_CommandContext[`CommandContext`] (SPI)
-* xref:rgsvc.adoc#_rgsvc-spi_CommandService[`CommandService`] (SPI)
-* xref:rgsvc.adoc#_rgsvc-spi_AuditingService[`AuditingService`] (SPI)
-* xref:rgsvc.adoc#_rgsvc-api_BackgroundService[`BackgroundService`]
-* xref:rgsvc.adoc#_rgsvc-spi_BackgroundCommandService[`BackgroundCommandService`] (SPI)
-* xref:rgsvc.adoc#_rgsvc-spi_PublishingService[`PublishingService`] (SPI)
-
-Information Sharing:
-
-* xref:rgsvc.adoc#_rgsvc-api_Scratchpad[`Scratchpad`]
-* xref:rgsvc.adoc#_rgsvc-api_ActionInvocationContext[`ActionInvocationContext`]
-* xref:rgsvc.adoc#_rgsvc-api_QueryResultsCache[`QueryResultsCache`]
-
-
-UserManagement:
-
-* xref:rgsvc.adoc#_rgsvc-spi_UserProfileService[`UserProfileService`] (SPI)
-* xref:rgsvc.adoc#_rgsvc-spi_UserRegistrationService[`UserRegistrationService`] (SPI)
-* xref:rgsvc.adoc#_rgsvc-spi_EmailNotificationService[`EmailNotificationService`] (SPI)
-
-
-Bookmarks and Mementos:
-
-* xref:rgsvc.adoc#_rgsvc-api_BookmarkService[`BookmarkService`]
-* xref:rgsvc.adoc#_rgsvc-api_MementoService[`MementoService`]
-* xref:rgsvc.adoc#_rgsvc-api_DeepLinkService[`DeepLinkService`]
-* xref:rgsvc.adoc#_rgsvc-api_XmlSnapshotService[`XmlSnapshotService`]
-
-
-A full list of services can be found in the xref:rgsvc.adoc#_rgsvc-api[Domain Services (API)]  and xref:rgsvc.adoc#_rgsvc-spi[Domain Services (SPI)] chapters of the reference guide.
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_other-deployment-options.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_other-deployment-options.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_other-deployment-options.adoc
deleted file mode 100644
index 6e2b359..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_other-deployment-options.adoc
+++ /dev/null
@@ -1,81 +0,0 @@
-[[_ug_core-concepts_other-deployment-options]]
-= Other Deployment Options
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-Apache Isis is a mature platform suitable for production deployment, with its "sweet spot" being line-of-business enterprise applications.  So if you're looking to develop that sort of application, we certainly hope you'll seriously evaluate it.
-
-But there are other ways that you can make Apache Isis work for you; in this chapter we explore a few of them.
-
-
-
-== Deploy to production
-
-Let's start though with the default use case for Apache Isis: building line-of-business enterprise applications, on top of its Wicket viewer.
-
-Apache Wicket, and therefore Apache Isis in this configuration, is a stateful architecture.  As a platform it is certainly capable of supporting user bases of several thousand (with perhaps one or two hundred concurrent); however it isn't an architecture that you should try to scale up to tens of thousands of concurrent users.
-
-The UI UI generated by the Wicket viewer is well suited to many line-of-business apps, but it's also worth knowing that (with a little knowledge of the Wicket APIs) it relatively straightforward to extend.  As described in xref:ug.adoc#_ug_core-concepts_add-ons[Isis addons] chapter, the viewer already has integrations with https://github.com/isisaddons/isis-wicket-gmap3[google maps], https://github.com/isisaddons/isis-wicket-fullcalendar2[a full calendar] and an https://github.com/isisaddons/isis-wicket-excel[export to Excel] component.  We are also aware of integrations with SVG images (for floor maps of shopping center) and of custom widgets displaying a catalogue (text and images) of medical diseases.
-
-Deploying on Apache Isis means that the framework also manages object persistence.  For many line-of-business applications this will mean using a relational database.  It is also possible (courtesy of its integratinon with link:http://www.datanucleus.org[DataNucleus]) to deploy an Isis app to a NoSQL store such as Neo4J or MongoDB; and it is also possible to deploy to cloud platforms such as link:https://cloud.google.com/appengine/docs[Google App Engine (GAE)].
-
-
-
-== Use for prototyping
-
-Even if you don't intend to deploy your application on top of Apache Isis, there can be a lot of value in using Apache Isis for prototyping.  Because all you need do to get an app running is write domain objects, you can very quickly explore a domain object model and validate ideas with a domain expert.
-
-By focusing just on the domain, you'll also find that you start to develop a ubiquitous language - a set of terms and concepts that the entire team (business and technologists alike) have a shared understanding.
-
-Once you've sketched out your domain model, you can then "start-over" using your preferred platform.
-
-
-
-
-
-== Deploy on your own platform
-
-The programming model defined by Apache Isis deliberately minimizes the dependencies on the rest of the framework. In fact, the only hard dependency that the domain model classes have on Apache Isis is through the `org.apache.isis.applib` classes, mostly to pick up annotations such as `@Disabled`.
-So, if you have used Apache Isis for prototyping (discussed above), then note that it's quite feasible to take your domain model a the basis of your actual development effort; Apache Isis' annotations and programming conventions will help ensure that any subtle semantics you might have captured in your prototyping are not lost.
-
-If you go this route, your deployment platform will of course need to provide similar capabilities to Apache Isis.  In particular, you'll need to figure out a way to inject domain services into domain entities (eg using a JPA listener), and you'll also need to reimplement any domain services you have used that Apache Isis provides "out-of-the-box" (eg xref:rgsvc.adoc#_rgsvc-api_QueryResultsCache[`QueryResultsCache`] domain service).
-
-
-
-
-
-== Deploy the REST API
-
-REST (Representation State Transfer) is an architectural style for building highly scalable distributed systems, using the same principles as the World Wide Web. Many commercial web APIs (twitter, facebook, Amazon) are implemented as either pure REST APIs or some approximation therein.
-
-The http://restfulobjects.org[Restful Objects specification] defines a means by a domain object model can be exposed as RESTful resources using JSON representations over HTTP. Apache Isis' xref:ugvro.adoc#[RestfulObjects viewer] is an implementation of that spec, making any Apache Isis domain object automatically available via REST.
-
-There are a number of use cases for deploying Isis as a REST API, including:
-
-* to allow a custom UI to be built against the RESTful API +
-+
-For example, using AngularJS or some other RIA technology such as Flex, JavaFX, Silverlight
-
-* to enable integration between systems +
-+
-REST is designed to be machine-readable, and so is an excellent choice for synchronous data interchange scenarios.
-
-* as a ready-made API for migrating data from one legacy system to its replacement.
-
-
-As for the auto-generated webapps, the framework manages object persistence. It is perfectly possible to deploy the REST API alongside an auto-generated webapp; both work from the same domain object model.
-
-
-
-
-
-== Implement your own viewer
-
-Isis' architecture was always designed to support multiple viewers; and indeed Apache Isis out-of-the-box supports two: the Wicket viewer, and the Restful Objects viewer (or three, if one includes the Wrapper Factory).
-
-While we mustn't understate the effort involved here, it is feasible to implement your own viewers too.  Indeed, one of Apache Isis' committers does indeed have a (closed source) viewer, based on http://www.wavemaker.com/[Wavemaker].
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy.adoc
deleted file mode 100644
index b31b507..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy.adoc
+++ /dev/null
@@ -1,21 +0,0 @@
-[[_ug_core-concepts_philosophy]]
-= Philosophy and Architecture
-: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 section describes some of the core ideas and architectural patterns upon which Apache Isis builds.
-
-include::_ug_core-concepts_philosophy_domain-driven-design.adoc[leveloffset=+1]
-
-include::_ug_core-concepts_philosophy_naked-objects-pattern.adoc[leveloffset=+1]
-
-include::_ug_core-concepts_philosophy_hexagonal-architecture.adoc[leveloffset=+1]
-
-include::_ug_core-concepts_philosophy_aop.adoc[leveloffset=+1]
-
-// include::_ug_core-concepts_philosophy_dci.adoc[leveloffset=+1]
-
-include::_ug_core-concepts_philosophy_how-eases-ddd.adoc[leveloffset=+1]
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_aop.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_aop.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_aop.adoc
deleted file mode 100644
index cf206fc..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_aop.adoc
+++ /dev/null
@@ -1,36 +0,0 @@
-[[_ug_core-concepts_philosophy_aop]]
-= Aspect Oriented
-: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/
-
-
-Although not a book about object modelling, Evans' "Domain Driven Design" does use object orientation as its primary modelling tool; while xref:ug.adoc#_ug_core-concepts_philosophy_naked-objects-pattern[naked objects pattern] very much comes from an OO background (it even has 'object' in its name); Richard Pawson lists Alan Kay as a key influence.
-
-It's certainly true that to develop an Apache Isis application you will need to have good object oriented modelling skills.  But given that all the mainstream languages for developing business systems are object oriented (Java, C#, Ruby), that's not such a stretch.
-
-However, what you'll also find as you write your applications is that in some ways an Isis application is more aspect-oriented than it is object oriented.  Given that aspect-orientation -- as a programming paradigm at least -- hasn't caught on, that statement probably needs unpacking a little.
-
-== AOP Concepts
-
-Aspect-orientation, then, is a different way of decomposing your application, by treating _cross-cutting concerns_ as a first-class citizen.  The canonical (also rather boring) example of a cross-cutting concern is that of logging (or tracing) all method calls.  An aspect can be written that will weave in some code (a logging statement) at specified points in the code).
-
-This idea sounds rather abstract, but what it really amounts to is the idea of interceptors.  When one method calls another the AOP code is called in first.  This is actually then one bit of AOP that is quite mainstream; DI containers such as Spring provide aspect orientation in supporting annotations such as `@Transactional` or `@Secured` to java beans.
-
-Another aspect (ahem!) of aspect-oriented programming has found its way into other programming languages, that of a mix-in or trait.  In languages such as Scala these mix-ins are specified statically as part of the inheritance hierarchy, whereas with AOP the binding of a trait to some other class/type is done without the class "knowing" that additional behaviour is being mixed-in to it.
-
-== Realization within Apache Isis
-
-What has all this to do with Apache Isis, then?
-
-Well, a different way to think of the naked objects pattern is that the visualization of a domain object within a UI is a cross-cutting concern.  By following certain very standard programming conventions that represent the _Apache Isis Programming Model_ (POJOs plus annotations), the framework is able to build a metamodel and from this can render your domain objects in a standard generic fashion.  That's a rather more interesting cross-cutting concern than boring old logging!
-
-Isis also draws heavily on the AOP concept of interceptors.  Whenever an object is rendered in the UI, it is filtered with respect to the user's permissions.  That is, if a user is not authorized to either view or perhaps modify an object, then this is applied transparently by the framework.  The http://github.com/isisaddons/isis-module-security[Isis addons' security] module, mentioned previously, provides a rich user/role/permissions subdomain to use out of the box; but you can integrate with a different security mechanism if you have one already.
-
-Another example of interceptors are the http://github.com/isisaddons/isis-module-command[Isis addons' command] and http://github.com/isisaddons/isis-module-audit[Isis addons' audit] modules.  The command module captures every user interaction that modifies the state of the system (the "cause" of a change) while the audit module captures every change to every object (the "effect" of a change).  Again, this is all transparent to the user.
-
-Apache Isis also has an internal event bus (you can switch between an underlying implementation of Gauva or Axon).  A domain event is fired whenever an object is interacted with, and this allows any subscribers to influence the operation (or even veto it).  This is a key mechanism in ensuring that Isis applications are maintainable, and we discuss it in depth in the section on  xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling[Decoupling].  But fundamentally its relying on this AOP concept of interceptors.
-
-Finally, Isis also a feature that is akin to AOP mix-ins.  A "contributed action" is one that is implemented on a domain service but that appears to be a behaviour of rendered domain object.  In other words, we can dissociate behaviour from data.  That's not always the right thing to do of course.  In Richard Pawson's description of the xref:ug.adoc#_ug_core-concepts_philosophy_naked-objects-pattern[naked objects pattern] he talks about "behaviourally rich" objects, in other words where the business functionality encapsulated the data.   But on the other hand sometimes the behaviour and data structures change at different rates.  The link:http://en.wikipedia.org/wiki/Single_responsibility_principle[single responsibility principle] says we should only lump code together that changes at the same rate.  Apache Isis' support for contributions (not only contributed actions, but also contributed properties and contributed collections) enables this.  And again, to loop back to the topic of
  this section, it's an AOP concept that being implemented by the framework.
-
-The nice thing about aspect orientation is that for the most part you can ignore these cross-cutting concerns and - at least initially at least - just focus on implementing your domain object.  Later when your app starts to grow and you start to break it out into smaller modules, you can leverage Apache Isis' AOP support for (xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling_mixins[mixins]), (xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling_contributions[contributions]) and interceptors (the xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling_event-bus[event bus]) to ensure that your codebase remains maintainable.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_dci.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_dci.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_dci.adoc
deleted file mode 100644
index 75d9786..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_dci.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-[[_ug_core-concepts_philosophy_dci]]
-= DCI
-: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/
-
-
-NOTE: TODO ... Trygve Reenskaug
-


[48/52] [abbrv] isis git commit: ISIS-1237, ISIS-1274: fix for Generation class, was ignoring domain services annotated as VIEW_REST_ONLY. Also enhanced simplified representation to return $$instanceId.

Posted by mg...@apache.org.
ISIS-1237, ISIS-1274: fix for Generation class, was ignoring domain services annotated as VIEW_REST_ONLY.  Also enhanced simplified representation to return $$instanceId.


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/94ccb54e
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/94ccb54e
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/94ccb54e

Branch: refs/heads/ISIS-1224-select2-v4
Commit: 94ccb54e85db68c1852d3b00afe2f01a3ce0e4e4
Parents: 2efbf48
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Sat Dec 12 16:15:54 2015 +0000
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Sat Dec 12 16:15:54 2015 +0000

----------------------------------------------------------------------
 .../services/swagger/internal/Generation.java   |   5 +-
 ...ontentNegotiationServiceOrgApacheIsisV1.java | 404 +++++++++++++++++++
 .../ContentNegotiationServiceSimplified.java    | 402 ------------------
 3 files changed, 407 insertions(+), 404 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/94ccb54e/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/Generation.java
----------------------------------------------------------------------
diff --git a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/Generation.java b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/Generation.java
index 1cce186..314b312 100644
--- a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/Generation.java
+++ b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/Generation.java
@@ -133,8 +133,9 @@ class Generation {
                     domainServiceFacet.getNatureOfService() != NatureOfService.VIEW_REST_ONLY) {
                 continue;
             }
-            if (domainServiceFacet.getNatureOfService() != NatureOfService.VIEW_MENU_ONLY &&
-                    domainServiceFacet.getNatureOfService() != NatureOfService.VIEW) {
+            if (    domainServiceFacet.getNatureOfService() != NatureOfService.VIEW_MENU_ONLY &&
+                    domainServiceFacet.getNatureOfService() != NatureOfService.VIEW &&
+                    domainServiceFacet.getNatureOfService() != NatureOfService.VIEW_REST_ONLY) {
                 continue;
             }
 

http://git-wip-us.apache.org/repos/asf/isis/blob/94ccb54e/core/viewer-restfulobjects-rendering/src/main/java/org/apache/isis/viewer/restfulobjects/rendering/service/conneg/ContentNegotiationServiceOrgApacheIsisV1.java
----------------------------------------------------------------------
diff --git a/core/viewer-restfulobjects-rendering/src/main/java/org/apache/isis/viewer/restfulobjects/rendering/service/conneg/ContentNegotiationServiceOrgApacheIsisV1.java b/core/viewer-restfulobjects-rendering/src/main/java/org/apache/isis/viewer/restfulobjects/rendering/service/conneg/ContentNegotiationServiceOrgApacheIsisV1.java
new file mode 100644
index 0000000..477f325
--- /dev/null
+++ b/core/viewer-restfulobjects-rendering/src/main/java/org/apache/isis/viewer/restfulobjects/rendering/service/conneg/ContentNegotiationServiceOrgApacheIsisV1.java
@@ -0,0 +1,404 @@
+/*
+ *  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.
+ */
+package org.apache.isis.viewer.restfulobjects.rendering.service.conneg;
+
+import java.util.Collection;
+import java.util.List;
+
+import javax.inject.Inject;
+import javax.ws.rs.core.MediaType;
+import javax.ws.rs.core.Response;
+
+import org.apache.isis.applib.DomainObjectContainer;
+import org.apache.isis.applib.annotation.DomainService;
+import org.apache.isis.applib.annotation.DomainServiceLayout;
+import org.apache.isis.applib.annotation.NatureOfService;
+import org.apache.isis.applib.annotation.Programmatic;
+import org.apache.isis.applib.annotation.Where;
+import org.apache.isis.core.metamodel.adapter.ObjectAdapter;
+import org.apache.isis.core.metamodel.consent.Consent;
+import org.apache.isis.core.metamodel.consent.InteractionInitiatedBy;
+import org.apache.isis.core.metamodel.facets.collections.modify.CollectionFacet;
+import org.apache.isis.core.metamodel.facets.collections.modify.CollectionFacetUtils;
+import org.apache.isis.core.metamodel.spec.ObjectSpecification;
+import org.apache.isis.core.metamodel.spec.feature.Contributed;
+import org.apache.isis.core.metamodel.spec.feature.OneToManyAssociation;
+import org.apache.isis.core.metamodel.spec.feature.OneToOneAssociation;
+import org.apache.isis.viewer.restfulobjects.applib.JsonRepresentation;
+import org.apache.isis.viewer.restfulobjects.applib.domainobjects.ActionResultRepresentation;
+import org.apache.isis.viewer.restfulobjects.rendering.RendererContext;
+import org.apache.isis.viewer.restfulobjects.rendering.domainobjects.ObjectAndAction;
+import org.apache.isis.viewer.restfulobjects.rendering.domainobjects.ObjectAndActionInvocation;
+import org.apache.isis.viewer.restfulobjects.rendering.domainobjects.ObjectAndCollection;
+import org.apache.isis.viewer.restfulobjects.rendering.domainobjects.ObjectAndProperty;
+import org.apache.isis.viewer.restfulobjects.rendering.domainobjects.ObjectPropertyReprRenderer;
+import org.apache.isis.viewer.restfulobjects.rendering.service.RepresentationService;
+
+@DomainService(
+        nature = NatureOfService.DOMAIN
+)
+@DomainServiceLayout(
+        menuOrder = "1500"
+)
+public class ContentNegotiationServiceOrgApacheIsisV1 extends ContentNegotiationServiceAbstract {
+
+    /**
+     * Unlike RO v1.0, use a single content-type of <code>application/json;profile="urn:org.apache.isis/v1"</code>.
+     *
+     * <p>
+     * The response content types ({@link #CONTENT_TYPE_OAI_V1_OBJECT}, {@link #CONTENT_TYPE_OAI_V1_OBJECT_COLLECTION},
+     * {@link #CONTENT_TYPE_OAI_V1_LIST}) append the 'repr-type' parameter.
+     * </p>
+     */
+    public static final String ACCEPT_PROFILE = "urn:org.apache.isis/v1";
+
+    /**
+     * Whether to suppress the RO v1.0 '$$ro' node; suppress='false' or suppress='true'
+     */
+    public static final String ACCEPT_RO = "suppress";
+
+    /**
+     * The media type (as a string) used as the content-Type header when a domain object is rendered.
+     *
+     * @see #ACCEPT_PROFILE for discussion.
+     */
+    public static final String CONTENT_TYPE_OAI_V1_OBJECT = "application/json;"
+            + "profile=\"" + ACCEPT_PROFILE + "\""
+            + ";repr-type=\"object\""
+            ;
+    /**
+     * The media type (as a string) used as the content-Type header when a parented collection is rendered.
+     *
+     * @see #ACCEPT_PROFILE for discussion.
+     */
+    public static final String CONTENT_TYPE_OAI_V1_OBJECT_COLLECTION = "application/json;"
+            + "profile=\"" + ACCEPT_PROFILE + "\""
+            + ";repr-type=\"object-collection\""
+            ;
+    /**
+     * The media type (as a string) used as the content-Type header when a standalone collection is rendered.
+     *
+     * @see #ACCEPT_PROFILE for discussion.
+     */
+    public static final String CONTENT_TYPE_OAI_V1_LIST = "application/json;"
+            + "profile=\"" + ACCEPT_PROFILE + "\""
+            + ";repr-type=\"list\""
+            ;
+
+    private ContentNegotiationServiceForRestfulObjectsV1_0 restfulObjectsV1_0 = new ContentNegotiationServiceForRestfulObjectsV1_0();
+
+    /**
+     * Domain object is returned as a map with the RO 1.0 representation as a special '$$ro' property
+     * within that map.
+     */
+    public Response.ResponseBuilder buildResponse(
+            final RepresentationService.Context2 rendererContext,
+            final ObjectAdapter objectAdapter) {
+
+        boolean canAccept = canAccept(rendererContext);
+        if(!canAccept) {
+            return null;
+        }
+        boolean suppressRO = suppress(rendererContext);
+
+        final JsonRepresentation rootRepresentation = JsonRepresentation.newMap();
+
+        appendObjectTo(rendererContext, objectAdapter, rootRepresentation);
+
+        final JsonRepresentation $$roRepresentation;
+        if(!suppressRO) {
+            $$roRepresentation = JsonRepresentation.newMap();
+            rootRepresentation.mapPut("$$ro", $$roRepresentation);
+        } else {
+            $$roRepresentation = null;
+        }
+        final Response.ResponseBuilder responseBuilder =
+                restfulObjectsV1_0.buildResponseTo(
+                        rendererContext, objectAdapter, $$roRepresentation, rootRepresentation);
+
+        responseBuilder.type(CONTENT_TYPE_OAI_V1_OBJECT);
+
+        return responseBuilder(responseBuilder);
+    }
+
+    /**
+     * Individual property of an object is not supported.
+     */
+    @Programmatic
+    public Response.ResponseBuilder buildResponse(
+            final RepresentationService.Context2 rendererContext,
+            final ObjectAndProperty objectAndProperty)  {
+
+        return null;
+    }
+
+    /**
+     * Individual (parented) collection of an object is returned as a list with the RO representation
+     * as an object in the list with a single property named '$$ro'
+     */
+    @Programmatic
+    public Response.ResponseBuilder buildResponse(
+            final RepresentationService.Context2 rendererContext,
+            final ObjectAndCollection objectAndCollection) {
+
+        if(!canAccept(rendererContext)) {
+            return null;
+        }
+        boolean suppressRO = suppress(rendererContext);
+
+        final JsonRepresentation rootRepresentation = JsonRepresentation.newArray();
+
+        ObjectAdapter objectAdapter = objectAndCollection.getObjectAdapter();
+        OneToManyAssociation collection = objectAndCollection.getMember();
+
+        appendCollectionTo(rendererContext, objectAdapter, collection, rootRepresentation);
+
+        final JsonRepresentation $$roRepresentation;
+        if(!suppressRO) {
+            // $$ro representation will be an object in the list with a single property named "$$ro"
+            final JsonRepresentation $$roContainerRepresentation = JsonRepresentation.newMap();
+            rootRepresentation.arrayAdd($$roContainerRepresentation);
+
+            $$roRepresentation = JsonRepresentation.newMap();
+            $$roContainerRepresentation.mapPut("$$ro", $$roRepresentation);
+        } else {
+            $$roRepresentation = null;
+        }
+
+        final Response.ResponseBuilder responseBuilder =
+                restfulObjectsV1_0.buildResponseTo(
+                        rendererContext, objectAndCollection, $$roRepresentation, rootRepresentation);
+
+        responseBuilder.type(CONTENT_TYPE_OAI_V1_OBJECT_COLLECTION);
+
+        return responseBuilder(responseBuilder);
+    }
+
+    /**
+     * Action prompt is not supported.
+     */
+    @Programmatic
+    public Response.ResponseBuilder buildResponse(
+            final RepresentationService.Context2 rendererContext,
+            final ObjectAndAction objectAndAction)  {
+        return null;
+    }
+
+    /**
+     * Action invocation is supported provided it returns a single domain object or a list of domain objects
+     * (ie invocations returning void or scalar value are not supported).
+     *
+     * Action invocations returning a domain object will be rendered as a map with the RO v1.0 representation as a
+     * '$$ro' property within (same as {@link #buildResponse(RepresentationService.Context2, ObjectAdapter)}), while
+     * action invocations returning a list will be rendered as a list with the RO v1.0 representation as a map object
+     * with a single '$$ro' property (similar to {@link #buildResponse(RepresentationService.Context2, ObjectAndCollection)})
+     */
+    @Programmatic
+    public Response.ResponseBuilder buildResponse(
+            final RepresentationService.Context2 rendererContext,
+            final ObjectAndActionInvocation objectAndActionInvocation) {
+
+        if(!canAccept(rendererContext)) {
+            return null;
+        }
+        boolean suppressRO = suppress(rendererContext);
+
+        JsonRepresentation rootRepresentation = null;
+        final JsonRepresentation $$roRepresentation;
+        if(!suppressRO) {
+            $$roRepresentation = JsonRepresentation.newMap();
+        } else {
+            $$roRepresentation = null;
+        }
+
+        final ObjectAdapter returnedAdapter = objectAndActionInvocation.getReturnedAdapter();
+        final ObjectSpecification returnType = objectAndActionInvocation.getAction().getReturnType();
+
+        if (returnedAdapter == null) {
+            return null;
+        }
+
+        final ActionResultRepresentation.ResultType resultType = objectAndActionInvocation.determineResultType();
+        switch (resultType) {
+            case DOMAIN_OBJECT:
+
+                rootRepresentation = JsonRepresentation.newMap();
+                appendObjectTo(rendererContext, returnedAdapter, rootRepresentation);
+
+                break;
+
+            case LIST:
+
+                rootRepresentation = JsonRepresentation.newArray();
+
+                final CollectionFacet collectionFacet = returnType.getFacet(CollectionFacet.class);
+                final Collection<ObjectAdapter> collectionAdapters = collectionFacet.collection(returnedAdapter);
+                appendIterableTo(rendererContext, collectionAdapters, rootRepresentation);
+
+                // $$ro representation will be an object in the list with a single property named "$$ro"
+                if(!suppressRO) {
+                    JsonRepresentation $$roContainerRepresentation = JsonRepresentation.newMap();
+                    rootRepresentation.arrayAdd($$roContainerRepresentation);
+                    $$roContainerRepresentation.mapPut("$$ro", $$roRepresentation);
+                }
+
+                break;
+
+            case SCALAR_VALUE:
+            case VOID:
+
+                // not supported
+                return null;
+        }
+
+        final Response.ResponseBuilder responseBuilder =
+                restfulObjectsV1_0.buildResponseTo(
+                        rendererContext, objectAndActionInvocation, $$roRepresentation, rootRepresentation);
+
+        // set appropriate Content-Type
+        responseBuilder.type(
+                resultType == ActionResultRepresentation.ResultType.DOMAIN_OBJECT
+                        ? CONTENT_TYPE_OAI_V1_OBJECT
+                        : CONTENT_TYPE_OAI_V1_LIST
+        );
+
+        return responseBuilder(responseBuilder);
+    }
+
+    /**
+     * For easy subclassing to further customize, eg additional headers
+     */
+    protected Response.ResponseBuilder responseBuilder(final Response.ResponseBuilder responseBuilder) {
+        return responseBuilder;
+    }
+
+    boolean canAccept(final RepresentationService.Context2 rendererContext) {
+        final List<MediaType> acceptableMediaTypes = rendererContext.getAcceptableMediaTypes();
+        return mediaTypeParameterMatches(acceptableMediaTypes, "profile", ACCEPT_PROFILE);
+    }
+
+    protected boolean suppress(
+            final RepresentationService.Context2 rendererContext) {
+        final List<MediaType> acceptableMediaTypes = rendererContext.getAcceptableMediaTypes();
+        return mediaTypeParameterMatches(acceptableMediaTypes, "suppress", "true");
+    }
+
+    private void appendObjectTo(
+            final RepresentationService.Context2 rendererContext,
+            final ObjectAdapter objectAdapter,
+            final JsonRepresentation rootRepresentation) {
+
+        appendPropertiesTo(rendererContext, objectAdapter, rootRepresentation);
+
+        final List<OneToManyAssociation> collections = objectAdapter.getSpecification().getCollections(Contributed.INCLUDED);
+        final Where where = rendererContext.getWhere();
+        for (final OneToManyAssociation collection : collections) {
+
+            final JsonRepresentation collectionRepresentation = JsonRepresentation.newArray();
+
+            rootRepresentation.mapPut(collection.getId(), collectionRepresentation);
+
+            final InteractionInitiatedBy interactionInitiatedBy = determineInteractionInitiatedByFrom(rendererContext);
+            final Consent visibility = collection.isVisible(objectAdapter, interactionInitiatedBy, where);
+            if (!visibility.isAllowed()) {
+                continue;
+            }
+
+            appendCollectionTo(rendererContext, objectAdapter, collection, collectionRepresentation);
+        }
+    }
+
+    private void appendPropertiesTo(
+            final RepresentationService.Context2 rendererContext,
+            final ObjectAdapter objectAdapter,
+            final JsonRepresentation rootRepresentation) {
+        final InteractionInitiatedBy interactionInitiatedBy = determineInteractionInitiatedByFrom(rendererContext);
+        final Where where = rendererContext.getWhere();
+        List<OneToOneAssociation> properties = objectAdapter.getSpecification().getProperties(Contributed.INCLUDED);
+        for (final OneToOneAssociation property : properties) {
+
+            final Consent visibility = property.isVisible(objectAdapter, interactionInitiatedBy, where);
+            if (!visibility.isAllowed()) {
+                continue;
+            }
+
+            final JsonRepresentation propertyRepresentation = JsonRepresentation.newMap();
+            final ObjectPropertyReprRenderer renderer =
+                    new ObjectPropertyReprRenderer(rendererContext, null, property.getId(), propertyRepresentation)
+                        .asStandalone();
+            renderer.with(new ObjectAndProperty(objectAdapter, property));
+
+            final JsonRepresentation propertyValueRepresentation = renderer.render();
+
+            final String upHref = propertyValueRepresentation.getString("links[rel=up].href");
+            rootRepresentation.mapPut("$$href", upHref);
+            final String upTitle = propertyValueRepresentation.getString("links[rel=up].title");
+            rootRepresentation.mapPut("$$title", upTitle);
+            final String upInstanceId = upHref.substring(upHref.lastIndexOf("/")+1);
+            rootRepresentation.mapPut("$$instanceId", upInstanceId);
+
+            final JsonRepresentation value = propertyValueRepresentation.getRepresentation("value");
+            rootRepresentation.mapPut(property.getId(), value);
+        }
+    }
+
+    private void appendCollectionTo(
+            final RepresentationService.Context2 rendererContext,
+            final ObjectAdapter objectAdapter,
+            final OneToManyAssociation collection,
+            final JsonRepresentation representation) {
+
+        final InteractionInitiatedBy interactionInitiatedBy = determineInteractionInitiatedByFrom(rendererContext);
+        final ObjectAdapter valueAdapter = collection.get(objectAdapter, interactionInitiatedBy);
+        if (valueAdapter == null) {
+            return;
+        }
+
+        final CollectionFacet facet = CollectionFacetUtils.getCollectionFacetFromSpec(valueAdapter);
+        final Iterable<ObjectAdapter> iterable = facet.iterable(valueAdapter);
+        appendIterableTo(rendererContext, iterable, representation);
+    }
+
+    private void appendIterableTo(
+            final RepresentationService.Context2 rendererContext,
+            final Iterable<ObjectAdapter> iterable,
+            final JsonRepresentation collectionRepresentation) {
+        for (final ObjectAdapter elementAdapter : iterable) {
+
+            JsonRepresentation elementRepresentation = JsonRepresentation.newMap();
+            appendPropertiesTo(rendererContext, elementAdapter, elementRepresentation);
+
+            collectionRepresentation.arrayAdd(elementRepresentation);
+        }
+    }
+
+    private static InteractionInitiatedBy determineInteractionInitiatedByFrom(
+            final RendererContext rendererContext) {
+        if (rendererContext instanceof RepresentationService.Context4) {
+            return ((RepresentationService.Context4) rendererContext).getInteractionInitiatedBy();
+        } else {
+            // fallback
+            return InteractionInitiatedBy.USER;
+        }
+    }
+
+
+    @Inject
+    protected DomainObjectContainer container;
+}

http://git-wip-us.apache.org/repos/asf/isis/blob/94ccb54e/core/viewer-restfulobjects-rendering/src/main/java/org/apache/isis/viewer/restfulobjects/rendering/service/conneg/ContentNegotiationServiceSimplified.java
----------------------------------------------------------------------
diff --git a/core/viewer-restfulobjects-rendering/src/main/java/org/apache/isis/viewer/restfulobjects/rendering/service/conneg/ContentNegotiationServiceSimplified.java b/core/viewer-restfulobjects-rendering/src/main/java/org/apache/isis/viewer/restfulobjects/rendering/service/conneg/ContentNegotiationServiceSimplified.java
deleted file mode 100644
index 2d774aa..0000000
--- a/core/viewer-restfulobjects-rendering/src/main/java/org/apache/isis/viewer/restfulobjects/rendering/service/conneg/ContentNegotiationServiceSimplified.java
+++ /dev/null
@@ -1,402 +0,0 @@
-/*
- *  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.
- */
-package org.apache.isis.viewer.restfulobjects.rendering.service.conneg;
-
-import java.util.Collection;
-import java.util.List;
-
-import javax.inject.Inject;
-import javax.ws.rs.core.MediaType;
-import javax.ws.rs.core.Response;
-
-import org.apache.isis.applib.DomainObjectContainer;
-import org.apache.isis.applib.annotation.DomainService;
-import org.apache.isis.applib.annotation.DomainServiceLayout;
-import org.apache.isis.applib.annotation.NatureOfService;
-import org.apache.isis.applib.annotation.Programmatic;
-import org.apache.isis.applib.annotation.Where;
-import org.apache.isis.core.metamodel.adapter.ObjectAdapter;
-import org.apache.isis.core.metamodel.consent.Consent;
-import org.apache.isis.core.metamodel.consent.InteractionInitiatedBy;
-import org.apache.isis.core.metamodel.facets.collections.modify.CollectionFacet;
-import org.apache.isis.core.metamodel.facets.collections.modify.CollectionFacetUtils;
-import org.apache.isis.core.metamodel.spec.ObjectSpecification;
-import org.apache.isis.core.metamodel.spec.feature.Contributed;
-import org.apache.isis.core.metamodel.spec.feature.OneToManyAssociation;
-import org.apache.isis.core.metamodel.spec.feature.OneToOneAssociation;
-import org.apache.isis.viewer.restfulobjects.applib.JsonRepresentation;
-import org.apache.isis.viewer.restfulobjects.applib.domainobjects.ActionResultRepresentation;
-import org.apache.isis.viewer.restfulobjects.rendering.RendererContext;
-import org.apache.isis.viewer.restfulobjects.rendering.domainobjects.ObjectAndAction;
-import org.apache.isis.viewer.restfulobjects.rendering.domainobjects.ObjectAndActionInvocation;
-import org.apache.isis.viewer.restfulobjects.rendering.domainobjects.ObjectAndCollection;
-import org.apache.isis.viewer.restfulobjects.rendering.domainobjects.ObjectAndProperty;
-import org.apache.isis.viewer.restfulobjects.rendering.domainobjects.ObjectPropertyReprRenderer;
-import org.apache.isis.viewer.restfulobjects.rendering.service.RepresentationService;
-
-@DomainService(
-        nature = NatureOfService.DOMAIN
-)
-@DomainServiceLayout(
-        menuOrder = "1500"
-)
-public class ContentNegotiationServiceSimplified extends ContentNegotiationServiceAbstract {
-
-    /**
-     * Unlike RO v1.0, use a single content-type of <code>application/json;profile="urn:org.apache.isis/v1"</code>.
-     *
-     * <p>
-     * The response content types ({@link #CONTENT_TYPE_OAI_V1_OBJECT}, {@link #CONTENT_TYPE_OAI_V1_OBJECT_COLLECTION},
-     * {@link #CONTENT_TYPE_OAI_V1_LIST}) append the 'repr-type' parameter.
-     * </p>
-     */
-    public static final String ACCEPT_PROFILE = "urn:org.apache.isis/v1";
-
-    /**
-     * Whether to suppress the RO v1.0 '$$ro' node; suppress='false' or suppress='true'
-     */
-    public static final String ACCEPT_RO = "suppress";
-
-    /**
-     * The media type (as a string) used as the content-Type header when a domain object is rendered.
-     *
-     * @see #ACCEPT_PROFILE for discussion.
-     */
-    public static final String CONTENT_TYPE_OAI_V1_OBJECT = "application/json;"
-            + "profile=\"" + ACCEPT_PROFILE + "\""
-            + ";repr-type=\"object\""
-            ;
-    /**
-     * The media type (as a string) used as the content-Type header when a parented collection is rendered.
-     *
-     * @see #ACCEPT_PROFILE for discussion.
-     */
-    public static final String CONTENT_TYPE_OAI_V1_OBJECT_COLLECTION = "application/json;"
-            + "profile=\"" + ACCEPT_PROFILE + "\""
-            + ";repr-type=\"object-collection\""
-            ;
-    /**
-     * The media type (as a string) used as the content-Type header when a standalone collection is rendered.
-     *
-     * @see #ACCEPT_PROFILE for discussion.
-     */
-    public static final String CONTENT_TYPE_OAI_V1_LIST = "application/json;"
-            + "profile=\"" + ACCEPT_PROFILE + "\""
-            + ";repr-type=\"list\""
-            ;
-
-    private ContentNegotiationServiceForRestfulObjectsV1_0 restfulObjectsV1_0 = new ContentNegotiationServiceForRestfulObjectsV1_0();
-
-    /**
-     * Domain object is returned as a map with the RO 1.0 representation as a special '$$ro' property
-     * within that map.
-     */
-    public Response.ResponseBuilder buildResponse(
-            final RepresentationService.Context2 rendererContext,
-            final ObjectAdapter objectAdapter) {
-
-        boolean canAccept = canAccept(rendererContext);
-        if(!canAccept) {
-            return null;
-        }
-        boolean suppressRO = suppress(rendererContext);
-
-        final JsonRepresentation rootRepresentation = JsonRepresentation.newMap();
-
-        appendObjectTo(rendererContext, objectAdapter, rootRepresentation);
-
-        final JsonRepresentation $$roRepresentation;
-        if(!suppressRO) {
-            $$roRepresentation = JsonRepresentation.newMap();
-            rootRepresentation.mapPut("$$ro", $$roRepresentation);
-        } else {
-            $$roRepresentation = null;
-        }
-        final Response.ResponseBuilder responseBuilder =
-                restfulObjectsV1_0.buildResponseTo(
-                        rendererContext, objectAdapter, $$roRepresentation, rootRepresentation);
-
-        responseBuilder.type(CONTENT_TYPE_OAI_V1_OBJECT);
-
-        return responseBuilder(responseBuilder);
-    }
-
-    /**
-     * Individual property of an object is not supported.
-     */
-    @Programmatic
-    public Response.ResponseBuilder buildResponse(
-            final RepresentationService.Context2 rendererContext,
-            final ObjectAndProperty objectAndProperty)  {
-
-        return null;
-    }
-
-    /**
-     * Individual (parented) collection of an object is returned as a list with the RO representation
-     * as an object in the list with a single property named '$$ro'
-     */
-    @Programmatic
-    public Response.ResponseBuilder buildResponse(
-            final RepresentationService.Context2 rendererContext,
-            final ObjectAndCollection objectAndCollection) {
-
-        if(!canAccept(rendererContext)) {
-            return null;
-        }
-        boolean suppressRO = suppress(rendererContext);
-
-        final JsonRepresentation rootRepresentation = JsonRepresentation.newArray();
-
-        ObjectAdapter objectAdapter = objectAndCollection.getObjectAdapter();
-        OneToManyAssociation collection = objectAndCollection.getMember();
-
-        appendCollectionTo(rendererContext, objectAdapter, collection, rootRepresentation);
-
-        final JsonRepresentation $$roRepresentation;
-        if(!suppressRO) {
-            // $$ro representation will be an object in the list with a single property named "$$ro"
-            final JsonRepresentation $$roContainerRepresentation = JsonRepresentation.newMap();
-            rootRepresentation.arrayAdd($$roContainerRepresentation);
-
-            $$roRepresentation = JsonRepresentation.newMap();
-            $$roContainerRepresentation.mapPut("$$ro", $$roRepresentation);
-        } else {
-            $$roRepresentation = null;
-        }
-
-        final Response.ResponseBuilder responseBuilder =
-                restfulObjectsV1_0.buildResponseTo(
-                        rendererContext, objectAndCollection, $$roRepresentation, rootRepresentation);
-
-        responseBuilder.type(CONTENT_TYPE_OAI_V1_OBJECT_COLLECTION);
-
-        return responseBuilder(responseBuilder);
-    }
-
-    /**
-     * Action prompt is not supported.
-     */
-    @Programmatic
-    public Response.ResponseBuilder buildResponse(
-            final RepresentationService.Context2 rendererContext,
-            final ObjectAndAction objectAndAction)  {
-        return null;
-    }
-
-    /**
-     * Action invocation is supported provided it returns a single domain object or a list of domain objects
-     * (ie invocations returning void or scalar value are not supported).
-     *
-     * Action invocations returning a domain object will be rendered as a map with the RO v1.0 representation as a
-     * '$$ro' property within (same as {@link #buildResponse(RepresentationService.Context2, ObjectAdapter)}), while
-     * action invocations returning a list will be rendered as a list with the RO v1.0 representation as a map object
-     * with a single '$$ro' property (similar to {@link #buildResponse(RepresentationService.Context2, ObjectAndCollection)})
-     */
-    @Programmatic
-    public Response.ResponseBuilder buildResponse(
-            final RepresentationService.Context2 rendererContext,
-            final ObjectAndActionInvocation objectAndActionInvocation) {
-
-        if(!canAccept(rendererContext)) {
-            return null;
-        }
-        boolean suppressRO = suppress(rendererContext);
-
-        JsonRepresentation rootRepresentation = null;
-        final JsonRepresentation $$roRepresentation;
-        if(!suppressRO) {
-            $$roRepresentation = JsonRepresentation.newMap();
-        } else {
-            $$roRepresentation = null;
-        }
-
-        final ObjectAdapter returnedAdapter = objectAndActionInvocation.getReturnedAdapter();
-        final ObjectSpecification returnType = objectAndActionInvocation.getAction().getReturnType();
-
-        if (returnedAdapter == null) {
-            return null;
-        }
-
-        final ActionResultRepresentation.ResultType resultType = objectAndActionInvocation.determineResultType();
-        switch (resultType) {
-            case DOMAIN_OBJECT:
-
-                rootRepresentation = JsonRepresentation.newMap();
-                appendObjectTo(rendererContext, returnedAdapter, rootRepresentation);
-
-                break;
-
-            case LIST:
-
-                rootRepresentation = JsonRepresentation.newArray();
-
-                final CollectionFacet collectionFacet = returnType.getFacet(CollectionFacet.class);
-                final Collection<ObjectAdapter> collectionAdapters = collectionFacet.collection(returnedAdapter);
-                appendIterableTo(rendererContext, collectionAdapters, rootRepresentation);
-
-                // $$ro representation will be an object in the list with a single property named "$$ro"
-                if(!suppressRO) {
-                    JsonRepresentation $$roContainerRepresentation = JsonRepresentation.newMap();
-                    rootRepresentation.arrayAdd($$roContainerRepresentation);
-                    $$roContainerRepresentation.mapPut("$$ro", $$roRepresentation);
-                }
-
-                break;
-
-            case SCALAR_VALUE:
-            case VOID:
-
-                // not supported
-                return null;
-        }
-
-        final Response.ResponseBuilder responseBuilder =
-                restfulObjectsV1_0.buildResponseTo(
-                        rendererContext, objectAndActionInvocation, $$roRepresentation, rootRepresentation);
-
-        // set appropriate Content-Type
-        responseBuilder.type(
-                resultType == ActionResultRepresentation.ResultType.DOMAIN_OBJECT
-                        ? CONTENT_TYPE_OAI_V1_OBJECT
-                        : CONTENT_TYPE_OAI_V1_LIST
-        );
-
-        return responseBuilder(responseBuilder);
-    }
-
-    /**
-     * For easy subclassing to further customize, eg additional headers
-     */
-    protected Response.ResponseBuilder responseBuilder(final Response.ResponseBuilder responseBuilder) {
-        return responseBuilder;
-    }
-
-    boolean canAccept(final RepresentationService.Context2 rendererContext) {
-        final List<MediaType> acceptableMediaTypes = rendererContext.getAcceptableMediaTypes();
-        return mediaTypeParameterMatches(acceptableMediaTypes, "profile", ACCEPT_PROFILE);
-    }
-
-    protected boolean suppress(
-            final RepresentationService.Context2 rendererContext) {
-        final List<MediaType> acceptableMediaTypes = rendererContext.getAcceptableMediaTypes();
-        return mediaTypeParameterMatches(acceptableMediaTypes, "suppress", "true");
-    }
-
-    private void appendObjectTo(
-            final RepresentationService.Context2 rendererContext,
-            final ObjectAdapter objectAdapter,
-            final JsonRepresentation rootRepresentation) {
-
-        appendPropertiesTo(rendererContext, objectAdapter, rootRepresentation);
-
-        final List<OneToManyAssociation> collections = objectAdapter.getSpecification().getCollections(Contributed.INCLUDED);
-        final Where where = rendererContext.getWhere();
-        for (final OneToManyAssociation collection : collections) {
-
-            final JsonRepresentation collectionRepresentation = JsonRepresentation.newArray();
-
-            rootRepresentation.mapPut(collection.getId(), collectionRepresentation);
-
-            final InteractionInitiatedBy interactionInitiatedBy = determineInteractionInitiatedByFrom(rendererContext);
-            final Consent visibility = collection.isVisible(objectAdapter, interactionInitiatedBy, where);
-            if (!visibility.isAllowed()) {
-                continue;
-            }
-
-            appendCollectionTo(rendererContext, objectAdapter, collection, collectionRepresentation);
-        }
-    }
-
-    private void appendPropertiesTo(
-            final RepresentationService.Context2 rendererContext,
-            final ObjectAdapter objectAdapter,
-            final JsonRepresentation rootRepresentation) {
-        final InteractionInitiatedBy interactionInitiatedBy = determineInteractionInitiatedByFrom(rendererContext);
-        final Where where = rendererContext.getWhere();
-        List<OneToOneAssociation> properties = objectAdapter.getSpecification().getProperties(Contributed.INCLUDED);
-        for (final OneToOneAssociation property : properties) {
-
-            final Consent visibility = property.isVisible(objectAdapter, interactionInitiatedBy, where);
-            if (!visibility.isAllowed()) {
-                continue;
-            }
-
-            final JsonRepresentation propertyRepresentation = JsonRepresentation.newMap();
-            final ObjectPropertyReprRenderer renderer =
-                    new ObjectPropertyReprRenderer(rendererContext, null, property.getId(), propertyRepresentation)
-                        .asStandalone();
-            renderer.with(new ObjectAndProperty(objectAdapter, property));
-
-            final JsonRepresentation propertyValueRepresentation = renderer.render();
-
-            final String upHref = propertyValueRepresentation.getString("links[rel=up].href");
-            rootRepresentation.mapPut("$$href", upHref);
-            final String upTitle = propertyValueRepresentation.getString("links[rel=up].title");
-            rootRepresentation.mapPut("$$title", upTitle);
-
-            final JsonRepresentation value = propertyValueRepresentation.getRepresentation("value");
-            rootRepresentation.mapPut(property.getId(), value);
-        }
-    }
-
-    private void appendCollectionTo(
-            final RepresentationService.Context2 rendererContext,
-            final ObjectAdapter objectAdapter,
-            final OneToManyAssociation collection,
-            final JsonRepresentation representation) {
-
-        final InteractionInitiatedBy interactionInitiatedBy = determineInteractionInitiatedByFrom(rendererContext);
-        final ObjectAdapter valueAdapter = collection.get(objectAdapter, interactionInitiatedBy);
-        if (valueAdapter == null) {
-            return;
-        }
-
-        final CollectionFacet facet = CollectionFacetUtils.getCollectionFacetFromSpec(valueAdapter);
-        final Iterable<ObjectAdapter> iterable = facet.iterable(valueAdapter);
-        appendIterableTo(rendererContext, iterable, representation);
-    }
-
-    private void appendIterableTo(
-            final RepresentationService.Context2 rendererContext,
-            final Iterable<ObjectAdapter> iterable,
-            final JsonRepresentation collectionRepresentation) {
-        for (final ObjectAdapter elementAdapter : iterable) {
-
-            JsonRepresentation elementRepresentation = JsonRepresentation.newMap();
-            appendPropertiesTo(rendererContext, elementAdapter, elementRepresentation);
-
-            collectionRepresentation.arrayAdd(elementRepresentation);
-        }
-    }
-
-    private static InteractionInitiatedBy determineInteractionInitiatedByFrom(
-            final RendererContext rendererContext) {
-        if (rendererContext instanceof RepresentationService.Context4) {
-            return ((RepresentationService.Context4) rendererContext).getInteractionInitiatedBy();
-        } else {
-            // fallback
-            return InteractionInitiatedBy.USER;
-        }
-    }
-
-
-    @Inject
-    protected DomainObjectContainer container;
-}


[49/52] [abbrv] isis git commit: Code cleanup (no functional changes!):

Posted by mg...@apache.org.
Code cleanup (no functional changes!):

- remove implicit modifiers for interface methods and static inner classes
- Java 7 diamonds


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/4e21fbc4
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/4e21fbc4
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/4e21fbc4

Branch: refs/heads/ISIS-1224-select2-v4
Commit: 4e21fbc45ea7e10162aad2d803801fc271c919ea
Parents: 94ccb54
Author: Martin Tzvetanov Grigorov <mg...@apache.org>
Authored: Sun Dec 13 10:26:03 2015 +0100
Committer: Martin Tzvetanov Grigorov <mg...@apache.org>
Committed: Sun Dec 13 10:26:03 2015 +0100

----------------------------------------------------------------------
 .../core/metamodel/facets/ContributeeMemberFacetFactory.java   | 3 +--
 .../core/metamodel/facets/object/parseable/ParseableFacet.java | 2 +-
 .../metamodel/facets/objectvalue/multiline/MultiLineFacet.java | 4 ++--
 .../apache/isis/core/metamodel/progmodel/ProgrammingModel.java | 6 +++---
 .../core/metamodel/specloader/specimpl/ContributeeMember.java  | 2 +-
 .../ShiroAuthenticatorOrAuthorizorTest_isVisibleInAnyRole.java | 3 ---
 .../wicket/ui/components/scalars/ScalarPanelAbstract.java      | 4 ++--
 .../scalars/ScalarPanelTextFieldParseableAbstract.java         | 2 +-
 8 files changed, 11 insertions(+), 15 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/4e21fbc4/core/metamodel/src/main/java/org/apache/isis/core/metamodel/facets/ContributeeMemberFacetFactory.java
----------------------------------------------------------------------
diff --git a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/facets/ContributeeMemberFacetFactory.java b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/facets/ContributeeMemberFacetFactory.java
index 4bf6662..05a6719 100644
--- a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/facets/ContributeeMemberFacetFactory.java
+++ b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/facets/ContributeeMemberFacetFactory.java
@@ -26,7 +26,6 @@ import com.google.common.collect.Lists;
 
 import org.apache.isis.applib.Identifier;
 import org.apache.isis.core.commons.lang.PropertiesExtensions;
-import org.apache.isis.core.metamodel.facets.members.order.MemberOrderFacet;
 import org.apache.isis.core.metamodel.spec.feature.ObjectAction;
 import org.apache.isis.core.metamodel.spec.feature.ObjectMember;
 import org.apache.isis.core.metamodel.spec.feature.OneToManyAssociation;
@@ -38,7 +37,7 @@ import org.apache.isis.core.metamodel.specloader.specimpl.ContributeeMember;
  */
 public interface ContributeeMemberFacetFactory extends FacetFactory {
 
-    public static class ProcessContributeeMemberContext extends AbstractProcessContext<ObjectMember> 
+    class ProcessContributeeMemberContext extends AbstractProcessContext<ObjectMember>
             implements ProcessContextWithMetadataProperties<ObjectMember> {
         
         private final Properties metadataProperties;

http://git-wip-us.apache.org/repos/asf/isis/blob/4e21fbc4/core/metamodel/src/main/java/org/apache/isis/core/metamodel/facets/object/parseable/ParseableFacet.java
----------------------------------------------------------------------
diff --git a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/facets/object/parseable/ParseableFacet.java b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/facets/object/parseable/ParseableFacet.java
index 4e63686..8650427 100644
--- a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/facets/object/parseable/ParseableFacet.java
+++ b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/facets/object/parseable/ParseableFacet.java
@@ -58,5 +58,5 @@ public interface ParseableFacet extends MultipleValueFacet {
      * field. So, a date might be rendered via a {@link TitleFacet} as
      * <tt>May 2, 2007</tt>, but its parseable form might be <tt>20070502</tt>.
      */
-    public String parseableTitle(ObjectAdapter obj);
+    String parseableTitle(ObjectAdapter obj);
 }

http://git-wip-us.apache.org/repos/asf/isis/blob/4e21fbc4/core/metamodel/src/main/java/org/apache/isis/core/metamodel/facets/objectvalue/multiline/MultiLineFacet.java
----------------------------------------------------------------------
diff --git a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/facets/objectvalue/multiline/MultiLineFacet.java b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/facets/objectvalue/multiline/MultiLineFacet.java
index 2678ed5..c78d044 100644
--- a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/facets/objectvalue/multiline/MultiLineFacet.java
+++ b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/facets/objectvalue/multiline/MultiLineFacet.java
@@ -34,7 +34,7 @@ public interface MultiLineFacet extends MultipleValueFacet {
     /**
      * How many lines to use.
      */
-    public int numberOfLines();
+    int numberOfLines();
 
     /**
      * Whether carriage returns should be used to split over multiple lines or
@@ -46,6 +46,6 @@ public interface MultiLineFacet extends MultipleValueFacet {
      * spills over the length of one line.
      */
     @Deprecated
-    public boolean preventWrapping();
+    boolean preventWrapping();
 
 }

http://git-wip-us.apache.org/repos/asf/isis/blob/4e21fbc4/core/metamodel/src/main/java/org/apache/isis/core/metamodel/progmodel/ProgrammingModel.java
----------------------------------------------------------------------
diff --git a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/progmodel/ProgrammingModel.java b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/progmodel/ProgrammingModel.java
index 590b779..44999b9 100644
--- a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/progmodel/ProgrammingModel.java
+++ b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/progmodel/ProgrammingModel.java
@@ -50,7 +50,7 @@ public interface ProgrammingModel extends MetaModelValidatorRefiner {
      *
      * @see #FACET_FACTORY_EXCLUDE_CLASS_NAME_LIST
      */
-    public static final String FACET_FACTORY_INCLUDE_CLASS_NAME_LIST = ConfigurationConstants.ROOT + "reflector.facets.include";
+    String FACET_FACTORY_INCLUDE_CLASS_NAME_LIST = ConfigurationConstants.ROOT + "reflector.facets.include";
 
     /**
      * Key used to lookup comma-separated list of {@link FacetFactory}s to
@@ -58,13 +58,13 @@ public interface ProgrammingModel extends MetaModelValidatorRefiner {
      *
      * @see #FACET_FACTORY_INCLUDE_CLASS_NAME_LIST
      */
-    public static final String FACET_FACTORY_EXCLUDE_CLASS_NAME_LIST = ConfigurationConstants.ROOT + "reflector.facets.exclude";
+    String FACET_FACTORY_EXCLUDE_CLASS_NAME_LIST = ConfigurationConstants.ROOT + "reflector.facets.exclude";
 
     /**
      * This is a bit nasty, but currently the bootstrapping of the metamodel for integration tests vs the webapp differs;
      * the intent of this class is to centralize some logic that should be applied in both cases.
      */
-    public static class Util {
+    class Util {
         private Util(){}
 
         public static void includeFacetFactories(final IsisConfiguration configuration, final ProgrammingModel programmingModel) {

http://git-wip-us.apache.org/repos/asf/isis/blob/4e21fbc4/core/metamodel/src/main/java/org/apache/isis/core/metamodel/specloader/specimpl/ContributeeMember.java
----------------------------------------------------------------------
diff --git a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/specloader/specimpl/ContributeeMember.java b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/specloader/specimpl/ContributeeMember.java
index 9aca015..a9cf21b 100644
--- a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/specloader/specimpl/ContributeeMember.java
+++ b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/specloader/specimpl/ContributeeMember.java
@@ -28,7 +28,7 @@ import org.apache.isis.core.metamodel.spec.feature.ObjectMember;
 public interface ContributeeMember extends ObjectMember {
 
 
-    public static class Predicates {
+    class Predicates {
         
         private Predicates(){}
 

http://git-wip-us.apache.org/repos/asf/isis/blob/4e21fbc4/core/security-shiro/src/test/java/org/apache/isis/security/shiro/ShiroAuthenticatorOrAuthorizorTest_isVisibleInAnyRole.java
----------------------------------------------------------------------
diff --git a/core/security-shiro/src/test/java/org/apache/isis/security/shiro/ShiroAuthenticatorOrAuthorizorTest_isVisibleInAnyRole.java b/core/security-shiro/src/test/java/org/apache/isis/security/shiro/ShiroAuthenticatorOrAuthorizorTest_isVisibleInAnyRole.java
index db4e793..37035f4 100644
--- a/core/security-shiro/src/test/java/org/apache/isis/security/shiro/ShiroAuthenticatorOrAuthorizorTest_isVisibleInAnyRole.java
+++ b/core/security-shiro/src/test/java/org/apache/isis/security/shiro/ShiroAuthenticatorOrAuthorizorTest_isVisibleInAnyRole.java
@@ -19,12 +19,9 @@
 package org.apache.isis.security.shiro;
 
 import static org.hamcrest.CoreMatchers.is;
-import static org.hamcrest.CoreMatchers.not;
-import static org.hamcrest.CoreMatchers.nullValue;
 import static org.junit.Assert.assertThat;
 
 import org.apache.isis.applib.Identifier;
-import org.apache.isis.core.commons.authentication.AuthenticationSession;
 import org.apache.isis.core.commons.config.IsisConfiguration;
 import org.apache.isis.core.runtime.authentication.AuthenticationRequest;
 import org.apache.isis.core.runtime.authentication.AuthenticationRequestPassword;

http://git-wip-us.apache.org/repos/asf/isis/blob/4e21fbc4/core/viewer-wicket-ui/src/main/java/org/apache/isis/viewer/wicket/ui/components/scalars/ScalarPanelAbstract.java
----------------------------------------------------------------------
diff --git a/core/viewer-wicket-ui/src/main/java/org/apache/isis/viewer/wicket/ui/components/scalars/ScalarPanelAbstract.java b/core/viewer-wicket-ui/src/main/java/org/apache/isis/viewer/wicket/ui/components/scalars/ScalarPanelAbstract.java
index efa428e..a9df6fa 100644
--- a/core/viewer-wicket-ui/src/main/java/org/apache/isis/viewer/wicket/ui/components/scalars/ScalarPanelAbstract.java
+++ b/core/viewer-wicket-ui/src/main/java/org/apache/isis/viewer/wicket/ui/components/scalars/ScalarPanelAbstract.java
@@ -395,7 +395,7 @@ public abstract class ScalarPanelAbstract extends PanelAbstract<ScalarModel> imp
 
     @Override
     public AdapterManager getAdapterManager() {
-    return getPersistenceSession();
-}
+        return getPersistenceSession();
+    }
 
 }

http://git-wip-us.apache.org/repos/asf/isis/blob/4e21fbc4/core/viewer-wicket-ui/src/main/java/org/apache/isis/viewer/wicket/ui/components/scalars/ScalarPanelTextFieldParseableAbstract.java
----------------------------------------------------------------------
diff --git a/core/viewer-wicket-ui/src/main/java/org/apache/isis/viewer/wicket/ui/components/scalars/ScalarPanelTextFieldParseableAbstract.java b/core/viewer-wicket-ui/src/main/java/org/apache/isis/viewer/wicket/ui/components/scalars/ScalarPanelTextFieldParseableAbstract.java
index cda2568..103dcc8 100644
--- a/core/viewer-wicket-ui/src/main/java/org/apache/isis/viewer/wicket/ui/components/scalars/ScalarPanelTextFieldParseableAbstract.java
+++ b/core/viewer-wicket-ui/src/main/java/org/apache/isis/viewer/wicket/ui/components/scalars/ScalarPanelTextFieldParseableAbstract.java
@@ -48,7 +48,7 @@ public abstract class ScalarPanelTextFieldParseableAbstract extends ScalarPanelT
 
     @Override
     protected AbstractTextComponent<String> createTextFieldForRegular() {
-        final AbstractTextComponent<String> textField = new TextField<String>(idTextField, new Model<String>() {
+        final AbstractTextComponent<String> textField = new TextField<>(idTextField, new Model<String>() {
             private static final long serialVersionUID = 1L;
 
             @Override


[28/52] [abbrv] isis git commit: ISIS-1243: fixing links to fundamentals guide; updating asciidoc live templates; updating contributors guide that documents the asciidoc live templates

Posted by mg...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_JaxbService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_JaxbService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_JaxbService.adoc
index 56c6328..303c0d5 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_JaxbService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_JaxbService.adoc
@@ -63,5 +63,5 @@ so no further configuration is required.
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ugfun.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_MementoService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_MementoService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_MementoService.adoc
index 6358231..5f4ceb9 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_MementoService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_MementoService.adoc
@@ -128,4 +128,4 @@ implementation of `MementoService` service is automatically registered and injec
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ugfun.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_MetamodelService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_MetamodelService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_MetamodelService.adoc
index 7aa8a58..7f4dd2f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_MetamodelService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_MetamodelService.adoc
@@ -39,4 +39,4 @@ implementation of `MetamodelService` service is automatically registered and inj
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ugfun.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_QueryResultsCache.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_QueryResultsCache.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_QueryResultsCache.adoc
index a5a63c3..ba1619c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_QueryResultsCache.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_QueryResultsCache.adoc
@@ -117,7 +117,7 @@ implementation of `QueryResultsCache` service is automatically registered and in
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ugfun.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_Scratchpad.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_Scratchpad.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_Scratchpad.adoc
index 3d091e2..0b550c0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_Scratchpad.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_Scratchpad.adoc
@@ -115,7 +115,7 @@ so no further configuration is required.
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ugfun.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_SudoService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_SudoService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_SudoService.adoc
index c1b8a84..8d29c42 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_SudoService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_SudoService.adoc
@@ -66,4 +66,4 @@ implementation of `SudoService` service is automatically registered and injected
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ugfun.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_WrapperFactory.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_WrapperFactory.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_WrapperFactory.adoc
index 7f7eba8..f8ebe76 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_WrapperFactory.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_WrapperFactory.adoc
@@ -159,4 +159,4 @@ implementation of `WrapperFactory` service is automatically registered and injec
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ugfun.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_XmlSnapshotService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_XmlSnapshotService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_XmlSnapshotService.adoc
index 316f4fa..e6fce99 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_XmlSnapshotService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_XmlSnapshotService.adoc
@@ -200,7 +200,7 @@ implementation of `XmlSnapshotService` service is automatically registered and i
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ugfun.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ClassDiscoveryService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ClassDiscoveryService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ClassDiscoveryService.adoc
index f40de54..5d328aa 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ClassDiscoveryService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ClassDiscoveryService.adoc
@@ -46,7 +46,7 @@ This implementation is also used to discover domain services annotated with xref
 The usage will vary depending upon the conventions of the design.  As of 1.9.0, the usage of the service has been
 centralized such that the packages to be scanned are located from the xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`]'s `#getModules()` method.
 
-For example, the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]'s app manifest includes:
+For example, the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]'s app manifest includes:
 
 [source,java]
 ----
@@ -77,6 +77,6 @@ implementation of `ClassDiscoveryService2` service is automatically registered a
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ugfun.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ContentNegotiationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ContentNegotiationService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ContentNegotiationService.adoc
index 4164327..f624c1e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ContentNegotiationService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ContentNegotiationService.adoc
@@ -193,7 +193,7 @@ implementation of `ContentNegotiationService` service is automatically registere
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ugfun.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_EmailNotificationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_EmailNotificationService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_EmailNotificationService.adoc
index 34553a2..1ab854b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_EmailNotificationService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_EmailNotificationService.adoc
@@ -70,7 +70,7 @@ implementation of `EmailNotificationService` service is automatically registered
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ugfun.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
 
 
 == Related Services

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_FixtureScriptsSpecificationProvider.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_FixtureScriptsSpecificationProvider.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_FixtureScriptsSpecificationProvider.adoc
index 2ea5d3a..666a7dc 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_FixtureScriptsSpecificationProvider.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_FixtureScriptsSpecificationProvider.adoc
@@ -56,7 +56,7 @@ The class is immutable but it has a builder (obtained using `FixturescriptsSpeci
 
 == Implementation
 
-The xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] has a simple implementation of this service:
+The xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] has a simple implementation of this service:
 
 [source,java]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_LocaleProvider.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_LocaleProvider.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_LocaleProvider.adoc
index 213b179..e5b66df 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_LocaleProvider.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_LocaleProvider.adoc
@@ -56,7 +56,7 @@ automatically registered and injected (it is annotated with `@DomainService`) so
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ugfun.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_RepresentationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_RepresentationService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_RepresentationService.adoc
index 5a4dd62..664f1e0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_RepresentationService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_RepresentationService.adoc
@@ -87,7 +87,7 @@ As discussed in the introduction, the framework provides a default implementatio
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ugfun.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
 
 
 == Registering the Services

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_TranslationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_TranslationService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_TranslationService.adoc
index 21a7e64..7227e52 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_TranslationService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_TranslationService.adoc
@@ -68,7 +68,7 @@ If the menu items are not required then these can be suppressed either using sec
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ugfun.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_TranslationsResolver.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_TranslationsResolver.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_TranslationsResolver.adoc
index eb61c5b..30dab51 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_TranslationsResolver.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_TranslationsResolver.adoc
@@ -52,7 +52,7 @@ automatically registered and injected (it is annotated with `@DomainService`) so
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ugfun.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_UrlEncodingService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_UrlEncodingService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_UrlEncodingService.adoc
index 39a352b..18167a7 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_UrlEncodingService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_UrlEncodingService.adoc
@@ -55,5 +55,5 @@ cases register an alternative implementation of this service.
 
 To use an alternative implementation, use
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ug.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
+further in this xref:ugfun.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/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
index 89c7785..04426c6 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_tg_pet-clinic.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_tg_pet-clinic.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-This is a step-by-step tutorial to build up a simple "petclinic" application, starting from the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].  It was originally written by Jeroen van der Wal.
+This is a step-by-step tutorial to build up a simple "petclinic" application, starting from the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].  It was originally written by Jeroen van der Wal.
 
 It consists of just three domain classes (http://yuml.me/edit/3db2078c[http://yuml.me/3db2078c]):
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_tg_stop-scaffolding-start-coding.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_tg_stop-scaffolding-start-coding.adoc b/adocs/documentation/src/main/asciidoc/guides/_tg_stop-scaffolding-start-coding.adoc
index 5a44e23..3656b2d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_tg_stop-scaffolding-start-coding.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_tg_stop-scaffolding-start-coding.adoc
@@ -202,8 +202,8 @@ Most domain objects in Apache Isis applications are persistent entities. In the
 ** eg rename to `Pet`
 * if required, rename the `SimpleObject` class' `name` property
 ** for `Pet`, can leave `name` property as is
-* specify a xref:ug.adoc#_ugfun_how-tos_ui-hints_object-titles-and-icons[title]
-* specify an xref:ug.adoc#_ugfun_how-tos_ui-hints_object-titles-and-icons[icon]
+* specify a xref:ugfun.adoc#_ugfun_how-tos_ui-hints_object-titles-and-icons[title]
+* specify an xref:ugfun.adoc#_ugfun_how-tos_ui-hints_object-titles-and-icons[icon]
 * make the entity bookmarkable by adding the xref:rgant.adoc#_rgant-DomainObjectLayout_bookmarking[`@DomainObjectLayout#bookmarking()`] attribute.
 * confirm is available from bookmark panel (top-left of Wicket UI)
 
@@ -219,11 +219,11 @@ In the simpleapp archetype the `SimpleObjects` service is a factory/repository f
 * rename the `SimpleObjects` class
 ** eg rename to `Pets`
 * review `create` action (acting as a factory)
-** as per the docs describing xref:ug.adoc#_ugfun_how-tos_crud[how to create or delete objects]
+** as per the docs describing xref:ugfun.adoc#_ugfun_how-tos_crud[how to create or delete objects]
 * rename if you wish
 ** eg `newPet(...)` or `addPet(...)`
 * review `listAll` action (acting as a repository)
-* as per the docs describing xref:ug.adoc#_ugfun_how-tos_crud[how to write a custom repository]
+* as per the docs describing xref:ugfun.adoc#_ugfun_how-tos_crud[how to write a custom repository]
 * note the annotations on the corresponding domain class (originally called `SimpleObject`, though renamed by now, eg to `Pet`)
 * rename if you wish
 ** eg `listPets()`
@@ -296,7 +296,7 @@ The semantics of an action (whether it is safe/query only, whether it is idempot
 
 Domain entities have state: either values (primitives, strings) or references to other entities. In this section we explore adding some value properties
 
-* add some xref:ug.adoc#_ugfun_how-tos_class-structure_properties[value properties]; also:
+* add some xref:ugfun.adoc#_ugfun_how-tos_class-structure_properties[value properties]; also:
 * for string properties
 ** use the xref:rgant.adoc#_rgant-PropertyLayout_multiLine[`@Property(multiLine=...)`] annotation to render a text area instead of a text box
 ** use the xref:rgant.adoc#_rgant-Property_maxLength[`@Property(maxLength=...)`] annotation to specify the maximum number of characters allowable
@@ -309,7 +309,7 @@ Domain entities have state: either values (primitives, strings) or references to
 * revisit the title, consider whether to use the xref:rgant.adoc#_rgant-Title[`@Title`] annotation
 ** rather than the xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`] `title()` method
 * order the properties using the xref:rgant.adoc#_rgant-MemberOrder[`@MemberOrder`], also `@MemberGroupLayout`
-** see also the docs on xref:ug.adoc#_ugfun_object-layout_static[static layouts]
+** see also the docs on xref:ugfun.adoc#_ugfun_object-layout_static[static layouts]
 * use the xref:rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`] annotation to position property/action parameter labels either to the LEFT, TOP or NONE
 ** do the same for parameters using xref:rgant.adoc#_rgant-ParameterLayout[`@ParameterLayout`]
 
@@ -320,7 +320,7 @@ Domain entities have state: either values (primitives, strings) or references to
 
 Domain entities can also reference other domain entities. These references may be either scalar (single-valued) or vector (multi-valued). In this section we focus on scalar reference properties.
 
-* add some xref:ug.adoc#_ugfun_how-tos_class-structure_properties[reference properties]
+* add some xref:ugfun.adoc#_ugfun_how-tos_class-structure_properties[reference properties]
 * update the corresponding domain service (for creation actoin)
 * use different techniques to obtain references (shown in drop-down list box)
 ** use the xref:rgant.adoc#_rgant-DomainObject_bounded[`@DomainObjectLayout(bounded=...)`] annotation on the referenced type if there are only a small number (bounded) of instances
@@ -338,7 +338,7 @@ Domain entities can also reference other domain entities. These references may b
 
 Quick detour: often we want to set up defaults to go with choices. Sensible defaults for action parameters can really improve the usability of the app.
 
-* Add xref:ug.adoc#_ugfun_how-tos_drop-downs-and-defaults[defaults] for action parameters
+* Add xref:ugfun.adoc#_ugfun_how-tos_drop-downs-and-defaults[defaults] for action parameters
 
 
 
@@ -350,7 +350,7 @@ Returning back to references, Isis also supports vector (multi-valued) reference
 * Ensure that all domain classes implement `java.lang.Comparable`
 ** use the xref:rgcms.adoc#_rgcms_classes_utility_ObjectContracts[`ObjectContracts`] utility class to help implement `Comparable`
 *** you can also `equals()`, `hashCode()`, `toString()`
-* Add a xref:ug.adoc#_ugfun_how-tos_class-structure_collections[collection] to one of the entities
+* Add a xref:ugfun.adoc#_ugfun_how-tos_class-structure_collections[collection] to one of the entities
 ** Use `SortedSet` as the class
 ** Use the xref:rgant.adoc#_rgant-CollectionLayout_render[`@CollectionLayout(render=...)`] annotation to indicate if the collection should be visible or hidden by default
 * optional: use the xref:rgant.adoc#_rgant-CollectionLayout_sortedBy[`@CollectionLayout(sortedBy=...)`] annotation to specify a different comparator than the natural ordering
@@ -364,7 +364,7 @@ Returning back to references, Isis also supports vector (multi-valued) reference
 The Wicket UI doesn't allow collections to be modified (added to/removed from). However, we can easily write actions to accomplish the same. Moreover, these actions can provide some additional business logic. For example: it probably shouldn't be possible to add an object twice into a collection, so it should not be presented in the list of choices/autoComplete; conversely, only those objects in the collection should be offered as choices to be removed.
 
 * Add domain actions to add/remove from the collection
-* to create objects, xref:ug.adoc#_ugfun_how-tos_class-structure_inject-services[inject] associated domain service
+* to create objects, xref:ugfun.adoc#_ugfun_how-tos_class-structure_inject-services[inject] associated domain service
 ** generally we recommend using the xref:rgant.adoc#_rgant-Inject[`@Inject`] annotation with either private or default visibility
 * the service itself should use xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer[`DomainObjectContainer`]
 * use the xref:rgant.adoc#_rgant-MemberOrder[`@MemberOrder(name=...)`] annotation to associate an action with a property or with a collection
@@ -380,7 +380,7 @@ CSS classes can be associated with any class member (property, collection, actio
 
 *  the http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome] icons can be used using the xref:rgant.adoc#_rgant-ActionLayout_cssClassFa[`@ActionLayout(cssClassFa=...)`]
 
-It's also possible to use Font Awesome icons for the xref:ug.adoc#_ugfun_how-tos_ui-hints_object-titles-and-icons[domain object icon].
+It's also possible to use Font Awesome icons for the xref:ugfun.adoc#_ugfun_how-tos_ui-hints_object-titles-and-icons[domain object icon].
 
 So:
 - for some of the actions of your domain services or entities, annotate using `@ActionLayout(cssClass=...)` or `@ActionLayout(cssClassFa=...)`
@@ -392,7 +392,7 @@ So:
 
 Up to this point we've been using annotations (`@MemberOrder`, `@MemberGroupLayout`, `@Named`, `@PropertyLayout`, `@ParameterLayout`, `@ActionLayout` and so on) for UI hints. However, the feedback loop is not good: it requires us stopping the app, editing the code, recompiling and running again. So instead, all these UI hints (and more) can be specified dynamically, using a corresponding `.layout.json` file. If edited while the app is running, it will be reloaded automatically (in IntelliJ, use Run&gt;Reload Changed Classes):
 
-* Delete the various hint annotations and instead specify layout hints using a xref:ug.adoc#_ugfun_object-layout_dynamic[.layout.json] file.
+* Delete the various hint annotations and instead specify layout hints using a xref:ugfun.adoc#_ugfun_object-layout_dynamic[.layout.json] file.
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_ugbtb_deployment_neo4j.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_deployment_neo4j.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_deployment_neo4j.adoc
index 9587662..6728047 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_deployment_neo4j.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_deployment_neo4j.adoc
@@ -6,7 +6,7 @@
 
 As of 1.8.0 Apache Isis has experimental support for Neo4J, courtesy of DataNucleus' http://www.datanucleus.org/products/datanucleus/datastores/neo4j.html[Neo4J Datastore] implementation.
 
-The xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] has been updated so that they can be optionally run under Neo4J.
+The xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] has been updated so that they can be optionally run under Neo4J.
 
 [TIP]
 ====
@@ -44,13 +44,13 @@ Add the following dependency to the `webapp` project's `pom.xml`:
 ----
 <1> for Isis v1.9.0, use the value shown.  for Isis v1.8.0, use 3.2.3.
 
-In the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] this is defined under the "neo4j" profile so can be activated using `-P neo4j`.
+In the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] this is defined under the "neo4j" profile so can be activated using `-P neo4j`.
 
 == Try it out!
 
 If you want to quickly try out neo4j for yourself:
 
-* run the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] (v1.8.0)
+* run the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] (v1.8.0)
 
 * build the app:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_decoupling_contributions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_decoupling_contributions.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_decoupling_contributions.adoc
index 29a75c2..255f716 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_decoupling_contributions.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_decoupling_contributions.adoc
@@ -15,7 +15,7 @@ singletons, whereas mixins are instantiated as required (by the framework) and t
 
 For more on contributed services:
 
-* the syntax of writing contributed actions/properties/collections is described in this xref:ug.adoc#_ugfun_how-tos_contributed-members[how-to]
+* the syntax of writing contributed actions/properties/collections is described in this xref:ugfun.adoc#_ugfun_how-tos_contributed-members[how-to]
 
 * there's also useful information in the reference guide, discussing the xref:rgant.adoc#_rgant-DomainService_nature[@DomainService#nature()] attribute, for the `NatureOfService.VIEW_CONTRIBUTIONS_ONLY` nature.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_i18n.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_i18n.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_i18n.adoc
index b7064a1..78008b3 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_i18n.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_i18n.adoc
@@ -110,7 +110,7 @@ However, for an application to be fully internationalized, any validation messag
 
 The first part of the puzzle is tackled by an extension to Apache Isis' programming model.  Whereas previously the `disableXxx()` / `validateXxx()` / `title()` methods could only return a `java.lang.String`, they may now optionally return a `TranslatableString` (defined in Isis applib) instead.
 
-Here's a (silly) example from the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]:
+Here's a (silly) example from the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]:
 
 [source,java]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_view-models_use-cases.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_view-models_use-cases.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_view-models_use-cases.adoc
index a9e523d..ccaffb6 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_view-models_use-cases.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_view-models_use-cases.adoc
@@ -87,7 +87,7 @@ what the use cases are that those domain entities are trying to support.  You ce
 domain layer that could support every conceivable use case before starting to think about view models.
 
 Instead, you should iterate.  Identify the use case/story/end-user objective that you will deliver value to the
-business.  Then build out the minimum domain entities to support that use case (refining the xref:ug.adoc#_ugfun_core-concepts_philosophy_domain-driven-design_ubiquitous-language[ubiquitous language] as you
+business.  Then build out the minimum domain entities to support that use case (refining the xref:ugfun.adoc#_ugfun_core-concepts_philosophy_domain-driven-design_ubiquitous-language[ubiquitous language] as you
 go).  Then, identify if there any view models that could be introduced which would simplify the end-user interactions
 with the system (perhaps automating several related use cases together).
 ****

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_ugbtb_programming-model_custom-validator.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_programming-model_custom-validator.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_programming-model_custom-validator.adoc
index 31777f3..a60e876 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_programming-model_custom-validator.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_programming-model_custom-validator.adoc
@@ -17,7 +17,7 @@ You can also impose your own application-specific rules by installing your own m
 
 [TIP]
 ====
-Isis' xref:ug.adoc#_ugfun_isis-maven-plugin[Maven plugin] will also validate the domain object model during build time.
+Isis' xref:ugfun.adoc#_ugfun_isis-maven-plugin[Maven plugin] will also validate the domain object model during build time.
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_ugbtb_programming-model_layout-metadata-reader.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_programming-model_layout-metadata-reader.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_programming-model_layout-metadata-reader.adoc
index d684ac1..ec088ec 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_programming-model_layout-metadata-reader.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_programming-model_layout-metadata-reader.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-The metadata for domain objects is obtained both xref:ug.adoc#_ugfun_object-layout_static[statically] and xref:ug.adoc#_ugfun_object-layout_dynamic[dynamically].
+The metadata for domain objects is obtained both xref:ugfun.adoc#_ugfun_object-layout_static[statically] and xref:ugfun.adoc#_ugfun_object-layout_dynamic[dynamically].
 
 The default implementation for reading dynamic layout metadata is `org.apache.isis.core.metamodel.layoutmetadata.json.LayoutMetadataReaderFromJson`, which is responsible for reading from the `Xxx.layout.json` files on the classpath (for each domain entity `Xxx`).
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_building-blocks.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_building-blocks.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_building-blocks.adoc
index b194875..c526ced 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_building-blocks.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_building-blocks.adoc
@@ -28,7 +28,7 @@ which can map domain objects either to an RDBMS or to various NoSQL objectstores
 recognizes a number of the JDO annotations such as `@javax.jdo.annotations.Column(allowNulls=...)`.
 
 In addition, the framework builds up the metamodel for each domain object using
-xref:ug.adoc#_ugfun_object-layout[layout hints], such as `Customer.layout.json`.  These provide metadata such as
+xref:ugfun.adoc#_ugfun_object-layout[layout hints], such as `Customer.layout.json`.  These provide metadata such as
 grouping elements of the UI together, using multi-column layouts, and so on.  The layout file can be modified while the
 application is still running, and are picked up automatically; a useful way to speed up feedback.
 
@@ -287,7 +287,7 @@ NOTE: TODO; see xref:rgcms.adoc#_rgcms_classes_uievent[UI event] classes.
 [[_ugfun_core-concepts_building-blocks_oid]]
 == OIDs
 
-As well as defining a xref:ug.adoc#_ugfun_core-concepts_building-blocks_metamodel[metamodel] of the structure (domain
+As well as defining a xref:ugfun.adoc#_ugfun_core-concepts_building-blocks_metamodel[metamodel] of the structure (domain
 classes) of its domain objects, Apache Isis also manages the runtime instances of said domain objects.
 
 When a domain entity is recreated from the database, the framework keeps track of its identity through an "OID": an

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_other-deployment-options.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_other-deployment-options.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_other-deployment-options.adoc
index ca69816..6d25950 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_other-deployment-options.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_other-deployment-options.adoc
@@ -18,7 +18,7 @@ Let's start though with the default use case for Apache Isis: building line-of-b
 
 Apache Wicket, and therefore Apache Isis in this configuration, is a stateful architecture.  As a platform it is certainly capable of supporting user bases of several thousand (with perhaps one or two hundred concurrent); however it isn't an architecture that you should try to scale up to tens of thousands of concurrent users.
 
-The UI UI generated by the Wicket viewer is well suited to many line-of-business apps, but it's also worth knowing that (with a little knowledge of the Wicket APIs) it relatively straightforward to extend.  As described in xref:ug.adoc#_ugfun_core-concepts_add-ons[Isis addons] chapter, the viewer already has integrations with https://github.com/isisaddons/isis-wicket-gmap3[google maps], https://github.com/isisaddons/isis-wicket-fullcalendar2[a full calendar] and an https://github.com/isisaddons/isis-wicket-excel[export to Excel] component.  We are also aware of integrations with SVG images (for floor maps of shopping center) and of custom widgets displaying a catalogue (text and images) of medical diseases.
+The UI UI generated by the Wicket viewer is well suited to many line-of-business apps, but it's also worth knowing that (with a little knowledge of the Wicket APIs) it relatively straightforward to extend.  As described in xref:ugfun.adoc#_ugfun_core-concepts_add-ons[Isis addons] chapter, the viewer already has integrations with https://github.com/isisaddons/isis-wicket-gmap3[google maps], https://github.com/isisaddons/isis-wicket-fullcalendar2[a full calendar] and an https://github.com/isisaddons/isis-wicket-excel[export to Excel] component.  We are also aware of integrations with SVG images (for floor maps of shopping center) and of custom widgets displaying a catalogue (text and images) of medical diseases.
 
 Deploying on Apache Isis means that the framework also manages object persistence.  For many line-of-business applications this will mean using a relational database.  It is also possible (courtesy of its integratinon with link:http://www.datanucleus.org[DataNucleus]) to deploy an Isis app to a NoSQL store such as Neo4J or MongoDB; and it is also possible to deploy to cloud platforms such as link:https://cloud.google.com/appengine/docs[Google App Engine (GAE)].
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy_aop.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy_aop.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy_aop.adoc
index a295fba..286296a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy_aop.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy_aop.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-Although not a book about object modelling, Evans' "Domain Driven Design" does use object orientation as its primary modelling tool; while xref:ug.adoc#_ugfun_core-concepts_philosophy_naked-objects-pattern[naked objects pattern] very much comes from an OO background (it even has 'object' in its name); Richard Pawson lists Alan Kay as a key influence.
+Although not a book about object modelling, Evans' "Domain Driven Design" does use object orientation as its primary modelling tool; while xref:ugfun.adoc#_ugfun_core-concepts_philosophy_naked-objects-pattern[naked objects pattern] very much comes from an OO background (it even has 'object' in its name); Richard Pawson lists Alan Kay as a key influence.
 
 It's certainly true that to develop an Apache Isis application you will need to have good object oriented modelling skills.  But given that all the mainstream languages for developing business systems are object oriented (Java, C#, Ruby), that's not such a stretch.
 
@@ -31,6 +31,6 @@ Another example of interceptors are the http://github.com/isisaddons/isis-module
 
 Apache Isis also has an internal event bus (you can switch between an underlying implementation of Gauva or Axon).  A domain event is fired whenever an object is interacted with, and this allows any subscribers to influence the operation (or even veto it).  This is a key mechanism in ensuring that Isis applications are maintainable, and we discuss it in depth in the section on  xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling[Decoupling].  But fundamentally its relying on this AOP concept of interceptors.
 
-Finally, Isis also a feature that is akin to AOP mix-ins.  A "contributed action" is one that is implemented on a domain service but that appears to be a behaviour of rendered domain object.  In other words, we can dissociate behaviour from data.  That's not always the right thing to do of course.  In Richard Pawson's description of the xref:ug.adoc#_ugfun_core-concepts_philosophy_naked-objects-pattern[naked objects pattern] he talks about "behaviourally rich" objects, in other words where the business functionality encapsulated the data.   But on the other hand sometimes the behaviour and data structures change at different rates.  The link:http://en.wikipedia.org/wiki/Single_responsibility_principle[single responsibility principle] says we should only lump code together that changes at the same rate.  Apache Isis' support for contributions (not only contributed actions, but also contributed properties and contributed collections) enables this.  And again, to loop back to the topic
  of this section, it's an AOP concept that being implemented by the framework.
+Finally, Isis also a feature that is akin to AOP mix-ins.  A "contributed action" is one that is implemented on a domain service but that appears to be a behaviour of rendered domain object.  In other words, we can dissociate behaviour from data.  That's not always the right thing to do of course.  In Richard Pawson's description of the xref:ugfun.adoc#_ugfun_core-concepts_philosophy_naked-objects-pattern[naked objects pattern] he talks about "behaviourally rich" objects, in other words where the business functionality encapsulated the data.   But on the other hand sometimes the behaviour and data structures change at different rates.  The link:http://en.wikipedia.org/wiki/Single_responsibility_principle[single responsibility principle] says we should only lump code together that changes at the same rate.  Apache Isis' support for contributions (not only contributed actions, but also contributed properties and contributed collections) enables this.  And again, to loop back to the to
 pic of this section, it's an AOP concept that being implemented by the framework.
 
 The nice thing about aspect orientation is that for the most part you can ignore these cross-cutting concerns and - at least initially at least - just focus on implementing your domain object.  Later when your app starts to grow and you start to break it out into smaller modules, you can leverage Apache Isis' AOP support for (xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling_mixins[mixins]), (xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling_contributions[contributions]) and interceptors (the xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling_event-bus[event bus]) to ensure that your codebase remains maintainable.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy_how-eases-ddd.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy_how-eases-ddd.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy_how-eases-ddd.adoc
index 1c42f71..affc49d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy_how-eases-ddd.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy_how-eases-ddd.adoc
@@ -40,7 +40,7 @@ If we are using code as the primary means of expressing the model, then we need
 
 We could generate UML diagrams and the like from code. That will work for some members of the business community, but not for everyone. Or we could generate a PDF document from Javadoc comments, but comments aren't code and so the document may be inaccurate.  Anyway, even if we do create such a document, not everyone will read it.
 
-A better way to represent the model is to show it in action as a working prototype. As we show in the xref:ug.adoc#_ugfun_getting-started[Getting Started] section, Apache Isis enables this with ease. Such prototypes bring the domain model to life, engaging the audience in a way that a piece of paper never can.
+A better way to represent the model is to show it in action as a working prototype. As we show in the xref:ugfun.adoc#_ugfun_getting-started[Getting Started] section, Apache Isis enables this with ease. Such prototypes bring the domain model to life, engaging the audience in a way that a piece of paper never can.
 
 Moreover, with Apache Isis prototypes, the domain model will come shining through. If there are mistakes or misunderstandings in the domain model (inevitable when building any complex system), they will be obvious to all.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping.adoc
index df40264..c38458d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping.adoc
@@ -13,6 +13,6 @@ This is the way that the link:http://metawidget.org/[MetaWidget] team, in partic
 
 [NOTE]
 ====
-We compare Apache Isis' with MetaWidget xref:ug.adoc#_ugfun_core-concepts_principles_apache-isis-vs_metawidget[here].
+We compare Apache Isis' with MetaWidget xref:ugfun.adoc#_ugfun_core-concepts_principles_apache-isis-vs_metawidget[here].
 ====
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_principles_apache-isis-vs_cqrs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_principles_apache-isis-vs_cqrs.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_principles_apache-isis-vs_cqrs.adoc
index 08a7d31..d1b4244 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_principles_apache-isis-vs_cqrs.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_principles_apache-isis-vs_cqrs.adoc
@@ -23,6 +23,6 @@ With respect to commands, Apache Isis does of course support the xref:rgsvc.adoc
 
 In CQRS the commands correspond to the business logic that mutates the system.  Whether this logic is part of the command class (`PlaceOrderCommand`) or whether that command delegates to methods on the domain object is an implementation detail; but it certainly is common for the business logic to be wholly within the command object and for the domain object to be merely a data holder of the data within the command/write datastore.
 
-In Apache Isis this same separation of business logic from the underlying data can be accomplished most straightforwardly using xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling_mixins[mixins] or xref:ug.adoc#_ugfun_how-tos_contributed-members[contributions].  In the UI (surfaced by the xref:ugvw.adoc#[Wicket viewer]) or in the REST API (surfaced by the xref:ugvro.adoc#[RestfulObjects viewer]) the behaviour appears to reside on the domain object; however the behaviour actually resides on separate classes and is mixed in (like a trait) only at runtime.
+In Apache Isis this same separation of business logic from the underlying data can be accomplished most straightforwardly using xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling_mixins[mixins] or xref:ugfun.adoc#_ugfun_how-tos_contributed-members[contributions].  In the UI (surfaced by the xref:ugvw.adoc#[Wicket viewer]) or in the REST API (surfaced by the xref:ugvro.adoc#[RestfulObjects viewer]) the behaviour appears to reside on the domain object; however the behaviour actually resides on separate classes and is mixed in (like a trait) only at runtime.
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_principles_apache-isis-vs_metawidget.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_principles_apache-isis-vs_metawidget.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_principles_apache-isis-vs_metawidget.adoc
index 67b02d3..298b19f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_principles_apache-isis-vs_metawidget.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_principles_apache-isis-vs_metawidget.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-MetaWidget (mentioned xref:ug.adoc#_ugfun_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping[earlier] has a number of ideas in common with Apache Isis, specifically the runtime generation of a UI for domain objects.  And like Apache Isis, MetaWidget builds its own metamodel of the domain objects and uses this to render the object.
+MetaWidget (mentioned xref:ugfun.adoc#_ugfun_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping[earlier] has a number of ideas in common with Apache Isis, specifically the runtime generation of a UI for domain objects.  And like Apache Isis, MetaWidget builds its own metamodel of the domain objects and uses this to render the object.
 
 However, there is a difference in philosophy in that MW is not a full-stack framework and does not (in their words) try to "own the UI".  Rather they support a huge variety of UI technologies and allow the domain object to be rendered in any of them.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_enabling-logging.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_enabling-logging.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_enabling-logging.adoc
index 571d1be..d183bec 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_enabling-logging.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_enabling-logging.adoc
@@ -16,7 +16,7 @@ As per the http://www.datanucleus.org/products/accessplatform/logging.html[DN lo
 
 * In the JDBC Driver +
 +
-Configure `log4jdbc` JDBC rather than the vanilla driver (see `WEB-INF/persistor_datanucleus.properties`) and configure log4j logging (see `WEB-INF/logging.properties`).  There are examples of both in the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
+Configure `log4jdbc` JDBC rather than the vanilla driver (see `WEB-INF/persistor_datanucleus.properties`) and configure log4j logging (see `WEB-INF/logging.properties`).  There are examples of both in the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
 
 * In the database +
 +

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started.adoc
index 2a4ad32..955501c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started.adoc
@@ -7,13 +7,13 @@
 
 
 
-To get you up and running quickly, Apache Isis provides a xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] to setup a simple application as the basis of your own apps.  This is deliberately very minimal so that you won't have to spend lots of time removing generated artifacts.  On the other hand, it does set up a standard multi-module maven structure with unit- and integration tests pre-configured, as well as a webapp module so that you can easily run your app.  We strongly recommend that you preserve this structure as you develop your own Isis application.
+To get you up and running quickly, Apache Isis provides a xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] to setup a simple application as the basis of your own apps.  This is deliberately very minimal so that you won't have to spend lots of time removing generated artifacts.  On the other hand, it does set up a standard multi-module maven structure with unit- and integration tests pre-configured, as well as a webapp module so that you can easily run your app.  We strongly recommend that you preserve this structure as you develop your own Isis application.
 
-In this chapter we also discuss the xref:ug.adoc#_ugfun_getting-started_datanucleus-enhancer[DataNucleus enhancer].  link:http://www.datanucleus.org/[DataNucleus] is the reference implementation of the JDO (Java data objects) spec, and Apache Isis integrates with DataNucleus as its persistence layer.  The enhancer performs post-processing on the bytecode of your persistent domain entities, such that they can be persisted by Apache Isis' JDO/DataNucleus objectstore.
+In this chapter we also discuss the xref:ugfun.adoc#_ugfun_getting-started_datanucleus-enhancer[DataNucleus enhancer].  link:http://www.datanucleus.org/[DataNucleus] is the reference implementation of the JDO (Java data objects) spec, and Apache Isis integrates with DataNucleus as its persistence layer.  The enhancer performs post-processing on the bytecode of your persistent domain entities, such that they can be persisted by Apache Isis' JDO/DataNucleus objectstore.
 
 [NOTE]
 ====
-The xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] automatically configures the enhancer, so there's little you need to do at this stage.  Even so we feel it's a good idea to be aware of this critical part of Apache Isis runtime; if the enhancer does not run, then you'll find the app fails to start with (what will seem like) quite an obscure exception message.
+The xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] automatically configures the enhancer, so there's little you need to do at this stage.  Even so we feel it's a good idea to be aware of this critical part of Apache Isis runtime; if the enhancer does not run, then you'll find the app fails to start with (what will seem like) quite an obscure exception message.
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started_datanucleus-enhancer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started_datanucleus-enhancer.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started_datanucleus-enhancer.adoc
index 88dc068..121277e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started_datanucleus-enhancer.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started_datanucleus-enhancer.adoc
@@ -21,7 +21,7 @@ If working from the Maven command line, JDO enhancement is done using the `maven
 
 [TIP]
 ====
-The configuration described below is automatically set up by the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
+The configuration described below is automatically set up by the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
 ====
 
 
@@ -75,7 +75,7 @@ The configuration described below is automatically set up by the xref:ug.adoc#_u
 </profile>
 ----
 
-The xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]  sets up the plugin correctly in the `dom` (domain object model) module.  (It's actually a little bit more complex to cater for users of the Eclipse IDE using Eclipse's m2e plugin).
+The xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]  sets up the plugin correctly in the `dom` (domain object model) module.  (It's actually a little bit more complex to cater for users of the Eclipse IDE using Eclipse's m2e plugin).
 
 
 
@@ -97,7 +97,7 @@ It's also a good idea to ensure that the `dom` module has a JDO `META-INF/persis
 ----
 <1> change as required; typically is the name of the app.
 
-Again, the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] does this.
+Again, the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] does this.
 
 [WARNING]
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started_simpleapp-archetype.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started_simpleapp-archetype.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started_simpleapp-archetype.adoc
index 6620162..336f7fc 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started_simpleapp-archetype.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started_simpleapp-archetype.adoc
@@ -143,7 +143,7 @@ You can also take the built WAR file and deploy it into a standalone servlet con
 
 === From within the IDE
 
-Most of the time, though, you'll probably want to run the app from within your IDE.  The mechanics of doing this will vary by IDE; see the xref:cg.adoc#_cg_ide[Contributors' Guide] for details of setting up Eclipse or IntelliJ IDEA.  Basically, though, it amounts to running `org.apache.isis.WebServer`, and ensuring that the xref:ug.adoc#_ugfun_getting-started_datanucleus-enhancer[DataNucleus enhancer] has properly processed all domain entities.
+Most of the time, though, you'll probably want to run the app from within your IDE.  The mechanics of doing this will vary by IDE; see the xref:cg.adoc#_cg_ide[Contributors' Guide] for details of setting up Eclipse or IntelliJ IDEA.  Basically, though, it amounts to running `org.apache.isis.WebServer`, and ensuring that the xref:ugfun.adoc#_ugfun_getting-started_datanucleus-enhancer[DataNucleus enhancer] has properly processed all domain entities.
 
 Here's what the setup looks like in IntelliJ IDEA:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_actions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_actions.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_actions.adoc
index 8f82ffa..e822517 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_actions.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_actions.adoc
@@ -13,7 +13,7 @@ NOTE: TODO
 ====
 While Apache 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 xref:ug.adoc#_ugfun_how-tos_class-structure_ignoring-methods[Ignoring Methods].  This ensures that the collection is ignored by Apache Isis.
+The workaround is to mark the collection as `@Programmatic`, as described in xref:ugfun.adoc#_ugfun_how-tos_class-structure_ignoring-methods[Ignoring Methods].  This ensures that the collection is ignored by Apache Isis.
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_collections.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_collections.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_collections.adoc
index 01afcd9..23f87bd 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_collections.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_collections.adoc
@@ -16,7 +16,7 @@ Or, actually, you can, because that is a valid mapping supported by JDO/DataNucl
 
 One workaround is to mark the collection as xref:rgant.adoc#_rgant-Programmatic[`@Programmatic`].  This ensures that the collection is ignored by Apache Isis.
 
-Another workaround is to wrap each value in a view model, as explained in this xref:ug.adoc#_ugfun_how-tos_simulating-collections-of-values[tip].
+Another workaround is to wrap each value in a view model, as explained in this xref:ugfun.adoc#_ugfun_how-tos_simulating-collections-of-values[tip].
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_properties.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_properties.adoc
index 6bc76fa..c1e5327 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_properties.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_properties.adoc
@@ -15,7 +15,7 @@ NOTE: TODO
 
 NOTE: TODO
 
-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 the xref:ug.adoc#_ugfun_how-tos_class-structure_properties-vs-parameters[Properties vs Parameters] section provides a handy reference of each.
+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 the xref:ugfun.adoc#_ugfun_how-tos_class-structure_properties-vs-parameters[Properties vs Parameters] section provides a handy reference of each.
 
 
 
@@ -190,7 +190,7 @@ More information can be found http://www.opentaps.org/docs/index.php/How_to_Use_
 
 Apache Isis configures JDO/DataNucleus so that the properties of type `org.apache.isis.applib.value.Blob` and `org.apache.isis.applib.value.Clob` can also be persisted.
 
-As for xref:ug.adoc#_ugfun_how-tos_class-structure_properties_mapping-joda-dates[Joda dates], this requires the `@javax.jdo.annotations.Persistent` annotation. However, whereas for dates one would always expect this value to be retrieved eagerly, for blobs and clobs it is not so clear cut.
+As for xref:ugfun.adoc#_ugfun_how-tos_class-structure_properties_mapping-joda-dates[Joda dates], this requires the `@javax.jdo.annotations.Persistent` annotation. However, whereas for dates one would always expect this value to be retrieved eagerly, for blobs and clobs it is not so clear cut.
 
 === Mapping Blobs
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_domain-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_domain-services.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_domain-services.adoc
index 0acd13e..a3f2e36 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_domain-services.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_domain-services.adoc
@@ -16,7 +16,7 @@ In Apache Isis domain services have several responsibilities:
 - they provide other services (eg performing calculations, attach a barcode, send an email etc).
 - to implement an SPI of the framework, most notably cross-cutting concerns such as security, command profiling, auditing and publishing.
 
-It's worth extending the xref:ug.adoc#_ugfun_core-concepts_philosophy_hexagonal-architecture[Hexagonal Architecture] to show where domain services -- and in particular the domain services provided by link:http://www.isisaddons.org[Isis Addons] (non-ASF) -- fit in:
+It's worth extending the xref:ugfun.adoc#_ugfun_core-concepts_philosophy_hexagonal-architecture[Hexagonal Architecture] to show where domain services -- and in particular the domain services provided by link:http://www.isisaddons.org[Isis Addons] (non-ASF) -- fit in:
 
 .The hexagonal architecture with Isis addons
 image::{_imagesdir}how-tos/domain-services/hexagonal-architecture-addons.png[width="700px"]
@@ -172,7 +172,7 @@ public OrderContributions {
 <2> contributed as an association, in particular as a collection because returns a `List<T>`.
 <3> Only actions with a single argument can be contributed as associations
 
-More information about contributions can be found xref:ug.adoc#_ugfun_how-tos_contributed-members[here].  More information
+More information about contributions can be found xref:ugfun.adoc#_ugfun_how-tos_contributed-members[here].  More information
 about using contributions and mixins to keep your domain application decoupled can be found xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling_contributions[here] and xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling_mixins[here].
 
 
@@ -207,7 +207,7 @@ public CustomerOrderSubscriptions {
 
 == Prototyping
 
-While for long-term maintainability we do recommend the naming conventions described xref:ug.adoc#_ugfun_how-tos_domain-services_organizing-services[above], you can get away with far fewer services when just prototyping a domain.
+While for long-term maintainability we do recommend the naming conventions described xref:ugfun.adoc#_ugfun_how-tos_domain-services_organizing-services[above], you can get away with far fewer services when just prototyping a domain.
 
 If the domain service nature is not specified (or is left to its default, `VIEW`), then the service's actions will
 appear in the UI both as menu items _and_ as contributions (and the service can of course be injected into other domain objects for programmatic invocation).

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_ui-hints_action-icons-and-css.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_ui-hints_action-icons-and-css.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_ui-hints_action-icons-and-css.adoc
index 859e2ca..146832c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_ui-hints_action-icons-and-css.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_ui-hints_action-icons-and-css.adoc
@@ -14,7 +14,7 @@ These UI hint can be applied either to individual actions, or can be applied en-
 NOTE: TODO - xref:rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`] and xref:rgant.adoc#_rgant-ActionLayout_cssClassFa[`@ActionLayout#cssClassFa()`]
 
 
-Alternatively, you can specify these hints dynamically in the xref:ug.adoc#_ugfun_object-layout[`Xxx.layout.json`] for the entity.
+Alternatively, you can specify these hints dynamically in the xref:ugfun.adoc#_ugfun_object-layout[`Xxx.layout.json`] for the entity.
 
 
 == Per pattern matching

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_ui-hints_layout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_ui-hints_layout.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_ui-hints_layout.adoc
index 390a69d..1226521 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_ui-hints_layout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_ui-hints_layout.adoc
@@ -5,5 +5,5 @@
 :_imagesdir: images/
 
 
-See the xref:ug.adoc#_ugfun_object-layout[object layout] chapter.
+See the xref:ugfun.adoc#_ugfun_object-layout[object layout] chapter.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_dynamic.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_dynamic.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_dynamic.adoc
index a0bdb51..53c488c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_dynamic.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_dynamic.adoc
@@ -101,7 +101,7 @@ The format of the file is:
 Although advisable, it is not necessary to list all class members in this file. Any members not listed with be
 ordered according either to annotations (if present) or fallback/default values.
 
-Note also that the layout file may contain entries for xref:ug.adoc#_ugfun_how-tos_contributed-members[contributed associations and actions]; this allows each contributee classes to define their own layout for their contributions, possibly overriding any static metadata on the original domain service contributor.
+Note also that the layout file may contain entries for xref:ugfun.adoc#_ugfun_how-tos_contributed-members[contributed associations and actions]; this allows each contributee classes to define their own layout for their contributions, possibly overriding any static metadata on the original domain service contributor.
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_static-vs-dynamic.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_static-vs-dynamic.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_static-vs-dynamic.adoc
index f5cfb98..980545c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_static-vs-dynamic.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_static-vs-dynamic.adoc
@@ -7,9 +7,9 @@
 
 
 
-Using xref:ug.adoc#_ugfun_object-layout_dynamic[dynamic object layout]s using JSON has the huge benefit that the layout can be updated without requiring a recompile of the code and redeploy of the app.  Many developers also find it easier to rationalize about layout when all the hints are collated together in a single place (rather than scattered across the class members as annotations).
+Using xref:ugfun.adoc#_ugfun_object-layout_dynamic[dynamic object layout]s using JSON has the huge benefit that the layout can be updated without requiring a recompile of the code and redeploy of the app.  Many developers also find it easier to rationalize about layout when all the hints are collated together in a single place (rather than scattered across the class members as annotations).
 
-Another benefit of dynamic layout is that UI hints can be provided for xref:ug.adoc#_ugfun_how-tos_contributed-members[contributed associations and actions] that are synthesised at runtime.
+Another benefit of dynamic layout is that UI hints can be provided for xref:ugfun.adoc#_ugfun_how-tos_contributed-members[contributed associations and actions] that are synthesised at runtime.
 
 The main downsides of using dynamic layouts are a lack of typesafety (a typo will result in the metadata not being picked up for the element) and syntactic fragility (an invalid JSON document will result in no metadata for the entire class).
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_ugsec_configuring-isis-to-use-shiro.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugsec_configuring-isis-to-use-shiro.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugsec_configuring-isis-to-use-shiro.adoc
index 62c565d..4b6880f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugsec_configuring-isis-to-use-shiro.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugsec_configuring-isis-to-use-shiro.adoc
@@ -9,7 +9,7 @@ Apache Isis' security mechanism is configurable, specifying an `Authenticator` a
 
 [TIP]
 ====
-The xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] is pre-configured to use Apache Shiro, so much of what follows is set up already.
+The xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] is pre-configured to use Apache Shiro, so much of what follows is set up already.
 ====
 
 == Telling Apache Isis to use Shiro

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_ugsec_shiro-ini-realm.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugsec_shiro-ini-realm.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugsec_shiro-ini-realm.adoc
index 623dfe4..9397bfd 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugsec_shiro-ini-realm.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugsec_shiro-ini-realm.adoc
@@ -7,7 +7,7 @@
 
 Probably the simplest realm to use is Shiro's built-in `IniRealm`, which reads from the (same) `WEB-INF/shiro.ini` file.
 
-This is suitable for prototyping, but isn't intended for production use, if only because user/password credentials are stored in plain text.  Nevertheless, it's a good starting point.  The app generated by the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] is configured to use this realm.
+This is suitable for prototyping, but isn't intended for production use, if only because user/password credentials are stored in plain text.  Nevertheless, it's a good starting point.  The app generated by the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] is configured to use this realm.
 
 The diagram below shows the Isis and components involved:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_ugtst_bdd-spec-support_maven-configuration.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugtst_bdd-spec-support_maven-configuration.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugtst_bdd-spec-support_maven-configuration.adoc
index edc20e3..13bc26b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugtst_bdd-spec-support_maven-configuration.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugtst_bdd-spec-support_maven-configuration.adoc
@@ -7,7 +7,7 @@
 
 
 
-Apache Isis' BDD spec support is automatically configured if you use the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].  To set it up manually, update the `pom.xml` of your domain object model module:
+Apache Isis' BDD spec support is automatically configured if you use the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].  To set it up manually, update the `pom.xml` of your domain object model module:
 
 [source,xml]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_ugtst_bdd-spec-support_writing-a-bdd-spec.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugtst_bdd-spec-support_writing-a-bdd-spec.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugtst_bdd-spec-support_writing-a-bdd-spec.adoc
index b8e483c..d8a730e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugtst_bdd-spec-support_writing-a-bdd-spec.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugtst_bdd-spec-support_writing-a-bdd-spec.adoc
@@ -24,7 +24,7 @@ The `glue` attribute of the Cucumber-JVM JUnit runner eallows you to indicate wh
 * a system initializer class.  You can reuse the  system initializer from any integration tests (as described in xref:ugtst.adoc#_ugtst_integ-test-support[Integration Test Support], bootstrapping section).
 
 
-Here's an example of a feature from the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]:
+Here's an example of a feature from the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]:
 
 [source,java]
 ----
@@ -49,7 +49,7 @@ Apache Isis does also support running BDD specs in unit test mode; by annotating
 
 To support unit testing scope Apache Isis provides the `InMemoryDB` class; a glorified hashmap of "persisted" objects.  Use of this utility class is optional.
 
-Writing a BDD spec that supports both modes of operation therefore takes more effort and we expect most users interested in BDD will use integration-testing scope; for these reasons we have chosen _not_ to include unit-testing support in the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].  For those who do require faster-executing test suite, it's worthwhile knowing that Apache Isis can support this.
+Writing a BDD spec that supports both modes of operation therefore takes more effort and we expect most users interested in BDD will use integration-testing scope; for these reasons we have chosen _not_ to include unit-testing support in the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].  For those who do require faster-executing test suite, it's worthwhile knowing that Apache Isis can support this.
 
 ====
 
@@ -72,7 +72,7 @@ public class RunSpecs {
 }
 ----
 
-The JSON formatter allows integration with enhanced reports, for example as provided by http://www.masterthought.net/section/cucumber-reporting[Masterthought.net] (screenshots at end of page). (Commented out) configuration for this is provided in the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
+The JSON formatter allows integration with enhanced reports, for example as provided by http://www.masterthought.net/section/cucumber-reporting[Masterthought.net] (screenshots at end of page). (Commented out) configuration for this is provided in the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
 
 The bootstrapping of Apache Isis can be moved into a `BootstrappingGlue` step definition:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_ugtst_fixture-scripts_api-and-usage.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugtst_fixture-scripts_api-and-usage.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugtst_fixture-scripts_api-and-usage.adoc
index 344f32a..079e7aa 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugtst_fixture-scripts_api-and-usage.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugtst_fixture-scripts_api-and-usage.adoc
@@ -23,7 +23,7 @@ As of 1.9.0 there is an alternative design.  Instead of subclassing `FixtureScri
 
 The actual implementation of the `FixtureScripts` service is then provided by the framework itself, namely the xref:rgsvc.adoc#_rgsvc-api_FixtureScriptsDefault[`FixtureScriptsDefault`] domain service, annotated to be rendered on the secondary "Prototyping" menu.  This uses the `FixtureScriptsSpecificationProvider` to adjust itself accordinly.
 
-For example, here's the `FixtureScriptsSpecificationProvider` service that's generated by the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]:
+For example, here's the `FixtureScriptsSpecificationProvider` service that's generated by the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]:
 
 [source,java]
 ----
@@ -113,7 +113,7 @@ If you had defined many fixture scripts then a drop-down might become unwieldy,
 
 ----
 
-You are free, of course, to add additional "convenience" actions into it if you wish for the most commonly used/demo'd setups ; you'll find that the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] adds this additional action:
+You are free, of course, to add additional "convenience" actions into it if you wish for the most commonly used/demo'd setups ; you'll find that the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] adds this additional action:
 
 [source,java]
 ----
@@ -139,7 +139,7 @@ Let's now look at the `FixtureScript` class, where there's a bit more going on.
 
 A fixture script is ultimately just a block of code that can be executed, so it's up to you how you implement it to set up the system.  However, we strongly recommend that you use it to invoke actions on business objects, in essence to replay what a real-life user would have done.  That way, the fixture script will remain valid even if the underlying implementation of the system changes in the future.
 
-Here's the `RecreateSimpleObjects` fixture script from the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]:
+Here's the `RecreateSimpleObjects` fixture script from the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]:
 
 [source,java]
 ----
@@ -251,7 +251,7 @@ public class SimpleObjectCreate extends FixtureScript {       // <1>
 
 Fixture scripts can be called from integration tests just the same way that fixture scripts can call one another.
 
-For example, here's an integration test from the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]:
+For example, here's an integration test from the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]:
 
 [source,java]
 ----
@@ -296,7 +296,7 @@ public class SimpleObjectIntegTest extends SimpleAppIntegTest {
 
 There are lots of ways to organize fixture scripts, but we've used them as either:
 
-* a fairly flat style, eg as in the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype], also as in the http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp];
+* a fairly flat style, eg as in the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype], also as in the http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp];
 
 * in a "composite pattern" style, eg as in the https://github.com/estatio/estatio/blob/ea20a6ce257acede50de6ce4fd2ff29713fcd689/estatioapp/fixture/src/main/java/org/estatio/fixture/invoice/InvoiceForLeaseItemTypeOfDiscountOneQuarterForOxfMiracle005.java#L66)[Estatio open source app].
 
@@ -318,7 +318,7 @@ image::{_imagesdir}testing/fixture-scripts/composite.png[width="550px",link="{_i
 
 Back in the earlier section we noted the `MultipleExecutionStrategy` setting.  We can now explain the meaning of this: the enum value of `EXECUTE` is designed for the flat style (where every fixture script will be called), whereas the enum value of `IGNORE` is designed for the composite style, and ensures that any fixture scripts visited more than once (eg TearDown) are only every executed the first time.
 
-As already noted , the app generated by the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] uses the flat structure, and we feel that it's a better at separating out the "how" (how we set up some graph of domain objects into a known state, eg a customer with shipped placed orders and a newly placed order) from the "what" (what data should we actually use for the customer's name, say).
+As already noted , the app generated by the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] uses the flat structure, and we feel that it's a better at separating out the "how" (how we set up some graph of domain objects into a known state, eg a customer with shipped placed orders and a newly placed order) from the "what" (what data should we actually use for the customer's name, say).
 
 The composite style tends to combine these, which one could argue does not separate responsibilities well enough.  On the other hand, one could also make an argument that the composite style is a good way to implement precanned personas, eg "Joe", the customer who has a newly placed order, from "Mary" customer who has none.
 


[13/52] [abbrv] isis git commit: ISIS-1243: removing manpage from .adoc file names.

Posted by mg...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-hide.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-hide.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-hide.adoc
deleted file mode 100644
index 73cce6d..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-hide.adoc
+++ /dev/null
@@ -1,82 +0,0 @@
-[[_rgcms_methods_prefixes_manpage-hide]]
-= `hide...()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `hide...()` supporting method is called for properties, collections and actions.  It allows the property/collection to be completely hidden from view.
-
-It's comparatively rare for properties or collections to be imperatively hidden from view, but actions are sometimes hidden or shown visible (as opposed to being just xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-disable[disabled], ie greyed out).
-
-
-== Actions
-
-For an action the signature of the supporting method is either:
-
-[source,java]
-----
-public bool hideXxx(...) { ... }
-----
-
-where the supporting method takes the same parameter types as the action itself, or more simply:
-
-[source,java]
-----
-public bool hideXxx() { ... }
-----
-
-with no parameters at all.  Returning `true` will hide the action, returning `false` leaves it visible.
-
-
-For example:
-
-[source,java]
-----
-public class Customer {
-    public boolean isBlacklisted() { ... }
-
-    public Order placeOrder(
-            final Product product,
-            @ParameterLayout(named="Quantity")
-            final int quantity) {
-        ...
-    }
-    public boolean hidePlaceOrder() {
-        return isBlacklisted();
-    }
-    ...
-}
-----
-
-
-
-== Properties and Collections
-
-For both properties and collections the signature of the supporting method is:
-
-[source,java]
-----
-public boolean hideXxx() { ... }
-----
-
-where returning `true` will hide the property/collection, returning `false` leaves it visible.
-
-
-
-For example:
-
-[source,java]
-----
-public class Customer {
-    public boolean isBlacklisted() { ... }
-
-    public BigDecimal getCreditLimit() { ... }
-    public void setCreditLimit(BigDecimal creditLimit) { ... }
-    public boolean hideCreditLimit() {
-        return isBlacklisted();
-    }
-    ...
-}
-----

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-modify.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-modify.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-modify.adoc
deleted file mode 100644
index faee86d..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-modify.adoc
+++ /dev/null
@@ -1,37 +0,0 @@
-[[_rgcms_methods_prefixes_manpage-modify]]
-= `modify...()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `modify...()` supporting method is called -- instead of the setter -- whenever a property has been set to be set to a new value.  Its purpose is to allow additional business logic to be performed.
-
-
-For example:
-
-[source,java]
-----
-public class LibraryMember {
-    public Title getFavoriteTitle() { ... }
-    public void setFavoriteTitle(Title title) { ... }
-    public void modifyFavoriteTitle(Title title) {
-        if(getTitle() != null) {
-            titleFavoritesService.decrement(getTitle());    // <1>
-        }
-        setFavoriteTitle(title);                            // <2>
-        titleFavoritesService.decrement(title);             // <3>
-    }
-    public void clearFavoriteTitle() { ... }
-    ...
-}
-----
-<1> perform some additional business logic
-<2> update the property
-<3> perform some additional business logic
-
-
-See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-clear[`clear...()`]`
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-removeFrom.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-removeFrom.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-removeFrom.adoc
deleted file mode 100644
index 88ef934..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-removeFrom.adoc
+++ /dev/null
@@ -1,37 +0,0 @@
-[[_rgcms_methods_prefixes_manpage-removeFrom]]
-= `removeFrom...()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `removeFrom...()` supporting method is called whenever an object is removed from a collection. Its purpose is to allow additional business logic to be performed.
-
-
-[NOTE]
-====
-Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer].  The suggested workaround is to simply define an action.
-====
-
-
-For example:
-
-[source,java]
-----
-public class LibraryMember {
-    public SortedSet<Book> getBorrowed() { ... }
-    public void setBorrowed(SortedSet<Book> borrowed) { ... }
-    public void addToBorrowed(Book book) { ... }
-    public void removeFromBorrowed(Book book) {
-        getBorrowed().remove(book);                         // <1>
-        reminderService.removeReminder(this, book);         // <2>
-    }
-    ...
-}
-----
-<1> update the collection
-<2> perform some additional business logic
-
-
-See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-addTo[`addTo...()`]`

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-set.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-set.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-set.adoc
deleted file mode 100644
index 03d9f0d..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-set.adoc
+++ /dev/null
@@ -1,13 +0,0 @@
-[[_rgcms_methods_prefixes_manpage-set]]
-= `set...()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-
-The `set...()` prefix is simply the normal JavaBean setter prefix that denotes writeable properties or collections.
-
-
-See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-get[`get...()`].

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-validate.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-validate.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-validate.adoc
deleted file mode 100644
index 74ccf58..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-validate.adoc
+++ /dev/null
@@ -1,113 +0,0 @@
-[[_rgcms_methods_prefixes_manpage-validate]]
-= `validate...()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `validate...()` supporting method is called for properties, actions and action parameters.  It allows the proposed new value for a property to be rejected, or the proposed argument of an action parameter to be rejected, or to reject a whole set of action arguments for an actio invocation.
-
-
-The reason for vetoing a modification/invocation is normally returned as a string.  However, Apache Isis' xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[i18n support] extends this so that reasons can be internationalized if required.
-
-
-
-== Action Parameter
-
-For an action parameter in (0-based) position _N_, and of type `T`, the signature is:
-
-[source,java]
-----
-public String validateNXxx(T proposed) { ... }
-----
-
-where the returned string is the reason why the argument is rejected (or `null` if not vetoed).
-
-
-For example:
-
-[source,java]
-----
-public class Customer {
-    public Order placeOrder(
-            final Product product,
-            @ParameterLayout(named="Quantity")
-            final int quantity) {
-        ...
-    }
-    public String validate0PlaceOrder(
-            final Product product) {
-        return product.isDiscontinued()
-                    ? "Product has been discontinued"
-                    : null;
-    }
-    ...
-}
-----
-
-
-== Action Parameter Set
-
-In addition to validating a single single action argument, it is also possible to validate a complete set of action arguments.  The signature is:
-
-[source,java]
-----
-public String validateXxx(...) { ... }
-----
-
-where the returned string is the reason why the argument is rejected (or `null` if not vetoed), and the supporting method takes the same parameter types as the action itself.
-
-
-For example:
-
-[source,java]
-----
-public class Customer {
-    public Order placeOrder(
-            final Product product,
-            @ParameterLayout(named="Quantity")
-            final int quantity) {
-        ...
-    }
-    public String validatePlaceOrder(
-            final Product product,
-            final int quantity) {
-        return quantity > product.getOrderLimit()
-                    ? "May not order more than " + product.getOrderLimit() + " items for this product"
-                    : null;
-    }
-    ...
-}
-----
-
-
-
-== Properties
-
-For properties of type `T` the signature of the supporting method is:
-
-[source,java]
-----
-public String validateXxx(T proposed) { ... }
-----
-
-where the returned string is the reason the modification is vetoed (or `null` if not vetoed).
-
-
-
-For example:
-
-[source,java]
-----
-public class Customer {
-    public BigDecimal getCreditLimit() { ... }
-    public void setCreditLimit(BigDecimal creditLimit) { ... }
-    public validateCreditLimit(BigDecimal creditLimit) {
-        return creditLimit.compareTo(BigDecimal.ZERO) < 0
-                    ? "Credit limit cannot be negative"
-                    : null;
-    }
-    ...
-}
-----

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-validateAddTo.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-validateAddTo.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-validateAddTo.adoc
deleted file mode 100644
index 3458533..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-validateAddTo.adoc
+++ /dev/null
@@ -1,45 +0,0 @@
-[[_rgcms_methods_prefixes_manpage-validateAddTo]]
-= `validateAddTo...()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `validateAddTo...()` supporting method is called whenever an object is to be added to a collection. Its purpose is to validate the proposed object and possibly veto the change.
-
-
-[NOTE]
-====
-Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer].  The suggested workaround is to simply define an action.
-====
-
-
-The signature of the supporting method for a collection with element type `E` is:
-
-[source,java]
-----
-public String validateAddToXxx(E element) { ... }
-----
-
-where the returned string is the reason the collection modification invocation is vetoed (or `null` if not vetoed).  Apache Isis' xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[i18n support] extends this so that reasons can be internationalized if required.
-
-
-For example:
-
-[source,java]
-----
-public class LibraryMember {
-    public SortedSet<Book> getBorrowed() { ... }
-    public void setBorrowed(SortedSet<Book> borrowed) { ... }
-    public String validateAddToBorrowed(Book book) {
-        return book.isReference()? "Reference books cannot be borrowed": null;
-    }
-    public void validateRemoveFromBorrowed(Book book) { ... }
-    ...
-}
-----
-
-
-See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-addTo[`addTo...()`] and  xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-validateRemoveFrom[`validateRemoveFrom...()`]`
-

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-validateRemoveFrom.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-validateRemoveFrom.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-validateRemoveFrom.adoc
deleted file mode 100644
index dbb9979..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-validateRemoveFrom.adoc
+++ /dev/null
@@ -1,45 +0,0 @@
-[[_rgcms_methods_prefixes_manpage-validateRemoveFrom]]
-= `validateRemoveFrom...()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `validateRemoveFrom...()` supporting method is called whenever an object is to be removed from a collection. Its purpose is to validate the proposed object removal and possibly veto the change.
-
-
-[NOTE]
-====
-Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer].  The suggested workaround is to simply define an action.
-====
-
-
-The signature of the supporting method for a collection with element type `E` is:
-
-[source,java]
-----
-public String validateRemoveFromXxx(E element) { ... }
-----
-
-where the returned string is the reason the collection modification invocation is vetoed (or `null` if not vetoed).  Apache Isis' xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[i18n support] extends this so that reasons can be internationalized if required.
-
-
-For example:
-
-[source,java]
-----
-public class LibraryMember {
-    public SortedSet<Book> getBorrowed() { ... }
-    public void setBorrowed(SortedSet<Book> borrowed) { ... }
-    public String validateAddToBorrowed(Book book) { ... }
-    public void validateRemoveFromBorrowed(Book book) {
-        return !book.hasBeenReadBy(this)? "You didn't read this book yet": null;
-    }
-    ...
-}
-----
-
-
-See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-removeFrom[`removeFrom...()`] and  xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-validateAddTo[`validateAddTo...()`]`
-

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_modify.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_modify.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_modify.adoc
new file mode 100644
index 0000000..5920687
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_modify.adoc
@@ -0,0 +1,37 @@
+[[_rgcms_methods_prefixes_modify]]
+= `modify...()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The `modify...()` supporting method is called -- instead of the setter -- whenever a property has been set to be set to a new value.  Its purpose is to allow additional business logic to be performed.
+
+
+For example:
+
+[source,java]
+----
+public class LibraryMember {
+    public Title getFavoriteTitle() { ... }
+    public void setFavoriteTitle(Title title) { ... }
+    public void modifyFavoriteTitle(Title title) {
+        if(getTitle() != null) {
+            titleFavoritesService.decrement(getTitle());    // <1>
+        }
+        setFavoriteTitle(title);                            // <2>
+        titleFavoritesService.decrement(title);             // <3>
+    }
+    public void clearFavoriteTitle() { ... }
+    ...
+}
+----
+<1> perform some additional business logic
+<2> update the property
+<3> perform some additional business logic
+
+
+See also xref:rgcms.adoc#_rgcms_methods_prefixes_clear[`clear...()`]`
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_removeFrom.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_removeFrom.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_removeFrom.adoc
new file mode 100644
index 0000000..ecf499c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_removeFrom.adoc
@@ -0,0 +1,37 @@
+[[_rgcms_methods_prefixes_removeFrom]]
+= `removeFrom...()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The `removeFrom...()` supporting method is called whenever an object is removed from a collection. Its purpose is to allow additional business logic to be performed.
+
+
+[NOTE]
+====
+Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer].  The suggested workaround is to simply define an action.
+====
+
+
+For example:
+
+[source,java]
+----
+public class LibraryMember {
+    public SortedSet<Book> getBorrowed() { ... }
+    public void setBorrowed(SortedSet<Book> borrowed) { ... }
+    public void addToBorrowed(Book book) { ... }
+    public void removeFromBorrowed(Book book) {
+        getBorrowed().remove(book);                         // <1>
+        reminderService.removeReminder(this, book);         // <2>
+    }
+    ...
+}
+----
+<1> update the collection
+<2> perform some additional business logic
+
+
+See also xref:rgcms.adoc#_rgcms_methods_prefixes_addTo[`addTo...()`]`

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_set.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_set.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_set.adoc
new file mode 100644
index 0000000..4135bf1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_set.adoc
@@ -0,0 +1,13 @@
+[[_rgcms_methods_prefixes_set]]
+= `set...()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+
+The `set...()` prefix is simply the normal JavaBean setter prefix that denotes writeable properties or collections.
+
+
+See also xref:rgcms.adoc#_rgcms_methods_prefixes_get[`get...()`].

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_validate.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_validate.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_validate.adoc
new file mode 100644
index 0000000..4c85cf9
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_validate.adoc
@@ -0,0 +1,113 @@
+[[_rgcms_methods_prefixes_validate]]
+= `validate...()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The `validate...()` supporting method is called for properties, actions and action parameters.  It allows the proposed new value for a property to be rejected, or the proposed argument of an action parameter to be rejected, or to reject a whole set of action arguments for an actio invocation.
+
+
+The reason for vetoing a modification/invocation is normally returned as a string.  However, Apache Isis' xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[i18n support] extends this so that reasons can be internationalized if required.
+
+
+
+== Action Parameter
+
+For an action parameter in (0-based) position _N_, and of type `T`, the signature is:
+
+[source,java]
+----
+public String validateNXxx(T proposed) { ... }
+----
+
+where the returned string is the reason why the argument is rejected (or `null` if not vetoed).
+
+
+For example:
+
+[source,java]
+----
+public class Customer {
+    public Order placeOrder(
+            final Product product,
+            @ParameterLayout(named="Quantity")
+            final int quantity) {
+        ...
+    }
+    public String validate0PlaceOrder(
+            final Product product) {
+        return product.isDiscontinued()
+                    ? "Product has been discontinued"
+                    : null;
+    }
+    ...
+}
+----
+
+
+== Action Parameter Set
+
+In addition to validating a single single action argument, it is also possible to validate a complete set of action arguments.  The signature is:
+
+[source,java]
+----
+public String validateXxx(...) { ... }
+----
+
+where the returned string is the reason why the argument is rejected (or `null` if not vetoed), and the supporting method takes the same parameter types as the action itself.
+
+
+For example:
+
+[source,java]
+----
+public class Customer {
+    public Order placeOrder(
+            final Product product,
+            @ParameterLayout(named="Quantity")
+            final int quantity) {
+        ...
+    }
+    public String validatePlaceOrder(
+            final Product product,
+            final int quantity) {
+        return quantity > product.getOrderLimit()
+                    ? "May not order more than " + product.getOrderLimit() + " items for this product"
+                    : null;
+    }
+    ...
+}
+----
+
+
+
+== Properties
+
+For properties of type `T` the signature of the supporting method is:
+
+[source,java]
+----
+public String validateXxx(T proposed) { ... }
+----
+
+where the returned string is the reason the modification is vetoed (or `null` if not vetoed).
+
+
+
+For example:
+
+[source,java]
+----
+public class Customer {
+    public BigDecimal getCreditLimit() { ... }
+    public void setCreditLimit(BigDecimal creditLimit) { ... }
+    public validateCreditLimit(BigDecimal creditLimit) {
+        return creditLimit.compareTo(BigDecimal.ZERO) < 0
+                    ? "Credit limit cannot be negative"
+                    : null;
+    }
+    ...
+}
+----

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_validateAddTo.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_validateAddTo.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_validateAddTo.adoc
new file mode 100644
index 0000000..5b1f535
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_validateAddTo.adoc
@@ -0,0 +1,45 @@
+[[_rgcms_methods_prefixes_validateAddTo]]
+= `validateAddTo...()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The `validateAddTo...()` supporting method is called whenever an object is to be added to a collection. Its purpose is to validate the proposed object and possibly veto the change.
+
+
+[NOTE]
+====
+Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer].  The suggested workaround is to simply define an action.
+====
+
+
+The signature of the supporting method for a collection with element type `E` is:
+
+[source,java]
+----
+public String validateAddToXxx(E element) { ... }
+----
+
+where the returned string is the reason the collection modification invocation is vetoed (or `null` if not vetoed).  Apache Isis' xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[i18n support] extends this so that reasons can be internationalized if required.
+
+
+For example:
+
+[source,java]
+----
+public class LibraryMember {
+    public SortedSet<Book> getBorrowed() { ... }
+    public void setBorrowed(SortedSet<Book> borrowed) { ... }
+    public String validateAddToBorrowed(Book book) {
+        return book.isReference()? "Reference books cannot be borrowed": null;
+    }
+    public void validateRemoveFromBorrowed(Book book) { ... }
+    ...
+}
+----
+
+
+See also xref:rgcms.adoc#_rgcms_methods_prefixes_addTo[`addTo...()`] and  xref:rgcms.adoc#_rgcms_methods_prefixes_validateRemoveFrom[`validateRemoveFrom...()`]`
+

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_validateRemoveFrom.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_validateRemoveFrom.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_validateRemoveFrom.adoc
new file mode 100644
index 0000000..773b269
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_validateRemoveFrom.adoc
@@ -0,0 +1,45 @@
+[[_rgcms_methods_prefixes_validateRemoveFrom]]
+= `validateRemoveFrom...()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The `validateRemoveFrom...()` supporting method is called whenever an object is to be removed from a collection. Its purpose is to validate the proposed object removal and possibly veto the change.
+
+
+[NOTE]
+====
+Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer].  The suggested workaround is to simply define an action.
+====
+
+
+The signature of the supporting method for a collection with element type `E` is:
+
+[source,java]
+----
+public String validateRemoveFromXxx(E element) { ... }
+----
+
+where the returned string is the reason the collection modification invocation is vetoed (or `null` if not vetoed).  Apache Isis' xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[i18n support] extends this so that reasons can be internationalized if required.
+
+
+For example:
+
+[source,java]
+----
+public class LibraryMember {
+    public SortedSet<Book> getBorrowed() { ... }
+    public void setBorrowed(SortedSet<Book> borrowed) { ... }
+    public String validateAddToBorrowed(Book book) { ... }
+    public void validateRemoveFromBorrowed(Book book) {
+        return !book.hasBeenReadBy(this)? "You didn't read this book yet": null;
+    }
+    ...
+}
+----
+
+
+See also xref:rgcms.adoc#_rgcms_methods_prefixes_removeFrom[`removeFrom...()`] and  xref:rgcms.adoc#_rgcms_methods_prefixes_validateAddTo[`validateAddTo...()`]`
+

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved.adoc
index bae5286..e405888 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved.adoc
@@ -15,33 +15,33 @@ The table below lists the reserved methods that are recognized as part of Apache
 |Method
 |Description
 
-|xref:rgcms.adoc#_rgcms_methods_reserved_manpage-cssClass[`cssClass()`]
+|xref:rgcms.adoc#_rgcms_methods_reserved_cssClass[`cssClass()`]
 |Provides a CSS class for this object instance.  In conjunction with xref:rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css`], can therefore provide custom styling of an object instance wherever it is rendered. +
 
-See also xref:rgcms.adoc#_rgcms_methods_reserved_manpage-title[`title()`] and xref:rgcms.adoc#_rgcms_methods_reserved_manpage-iconName[`iconName()`].
+See also xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`] and xref:rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`].
 
-|xref:rgcms.adoc#_rgcms_methods_reserved_manpage-disable[`disable(...)`]
+|xref:rgcms.adoc#_rgcms_methods_reserved_disable[`disable(...)`]
 |Disable all or some of an object's properties
 
-|xref:rgcms.adoc#_rgcms_methods_reserved_manpage-getId[`getId()`]
+|xref:rgcms.adoc#_rgcms_methods_reserved_getId[`getId()`]
 |Provides an optional unique identifier of a service. +
 
 If not provided, the service's fully-qualified class name is used.
 
-|xref:rgcms.adoc#_rgcms_methods_reserved_manpage-hide[`hide(...)`]
+|xref:rgcms.adoc#_rgcms_methods_reserved_hide[`hide(...)`]
 |Hide all or some of an object's properties
 
-|xref:rgcms.adoc#_rgcms_methods_reserved_manpage-iconName[`iconName()`]
+|xref:rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`]
 |Provides the name of the image to render, usually alongside the title, to represent the object. If not provided, then the class name is used to locate an image. +
 
-See also xref:rgcms.adoc#_rgcms_methods_reserved_manpage-title[`title()`] and xref:rgcms.adoc#_rgcms_methods_reserved_manpage-cssClass[`cssClass()`]
+See also xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`] and xref:rgcms.adoc#_rgcms_methods_reserved_cssClass[`cssClass()`]
 
-|xref:rgcms.adoc#_rgcms_methods_reserved_manpage-title[`title()`]
+|xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`]
 |Provides a title for the object. +
 
-See also xref:rgcms.adoc#_rgcms_methods_reserved_manpage-iconName[`iconName()`] and xref:rgcms.adoc#_rgcms_methods_reserved_manpage-cssClass[`cssClass()`]
+See also xref:rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`] and xref:rgcms.adoc#_rgcms_methods_reserved_cssClass[`cssClass()`]
 
-|xref:rgcms.adoc#_rgcms_methods_reserved_manpage-validate[`validate()`]
+|xref:rgcms.adoc#_rgcms_methods_reserved_validate[`validate()`]
 |Validate the object's state prior to persisting.
 
 |===
@@ -49,10 +49,10 @@ See also xref:rgcms.adoc#_rgcms_methods_reserved_manpage-iconName[`iconName()`]
 
 
 
-include::_rgcms_methods_reserved_manpage-cssClass.adoc[leveloffset=+1]
-include::_rgcms_methods_reserved_manpage-disable.adoc[leveloffset=+1]
-include::_rgcms_methods_reserved_manpage-getId.adoc[leveloffset=+1]
-include::_rgcms_methods_reserved_manpage-hide.adoc[leveloffset=+1]
-include::_rgcms_methods_reserved_manpage-iconName.adoc[leveloffset=+1]
-include::_rgcms_methods_reserved_manpage-title.adoc[leveloffset=+1]
-include::_rgcms_methods_reserved_manpage-validate.adoc[leveloffset=+1]
+include::_rgcms_methods_reserved_cssClass.adoc[leveloffset=+1]
+include::_rgcms_methods_reserved_disable.adoc[leveloffset=+1]
+include::_rgcms_methods_reserved_getId.adoc[leveloffset=+1]
+include::_rgcms_methods_reserved_hide.adoc[leveloffset=+1]
+include::_rgcms_methods_reserved_iconName.adoc[leveloffset=+1]
+include::_rgcms_methods_reserved_title.adoc[leveloffset=+1]
+include::_rgcms_methods_reserved_validate.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_cssClass.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_cssClass.adoc
new file mode 100644
index 0000000..9e98b39
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_cssClass.adoc
@@ -0,0 +1,46 @@
+[[_rgcms_methods_reserved_cssClass]]
+= `cssClass()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The `cssClass()` returns a CSS class for a particular object instance.
+
+The xref:ugvw.adoc#[Wicket viewer] wraps the object's representation in a containing `<div>` with the class added.  This is done both for rendering the object either in a table or when rendering the object on its own page.
+
+In conjunction with xref:rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css`], can therefore provide custom styling of an object instance wherever it is rendered. +
+
+
+For example, the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] uses this technique to add a strikethrough for completed todo items.  This is shown on the home page:
+
+image::{_imagesdir}reference-methods/reserved/cssClass/strikethrough.png[width="800px",link="{_imagesdir}reference-methods/reserved/cssClass/strikethrough.png"]
+
+
+The code to accomplish this is straightforward:
+
+[source,java]
+----
+public class ToDoItem ... {
+    public String cssClass() {
+        return !isComplete() ? "todo" : "done";
+    }
+    ...
+}
+----
+
+In the xref:rgcfg.adoc#_rgcfg_application-specific_application-css[application.css], the following styles were then added:
+
+[source,css]
+----
+tr.todo {
+}
+tr.done {
+    text-decoration: line-through;
+    color: #d3d3d3;
+}
+----
+
+
+See also xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`] and xref:rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`].

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_disable.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_disable.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_disable.adoc
new file mode 100644
index 0000000..0490c73
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_disable.adoc
@@ -0,0 +1,102 @@
+[[_rgcms_methods_reserved_disable]]
+= `disable()`
+: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/
+
+
+One use case that Apache Isis supports is that of a domain object with a lifecycle whereby at some stage it should become immutable: all its properties/collections should be disabled, and/or its actions become not invokable.
+
+It would be painful to have to write a separate xref:rgcms.adoc#_rgcms_methods_prefixes_disable[`disable...()`] method for each and every member, so instead Isis allows a single `disable...(...)` method to be implemented that is applied to all members.
+
+The signature of the method is:
+
+[source,java]
+----
+public String disable(Identifier.Type identifierType) { ... }
+----
+
+where `Identifier.Type` is part of the Isis applib (nested static class of `o.a.i.applib.Identifier`) to distinguish between an interaction with an action, a property or an action.
+
+Note that Apache Isis' xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[i18n support] extends this so that the returned reason can also be internationalized.
+
+For example:
+
+[source,java]
+----
+public String disable(Identifier.Type identifierType) {
+    return !calendarService.isOfficeHours(clock.today()
+            ? "Cannot modify objects outside of office hours"
+            : null;
+}
+----
+
+See also the similar methods to xref:rgcms.adoc#_rgcms_methods_reserved_hide[`hide()`] object members en-masse.
+
+
+== Alternatives
+
+An alternative design -- and one that could be easily argued is actually more flexible -- is to leverage domain events with vetoing subscribers.
+
+With this approach we define, for a given domain class, a base `PropertyDomainEvent`, `CollectionDomainEvent` and `ActionDomainEvent`.  A good pattern is to make these nested static classes.  For example:
+
+[source,java]
+----
+public class ToDoItem ... {
+    public static abstract class PropertyDomainEvent<T>
+            extends ToDoAppDomainModule.PropertyDomainEvent<ToDoItem, T> {
+        ...
+    }
+    ...
+}
+----
+
+where in turn:
+
+[source,java]
+----
+public final class ToDoAppDomainModule {
+    private ToDoAppDomainModule(){}
+    public abstract static class PropertyDomainEvent<S,T>
+            extends org.apache.isis.applib.services.eventbus.PropertyDomainEvent<S,T> {
+        ...
+    }
+    ...
+}
+----
+
+Then, each property/collection/action emits either these base domain events or their own subclass:
+
+[source,java]
+----
+public class ToDoItem ... {
+    public static class DescriptionDomainEvent
+            extends PropertyDomainEvent<String> {
+        ...
+    }
+    @Property(
+        domainEvent = DescriptionDomainEvent.class
+    )
+    public String getDescription() { ... }
+    ...
+}
+----
+
+A vetoing subscriber can then subscribe to the domain events and veto access, eg:
+
+[source,java]
+----
+@DomainObject
+public class VetoOutOfOfficeHours {
+    @Subscribe
+    public void on(ToDoItem.PropertyDomainEvent ev) {
+        if(!calendarService.isOfficeHours(clock.today()) {
+            ev.veto("Cannot modify objects outside of office hours");
+        }
+    }
+    ...
+}
+----
+
+Obviously there's an awful lot more boilerplate here, but there's also a lot more flexibility.
+

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_getId.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_getId.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_getId.adoc
new file mode 100644
index 0000000..3c37320
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_getId.adoc
@@ -0,0 +1,19 @@
+[[_rgcms_methods_reserved_getId]]
+= `getId()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+The `getId()` method applies only to domain services, and allows a unique identifer to be provided for that service.
+
+This identifier corresponds in many ways to the xref:rgant.adoc#_rgant-DomainObject_objectType[`objectType()`] attribute for domain objects; it is used as an internal identifier but also appears in URLs within the xref:ugvro.adoc#[RestfulObjects viewer]'s REST API.
+
+If the identifier is omitted, the services fully qualified class name is used.
+
+[TIP]
+====
+Unlike domain objects, where the use of an object type is strongly encouraged (eg using xref:rgant.adoc#_rgant-PersistenceCapable[`@PersistenceCapable`]), it matters much less if an id is specified for domain services.  The principle benefit is shorter URLs in the REST API.
+====
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_hide.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_hide.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_hide.adoc
new file mode 100644
index 0000000..0ee32e7
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_hide.adoc
@@ -0,0 +1,39 @@
+[[_rgcms_methods_reserved_hide]]
+= `hide()`
+: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/
+
+
+
+One use case that Apache Isis supports is that of a domain object with a lifecycle whereby at some stage some number of the object's members should be hidden.  For example, for an object that at some stage is logically immutable, we might want to make all its properties/collections unmodifiable and hide all its actions.
+
+While we could write a separate xref:rgcms.adoc#_rgcms_methods_prefixes_hide[`hide...()`] method for each and every action, this could become painful.  So instead Isis allows a single `hide...(...)` method to be implemented that is applied to all members.
+
+The signature of the method is:
+
+[source,java]
+----
+public boolean hide(Identifier.Type identifierType) { ... }
+----
+
+where `Identifier.Type` is part of the Isis applib (nested static class of `o.a.i.applib.Identifier`) to distinguish between an interaction with an action, a property or an action.
+
+For example:
+
+[source,java]
+----
+public boolean hide(Identifier.Type identifierType) {
+    return identifierType == Identifier.Type.ACTION && isFrozen();
+}
+----
+
+See also the similar method to xref:rgcms.adoc#_rgcms_methods_reserved_disable[`disable()`] object members en-masse.
+
+
+== Alternatives
+
+An alternative design -- and one that could be easily argued is actually more flexible -- is to leverage domain events with vetoing subscribers.
+
+There is further discussion on this approach in xref:rgcms.adoc#_rgcms_methods_reserved_disable[here].
+

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_iconName.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_iconName.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_iconName.adoc
new file mode 100644
index 0000000..b9e74b1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_iconName.adoc
@@ -0,0 +1,36 @@
+[[_rgcms_methods_reserved_iconName]]
+= `iconName()`
+: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/
+
+
+Every object is represented by an icon; this is based on the domain object's simple name.  The xref:ugvw.adoc#[Wicket viewer] searches for the image in the same package as the `.class` file for the domain object.
+
+The `iconName()` allows the icon that to be used to change for individual object instances.  These are usually quite subtle, for example to reflect the particular status of an object.  The value returned by the `iconName()` method is added as a suffix to the base icon name.
+
+For example, the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] uses this technique to add an overlay for todo items that have been completed:
+
+image::{_imagesdir}reference-methods/reserved/iconName/differing.png[width="200px",link="{_imagesdir}reference-methods/reserved/iconName/differing.png"]
+
+
+
+The screenshot below shows the location of these png icon files:
+
+image::{_imagesdir}reference-methods/reserved/iconName/png-files.png[width="200px",link="{_imagesdir}reference-methods/reserved/iconName/png-files.png"]
+
+
+
+The code to accomplish this is straightforward:
+
+[source,java]
+----
+public class ToDoItem ... {
+    public String iconName() {
+        return !isComplete() ? "todo" : "done";
+    }
+    ...
+}
+----
+
+See also xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`] and xref:rgcms.adoc#_rgcms_methods_reserved_cssClass[`cssClass()`]

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-cssClass.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-cssClass.adoc
deleted file mode 100644
index ecf7f39..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-cssClass.adoc
+++ /dev/null
@@ -1,46 +0,0 @@
-[[_rgcms_methods_reserved_manpage-cssClass]]
-= `cssClass()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `cssClass()` returns a CSS class for a particular object instance.
-
-The xref:ugvw.adoc#[Wicket viewer] wraps the object's representation in a containing `<div>` with the class added.  This is done both for rendering the object either in a table or when rendering the object on its own page.
-
-In conjunction with xref:rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css`], can therefore provide custom styling of an object instance wherever it is rendered. +
-
-
-For example, the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] uses this technique to add a strikethrough for completed todo items.  This is shown on the home page:
-
-image::{_imagesdir}reference-methods/reserved/cssClass/strikethrough.png[width="800px",link="{_imagesdir}reference-methods/reserved/cssClass/strikethrough.png"]
-
-
-The code to accomplish this is straightforward:
-
-[source,java]
-----
-public class ToDoItem ... {
-    public String cssClass() {
-        return !isComplete() ? "todo" : "done";
-    }
-    ...
-}
-----
-
-In the xref:rgcfg.adoc#_rgcfg_application-specific_application-css[application.css], the following styles were then added:
-
-[source,css]
-----
-tr.todo {
-}
-tr.done {
-    text-decoration: line-through;
-    color: #d3d3d3;
-}
-----
-
-
-See also xref:rgcms.adoc#_rgcms_methods_reserved_manpage-title[`title()`] and xref:rgcms.adoc#_rgcms_methods_reserved_manpage-iconName[`iconName()`].

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-disable.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-disable.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-disable.adoc
deleted file mode 100644
index a56b684..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-disable.adoc
+++ /dev/null
@@ -1,102 +0,0 @@
-[[_rgcms_methods_reserved_manpage-disable]]
-= `disable()`
-: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/
-
-
-One use case that Apache Isis supports is that of a domain object with a lifecycle whereby at some stage it should become immutable: all its properties/collections should be disabled, and/or its actions become not invokable.
-
-It would be painful to have to write a separate xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-disable[`disable...()`] method for each and every member, so instead Isis allows a single `disable...(...)` method to be implemented that is applied to all members.
-
-The signature of the method is:
-
-[source,java]
-----
-public String disable(Identifier.Type identifierType) { ... }
-----
-
-where `Identifier.Type` is part of the Isis applib (nested static class of `o.a.i.applib.Identifier`) to distinguish between an interaction with an action, a property or an action.
-
-Note that Apache Isis' xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[i18n support] extends this so that the returned reason can also be internationalized.
-
-For example:
-
-[source,java]
-----
-public String disable(Identifier.Type identifierType) {
-    return !calendarService.isOfficeHours(clock.today()
-            ? "Cannot modify objects outside of office hours"
-            : null;
-}
-----
-
-See also the similar methods to xref:rgcms.adoc#_rgcms_methods_reserved_manpage-hide[`hide()`] object members en-masse.
-
-
-== Alternatives
-
-An alternative design -- and one that could be easily argued is actually more flexible -- is to leverage domain events with vetoing subscribers.
-
-With this approach we define, for a given domain class, a base `PropertyDomainEvent`, `CollectionDomainEvent` and `ActionDomainEvent`.  A good pattern is to make these nested static classes.  For example:
-
-[source,java]
-----
-public class ToDoItem ... {
-    public static abstract class PropertyDomainEvent<T>
-            extends ToDoAppDomainModule.PropertyDomainEvent<ToDoItem, T> {
-        ...
-    }
-    ...
-}
-----
-
-where in turn:
-
-[source,java]
-----
-public final class ToDoAppDomainModule {
-    private ToDoAppDomainModule(){}
-    public abstract static class PropertyDomainEvent<S,T>
-            extends org.apache.isis.applib.services.eventbus.PropertyDomainEvent<S,T> {
-        ...
-    }
-    ...
-}
-----
-
-Then, each property/collection/action emits either these base domain events or their own subclass:
-
-[source,java]
-----
-public class ToDoItem ... {
-    public static class DescriptionDomainEvent
-            extends PropertyDomainEvent<String> {
-        ...
-    }
-    @Property(
-        domainEvent = DescriptionDomainEvent.class
-    )
-    public String getDescription() { ... }
-    ...
-}
-----
-
-A vetoing subscriber can then subscribe to the domain events and veto access, eg:
-
-[source,java]
-----
-@DomainObject
-public class VetoOutOfOfficeHours {
-    @Subscribe
-    public void on(ToDoItem.PropertyDomainEvent ev) {
-        if(!calendarService.isOfficeHours(clock.today()) {
-            ev.veto("Cannot modify objects outside of office hours");
-        }
-    }
-    ...
-}
-----
-
-Obviously there's an awful lot more boilerplate here, but there's also a lot more flexibility.
-

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-getId.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-getId.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-getId.adoc
deleted file mode 100644
index e2a46ea..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-getId.adoc
+++ /dev/null
@@ -1,19 +0,0 @@
-[[_rgcms_methods_reserved_manpage-getId]]
-= `getId()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-The `getId()` method applies only to domain services, and allows a unique identifer to be provided for that service.
-
-This identifier corresponds in many ways to the xref:rgant.adoc#_rgant-DomainObject_objectType[`objectType()`] attribute for domain objects; it is used as an internal identifier but also appears in URLs within the xref:ugvro.adoc#[RestfulObjects viewer]'s REST API.
-
-If the identifier is omitted, the services fully qualified class name is used.
-
-[TIP]
-====
-Unlike domain objects, where the use of an object type is strongly encouraged (eg using xref:rgant.adoc#_rgant-PersistenceCapable[`@PersistenceCapable`]), it matters much less if an id is specified for domain services.  The principle benefit is shorter URLs in the REST API.
-====
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-hide.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-hide.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-hide.adoc
deleted file mode 100644
index c069657..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-hide.adoc
+++ /dev/null
@@ -1,39 +0,0 @@
-[[_rgcms_methods_reserved_manpage-hide]]
-= `hide()`
-: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/
-
-
-
-One use case that Apache Isis supports is that of a domain object with a lifecycle whereby at some stage some number of the object's members should be hidden.  For example, for an object that at some stage is logically immutable, we might want to make all its properties/collections unmodifiable and hide all its actions.
-
-While we could write a separate xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-hide[`hide...()`] method for each and every action, this could become painful.  So instead Isis allows a single `hide...(...)` method to be implemented that is applied to all members.
-
-The signature of the method is:
-
-[source,java]
-----
-public boolean hide(Identifier.Type identifierType) { ... }
-----
-
-where `Identifier.Type` is part of the Isis applib (nested static class of `o.a.i.applib.Identifier`) to distinguish between an interaction with an action, a property or an action.
-
-For example:
-
-[source,java]
-----
-public boolean hide(Identifier.Type identifierType) {
-    return identifierType == Identifier.Type.ACTION && isFrozen();
-}
-----
-
-See also the similar method to xref:rgcms.adoc#_rgcms_methods_reserved_manpage-disable[`disable()`] object members en-masse.
-
-
-== Alternatives
-
-An alternative design -- and one that could be easily argued is actually more flexible -- is to leverage domain events with vetoing subscribers.
-
-There is further discussion on this approach in xref:rgcms.adoc#_rgcms_methods_reserved_manpage-disable[here].
-

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-iconName.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-iconName.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-iconName.adoc
deleted file mode 100644
index 049151b..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-iconName.adoc
+++ /dev/null
@@ -1,36 +0,0 @@
-[[_rgcms_methods_reserved_manpage-iconName]]
-= `iconName()`
-: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/
-
-
-Every object is represented by an icon; this is based on the domain object's simple name.  The xref:ugvw.adoc#[Wicket viewer] searches for the image in the same package as the `.class` file for the domain object.
-
-The `iconName()` allows the icon that to be used to change for individual object instances.  These are usually quite subtle, for example to reflect the particular status of an object.  The value returned by the `iconName()` method is added as a suffix to the base icon name.
-
-For example, the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] uses this technique to add an overlay for todo items that have been completed:
-
-image::{_imagesdir}reference-methods/reserved/iconName/differing.png[width="200px",link="{_imagesdir}reference-methods/reserved/iconName/differing.png"]
-
-
-
-The screenshot below shows the location of these png icon files:
-
-image::{_imagesdir}reference-methods/reserved/iconName/png-files.png[width="200px",link="{_imagesdir}reference-methods/reserved/iconName/png-files.png"]
-
-
-
-The code to accomplish this is straightforward:
-
-[source,java]
-----
-public class ToDoItem ... {
-    public String iconName() {
-        return !isComplete() ? "todo" : "done";
-    }
-    ...
-}
-----
-
-See also xref:rgcms.adoc#_rgcms_methods_reserved_manpage-title[`title()`] and xref:rgcms.adoc#_rgcms_methods_reserved_manpage-cssClass[`cssClass()`]

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-title.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-title.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-title.adoc
deleted file mode 100644
index 394c9f1..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-title.adoc
+++ /dev/null
@@ -1,65 +0,0 @@
-[[_rgcms_methods_reserved_manpage-title]]
-= `title()`
-: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/
-
-
-
-Every object is represented by a title.  This appears both as a main header for the object when viewed as well as being used as a hyperlink within properties and collections.   It therefore must contain enough information for the end-user to distinguish the object from any others.
-
-This is most commonly done by including some unique key within the title, for example a customer's SSN, or an order number, and so forth.  However note that Apache Isis itself does _not_ require the title to be unique; it is merely recommended in most cases.
-
-An object's title can be constructed in various ways, but the most flexible is to use the `title()` method.  The signature of this method is usually:
-
-[source,java]
-----
-public String title() { ... }
-----
-
-Note that Apache Isis' xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[i18n support] extends this so that titles can also be internationalized.
-
-For example, the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] uses this technique to add an overlay for todo items that have been completed:
-
-[source,java]
-----
-public String title() {
-    final TitleBuffer buf = new TitleBuffer();                              // <1>
-    buf.append(getDescription());
-    if (isComplete()) {                                                     // <2>
-        buf.append("- Completed!");
-    } else {
-        try {
-            final LocalDate dueBy = wrapperFactory.wrap(this).getDueBy();   // <3>
-            if (dueBy != null) {
-                buf.append(" due by", dueBy);
-            }
-        } catch(final HiddenException ignored) {                            // <4>
-        }
-    }
-    return buf.toString();
-}
-----
-<1> simple xref:rgcms.adoc#_rgcms_classes_utility_manpage-TitleBuffer[tility class] to help construct the title string
-<2> imperative conditional logic
-<3> using the xref:rgsvc.adoc#_rgsvc-api_WrapperFactory[`WrapperFactory`] to determine if the `dueBy` field is visible for this user ...
-<4> ... but ignore if not
-
-As the example above shows, the implementation can be as complex as you like.
-
-In many cases, though, you may be able to use the xref:rgant.adoc#_rgant-Title[`@Title`] annotation.
-
-
-See also xref:rgcms.adoc#_rgcms_methods_reserved_manpage-iconName[`iconName()`] and xref:rgcms.adoc#_rgcms_methods_reserved_manpage-cssClass[`cssClass()`]
-
-
-
-
-
-
-
-
-
-
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-validate.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-validate.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-validate.adoc
deleted file mode 100644
index 24c83f9..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-validate.adoc
+++ /dev/null
@@ -1,27 +0,0 @@
-[[_rgcms_methods_reserved_manpage-validate]]
-= `validate()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `validate()` method is used to specify that invariants pertaining to an object's state are enforced.
-
-
-[WARNING]
-====
-(As of 1.8.0) there are known limitations with this functionality.  Invariants are enforced when an object is initially created and when it is edited, however invariants are currently _not_ enforced if an action is invoked.
-====
-
-
-The signature of the method is:
-
-[source,java]
-----
-public String validate() { ... }
-----
-
-where the returned string is the reason that the invocation is vetoed.
-
-Note that Apache Isis' xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[i18n support] extends this so that the returned reason can also be internationalized.

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_title.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_title.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_title.adoc
new file mode 100644
index 0000000..4a97ea5
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_title.adoc
@@ -0,0 +1,65 @@
+[[_rgcms_methods_reserved_title]]
+= `title()`
+: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/
+
+
+
+Every object is represented by a title.  This appears both as a main header for the object when viewed as well as being used as a hyperlink within properties and collections.   It therefore must contain enough information for the end-user to distinguish the object from any others.
+
+This is most commonly done by including some unique key within the title, for example a customer's SSN, or an order number, and so forth.  However note that Apache Isis itself does _not_ require the title to be unique; it is merely recommended in most cases.
+
+An object's title can be constructed in various ways, but the most flexible is to use the `title()` method.  The signature of this method is usually:
+
+[source,java]
+----
+public String title() { ... }
+----
+
+Note that Apache Isis' xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[i18n support] extends this so that titles can also be internationalized.
+
+For example, the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] uses this technique to add an overlay for todo items that have been completed:
+
+[source,java]
+----
+public String title() {
+    final TitleBuffer buf = new TitleBuffer();                              // <1>
+    buf.append(getDescription());
+    if (isComplete()) {                                                     // <2>
+        buf.append("- Completed!");
+    } else {
+        try {
+            final LocalDate dueBy = wrapperFactory.wrap(this).getDueBy();   // <3>
+            if (dueBy != null) {
+                buf.append(" due by", dueBy);
+            }
+        } catch(final HiddenException ignored) {                            // <4>
+        }
+    }
+    return buf.toString();
+}
+----
+<1> simple xref:rgcms.adoc#_rgcms_classes_utility_TitleBuffer[tility class] to help construct the title string
+<2> imperative conditional logic
+<3> using the xref:rgsvc.adoc#_rgsvc-api_WrapperFactory[`WrapperFactory`] to determine if the `dueBy` field is visible for this user ...
+<4> ... but ignore if not
+
+As the example above shows, the implementation can be as complex as you like.
+
+In many cases, though, you may be able to use the xref:rgant.adoc#_rgant-Title[`@Title`] annotation.
+
+
+See also xref:rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`] and xref:rgcms.adoc#_rgcms_methods_reserved_cssClass[`cssClass()`]
+
+
+
+
+
+
+
+
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_validate.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_validate.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_validate.adoc
new file mode 100644
index 0000000..3fae49e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_validate.adoc
@@ -0,0 +1,27 @@
+[[_rgcms_methods_reserved_validate]]
+= `validate()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The `validate()` method is used to specify that invariants pertaining to an object's state are enforced.
+
+
+[WARNING]
+====
+(As of 1.8.0) there are known limitations with this functionality.  Invariants are enforced when an object is initially created and when it is edited, however invariants are currently _not_ enforced if an action is invoked.
+====
+
+
+The signature of the method is:
+
+[source,java]
+----
+public String validate() { ... }
+----
+
+where the returned string is the reason that the invocation is vetoed.
+
+Note that Apache Isis' xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[i18n support] extends this so that the returned reason can also be internationalized.

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api.adoc
index 660f74e..b494369 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api.adoc
@@ -132,7 +132,7 @@ xref:rgsvc.adoc#_rgsvc-spi_CommandService[`CommandService`] for persistent `Comm
 `services.` +
 `fixturespec` +
 `FixtureScriptsDefault`]
-|Fallback implementation of xref:rgcms.adoc#_rgcms_classes_super_manpage-FixtureScripts[`FixtureScripts`], providing the ability to execute fixture scripts.
+|Fallback implementation of xref:rgcms.adoc#_rgcms_classes_super_FixtureScripts[`FixtureScripts`], providing the ability to execute fixture scripts.
 |`FixtureScriptsDefault` +
 ``o.a.i.core`` +
 ``isis-core-applib``
@@ -214,7 +214,7 @@ SpecificationProvider`].
 |xref:rgsvc.adoc#_rgsvc-api_SudoService[`o.a.i.applib.` +
 `services.sudo` +
 `SudoService`]
-|For use in testing while running xref:rgcms.adoc#_rgcms_classes_super_manpage-FixtureScripts[fixture scripts], allows a block of code to run as a specified user account.
+|For use in testing while running xref:rgcms.adoc#_rgcms_classes_super_FixtureScripts[fixture scripts], allows a block of code to run as a specified user account.
 |`SudoServiceDefault` +
 ``o.a.i.core`` +
 ``isis-core-runtime``

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_object-creation-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_object-creation-api.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_object-creation-api.adoc
index d24f7fb..0e5a50f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_object-creation-api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_object-creation-api.adoc
@@ -21,7 +21,7 @@ public interface DomainObjectContainer {
 }
 ----
 <1> create a new non-persisted domain entity.  Any services will be automatically injected into the service
-<2> create a new view model, with the specified memento (as per xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractViewModel[ViewModel#viewModelMemento()].  In general it is easier to just annotate with xref:rgant.adoc#_rgant-ViewModel[`@ViewModel`] and let Apache Isis manage the memento automatically.
+<2> create a new view model, with the specified memento (as per xref:rgcms.adoc#_rgcms_classes_super_AbstractViewModel[ViewModel#viewModelMemento()].  In general it is easier to just annotate with xref:rgant.adoc#_rgant-ViewModel[`@ViewModel`] and let Apache Isis manage the memento automatically.
 <3> programmatically instantiate a mixin, as annotated with
 xref:rgant.adoc#_rgant-Mixin[`@Mixin`] or xref:rgant.adoc#_rgant-DomainObject_nature[`@DomainObject#nature()`].
 
@@ -40,9 +40,9 @@ Doing this will not inject any domain services, but they can be injected manuall
 
 [NOTE]
 ====
-Calling `new(...)` also this circumvents Apache Isis' xref:rgcms.adoc#_rgcms_methods_reserved_manpage-created[`created()`]
+Calling `new(...)` also this circumvents Apache Isis' xref:rgcms.adoc#_rgcms_methods_reserved_created[`created()`]
 callback, and in addition any default values for properties (either explicitly set by
-xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-default[`default...()`] or defaulted implicitly according to Apache Isis'
+xref:rgcms.adoc#_rgcms_methods_prefixes_default[`default...()`] or defaulted implicitly according to Apache Isis'
 own conventions) will not be called either.  If you don't intend to use these features, though, the net effect is code
 that has less coupling to Isis and is arguably easier to understand (has "less magic" happening).
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_presentation-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_presentation-api.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_presentation-api.adoc
index a3de5d0..8c6378f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_presentation-api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_presentation-api.adoc
@@ -7,7 +7,7 @@
 
 
 
-A responsibility of every domain object is to return a title.  This can be done declaratively using the xref:rgant.adoc#_rgant-Title[`@Title`] annotation on property/ies, or it can be done imperatively by writing a xref:rgcms.adoc#_rgcms_methods_reserved_manpage-title[`title()`] method.
+A responsibility of every domain object is to return a title.  This can be done declaratively using the xref:rgant.adoc#_rgant-Title[`@Title`] annotation on property/ies, or it can be done imperatively by writing a xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`] method.
 
 It's quite common for titles to be built up of the titles of other objects.  If using building up the title using `@Title` then Apache Isis will automatically use the title of the objects referenced by the annotated properties.  We also need programmatic access to these titles if going the imperative route.
 


[20/52] [abbrv] isis git commit: ISIS-1243: renamed ug.adoc to ugfun.adoc. Added standard section to each of the guides so can navigate between each easily.

Posted by mg...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_per-user-themes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_per-user-themes.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_per-user-themes.adoc
new file mode 100644
index 0000000..0afe2ce
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_per-user-themes.adoc
@@ -0,0 +1,85 @@
+[[_ugfun_faqs_per-user-themes]]
+= Per-user Themes
+: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/
+
+From the Apache Isis mailing list is:
+
+* _Is it possible to have each of our resellers (using our Isis application) use there own theme/branding with their own logo and colors? Would this also be possible for the login page, possibly depending on the used host name?_
+
+
+Yes, you can do this, by installing a custom implementation of the Wicket Bootstrap's `ActiveThemeProvider`.
+
+The http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] (non-ASF) actually link:https://github.com/isisaddons/isis-app-todoapp/tree/61b8114a8e01dbb3c380b31cf09eaed456407570[does this], storing the info via the http://github.com/isisaddons/isis-module-settings[Isis addons' settings module] settings modules:
+
+[source,java]
+.IActiveThemeProvider implementation
+----
+public class UserSettingsThemeProvider implements ActiveThemeProvider {
+    ...
+    @Override
+    public ITheme getActiveTheme() {
+        if(IsisContext.getSpecificationLoader().isInitialized()) {
+            final String themeName = IsisContext.doInSession(new Callable<String>() {
+                @Override
+                public String call() throws Exception {
+                    final Class<UserSettingsService> serviceClass = UserSettingsService.class;
+                    final UserSettingsService userSettingsService = lookupService(serviceClass);
+                    final UserSetting activeTheme = userSettingsService.find(
+                            IsisContext.getAuthenticationSession().getUserName(), ACTIVE_THEME);
+                    return activeTheme != null ? activeTheme.valueAsString() : null;
+                }
+            });
+            return themeFor(themeName);
+        }
+        return new SessionThemeProvider().getActiveTheme();
+    }
+    @Override
+    public void setActiveTheme(final String themeName) {
+        IsisContext.doInSession(new Runnable() {
+            @Override
+            public void run() {
+                final String currentUsrName = IsisContext.getAuthenticationSession().getUserName();
+                final UserSettingsServiceRW userSettingsService =
+                        lookupService(UserSettingsServiceRW.class);
+                final UserSettingJdo activeTheme =
+                        (UserSettingJdo) userSettingsService.find(currentUsrName, ACTIVE_THEME);
+                if(activeTheme != null) {
+                    activeTheme.updateAsString(themeName);
+                } else {
+                    userSettingsService.newString(
+                        currentUsrName, ACTIVE_THEME, "Active Bootstrap theme for user", themeName);
+                }
+            }
+        });
+    }
+    private ITheme themeFor(final String themeName) {
+        final ThemeProvider themeProvider = settings.getThemeProvider();
+        if(themeName != null) {
+            for (final ITheme theme : themeProvider.available()) {
+                if (themeName.equals(theme.name()))
+                    return theme;
+            }
+        }
+        return themeProvider.defaultTheme();
+    }
+    ...
+}
+----
+
+and
+
+[source,java]
+.Using the ActiveThemeProvider
+----
+@Override
+protected void init() {
+    super.init();
+
+    final IBootstrapSettings settings = Bootstrap.getSettings();
+    settings.setThemeProvider(new BootswatchThemeProvider(BootswatchTheme.Flatly));
+
+    settings.setActiveThemeProvider(new UserSettingsThemeProvider(settings));
+}
+----

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_restful-image-property.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_restful-image-property.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_restful-image-property.adoc
new file mode 100644
index 0000000..a4bd8de
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_restful-image-property.adoc
@@ -0,0 +1,20 @@
+[[_ugfun_faqs_restful-image-property]]
+= How parse image properties from Restful Objects?
+: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/
+
+
+ref: link:http://markmail.org/message/4kcu7sml4ufdsah3[mailing list thread]
+
+The RO viewer returns the image as a string, in the form:
+
+    "Tacos.jpg:image/jpeg:/9j//4AAQSkZJRgABAQEAlgCWAAD/  ...."
+
+This is in the form:
+
+    (filename):(mime type):(binary data in base64)
+
+This is basically the xref:rgcms.adoc#_rgcms_classes_value-types_Blob[`Blob`] value type, in string form.
+
+To use, split the parts then format the mime type and base64 data correctly before using as source in an `<img>` tag.

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_subtype-entity-not-fully-populated.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_subtype-entity-not-fully-populated.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_subtype-entity-not-fully-populated.adoc
new file mode 100644
index 0000000..8ec1e85
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_subtype-entity-not-fully-populated.adoc
@@ -0,0 +1,67 @@
+[[_ugfun_troubleshooting_faqs]]
+= (Subtype) entity not fully populated
+: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/
+
+
+ref: link:http://markmail.org/message/ovgai56uqgfgnrx7[mailing list thread]
+
+If it seems that Apache Isis (or rather DataNucleus) isn't fully populating domain entities (ie leaving some properties
+as `null`), then check that your actions are not accessing the fields directly.  Use getters instead.  that is:
+
+[WARNING]
+====
+Properties of domain entities should always be accessed using getters.  The only code that should access to fields
+should be the getters themselves.
+====
+
+Why so? Because DataNucleus will potentially lazy load some properties, but to do this it needs to know that the
+field is being requested.  This is the purpose of the enhancement phase: the bytecode of the original getter method is
+actually wrapped in code that does the lazy loading checking.  But hitting the field directly means that the lazy
+loading code does not run.
+
+This error can be subtle: sometimes "incorrect" code that accesses the fields will seem to work.  But that will be
+because the field has been populated already, for whatever reason.
+
+One case where you will find the issue highlighted is for subtype tables that have been mapped using an inheritance
+strategy of `NEW_TABLE`, eg:
+
+[source,java]
+----
+@javax.jdo.annotations.PersistenceCapable
+@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.NEW_TABLE)
+public class SupertypeEntity {
+    ...
+}
+----
+
+and then:
+
+[source,java]
+----
+@javax.jdo.annotations.PersistenceCapable
+@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.NEW_TABLE)
+public class SubtypeEntity extends SupertypeEntity {
+    ...
+}
+----
+
+This will generate two tables in the database, with the primary key of the supertype table propagated as a foreign key
+(also primary key) of the subtype table (sometimes called "table per type" strategy).  This means that DataNucleus
+might retrieve data from only the supertype table, and the lazily load the subtype fields only as required.  This is
+preferable to doing a left outer join from the super- to the subtype tables to retrieve data that might not be needed.
+
+On the other hand, if the `SUPERCLASS_TABLE` strategy (aka "table per hierarchy" or roll-up) or the `SUBCLASS_TABLE`
+strategy (roll-down) was used, then the problem is less likely to occur because DataNucleus would obtain all the data
+for any given instance from a single table.
+
+Final note: references to other objects (either scalar references or in collections) in particular require that getters
+rather than fields to be used to obtain them: it's hopefully obvious that DataNucleus (like all ORMs) should not and
+will not resolve such references (otherwise, where to stop... and the whole database would be loaded into memory).
+
+In summary, there's just one rule: *always use the getters, never the fields*.
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started.adoc
new file mode 100644
index 0000000..2a4ad32
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started.adoc
@@ -0,0 +1,37 @@
+[[_ugfun_getting-started]]
+= 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/
+
+
+
+
+To get you up and running quickly, Apache Isis provides a xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] to setup a simple application as the basis of your own apps.  This is deliberately very minimal so that you won't have to spend lots of time removing generated artifacts.  On the other hand, it does set up a standard multi-module maven structure with unit- and integration tests pre-configured, as well as a webapp module so that you can easily run your app.  We strongly recommend that you preserve this structure as you develop your own Isis application.
+
+In this chapter we also discuss the xref:ug.adoc#_ugfun_getting-started_datanucleus-enhancer[DataNucleus enhancer].  link:http://www.datanucleus.org/[DataNucleus] is the reference implementation of the JDO (Java data objects) spec, and Apache Isis integrates with DataNucleus as its persistence layer.  The enhancer performs post-processing on the bytecode of your persistent domain entities, such that they can be persisted by Apache Isis' JDO/DataNucleus objectstore.
+
+[NOTE]
+====
+The xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] automatically configures the enhancer, so there's little you need to do at this stage.  Even so we feel it's a good idea to be aware of this critical part of Apache Isis runtime; if the enhancer does not run, then you'll find the app fails to start with (what will seem like) quite an obscure exception message.
+====
+
+
+
+
+== Prerequisites
+
+Apache Isis is a Java based framework, so in terms of prerequisites, you'll need to install:
+
+* Java 7 or 8 JDK
+* link:http://maven.apache.org[Apache Maven] 3.0.5 or later
+
+You'll probably also want to use an IDE; the Apache Isis committers use either IntelliJ or Eclipse; in the xref:cg.adoc#_cg_ide[Contributors' Guide] we have detailed setup instructions for using these two IDEs.  If you're a NetBeans user you should have no problems as it too has strong support for Maven.
+
+When building and running within an IDE, you'll also need to configure the Datanucleus enhancer.  This is implemented as a Maven plugin, so in the case of IntelliJ, it's easy enough to run the enhancer as required. It should be just as straightforward for NetBeans too.
+
+For Eclipse the maven integration story is a little less refined.  All is not lost, however; DataNucleus also has an implementation of the enhancer as an Eclipse plugin, which usually works well enough.
+
+include::_ugfun_getting-started_simpleapp-archetype.adoc[leveloffset=+1]
+include::_ugfun_getting-started_datanucleus-enhancer.adoc[leveloffset=+1]
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started_datanucleus-enhancer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started_datanucleus-enhancer.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started_datanucleus-enhancer.adoc
new file mode 100644
index 0000000..88dc068
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started_datanucleus-enhancer.adoc
@@ -0,0 +1,107 @@
+[[_ugfun_getting-started_datanucleus-enhancer]]
+= Datanucleus Enhancer
+: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/
+
+
+
+link:http://www.datanucleus.org/[DataNucleus] is the reference implementation of the JDO (Java data objects) spec, and Apache Isis integrates with DataNucleus as its persistence layer.  Datanucleus is a very powerful library, allowing domain entities to be mapped not only to relational database tables, but also to NoSQL stores such as link:http://neo4j.com/[Neo4J], link:http://www.mongodb.org/[MongoDB] and link:http://cassandra.apache.org/[Apache Cassandra].
+
+With such power comes a little bit of complexity to the development environment: all domain entities must be enhanced through the DataNucleus enhancer.
+
+[NOTE]
+====
+Bytecode enhancement is actually a requirement of the JDO spec; the process is described in outline http://db.apache.org/jdo/enhancement.html[here].
+====
+
+What this means is that the enhancer -- available as both a Maven plugin and as an Eclipse plugin -- must, one way or another, be integrated into your development environment.
+
+If working from the Maven command line, JDO enhancement is done using the `maven-datanucleus-plugin`.  As of 1.9.0, we put all the configuration into an (always active) profile:
+
+[TIP]
+====
+The configuration described below is automatically set up by the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
+====
+
+
+[source,xml]
+----
+<profile>
+    <id>enhance</id>
+    <activation>
+        <activeByDefault>true</activeByDefault>
+    </activation>
+    <properties>
+        <datanucleus-maven-plugin.version>4.0.1</datanucleus-maven-plugin.version>
+    </properties>
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.datanucleus</groupId>
+                <artifactId>datanucleus-maven-plugin</artifactId>
+                <version>${datanucleus-maven-plugin.version}</version>
+                <configuration>
+                    <fork>false</fork>
+                    <log4jConfiguration>${basedir}/log4j.properties</log4jConfiguration>
+                    <verbose>true</verbose>
+                    <props>${basedir}/datanucleus.properties</props>
+                </configuration>
+                <executions>
+                    <execution>
+                        <phase>process-classes</phase>
+                        <goals>
+                            <goal>enhance</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+    </build>
+    <dependencies>
+        <dependency>
+            <groupId>org.datanucleus</groupId>
+            <artifactId>datanucleus-core</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.datanucleus</groupId>
+            <artifactId>datanucleus-jodatime</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.datanucleus</groupId>
+            <artifactId>datanucleus-api-jdo</artifactId>
+        </dependency>
+    </dependencies>
+</profile>
+----
+
+The xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]  sets up the plugin correctly in the `dom` (domain object model) module.  (It's actually a little bit more complex to cater for users of the Eclipse IDE using Eclipse's m2e plugin).
+
+
+
+
+== `META-INF/persistence.xml`
+
+It's also a good idea to ensure that the `dom` module has a JDO `META-INF/persistence.xml` file:
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8" ?>
+<persistence xmlns="http://java.sun.com/xml/ns/persistence"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd" version="1.0">
+
+    <persistence-unit name="simple"> <!--1-->
+    </persistence-unit>
+</persistence>
+----
+<1> change as required; typically is the name of the app.
+
+Again, the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] does this.
+
+[WARNING]
+====
+If running on Windows, then there's a good chance you'll hit the http://msdn.microsoft.com/en-us/library/aa365247%28VS.85%29.aspx#maxpath[maximum path length limit].   In this case the `persistence.xml` file is mandatory rather than optional.
+
+This file is also required if you are using developing in Eclipse and relying on the DataNucleus plugin for Eclipse rather than the DataNucleus plugin for Maven.  More information can be found xref:cg.adoc#_cg_ide_eclipse[here].
+====

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started_simpleapp-archetype.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started_simpleapp-archetype.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started_simpleapp-archetype.adoc
new file mode 100644
index 0000000..6620162
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started_simpleapp-archetype.adoc
@@ -0,0 +1,304 @@
+[[_ugfun_getting-started_simpleapp-archetype]]
+= 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/
+
+
+The quickest way to get started with Apache Isis is to run the simple archetype.  This will generate a very simple one-class domain model, called `SimpleObject`, with a single property `name`.
+
+There is also a corresponding `SimpleObjectRepository` domain service.  From this you can easily rename these initial classes, and extend to build up your own Apache Isis domain application.
+
+
+
+== Generating the App
+
+Create a new directory, and `cd` into that directory.
+
+To build the app from the latest stable release, then run the following command:
+
+[source,bash]
+----
+mvn archetype:generate  \
+    -D archetypeGroupId=org.apache.isis.archetype \
+    -D archetypeArtifactId=simpleapp-archetype \
+    -D archetypeVersion=1.10.0 \
+    -D groupId=com.mycompany \
+    -D artifactId=myapp \
+    -D version=1.0-SNAPSHOT \
+    -B
+----
+
+where:
+
+- `groupId` represents your own organization, and
+- `artifactId` is a unique identifier for this app within your organization.
+- `version` is the initial (snapshot) version of your app
+
+The archetype generation process will then run; it only takes a few seconds.
+
+
+We also maintain the archetype for the most current `-SNAPSHOT`; an app generated with this archetype will contain the latest features of Apache Isis, but the usual caveats apply: some features still in development may be unstable.
+
+The process is almost identical to that for stable releases, however the `archetype:generate` goal is called with slightly different arguments:
+
+[source,bash]
+----
+mvn archetype:generate  \
+    -D archetypeGroupId=org.apache.isis.archetype \
+    -D archetypeArtifactId=simpleapp-archetype \
+    -D archetypeVersion=1.11.0-SNAPSHOT \
+    -D groupId=com.mycompany \
+    -D artifactId=myapp \
+    -D version=1.0-SNAPSHOT \
+    -D archetypeRepository=http://repository-estatio.forge.cloudbees.com/snapshot/ \
+    -B
+----
+
+where as before:
+
+- `groupId` represents your own organization, and
+- `artifactId` is a unique identifier for this app within your organization.
+- `version` is the initial (snapshot) version of your app
+
+but also:
+
+- `archetypeVersion` is the SNAPSHOT version of Apache Isis.
+- `archetypeRepository` specifies the location of our snapshot repo (hosted on link:http://www.cloudbees.com[CloudBees]), and
+
+The archetype generation process will then run; it only takes a few seconds.
+
+
+
+== Building the App
+
+Switch into the root directory of your newly generated app, and build your app:
+
+[source,bash]
+----
+cd myapp
+mvn clean install
+----
+
+where `myapp` is the `artifactId` entered above.
+
+
+
+
+== Running the App
+
+The `simpleapp` archetype generates a single WAR file, configured to run both the xref:ugvw.adoc#[Wicket viewer] and the xref:ugvro.adoc#[Restful Objects viewer].  The archetype also configures the DataNucleus/JDO Objectstore to use an in-memory HSQLDB connection.
+
+Once you've built the app, you can run the WAR in a variety of ways.
+
+
+=== Self-hosted
+
+The easiest way to run the app, at least while getting started, is to run the self-hosting version of the WAR.  With this style the app runs up its own internal instance of Jetty web server.
+
+For example:
+
+
+[source,bash]
+----
+java -jar webapp/target/myapp-webapp-1.0-SNAPSHOT-jetty-console.jar
+----
+
+
+This can also be accomplished using an embedded Ant target provided in the build script:
+
+[source,bash]
+----
+mvn -P self-host antrun:run
+----
+
+
+=== Using mvn Jetty plugin
+
+Alternatively, you could run the WAR in a Maven-hosted Jetty instance, though you need to `cd` into the `webapp` module:
+
+[source,bash]
+----
+cd webapp
+mvn jetty:run
+----
+
+If you use `mvn jetty:run`, then the context path changes; check the console output (eg link:http://localhost:8080/myapp-webapp [http://localhost:8080/myapp-webapp]).
+
+
+You can also provide a system property to change the port:
+
+[source,bash]
+----
+cd webapp
+mvn jetty:run -D jetty.port=9090
+----
+
+
+=== Using a regular servlet container
+
+You can also take the built WAR file and deploy it into a standalone servlet container such as [Tomcat](http://tomcat.apache.org).  The default configuration does not require any configuration of the servlet container; just drop the WAR file into the `webapps` directory.
+
+
+
+=== From within the IDE
+
+Most of the time, though, you'll probably want to run the app from within your IDE.  The mechanics of doing this will vary by IDE; see the xref:cg.adoc#_cg_ide[Contributors' Guide] for details of setting up Eclipse or IntelliJ IDEA.  Basically, though, it amounts to running `org.apache.isis.WebServer`, and ensuring that the xref:ug.adoc#_ugfun_getting-started_datanucleus-enhancer[DataNucleus enhancer] has properly processed all domain entities.
+
+Here's what the setup looks like in IntelliJ IDEA:
+
+image::{_imagesdir}getting-started/simpleapp-webapp.png[width="600px",link="{_imagesdir}getting-started/simpleapp-webapp.png"]
+
+
+
+== Running with Fixtures
+
+It is also possible to start the application with a pre-defined set of data; useful for demos or manual exploratory testing.  This is done by specifying a xref:ugtst.adoc#_ugtst_fixture-scripts[fixture script] on the command line.
+
+If running the self-hosted console, you can specify the fixtures using the `--initParam` flag:
+
+[source,bash]
+----
+java -jar webapp/target/myapp-webapp-1.0-SNAPSHOT-jetty-console.jar \
+     --initParam isis.persistor.datanucleus.install-fixtures=true  \
+     --initParam isis.fixtures=domainapp.fixture.scenarios.RecreateSimpleObjects
+----
+
+where (in the above example) `domainapp.fixture.scenarios.RecreateSimpleObjects` is the fully qualified class name of the fixture
+script to be run.
+
+If you are running the app from an IDE, then you can specify the fixture script using the `--fixture` flag:
+
+image::{_imagesdir}getting-started/simpleapp-webapp-with-fixtures.png[width="600px",link="{_imagesdir}getting-started/simpleapp-webapp-with-fixtures.png"]
+
+
+
+== Using the App
+
+When you start the app, you'll be presented with a welcome page from which you can access the webapp using either the xref:ugvw.adoc#[Wicket viewer] or the xref:ugvro.adoc#[Restful Objects viewer]:
+
+image::{_imagesdir}getting-started/using-simple-app/010-root-page.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/010-root-page.png"]
+
+
+The Wicket viewer provides a human usable web UI (implemented, as you might have guessed from its name, using link:http://wicket.apache.org[Apache Wicket]), so choose that and navigate to the login page:
+
+image::{_imagesdir}getting-started/using-simple-app/020-login-to-wicket-viewer.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/020-login-to-wicket-viewer.png"]
+
+The app itself is configured to run using xref:ugsec.adoc#[shiro security], as configured in the `WEB-INF/shiro.ini` config file.  You can login with:
+
+* username: _sven_
+* password: _pass_
+
+The application is configured to run with an in-memory database, and (unless you started the app with fixture scripts as described above), initially there is no data.  We can though run a fixture script from the app itself:
+
+image::{_imagesdir}getting-started/using-simple-app/030-home-page-run-fixture-scripts.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/030-home-page-run-fixture-scripts.png"]
+
+The fixture script creates three objects, and the action returns the first of these:
+
+image::{_imagesdir}getting-started/using-simple-app/040-first-object.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/040-first-object.png"]
+
+The application generated is deliberaetly very minimal; we don't want you to have to waste valuable time removing generated files.  The object contains a single "name" property, and a single action to update that property:
+
+image::{_imagesdir}getting-started/using-simple-app/050-update-name-prompt.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/050-update-name-prompt.png"]
+
+When you hit OK, the object is updated:
+
+image::{_imagesdir}getting-started/using-simple-app/060-object-updated.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/060-object-updated.png"]
+
+
+For your most signficant domain entities you'll likely have a domain service to retrieve or create instances of those obejcts.  In the generated app we have a "Simple Objects" domain service that lets us list all objects:
+
+image::{_imagesdir}getting-started/using-simple-app/070-list-all-prompt.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/070-list-all-prompt.png"]
+
+whereby we see the three objects created by the fixture script (one having been updated):
+
+image::{_imagesdir}getting-started/using-simple-app/080-list-all.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/080-list-all.png"]
+
+and we can also use the domain service to create new instances:
+
+image::{_imagesdir}getting-started/using-simple-app/090-create.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/090-create.png"]
+
+prompting us for the mandatory information (the name):
+
+image::{_imagesdir}getting-started/using-simple-app/100-create-prompt.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/100-create-prompt.png"]
+
+which, of course, returns the newly created object:
+
+image::{_imagesdir}getting-started/using-simple-app/110-object-created.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/110-object-created.png"]
+
+When we list all objects again, we can see that the object was indeed created:
+
+image::{_imagesdir}getting-started/using-simple-app/120-list-all.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/120-list-all.png"]
+
+Going back to the home page (link:http://localhost:8080[localhost:8080]) we can also access the Restful Objects viewer.  The generated application is configured to use HTTP Basic Auth:
+
+image::{_imagesdir}getting-started/using-simple-app/220-login-to-restful-viewer.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/220-login-to-restful-viewer.png"]
+
+The Restful Objects viewer provides a REST API for computer-to-computer interaction, but we can still interact with it from a browser:
+
+image::{_imagesdir}getting-started/using-simple-app/230-home-page.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/230-home-page.png"]
+
+[TIP]
+====
+Depending on your browser, you may need to install plugins.  For Chrome, we recommend json-view (which renders the JSON indented and automatically detects hyperlinks) and REST Postman.
+====
+
+The REST API is a complete hypermedia API, in other words you can follow the links to access all the behaviour exposed in the regular Wicket app.  For example, we can navigate to the `listAll/invoke` resource:
+
+image::{_imagesdir}getting-started/using-simple-app/240-list-all-invoke.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/240-list-all-invoke.png"]
+
+which when invoked (with an HTTP GET) will return a representation of the domain objects.
+
+image::{_imagesdir}getting-started/using-simple-app/250-list-all-results.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/250-list-all-results.png"]
+
+
+To log in, use `sven/pass`.
+
+
+
+
+
+== Modifying the App
+
+Once you are familiar with the generated app, you'll want to start modifying it.  There is plenty of guidance on this site; check out the 'programming model how-tos' section on the main link:../documentation.html[documentation] page first).
+
+If you use Eclipse or IntelliJ IDEA, do also install the xref:cg.adoc#_cg_ide-templates[IDE templates]; these will help you follow the Apache Isis naming conventions.
+
+
+
+
+
+== App Structure
+
+As noted above, the generated app is a very simple application consisting of a single domain object that can be easily renamed and extended. The intention is not to showcase all of Apache Isis' capabilities; rather it is to allow you to very easily modify the generated application (eg rename `SimpleObject` to `Customer`) without having to waste time deleting lots of generated code.
+
+
+
+[cols="1,3", options="header"]
+|===
+| Module
+| Description
+
+|`myapp`
+|The parent (aggregator) module
+
+|`myapp-app`
+|(1.9.0) The "app" module, containing the (optional) app manifest and any application-level services.
+
+|`myapp-dom`
+|The domain object model, consisting of `SimpleObject` and `SimpleObjects` (repository) domain service.
+
+|`myapp-fixture`
+|Domain object fixtures used for initializing the system when being demo'ed or for unit testing.
+
+|`myapp-integtests`
+|End-to-end xref:ugtst.adoc#_ugtst_integ-test-support[integration tests] that exercise from the UI through to the database
+
+|`myapp-webapp`
+|Run as a webapp (from `web.xml`) hosting the xref:ugvw.adoc#[Wicket viewer] and/or the xref:ugvro.adoc#[RestfulObjects viewer]
+
+|===
+
+
+
+If you run into issues, please don't hesitate to ask for help on the link:http://isis.apache.org/help.html[users mailing list].

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos.adoc
new file mode 100644
index 0000000..4c05fe6
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos.adoc
@@ -0,0 +1,22 @@
+[[_ugfun_how-tos]]
+= 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/
+
+
+This chapter provides a grab bag of "how-to"s and tips to help you go about actually developing Apache Isis domain applications.
+
+include::_ugfun_how-tos_class-structure.adoc[leveloffset=+1]
+include::_ugfun_how-tos_ui-hints.adoc[leveloffset=+1]
+include::_ugfun_how-tos_domain-services.adoc[leveloffset=+1]
+include::_ugfun_how-tos_crud.adoc[leveloffset=+1]
+include::_ugfun_how-tos_entity-relationships.adoc[leveloffset=+1]
+include::_ugfun_how-tos_contributed-members.adoc[leveloffset=+1]
+include::_ugfun_how-tos_business-rules.adoc[leveloffset=+1]
+include::_ugfun_how-tos_derived-members.adoc[leveloffset=+1]
+include::_ugfun_how-tos_drop-downs-and-defaults.adoc[leveloffset=+1]
+include::_ugfun_how-tos_bulk-actions.adoc[leveloffset=+1]
+include::_ugfun_how-tos_simulating-collections-of-values.adoc[leveloffset=+1]
+include::_ugfun_how-tos_render-all-properties-in-tables.adoc[leveloffset=+1]
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_bulk-actions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_bulk-actions.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_bulk-actions.adoc
new file mode 100644
index 0000000..fba2501
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_bulk-actions.adoc
@@ -0,0 +1,8 @@
+[[_ugfun_how-tos_bulk-actions]]
+= Bulk Actions
+: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/
+
+NOTE: TODO - xref:rgant.adoc#_rgant-Action_invokeOn[`@Action#invokeOn()`]
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_business-rules.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_business-rules.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_business-rules.adoc
new file mode 100644
index 0000000..cf4411e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_business-rules.adoc
@@ -0,0 +1,72 @@
+[[_ugfun_how-tos_business-rules]]
+= 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/
+
+NOTE: TODO
+
+
+
+== Visibility ("see it")
+
+NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_hide[`hide...()`]
+
+### Hide a Property
+
+### Hide a Collection
+
+### Hide an Action
+
+### Hide a Contributed Property, Collection or Action
+
+### All Members Hidden
+
+
+
+
+== Usability ("use it")
+
+NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_disable[`disable...()`]
+
+### 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")
+
+NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_validate[`validate...()`], xref:rgcms.adoc#_rgcms_methods_prefixes_validateAddTo[`validateAddTo...()`], xref:rgcms.adoc#_rgcms_methods_prefixes_validateRemoveFrom[`validateRemoveFrom...()`] and xref:rgcms.adoc#_rgcms_methods_reserved_validate[`validate()`]
+
+
+### 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
+
+NOTE: TODO - using xref:rgant.adoc#_rgant-Parameter_mustSatisfy[`@Parameter#mustSatisfy()`], xref:rgant.adoc#_rgant-Property_mustSatisfy[`@Property#mustSatisfy()`]
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure.adoc
new file mode 100644
index 0000000..4907108
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure.adoc
@@ -0,0 +1,38 @@
+[[_ugfun_how-tos_class-structure]]
+= 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/
+
+
+Apache Isis works by building a metamodel of the domain objects: entities, xref:ugbtb.adoc#_ugbtb_more-advanced_view-models[view model]s and services.  The class members of both entities and view models represent both state -- (single-valued) properties and (multi-valued) collections -- and behaviour -- actions.  The class members of domain services is simpler: just behaviour, ie actions.
+
+In the automatically generated UI a property is rendered as a field.  This can be either of a value type (a string, number, date, boolean etc) or can be a reference to another entity.  A collection is generally rendered as a table.
+
+In order for Apache Isis to build its metamodel the domain objects must follow some conventions: what we call the _Apache Isis Programming Model_.  This is just an extension of the pojo / JavaBean standard of yesteryear: properties and collections are getters/setters, while actions are simply any remaining `public` methods.
+
+Additional metamodel semantics are inferred both imperatively from _supporting methods_ and declaratively from annotations.
+
+In this section we discuss the mechanics of writing domain objects that comply with Apache Isis' programming model.
+
+[TIP]
+====
+In fact, the Apache Isis programming model is extensible; you can teach Apache Isis new programming conventions and you can remove existing ones; ultimately they amount to syntax.   The only real fundamental that can't be changed is the notion that objects consist of properties, collections and actions.
+
+You can learn more about extending Apache Isis programming model xref:ugbtb.adoc#_ugbtb_programming-model[here].
+====
+
+
+include::_ugfun_how-tos_class-structure_class-definition.adoc[leveloffset=+1]
+include::_ugfun_how-tos_class-structure_properties.adoc[leveloffset=+1]
+include::_ugfun_how-tos_class-structure_collections.adoc[leveloffset=+1]
+include::_ugfun_how-tos_class-structure_actions.adoc[leveloffset=+1]
+include::_ugfun_how-tos_class-structure_action-parameters.adoc[leveloffset=+1]
+include::_ugfun_how-tos_class-structure_inject-services.adoc[leveloffset=+1]
+
+include::_ugfun_how-tos_class-structure_properties-vs-parameters.adoc[leveloffset=+1]
+
+include::_ugfun_how-tos_class-structure_ignoring-methods.adoc[leveloffset=+1]
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_action-parameters.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_action-parameters.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_action-parameters.adoc
new file mode 100644
index 0000000..3d87032
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_action-parameters.adoc
@@ -0,0 +1,26 @@
+[[_ugfun_how-tos_class-structure_action-parameters]]
+= Action Parameters
+: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/
+
+
+NOTE: TODO
+
+
+
+== ``String``s (Length)
+
+NOTE: TODO
+
+
+== ``BigDecimal``s (Precision)
+
+NOTE: TODO
+
+
+== Optional
+
+NOTE: TODO
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_actions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_actions.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_actions.adoc
new file mode 100644
index 0000000..8f82ffa
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_actions.adoc
@@ -0,0 +1,19 @@
+[[_ugfun_how-tos_class-structure_actions]]
+= Actions
+: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/
+
+
+
+NOTE: TODO
+
+
+[NOTE]
+====
+While Apache 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 xref:ug.adoc#_ugfun_how-tos_class-structure_ignoring-methods[Ignoring Methods].  This ensures that the collection is ignored by Apache Isis.
+====
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_class-definition.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_class-definition.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_class-definition.adoc
new file mode 100644
index 0000000..94ed01c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_class-definition.adoc
@@ -0,0 +1,24 @@
+[[_ugfun_how-tos_class-structure_class-definition]]
+= Class Definition
+: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/
+
+
+
+NOTE: TODO
+
+
+Classes are defined both to Isis and (if an 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.
+
+[TIP]
+====
+For more on this topic, see the topic discussing modules and xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling[decoupling].
+====
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_collections.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_collections.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_collections.adoc
new file mode 100644
index 0000000..01afcd9
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_collections.adoc
@@ -0,0 +1,26 @@
+[[_ugfun_how-tos_class-structure_collections]]
+= Collections
+: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/
+
+
+NOTE: TODO
+
+
+[NOTE]
+====
+While Apache 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, Apache Isis has no default visualization.
+
+One workaround is to mark the collection as xref:rgant.adoc#_rgant-Programmatic[`@Programmatic`].  This ensures that the collection is ignored by Apache Isis.
+
+Another workaround is to wrap each value in a view model, as explained in this xref:ug.adoc#_ugfun_how-tos_simulating-collections-of-values[tip].
+====
+
+
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_ignoring-methods.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_ignoring-methods.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_ignoring-methods.adoc
new file mode 100644
index 0000000..cbaf310
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_ignoring-methods.adoc
@@ -0,0 +1,16 @@
+[[_ugfun_how-tos_class-structure_ignoring-methods]]
+= Ignoring Methods
+: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/
+
+
+
+NOTE: TODO
+
+
+Sometimes you want to define a `public` method on a domain object that is not intended to be rendered in Apache Isis' UI.
+
+To exclude such methods, use the xref:rgant.adoc#_rgant-Programmatic[`@Programmatic`] annotation.
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_inject-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_inject-services.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_inject-services.adoc
new file mode 100644
index 0000000..2f4a98d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_inject-services.adoc
@@ -0,0 +1,83 @@
+[[_ugfun_how-tos_class-structure_inject-services]]
+= Injecting 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/
+
+
+Apache Isis autowires (automatically injects) domain services into each entity, as well as into the domain services themselves, using either method injection or field injection. The applib `DomainObjectContainer` is also a service, so can be injected in exactly the same manner.
+
+
+[NOTE]
+====
+Isis currently does _not_ support qualified injection of services; the domain service of each type must be distinct from any other.
+
+If you find a requirement to inject two instances of type `SomeService`, say, then the work-around is to create trivial subclasses `SomeServiceA` and `SomeServiceB` and inject these instead.
+====
+
+
+== Field Injection
+
+Field injection is recommended, using the `@javax.inject.Inject` annotation. For example:
+
+[source,java]
+----
+public class Customer {
+    @javax.inject.Inject
+    OrderRepository orderRepository;
+    ...
+}
+----
+
+
+We recommend using default rather than `private` visibility so that the field can be mocked out within unit tests (placed in the same package as the code under test).
+
+
+
+
+== Method Injection
+
+Isis also supports two forms of method injection.  All that is required to inject a service into a entity/service is to provide an appropriate method or field. The name
+of the method does not matter, only that it is prefixed either `set` or `inject`, is
+public, and has a single parameter of the correct type.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+    private OrderRepository orderRepository;
+    public void setOrderRepository(OrderRepository orderRepository) {
+        this.orderRepository = orderRepository;
+    }
+    ...
+}
+----
+
+or alternatively, using 'inject' as the prefix:
+
+[source,java]
+----
+public class Customer {
+    private OrderRepository orderRepository;
+    public void injectOrderRepository(OrderRepository orderRepository) {
+        this.orderRepository = orderRepository;
+    }
+    ...
+}
+----
+
+Note that the method name can be anything; it doesn't need to be related to the type being injected.
+
+
+
+
+== Constructor injection
+
+Simply to note that constructor injection is _not_ supported by Apache Isis (and is unlikely to be, because the JDO specification for entities requires a no-arg constructor).
+
+
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_properties-vs-parameters.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_properties-vs-parameters.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_properties-vs-parameters.adoc
new file mode 100644
index 0000000..5cbd40f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_properties-vs-parameters.adoc
@@ -0,0 +1,45 @@
+[[_ugfun_how-tos_class-structure_properties-vs-parameters]]
+= Properties vs Parameters
+: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/
+
+
+
+NOTE: TODO
+
+
+In many cases the value types of properties and of action parameters align. For example, a `Customer` entity might have a `surname` property, and there might also be corresponding `changeSurname`.  Ideally we want the surname property and surname action parameter to use the same value type.
+
+Having first-class support for this is a goal of Apache Isis, and it is already possible (by writing some plumbing and glue code using Isis and DataNucleus APIs) to get some way towards this ideal.  However, in the vast majority of cases it is much easier and more practical to simply use standard value types such as `java.lang.String`.
+
+However, the JDO/DataNucleus annotations for specifying semantics such as optionality or maximum length are restricted to only apply to fields and to methods; they cannot be applied to action parameters.  It is therefore necessary to use Apache Isis' equivalent annotations for action parameters.
+
+The table below summarises the equivalence of some of the most common cases.
+
+
+.Comparing annotations of Properties vs Action Parameters
+[cols="2,3,3", options="header"]
+|===
+|value type/semantic
+|property
+|action parameter
+
+|string (length)
+|
+|
+
+|big decimal (precision)
+|
+|
+
+|Isis blob
+|
+|
+
+|optional
+|`@Column(allowsNull="true")`
+|`ParameterLayout(optionality=Optionality.OPTIONAL`) or `@Optional`
+|===
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_properties.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_properties.adoc
new file mode 100644
index 0000000..6bc76fa
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_properties.adoc
@@ -0,0 +1,299 @@
+[[_ugfun_how-tos_class-structure_properties]]
+= Property
+: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/
+
+
+NOTE: TODO
+
+
+
+
+
+== Value vs Reference Types
+
+NOTE: TODO
+
+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 the xref:ug.adoc#_ugfun_how-tos_class-structure_properties-vs-parameters[Properties vs Parameters] section provides a handy reference of each.
+
+
+
+== Optional Properties
+
+JDO/DataNucleus' default is that a property is assumed to be mandatory if it is a primitive type (eg `int`, `boolean`), but optional if a reference type (eg `String`, `BigDecimal` etc).  To override optionality in JDO/DataNucleus the `@Column(allowsNull="...")` annotations is used.
+
+Apache Isis on the other hand assumes that all properties (and action parameters, for that matter) are mandatory, not optional.  These defaults can also be overridden using Apache Isis' own annotations, specifically `@Property(optionality=...)`.
+
+These different defaults can lead to incompatibilities between the two frameworks.  To counteract that, Apache Isis also recognizes and honours JDO's `@Column(allowsNull=...)`.
+
+For example, rather than:
+
+[source,java]
+----
+@javax.jdo.annotations.Column(allowNulls="true")
+private LocalDate date;
+@Property(optionality=Optionality.OPTIONAL)
+public LocalDate getDate() { ... }
+public void setDate(LocalDate d) { ... }
+----
+
+you should instead simply write:
+
+[source,java]
+----
+private LocalDate date;
+@javax.jdo.annotations.Column(allowNulls="true")
+public LocalDate getDate() { ... }
+public void setDate(LocalDate d) { ... }
+----
+
+[WARNING]
+====
+With JDO/DataNucleus it's valid for the `@Column` annotation to be placed on either the field or the getter.  Apache Isis (currently) only looks for annotations on the getter.  We therefore recommend that you always place `@Column` on the gettter.
+====
+
+In all cases the framework will search for any incompatibilities in optionality (whether specified explicitly or defaulted implicitly) between Isis' defaults and DataNucleus, and refuse to boot if any are found (fail fast).
+
+
+
+=== Handling Mandatory Properties in Subtypes
+
+If you have a hierarchy of classes then you need to decide which inheritance strategy to use.
+
+* "table per hierarchy", or "rollup" (`InheritanceStrategy.SUPERCLASS_TABLE`) +
++
+whereby a single table corresponds to the superclass, and also holds the properties of the subtype (or subtypes) being rolled up
+
+* "table per class" (`InheritanceStrategy.NEW_TABLE`) +
++
+whereby is a table for both superclass and subclass, in 1:1 correspondence
+
+* "rolldown" (`InheritanceStrategy.SUBCLASS_TABLE`) +
++
+whereby a single table holds the properties of the subtype, and also holds the properties of its supertype
+
+In the first "rollup" case, we can have a situation where - logically speaking - the property is mandatory in the subtype - but it must be mapped as nullable in the database because it is n/a for any other subtypes that are rolled up.
+
+In this situation we must tell JDO that the column is optional, but to Apache Isis we want to enforce it being mandatory. This can be done using the `@Property(optionality=Optionality.MANDATORY)` annotation.
+
+For example:
+
+[source,java]
+----
+@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.SUPER_TABLE)
+public class SomeSubtype extends SomeSuperType {
+    private LocalDate date;
+    @javax.jdo.annotations.Column(allowNulls="true")
+    @Property(optionality=Optionality.MANDATORY)
+    public LocalDate getDate() { ... }
+    public void setDate(LocalDate d) { ... }
+}
+----
+
+[TIP]
+====
+The `@Property(optionality=...)` annotation is equivalent to the older but still supported `@Optional` annotation and `@Mandatory` annotations. Its benefit is that it lumps together all Apache Isis' property metadata in a single annotation.  Its downside is that it is rather verbose if the only semantic that needs to be specified -- as is often the case -- is optionality.
+====
+
+An alternative way to achieve this is to leave the JDO annotation on the field (where it is invisible to Apache Isis), and rely on Isis' default, eg:
+
+[source,java]
+----
+@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.SUPER_TABLE)
+public class SomeSubtype extends SomeSuperType {
+    @javax.jdo.annotations.Column(allowNulls="true")
+    private LocalDate date;
+    // mandatory in Apache Isis by default
+    public LocalDate getDate() { }
+    public void setDate(LocalDate d) { }
+}
+----
+
+We recommend the former mapping, though, using `@Property(optionality=Optionality.MANDATORY)`.
+
+
+
+
+
+== ``String``s (Length)
+
+NOTE: TODO
+
+
+
+
+
+[[_ugfun_how-tos_class-structure_properties_mapping-joda-dates]]
+== Mapping JODA Dates
+
+Isis' JDO objectstore bundles DataNucleus' http://www.datanucleus.org/documentation/products/plugins.html[built-in support] for Joda `LocalDate` and `LocalDateTime` datatypes, meaning that entity properties of these types will be persisted as appropriate data types in the database tables.
+
+It is, however, necessary to annotate your properties with `@javax.jdo.annotations.Persistent`, otherwise the data won't actually be persisted. See the http://db.apache.org/jdo/field_types.html[JDO docs] for more details on this.
+
+Moreover, these datatypes are _not_ in the default fetch group, meaning that JDO/DataNucleus will perform an additional `SELECT` query for each attribute. To avoid this extra query, the annotation should indicate that the property is in the default fetch group.
+
+For example, the `ToDoItem` (in the https://github.com/isisaddons/isis-app-todoapp[todoapp example app] (not ASF)) defines the `dueBy` property as follows:
+
+
+
+== ``BigDecimal``s (Precision)
+
+Working with `java.math.BigDecimal` properties takes a little care due to scale/precision issues.
+
+For example, suppose we have:
+
+[source,java]
+----
+private BigDecimal impact;
+public BigDecimal getImpact() {
+    return impact;
+}
+public void setImpact(final BigDecimal impact) {
+    this.impact = impact;
+}
+----
+
+JDO/DataNucleus creates, at least with HSQL, the table with the field type as NUMERIC(19). No decimal digits are admitted. (Further details http://hsqldb.org/doc/2.0/guide/sqlgeneral-chapt.html#sgc_numeric_types[here]).
+
+What this implies is that, when a record is inserted, a log entry similar to this one appears:
+
+[source,java]
+----
+INSERT INTO ENTITY(..., IMPACT, ....) VALUES (...., 0.5, ....)
+----
+
+But when that same record is retrieved, the log will show that a value of "0" is returned, instead of 0.5.
+
+The solution is to explicitly add the scale to the field like this:
+
+[source,java]
+----
+@javax.jdo.annotations.Column(scale=2)
+private BigDecimal impact;
+public BigDecimal getImpact() {
+    return impact;
+}
+public void setImpact(final BigDecimal impact) {
+    this.impact = impact;
+}
+----
+
+In addition, you should also set the scale of the `BigDecimal`, using `setScale(scale, roundingMode)`.
+
+More information can be found http://www.opentaps.org/docs/index.php/How_to_Use_Java_BigDecimal:_A_Tutorial[here] and http://www.tutorialspoint.com/java/math/bigdecimal_setscale_rm_roundingmode.htm[here].
+
+
+
+
+== Mapping Blobs and Clobs
+
+Apache Isis configures JDO/DataNucleus so that the properties of type `org.apache.isis.applib.value.Blob` and `org.apache.isis.applib.value.Clob` can also be persisted.
+
+As for xref:ug.adoc#_ugfun_how-tos_class-structure_properties_mapping-joda-dates[Joda dates], this requires the `@javax.jdo.annotations.Persistent` annotation. However, whereas for dates one would always expect this value to be retrieved eagerly, for blobs and clobs it is not so clear cut.
+
+=== Mapping Blobs
+
+For example, in the `ToDoItem` class (of the https://github.com/isisaddons/isis-app-todoapp/blob/61b8114a8e01dbb3c380b31cf09eaed456407570/dom/src/main/java/todoapp/dom/module/todoitem/ToDoItem.java#L475[todoapp example app] (non-ASF) the `attachment` property is as follows:
+
+[source,java]
+----
+@javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = {
+    @javax.jdo.annotations.Column(name = "attachment_name"),
+    @javax.jdo.annotations.Column(name = "attachment_mimetype"),
+    @javax.jdo.annotations.Column(name = "attachment_bytes", jdbcType="BLOB", sqlType = "LONGVARBINARY")
+})
+private Blob attachment;
+@Property(
+        optionality = Optionality.OPTIONAL
+)
+public Blob getAttachment() {
+    return attachment;
+}
+public void setAttachment(final Blob attachment) {
+    this.attachment = attachment;
+}
+----
+
+The three `@javax.jdo.annotations.Column` annotations are required because the mapping classes that Apache Isis provides (https://github.com/apache/isis/blob/isis-1.4.0/component/objectstore/jdo/jdo-datanucleus/src/main/java/org/apache/isis/objectstore/jdo/datanucleus/valuetypes/IsisBlobMapping.java#L59[IsisBlobMapping] and https://github.com/apache/isis/blob/isis-1.4.0/component/objectstore/jdo/jdo-datanucleus/src/main/java/org/apache/isis/objectstore/jdo/datanucleus/valuetypes/IsisClobMapping.java#L59[IsisClobMapping]) map to 3 columns. (It is not an error to omit these `@Column` annotations, but without them the names of the table columns are simply suffixed `_0`, `_1`, `_2` etc.
+
+If the `Blob` is mandatory, then use:
+
+[source,java]
+----
+@javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = {
+    @javax.jdo.annotations.Column(name = "attachment_name", allowsNull="false"),
+    @javax.jdo.annotations.Column(name = "attachment_mimetype", allowsNull="false"),
+    @javax.jdo.annotations.Column(name = "attachment_bytes",
+                                  jdbcType="BLOB", sqlType = "LONGVARBINARY",
+                                  allowsNull="false")
+})
+private Blob attachment;
+@Property(
+    optionality = Optionality.MANDATORY
+)
+public Blob getAttachment() {
+return attachment;
+}
+public void setAttachment(final Blob attachment) {
+this.attachment = attachment;
+}
+----
+
+[NOTE]
+====
+If specifying a `sqlType` of "LONGVARBINARY" does not work, try instead "BLOB".  There can be differences in behaviour between JDBC drivers.
+====
+
+
+=== Mapping Clobs
+
+Mapping `Clob`s works in a very similar way, but the `jdbcType` and `sqlType` attributes will, respectively, be `CLOB` and `LONGVARCHAR`:
+
+[source,java]
+----
+@javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = {
+    @javax.jdo.annotations.Column(name = "attachment_name"),
+    @javax.jdo.annotations.Column(name = "attachment_mimetype"),
+    @javax.jdo.annotations.Column(name = "attachment_chars",
+                                  jdbcType="CLOB", sqlType = "LONGVARCHAR")
+})
+private Clob doc;
+@Property(
+    optionality = Optionality.OPTIONAL
+)
+public Clob getDoc() {
+    return doc;
+}
+public void setDoc(final Clob doc) {
+    this.doc = doc;
+}
+----
+
+[NOTE]
+====
+If specifying a `sqlType` of "LONGVARCHAR" does not work, try instead "CLOB".  There can be differences in behaviour between JDBC drivers.
+====
+
+=== Mapping to VARBINARY or VARCHAR
+
+Instead of mapping to a sqlType of `LONGVARBINARY` (or perhaps `BLOB`), you might instead decide to map to a `VARBINARY`.  The difference is whether the binary data is held "on-row" or as a pointer "off-row"; with a `VARBINARY` the data is held on-row and so you will need to specify a length.
+
+For example:
+
+
+[source,java]
+----
+@javax.jdo.annotations.Column(name = "attachment_bytes", jdbcTypr="BLOB", sqlType = "VARBINARY", length=2048)
+----
+
+
+The same argument applies to `LONGVARCHAR` (or `CLOB`); you could instead map to a regular `VARCHAR`:
+
+
+[source,java]
+----
+@javax.jdo.annotations.Column(name = "attachment_chars", sqlType = "VARCHAR", length=2048)
+----
+
+Support and maximum allowed length will vary by database vendor.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_contributed-members.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_contributed-members.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_contributed-members.adoc
new file mode 100644
index 0000000..3b48ccf
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_contributed-members.adoc
@@ -0,0 +1,69 @@
+[[_ugfun_how-tos_contributed-members]]
+= 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/
+
+
+
+NOTE: TODO - generalize to discussion on contributed collections/properties; update to new annotations
+
+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,java]
+----
+public interface Library {
+    public Loan borrow(Loanable l, Borrower b);
+}
+----
+
+and the entities:
+
+[source,java]
+----
+public class Book implements Loanable { ... }
+----
+
+and
+
+[source,java]
+----
+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,java]
+----
+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`.
+
+
+## Contributed Action
+
+NOTE: TODO
+
+## Contributed Property
+
+NOTE: TODO
+
+## Contributed Collection
+
+NOTE: TODO
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_crud.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_crud.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_crud.adoc
new file mode 100644
index 0000000..98a2f83
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_crud.adoc
@@ -0,0 +1,29 @@
+[[_ugfun_how-tos_crud]]
+= 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/
+
+NOTE: TODO
+
+
+## Instantiating and Persisting Objects
+
+NOTE: TODO - using ``DomainObjectContainer``'s support for  xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-creation-api[creation] and xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-persistence-api[persistence]
+
+## Finding Objects
+
+NOTE: TODO - using xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_generic-repository-api[`DomainObjectContainer`]
+
+### Using DataNucleus type-safe queries
+
+NOTE: TODO - as described xref:rgsvc.adoc#_rgsvc-api_IsisJdoSupport_type-safe-jdoql-queries[here]
+
+
+
+## Deleting Objects
+
+NOTE: TODO using ``DomainObjectContainer``'s support for  xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-persistence-api[persistence]
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_derived-members.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_derived-members.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_derived-members.adoc
new file mode 100644
index 0000000..9a472f8
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_derived-members.adoc
@@ -0,0 +1,48 @@
+[[_ugfun_how-tos_derived-members]]
+= 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/
+
+NOTE: TODO
+
+
+
+
+== Derived Property
+
+NOTE: TODO
+
+
+
+
+== Derived Collection
+
+NOTE: TODO
+
+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
+
+NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_modify[`modify...()`], xref:rgcms.adoc#_rgcms_methods_prefixes_clear[`clear...()`]
+
+
+
+== Trigger on collection change
+
+NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_addTo[`addTo...()`], xref:rgcms.adoc#_rgcms_methods_prefixes_removeFrom[`removeFrom...()`]


[26/52] [abbrv] isis git commit: ISIS-1243: renamed ug.adoc to ugfun.adoc. Added standard section to each of the guides so can navigate between each easily.

Posted by mg...@apache.org.
ISIS-1243: renamed ug.adoc to ugfun.adoc.  Added standard section to each of the guides so can navigate between each easily.


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/1ad82470
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/1ad82470
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/1ad82470

Branch: refs/heads/ISIS-1224-select2-v4
Commit: 1ad824700c01b17b78753f5659b3598a67571636
Parents: 43fc7bc
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Thu Dec 3 18:01:31 2015 +0000
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Dec 3 18:01:31 2015 +0000

----------------------------------------------------------------------
 README.adoc                                     |   8 +-
 ...o-1.9.0_bootstrapping-using-AppManifest.adoc |   2 +-
 ...n-notes_1.8.0-to-1.9.0_upgrading-to-dn4.adoc |   2 +-
 ...tion-notes_1.8.0-to-1.9.0_war-packaging.adoc |   4 +-
 .../src/main/asciidoc/common-use-cases.adoc     |   4 +-
 .../src/main/asciidoc/documentation.adoc        |   2 +-
 .../asciidoc/guides/_cg_asciidoc-templates.adoc |  20 +-
 .../main/asciidoc/guides/_cg_ide_eclipse.adoc   |   2 +-
 .../asciidoc/guides/_cg_isis-maven-plugin.adoc  |   2 +-
 .../guides/_cg_isis-maven-plugin_validate.adoc  |   2 +-
 .../asciidoc/guides/_rgant-ActionLayout.adoc    |   2 +-
 .../guides/_rgant-ActionLayout_bookmarking.adoc |   2 +-
 .../_rgant-ActionLayout_contributedAs.adoc      |   2 +-
 .../guides/_rgant-ActionLayout_cssClass.adoc    |   2 +-
 .../guides/_rgant-ActionLayout_cssClassFa.adoc  |   2 +-
 .../guides/_rgant-ActionLayout_describedAs.adoc |   2 +-
 .../guides/_rgant-ActionLayout_hidden.adoc      |   2 +-
 .../guides/_rgant-ActionLayout_named.adoc       |   2 +-
 .../guides/_rgant-ActionLayout_position.adoc    |   2 +-
 .../asciidoc/guides/_rgant-Action_hidden.adoc   |   2 +-
 .../guides/_rgant-CollectionLayout.adoc         |   2 +-
 .../_rgant-CollectionLayout_cssClass.adoc       |   2 +-
 .../_rgant-CollectionLayout_defaultView.adoc    |   2 +-
 .../_rgant-CollectionLayout_describedAs.adoc    |   2 +-
 .../guides/_rgant-CollectionLayout_hidden.adoc  |   2 +-
 .../guides/_rgant-CollectionLayout_named.adoc   |   2 +-
 .../guides/_rgant-CollectionLayout_paged.adoc   |   2 +-
 .../guides/_rgant-CollectionLayout_render.adoc  |   4 +-
 .../_rgant-CollectionLayout_sortedBy.adoc       |   2 +-
 .../guides/_rgant-Collection_hidden.adoc        |   2 +-
 .../guides/_rgant-DomainObjectLayout.adoc       |   2 +-
 .../guides/_rgant-DomainServiceLayout.adoc      |   4 +-
 .../main/asciidoc/guides/_rgant-HomePage.adoc   |   2 +-
 .../src/main/asciidoc/guides/_rgant-Inject.adoc |   2 +-
 .../guides/_rgant-MemberGroupLayout.adoc        |   2 +-
 .../asciidoc/guides/_rgant-MemberOrder.adoc     |   2 +-
 .../asciidoc/guides/_rgant-ParameterLayout.adoc |   2 +-
 .../asciidoc/guides/_rgant-PostConstruct.adoc   |   2 +-
 .../asciidoc/guides/_rgant-PropertyLayout.adoc  |   2 +-
 .../guides/_rgant-PropertyLayout_cssClass.adoc  |   2 +-
 .../_rgant-PropertyLayout_describedAs.adoc      |   2 +-
 .../guides/_rgant-PropertyLayout_hidden.adoc    |   4 +-
 .../_rgant-PropertyLayout_labelPosition.adoc    |   2 +-
 .../guides/_rgant-PropertyLayout_multiLine.adoc |   2 +-
 .../guides/_rgant-PropertyLayout_named.adoc     |   2 +-
 ...gant-PropertyLayout_renderedAsDayBefore.adoc |   2 +-
 .../asciidoc/guides/_rgant-ViewModelLayout.adoc |   2 +-
 .../asciidoc/guides/_rgant-XmlRootElement.adoc  |   2 +-
 .../asciidoc/guides/_rgant_aaa_deprecated.adoc  |   2 +-
 .../main/asciidoc/guides/_rgant_aaa_jee.adoc    |   2 +-
 .../main/asciidoc/guides/_rgant_aaa_main.adoc   |   4 +-
 .../main/asciidoc/guides/_rgant_aaa_other.adoc  |   2 +-
 .../guides/_rgcfg_configuring-core.adoc         |   6 +-
 ...s_disabling-persistence-by-reachability.adoc |   2 +-
 .../guides/_rgcfg_specifying-components.adoc    |   2 +-
 .../main/asciidoc/guides/_rgcms_classes.adoc    |   2 +-
 ...rgcms_classes_AppManifest-bootstrapping.adoc |   2 +-
 .../guides/_rgcms_methods_prefixes_choices.adoc |   2 +-
 .../guides/_rgcms_methods_prefixes_default.adoc |   2 +-
 .../asciidoc/guides/_rgcms_schema-common.adoc   |   2 +-
 .../_rgsvc-api_ActionInvocationContext.adoc     |   2 +-
 .../guides/_rgsvc-api_BackgroundService.adoc    |   2 +-
 .../guides/_rgsvc-api_BookmarkService.adoc      |   2 +-
 .../guides/_rgsvc-api_CommandContext.adoc       |   2 +-
 .../guides/_rgsvc-api_DeepLinkService.adoc      |   2 +-
 .../guides/_rgsvc-api_EmailService.adoc         |   2 +-
 .../guides/_rgsvc-api_EventBusService.adoc      |   2 +-
 .../guides/_rgsvc-api_GuiceBeanProvider.adoc    |   2 +-
 .../guides/_rgsvc-api_IsisJdoSupport.adoc       |   2 +-
 .../asciidoc/guides/_rgsvc-api_JaxbService.adoc |   2 +-
 .../guides/_rgsvc-api_MementoService.adoc       |   2 +-
 .../guides/_rgsvc-api_MetamodelService.adoc     |   2 +-
 .../guides/_rgsvc-api_QueryResultsCache.adoc    |   2 +-
 .../asciidoc/guides/_rgsvc-api_Scratchpad.adoc  |   2 +-
 .../asciidoc/guides/_rgsvc-api_SudoService.adoc |   2 +-
 .../guides/_rgsvc-api_WrapperFactory.adoc       |   2 +-
 .../guides/_rgsvc-api_XmlSnapshotService.adoc   |   2 +-
 .../_rgsvc-spi_ClassDiscoveryService.adoc       |   4 +-
 .../_rgsvc-spi_ContentNegotiationService.adoc   |   2 +-
 .../_rgsvc-spi_EmailNotificationService.adoc    |   2 +-
 ...spi_FixtureScriptsSpecificationProvider.adoc |   2 +-
 .../guides/_rgsvc-spi_LocaleProvider.adoc       |   2 +-
 .../_rgsvc-spi_RepresentationService.adoc       |   2 +-
 .../guides/_rgsvc-spi_TranslationService.adoc   |   2 +-
 .../guides/_rgsvc-spi_TranslationsResolver.adoc |   2 +-
 .../guides/_rgsvc-spi_UrlEncodingService.adoc   |   2 +-
 .../main/asciidoc/guides/_tg_pet-clinic.adoc    |   2 +-
 .../_tg_stop-scaffolding-start-coding.adoc      |  24 +-
 .../main/asciidoc/guides/_ug_core-concepts.adoc |  22 --
 .../guides/_ug_core-concepts_add-ons.adoc       |  35 --
 .../_ug_core-concepts_building-blocks.adoc      | 335 -------------------
 ...re-concepts_framework-provided-services.adoc |  54 ---
 ..._core-concepts_other-deployment-options.adoc |  81 -----
 .../guides/_ug_core-concepts_philosophy.adoc    |  21 --
 .../_ug_core-concepts_philosophy_aop.adoc       |  36 --
 .../_ug_core-concepts_philosophy_dci.adoc       |   9 -
 ...oncepts_philosophy_domain-driven-design.adoc |  79 -----
 ...cepts_philosophy_hexagonal-architecture.adoc |  29 --
 ..._core-concepts_philosophy_how-eases-ddd.adoc |  74 ----
 ...ncepts_philosophy_naked-objects-pattern.adoc |  60 ----
 ...bjects-pattern_object-interface-mapping.adoc |  18 -
 .../guides/_ug_core-concepts_principles.adoc    |  16 -
 ...core-concepts_principles_apache-isis-vs.adoc |  16 -
 ...concepts_principles_apache-isis-vs_cqrs.adoc |  28 --
 ...rinciples_apache-isis-vs_event-sourcing.adoc |  19 --
 ...ts_principles_apache-isis-vs_metawidget.adoc |  16 -
 ...ache-isis-vs_mvc-server-side-frameworks.adoc |  19 --
 ...ug_core-concepts_principles_isis-itself.adoc |  47 ---
 .../_ug_core-concepts_principles_your-apps.adoc |  39 ---
 .../src/main/asciidoc/guides/_ug_faqs.adoc      |  16 -
 .../guides/_ug_faqs_enabling-logging.adoc       |  39 ---
 .../asciidoc/guides/_ug_faqs_enhance-only.adoc  |  17 -
 .../guides/_ug_faqs_per-user-themes.adoc        |  85 -----
 .../guides/_ug_faqs_restful-image-property.adoc |  20 --
 ...faqs_subtype-entity-not-fully-populated.adoc |  67 ----
 .../asciidoc/guides/_ug_getting-started.adoc    |  37 --
 ...ug_getting-started_datanucleus-enhancer.adoc | 107 ------
 ..._ug_getting-started_simpleapp-archetype.adoc | 304 -----------------
 .../src/main/asciidoc/guides/_ug_how-tos.adoc   |  22 --
 .../guides/_ug_how-tos_bulk-actions.adoc        |   8 -
 .../guides/_ug_how-tos_business-rules.adoc      |  72 ----
 .../guides/_ug_how-tos_class-structure.adoc     |  38 ---
 ...w-tos_class-structure_action-parameters.adoc |  26 --
 .../_ug_how-tos_class-structure_actions.adoc    |  19 --
 ...ow-tos_class-structure_class-definition.adoc |  24 --
 ..._ug_how-tos_class-structure_collections.adoc |  26 --
 ...ow-tos_class-structure_ignoring-methods.adoc |  16 -
 ...how-tos_class-structure_inject-services.adoc |  83 -----
 ...lass-structure_properties-vs-parameters.adoc |  45 ---
 .../_ug_how-tos_class-structure_properties.adoc | 299 -----------------
 .../guides/_ug_how-tos_contributed-members.adoc |  69 ----
 .../main/asciidoc/guides/_ug_how-tos_crud.adoc  |  29 --
 .../guides/_ug_how-tos_derived-members.adoc     |  48 ---
 .../guides/_ug_how-tos_domain-services.adoc     | 313 -----------------
 .../_ug_how-tos_drop-downs-and-defaults.adoc    |  65 ----
 .../_ug_how-tos_entity-relationships.adoc       |  15 -
 ...aged-1-to-m-bidirectional-relationships.adoc |  59 ----
 ...how-tos_render-all-properties-in-tables.adoc |  49 ---
 ...ow-tos_simulating-collections-of-values.adoc |  23 --
 .../asciidoc/guides/_ug_how-tos_ui-hints.adoc   |  15 -
 ...g_how-tos_ui-hints_action-icons-and-css.adoc |  58 ----
 .../_ug_how-tos_ui-hints_eager-rendering.adoc   |  58 ----
 .../guides/_ug_how-tos_ui-hints_layout.adoc     |   9 -
 ...how-tos_ui-hints_names-and-descriptions.adoc |  47 ---
 ...ow-tos_ui-hints_object-titles-and-icons.adoc |  97 ------
 .../guides/_ug_how-tos_ui_are-you-sure.adoc     |  76 -----
 .../main/asciidoc/guides/_ug_object-layout.adoc |  18 -
 .../_ug_object-layout_application-menu.adoc     | 171 ----------
 .../guides/_ug_object-layout_dynamic.adoc       | 113 -------
 .../_ug_object-layout_static-vs-dynamic.adoc    |  26 --
 .../guides/_ug_object-layout_static.adoc        | 159 ---------
 .../guides/_ugbtb_deployment_neo4j.adoc         |   6 +-
 ..._more-advanced_decoupling_contributions.adoc |   2 +-
 .../guides/_ugbtb_more-advanced_i18n.adoc       |   2 +-
 ...btb_more-advanced_view-models_use-cases.adoc |   2 +-
 ...gbtb_programming-model_custom-validator.adoc |   2 +-
 ...rogramming-model_layout-metadata-reader.adoc |   2 +-
 .../asciidoc/guides/_ugfun_core-concepts.adoc   |  22 ++
 .../guides/_ugfun_core-concepts_add-ons.adoc    |  35 ++
 .../_ugfun_core-concepts_building-blocks.adoc   | 335 +++++++++++++++++++
 ...re-concepts_framework-provided-services.adoc |  54 +++
 ..._core-concepts_other-deployment-options.adoc |  81 +++++
 .../guides/_ugfun_core-concepts_philosophy.adoc |  21 ++
 .../_ugfun_core-concepts_philosophy_aop.adoc    |  36 ++
 .../_ugfun_core-concepts_philosophy_dci.adoc    |   9 +
 ...oncepts_philosophy_domain-driven-design.adoc |  79 +++++
 ...cepts_philosophy_hexagonal-architecture.adoc |  29 ++
 ..._core-concepts_philosophy_how-eases-ddd.adoc |  74 ++++
 ...ncepts_philosophy_naked-objects-pattern.adoc |  60 ++++
 ...bjects-pattern_object-interface-mapping.adoc |  18 +
 .../guides/_ugfun_core-concepts_principles.adoc |  16 +
 ...core-concepts_principles_apache-isis-vs.adoc |  16 +
 ...concepts_principles_apache-isis-vs_cqrs.adoc |  28 ++
 ...rinciples_apache-isis-vs_event-sourcing.adoc |  19 ++
 ...ts_principles_apache-isis-vs_metawidget.adoc |  16 +
 ...ache-isis-vs_mvc-server-side-frameworks.adoc |  19 ++
 ...un_core-concepts_principles_isis-itself.adoc |  47 +++
 ...gfun_core-concepts_principles_your-apps.adoc |  39 +++
 .../src/main/asciidoc/guides/_ugfun_faqs.adoc   |  16 +
 .../guides/_ugfun_faqs_enabling-logging.adoc    |  39 +++
 .../guides/_ugfun_faqs_enhance-only.adoc        |  17 +
 .../guides/_ugfun_faqs_per-user-themes.adoc     |  85 +++++
 .../_ugfun_faqs_restful-image-property.adoc     |  20 ++
 ...faqs_subtype-entity-not-fully-populated.adoc |  67 ++++
 .../asciidoc/guides/_ugfun_getting-started.adoc |  37 ++
 ...un_getting-started_datanucleus-enhancer.adoc | 107 ++++++
 ...fun_getting-started_simpleapp-archetype.adoc | 304 +++++++++++++++++
 .../main/asciidoc/guides/_ugfun_how-tos.adoc    |  22 ++
 .../guides/_ugfun_how-tos_bulk-actions.adoc     |   8 +
 .../guides/_ugfun_how-tos_business-rules.adoc   |  72 ++++
 .../guides/_ugfun_how-tos_class-structure.adoc  |  38 +++
 ...w-tos_class-structure_action-parameters.adoc |  26 ++
 .../_ugfun_how-tos_class-structure_actions.adoc |  19 ++
 ...ow-tos_class-structure_class-definition.adoc |  24 ++
 ...fun_how-tos_class-structure_collections.adoc |  26 ++
 ...ow-tos_class-structure_ignoring-methods.adoc |  16 +
 ...how-tos_class-structure_inject-services.adoc |  83 +++++
 ...lass-structure_properties-vs-parameters.adoc |  45 +++
 ...gfun_how-tos_class-structure_properties.adoc | 299 +++++++++++++++++
 .../_ugfun_how-tos_contributed-members.adoc     |  69 ++++
 .../asciidoc/guides/_ugfun_how-tos_crud.adoc    |  29 ++
 .../guides/_ugfun_how-tos_derived-members.adoc  |  48 +++
 .../guides/_ugfun_how-tos_domain-services.adoc  | 313 +++++++++++++++++
 .../_ugfun_how-tos_drop-downs-and-defaults.adoc |  65 ++++
 .../_ugfun_how-tos_entity-relationships.adoc    |  15 +
 ...aged-1-to-m-bidirectional-relationships.adoc |  59 ++++
 ...how-tos_render-all-properties-in-tables.adoc |  49 +++
 ...ow-tos_simulating-collections-of-values.adoc |  23 ++
 .../guides/_ugfun_how-tos_ui-hints.adoc         |  15 +
 ...n_how-tos_ui-hints_action-icons-and-css.adoc |  58 ++++
 ..._ugfun_how-tos_ui-hints_eager-rendering.adoc |  58 ++++
 .../guides/_ugfun_how-tos_ui-hints_layout.adoc  |   9 +
 ...how-tos_ui-hints_names-and-descriptions.adoc |  47 +++
 ...ow-tos_ui-hints_object-titles-and-icons.adoc |  97 ++++++
 .../guides/_ugfun_how-tos_ui_are-you-sure.adoc  |  76 +++++
 .../asciidoc/guides/_ugfun_object-layout.adoc   |  18 +
 .../_ugfun_object-layout_application-menu.adoc  | 171 ++++++++++
 .../guides/_ugfun_object-layout_dynamic.adoc    | 113 +++++++
 .../_ugfun_object-layout_static-vs-dynamic.adoc |  26 ++
 .../guides/_ugfun_object-layout_static.adoc     | 159 +++++++++
 .../_ugsec_configuring-isis-to-use-shiro.adoc   |   2 +-
 .../asciidoc/guides/_ugsec_shiro-ini-realm.adoc |   2 +-
 ...st_bdd-spec-support_maven-configuration.adoc |   2 +-
 ...tst_bdd-spec-support_writing-a-bdd-spec.adoc |   6 +-
 .../_ugtst_fixture-scripts_api-and-usage.adoc   |  12 +-
 ..._ugtst_integ-test-support_bootstrapping.adoc |   2 +-
 ..._integ-test-support_maven-configuration.adoc |   2 +-
 ..._ugtst_unit-test-support_contract-tests.adoc |   4 +-
 ...t_unit-test-support_maven-configuration.adoc |   2 +-
 .../guides/_ugvw_customisation_about-page.adoc  |   2 +-
 ...ugvw_customisation_tweaking-css-classes.adoc |   2 +-
 .../src/main/asciidoc/guides/_ugvw_layout.adoc  |   6 +-
 .../src/main/asciidoc/guides/cg.adoc            |  30 +-
 .../src/main/asciidoc/guides/rg.adoc            |  27 ++
 .../src/main/asciidoc/guides/rgant.adoc         |  35 +-
 .../src/main/asciidoc/guides/rgcfg.adoc         |  30 +-
 .../src/main/asciidoc/guides/rgcms.adoc         |  21 +-
 .../src/main/asciidoc/guides/rgsvc.adoc         |  21 +-
 .../asciidoc/guides/simpleapp-archetype.adoc    |   2 +-
 .../src/main/asciidoc/guides/ug.adoc            |  33 +-
 .../src/main/asciidoc/guides/ugbtb.adoc         |  19 +-
 .../src/main/asciidoc/guides/ugfun.adoc         |  50 +++
 .../src/main/asciidoc/guides/ugsec.adoc         |  21 +-
 .../src/main/asciidoc/guides/ugtst.adoc         |  18 +-
 .../src/main/asciidoc/guides/ugvro.adoc         |  18 +-
 .../src/main/asciidoc/guides/ugvw.adoc          |  18 +-
 246 files changed, 4380 insertions(+), 4143 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/README.adoc
----------------------------------------------------------------------
diff --git a/README.adoc b/README.adoc
index c72e3bf..5432332 100644
--- a/README.adoc
+++ b/README.adoc
@@ -1,8 +1,8 @@
 = Apache Isis
 
-_http://isis.apache.org[Apache Isis]� software is a framework for rapidly developing domain-driven apps in Java. Write your business logic in entities, domain services and repositories, and the framework dynamically generates a representation of that domain model as a webapp or a RESTful API._
+_http://isis.apache.org[Apache Isis]� software is a framework for rapidly developing domain-driven apps in Java. Write your business logic in entities, domain services and repositories, and the framework dynamically generates a representation of that domain model as a webapp or a RESTful API._
 
-Get started using our "simpleapp" https://isis.apache.org/guides/ug.html#_ug_getting-started_simpleapp-archetype[Maven archetype].
+Get started using our "simpleapp" https://isis.apache.org/guides/ugfun.html#_ugfun_getting-started_simpleapp-archetype[Maven archetype].
 
 For help and support, join the http://isis.apache.org/support.html[mailing lists]. To contribute to our documentation, see our https://github.com/apache/isis/tree/master/adocs/documentation[Asciidoctor source].
 
@@ -16,7 +16,7 @@ The todoapp also integrates with a number of other http://www.isisaddons.org[Isi
 
 === Sign-in
 
-Apache Isis integrates with http://shiro.apache.org[Apache Shiro]�. The core framework supports file-based realms, while the Isis Addons http://github.com/isisaddons/isis-module-security[security module] provides a well-features subdomain of users, roles and permissions against features derived from the Isis metamodel. The example todoapp integrates with the security module.
+Apache Isis integrates with http://shiro.apache.org[Apache Shiro]�. The core framework supports file-based realms, while the Isis Addons http://github.com/isisaddons/isis-module-security[security module] provides a well-features subdomain of users, roles and permissions against features derived from the Isis metamodel. The example todoapp integrates with the security module.
 
 image::https://raw.github.com/apache/isis/master/adocs/documentation/src/main/asciidoc/images/isis-in-pictures/010-login.png[link="https://raw.github.com/apache/isis/master/adocs/documentation/src/main/asciidoc/images/isis-in-pictures/010-login.png"]
 
@@ -79,7 +79,7 @@ image::https://raw.github.com/apache/isis/master/adocs/documentation/src/main/as
 
 == Extensible Views
 
-The Apache Isis viewer is implemented using http://wicket.apache.org[Apache Wicket]�, and has been architected to be extensible. For example, when a collection of objects is rendered, this is just one several views, as shown in the selector drop-down:
+The Apache Isis viewer is implemented using http://wicket.apache.org[Apache Wicket]�, and has been architected to be extensible. For example, when a collection of objects is rendered, this is just one several views, as shown in the selector drop-down:
 
 image::https://raw.github.com/apache/isis/master/adocs/documentation/src/main/asciidoc/images/isis-in-pictures/070-pluggable-views.png[link="https://raw.github.com/apache/isis/master/adocs/documentation/src/main/asciidoc/images/isis-in-pictures/070-pluggable-views.png"]
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_bootstrapping-using-AppManifest.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_bootstrapping-using-AppManifest.adoc b/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_bootstrapping-using-AppManifest.adoc
index 16fe795..0617439 100644
--- a/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_bootstrapping-using-AppManifest.adoc
+++ b/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_bootstrapping-using-AppManifest.adoc
@@ -8,7 +8,7 @@
 
 Apache Isis 1.9.0 provides a simplified programmatic way of bootstrapping the application, that also unifies bootstrapping for integration tests.
 
-For now this new bootstrapping mechanism is optional (you don't have to change your code), but it may become mandatory in future releases.  The xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype] has been updated to use this new mechanism.
+For now this new bootstrapping mechanism is optional (you don't have to change your code), but it may become mandatory in future releases.  The xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] has been updated to use this new mechanism.
 
 The instructions below assume that your application is structured as per the simpleapp archetype.  Adjust accordingly.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_upgrading-to-dn4.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_upgrading-to-dn4.adoc b/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_upgrading-to-dn4.adoc
index 63f1200..7fd697d 100644
--- a/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_upgrading-to-dn4.adoc
+++ b/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_upgrading-to-dn4.adoc
@@ -8,7 +8,7 @@
 
 Apache Isis 1.9.0 updates to DataNucleus 4.0.0, which requires some changes (simplifications) to the Maven configuration.
 
-If you starting a new app then you can start from the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype]; its Maven configuration has been updated.
+If you starting a new app then you can start from the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]; its Maven configuration has been updated.
 
 If you have an existing Apache Isis app that you want to upgrade, then you'll need to make some changes.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_war-packaging.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_war-packaging.adoc b/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_war-packaging.adoc
index a71e83d..5e72ba0 100644
--- a/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_war-packaging.adoc
+++ b/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_war-packaging.adoc
@@ -6,7 +6,7 @@
 
 
 
-As discussed in xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype] and elsewhere, the `org.apache.isis.WebServer` provides the ability to run your app from an embedded jetty.  This is great for prototyping.  The class resides in the `isis-core-webserver` module, which also has the dependency on jetty.
+As discussed in xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] and elsewhere, the `org.apache.isis.WebServer` provides the ability to run your app from an embedded jetty.  This is great for prototyping.  The class resides in the `isis-core-webserver` module, which also has the dependency on jetty.
 
 In 1.9.0 we have upgraded the jetty dependency to use Jetty 9.2.0 (`org.eclipse.jetty.aggregate:jetty-all:9.2.11.v20150529`, to be precise).  One consequence of this is that the packaged WAR file will not boot on Tomcat.
 
@@ -31,4 +31,4 @@ Alternatively you can change your webapp's `pom.xml` so that when the war is pac
 ----
 
 
-For future projects the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype] has been updated with this change.
+For future projects the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] has been updated with this change.

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/common-use-cases.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/common-use-cases.adoc b/adocs/documentation/src/main/asciidoc/common-use-cases.adoc
index 2c5acc2..6e32b6d 100644
--- a/adocs/documentation/src/main/asciidoc/common-use-cases.adoc
+++ b/adocs/documentation/src/main/asciidoc/common-use-cases.adoc
@@ -26,7 +26,7 @@ Once you've sketched out your domain model, you can then either start-over using
 
 One of the original motivations for Apache Isis itself was to be able automatically generate a user interface for a domain object model.
 
-Apache Isis' has a pluggable architecture allowing different user interface technologies. The principal implementation (as configured by the link:./simple-archetype.html[simple archetype]) is the link:guides/ug.html#_ug_wicket-viewer[Wicket viewer]. This provides an appealing default user interface, with the ability to customize the user interface by writing new http://wicket.apache.org[Apache Wicket] components. Some third-party components can be found in the (non-ASF) link:http://isisaddons.org[Isis Addons] (non-ASF) project, integrating the Wicket viewer with https://github.com/isisaddons/isis-wicket-gmap3[google maps], https://github.com/isisaddons/isis-wicket-fullcalendar2[a full calendar] and a https://github.com/isisaddons/isis-wicket-excel[export to Excel] component.
+Apache Isis' has a pluggable architecture allowing different user interface technologies. The principal implementation (as configured by the link:./simple-archetype.html[simple archetype]) is the link:guides/ugvw.html#[Wicket viewer]. This provides an appealing default user interface, with the ability to customize the user interface by writing new http://wicket.apache.org[Apache Wicket] components. Some third-party components can be found in the (non-ASF) link:http://isisaddons.org[Isis Addons] (non-ASF) project, integrating the Wicket viewer with https://github.com/isisaddons/isis-wicket-gmap3[google maps], https://github.com/isisaddons/isis-wicket-fullcalendar2[a full calendar] and a https://github.com/isisaddons/isis-wicket-excel[export to Excel] component.
 
 
 Deploying on Apache Isis means that the framework also manages object persistence. Again this is pluggable, but the principal implementation is the JDO/DataNucleus objectstore. Because JDO supports both SQL and NoSQL databases, you can then deploy on a variety of platforms, including the link:https://developers.google.com/appengine/[Google App Engine (GAE)] and link:http://neo4j.com/[Neo4J].
@@ -38,7 +38,7 @@ Deploying on Apache Isis means that the framework also manages object persistenc
 
 REST (Representation State Transfer) is an architectural style for building highly scalable distributed systems, using the same principles as the World Wide Web. Many commercial web APIs (twitter, facebook, Amazon) are implemented as either pure REST APIs or some approximation therein.
 
-The http://restfulobjects.org[Restful Objects specification] defines a means by a domain object model can be exposed as RESTful resources using JSON representations over HTTP. Apache Isis' link:guides/ugvro.html[RestfulObjects viewer] is an implementation of that spec, making any Apache Isis domain object automatically available via REST.
+The http://restfulobjects.org[Restful Objects specification] defines a means by a domain object model can be exposed as RESTful resources using JSON representations over HTTP. Apache Isis' link:guides/ugvro.html#[RestfulObjects viewer] is an implementation of that spec, making any Apache Isis domain object automatically available via REST.
 
 There are two main use cases for deploying Apache Isis as a RESTful web service are:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/documentation.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/documentation.adoc b/adocs/documentation/src/main/asciidoc/documentation.adoc
index 6e8d6de..5e1b2d8 100644
--- a/adocs/documentation/src/main/asciidoc/documentation.adoc
+++ b/adocs/documentation/src/main/asciidoc/documentation.adoc
@@ -59,7 +59,7 @@ pass:[<br/>]
 
 |*User Guides:*
 
-* *link:./guides/ug.html[Fundamentals^]*
+* *link:./guides/ugfun.html[Fundamentals^]*
 * link:./guides/ugvw.html[Wicket Viewer^]
 * link:./guides/ugvro.html[Restful Objects Viewer^]
 * link:./guides/ugsec.html[Security^]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_cg_asciidoc-templates.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_asciidoc-templates.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_asciidoc-templates.adoc
index 5b6e3ea..6a97968 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_cg_asciidoc-templates.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_asciidoc-templates.adoc
@@ -185,9 +185,9 @@ a hyperlink to a level 2 (chapter and section) within the reference guide, where
 
 for example:
 
-pass:[<pre>xref:ug.adoc#_ug_object-layout_dynamic_[Dynamic object layout]</pre>]
+pass:[<pre>xref:ug.adoc#_ugfun_object-layout_dynamic_[Dynamic object layout]</pre>]
 
-|xref:ug.adoc#_ug_object-layout_dynamic[Dynamic object layout]
+|xref:ug.adoc#_ugfun_object-layout_dynamic[Dynamic object layout]
 
 
 
@@ -385,9 +385,9 @@ a hyperlink to a level 1 (chapter) within the users' guide, where:
 
 for example:
 
-pass:[<pre>xref:ug.adoc#_ug_core-concepts[Core concepts\]</pre>]
+pass:[<pre>xref:ug.adoc#_ugfun_core-concepts[Core concepts\]</pre>]
 
-|xref:ug.adoc#_ug_core-concepts[Core concepts]
+|xref:ug.adoc#_ugfun_core-concepts[Core concepts]
 
 
 
@@ -418,19 +418,19 @@ a hyperlink to a level 3 (chapter, section, subsection) within the users' guide,
 
 for example:
 
-pass:[<pre>xref:ug.adoc#_ug_core-concepts_philosophy_naked-objects-pattern[Naked objects pattern\]</pre>]
+pass:[<pre>xref:ug.adoc#_ugfun_core-concepts_philosophy_naked-objects-pattern[Naked objects pattern\]</pre>]
 
-|xref:ug.adoc#_ug_core-concepts_philosophy_naked-objects-pattern[Naked objects pattern]
+|xref:ug.adoc#_ugfun_core-concepts_philosophy_naked-objects-pattern[Naked objects pattern]
 
 
 
 
 |`adugsimpleapp`
-|pass:[<pre>xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype\]</pre>]
+|pass:[<pre>xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype\]</pre>]
 
 A hyperlink to the `simpleapp` archetype in the "getting started" chapter.
 
-|xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype]
+|xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]
 
 
 |`adugvro`
@@ -769,11 +769,11 @@ defines an inline anchor to any heading, where:
 
 For example:
 
-pass:[<pre>= anchor:[_ug_i18n\] Internationalization</pre>]
+pass:[<pre>= anchor:[_ugfun_i18n\] Internationalization</pre>]
 
 An alternative (more commonly used in our documentation) is to use the `[[...]]` directly above the heading:
 
-pass:[<pre>[[_ug_i18n\]\]
+pass:[<pre>[[_ugfun_i18n\]\]
 = Internationalization</pre>]
 
 |

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_cg_ide_eclipse.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_ide_eclipse.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_ide_eclipse.adoc
index 793d27c..bbf0d98 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_cg_ide_eclipse.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_ide_eclipse.adoc
@@ -62,7 +62,7 @@ image::{_imagesdir}appendices/dev-env/eclipse/eclipse-110-project-support.png[wi
 
 DataNucleus' enhancer uses the domain object model's own classpath to reference DataNucleus JARs. So, even though your domain objects are unlikely to depend on DataNucleus, these references must still be present.
 
-See the earlier section on xref:ug.adoc#_ug_getting-started_datanucleus-enhancer[DataNucleus enhancer] for details of the contents of the `pom.xml`.  Chances are it is already set up from running the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype].
+See the earlier section on xref:ug.adoc#_ugfun_getting-started_datanucleus-enhancer[DataNucleus enhancer] for details of the contents of the `pom.xml`.  Chances are it is already set up from running the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
 
 
 Then, tell DataNucleus to use the project classpath:

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin.adoc
index b46dfdd..6b9a13d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin.adoc
@@ -29,7 +29,7 @@ it knows how to bootstrap an Isis runtime.  This is discussed below, followed by
 As noted in the introduction, both goals require an xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`]
 to point the plugin at, so that it knows how to bootstrap an Isis runtime.
 
-This can be extremely minimal.  For example, the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp]'s
+This can be extremely minimal.  For example, the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp]'s
 manifest is:
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin_validate.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin_validate.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin_validate.adoc
index 51d6d2a..9771752 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin_validate.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin_validate.adoc
@@ -110,7 +110,7 @@ mvn test -Dskip.isis-validate
 
 == Example of failure
 
-In the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp] application the `SimpleObject` defines an `updateName` action.  This has a supporting method:
+In the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp] application the `SimpleObject` defines an `updateName` action.  This has a supporting method:
 
 
 [source,java]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout.adoc
index 963c41c..cc16e56 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout.adoc
@@ -100,7 +100,7 @@ public class ToDoItems {
 
 
 
-As an alternative to using the `@ActionLayout` annotation, a dynamic layout using  xref:ug.adoc#_ug_object-layout_dynamic[`.layout.json`] file can be specified; for example:
+As an alternative to using the `@ActionLayout` annotation, a dynamic layout using  xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`] file can be specified; for example:
 
 [source,javascript]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_bookmarking.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_bookmarking.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_bookmarking.adoc
index 2655d6d..6a646dc 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_bookmarking.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_bookmarking.adoc
@@ -50,7 +50,7 @@ The enum value `AS_CHILD` has no meaning for actions; it relates only to bookmar
 
 
 
-As an alternative to using the annotation, the dynamic xref:ug.adoc#_ug_object-layout_dynamic[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_contributedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_contributedAs.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_contributedAs.adoc
index 983987d..13b1fe8 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_contributedAs.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_contributedAs.adoc
@@ -49,6 +49,6 @@ In such cases, though, it would probably make more sense to annotate the action
 
 [NOTE]
 ====
-Unlike other `@ActionLayout` attributes, this attribute _cannot_ be specified dynamically in the `.layout.json` xref:ug.adoc#_ug_object-layout_dynamic[dynamic layout file] because it relates to the contributor domain service, not the contributee domain object.
+Unlike other `@ActionLayout` attributes, this attribute _cannot_ be specified dynamically in the `.layout.json` xref:ug.adoc#_ugfun_object-layout_dynamic[dynamic layout file] because it relates to the contributor domain service, not the contributee domain object.
 ====
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_cssClass.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_cssClass.adoc
index fb090cf..e2f0bac 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_cssClass.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_cssClass.adoc
@@ -30,7 +30,7 @@ to apply CSS, specifically to add http://fortawesome.github.io/Font-Awesome/icon
 
 
 
-As an alternative to using the annotation, the dynamic xref:ug.adoc#_ug_object-layout_dynamic[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_cssClassFa.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_cssClassFa.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_cssClassFa.adoc
index 0702f30..3e393c7 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_cssClassFa.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_cssClassFa.adoc
@@ -31,7 +31,7 @@ public class ToDoItem {
 There can be multiple "fa-" classes, eg to mirror or rotate the icon. There is no need to include the mandatory `fa` "marker" CSS class; it will be automatically added to the list.  The `fa-` prefix can also be omitted from the class names; it will be prepended to each if required.
 
 
-As an alternative to using the annotation, the dynamic xref:ug.adoc#_ug_object-layout_dynamic[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_describedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_describedAs.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_describedAs.adoc
index d4ec9cc..f1543f8 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_describedAs.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_describedAs.adoc
@@ -24,7 +24,7 @@ public class Customer {
 
 
 
-As an alternative to using the annotation, the dynamic xref:ug.adoc#_ug_object-layout_dynamic[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_hidden.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_hidden.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_hidden.adoc
index 8ba695a..bb28835 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_hidden.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_hidden.adoc
@@ -37,7 +37,7 @@ The action should not be hidden.
 The other values of the `Where` enum have no meaning for a collection.
 
 
-As an alternative to using the annotation, the dynamic xref:ug.adoc#_ug_object-layout_dynamic[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_named.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_named.adoc
index 13993a3..7813dca 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_named.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_named.adoc
@@ -25,7 +25,7 @@ public class Customer {
 ----
 
 
-As an alternative to using the annotation, the dynamic xref:ug.adoc#_ug_object-layout_dynamic[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_position.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_position.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_position.adoc
index 596530f..c3d09c0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_position.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_position.adoc
@@ -67,7 +67,7 @@ image::{_imagesdir}reference-annotations/ActionLayout/position-PANEL_DROPDOWN.pn
 If there are multiple actions associated with a single property then the positioning can be mix'ed-and-match'ed as required.  If the `PANEL` or `PANEL_DROPDOWN` are used, then (as the screenshots above show) the actions from potentially multiple properties grouped by that panel will be shown together.
 
 
-As an alternative to using the annotation, the dynamic xref:ug.adoc#_ug_object-layout_dynamic[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgant-Action_hidden.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-Action_hidden.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-Action_hidden.adoc
index dc3add8..f65b28c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-Action_hidden.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-Action_hidden.adoc
@@ -11,7 +11,7 @@ Actions can be hidden at the domain-level, indicating that they are not visible
 
 [TIP]
 ====
-It is also possible to use xref:rgant.adoc#_rgant-ActionLayout_hidden[`@ActionLayout#hidden()`] or xref:ug.adoc#_ug_object-layout_dynamic[dynamic layouts] such that the action can be hidden at the view layer. Both options are provided with a view that in the future the view-layer semantics may be under the control of (expert) users, whereas domain-layer semantics should never be overridden or modified by the user.
+It is also possible to use xref:rgant.adoc#_rgant-ActionLayout_hidden[`@ActionLayout#hidden()`] or xref:ug.adoc#_ugfun_object-layout_dynamic[dynamic layouts] such that the action can be hidden at the view layer. Both options are provided with a view that in the future the view-layer semantics may be under the control of (expert) users, whereas domain-layer semantics should never be overridden or modified by the user.
 ====
 
 For example:

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout.adoc
index 3362a94..0ff2f80 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout.adoc
@@ -94,7 +94,7 @@ public class ToDoItem {
 
 
 
-As an alternative to using the `@CollectionLayout` annotation, a dynamic layout using  xref:ug.adoc#_ug_object-layout_dynamic[`.layout.json`] file can be specified; for example:
+As an alternative to using the `@CollectionLayout` annotation, a dynamic layout using  xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`] file can be specified; for example:
 
 [source,javascript]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_cssClass.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_cssClass.adoc
index c8d3d19..e18e3e1 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_cssClass.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_cssClass.adoc
@@ -24,7 +24,7 @@ public class ToDoItem {
 ----
 
 
-As an alternative to using the annotation, the dynamic xref:ug.adoc#_ug_object-layout_dynamic[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_defaultView.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_defaultView.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_defaultView.adoc
index de4108a..9641d78 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_defaultView.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_defaultView.adoc
@@ -24,7 +24,7 @@ public class BusRoute {
 ----
 
 
-As an alternative to using the annotation, the dynamic xref:ug.adoc#_ug_object-layout_dynamic[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_describedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_describedAs.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_describedAs.adoc
index 5f27ca0..effc006 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_describedAs.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_describedAs.adoc
@@ -24,7 +24,7 @@ public class ToDoItem {
 ----
 
 
-As an alternative to using the annotation, the dynamic xref:ug.adoc#_ug_object-layout_dynamic[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_hidden.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_hidden.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_hidden.adoc
index 810f530..ad906c3 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_hidden.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_hidden.adoc
@@ -47,7 +47,7 @@ The collection should not be hidden.
 The other values of the `Where` enum have no meaning for a collection.
 
 
-As an alternative to using the annotation, the dynamic xref:ug.adoc#_ug_object-layout_dynamic[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_named.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_named.adoc
index 79fd145..9fe50e2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_named.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_named.adoc
@@ -33,7 +33,7 @@ public class ToDoItem {
 
 
 
-As an alternative to using the annotation, the dynamic xref:ug.adoc#_ug_object-layout_dynamic[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_paged.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_paged.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_paged.adoc
index f371d7a..2551458 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_paged.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_paged.adoc
@@ -31,7 +31,7 @@ It is also possible to specify a global default for the page size of standalone
 
 
 
-As an alternative to using the annotation, the dynamic xref:ug.adoc#_ug_object-layout_dynamic[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_render.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_render.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_render.adoc
index 375dc08..121e185 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_render.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_render.adoc
@@ -20,7 +20,7 @@ public class Order {
 ----
 
 
-As an alternative to using the annotation, the dynamic xref:ug.adoc#_ug_object-layout_dynamic[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]
@@ -35,7 +35,7 @@ can be used instead, eg:
 
 [NOTE]
 ====
-Note that xref:ug.adoc#_ug_how-tos_contributed-members[contributed collections] (which, under the covers are just action invocations against a domain service) are always rendered eagerly.
+Note that xref:ug.adoc#_ugfun_how-tos_contributed-members[contributed collections] (which, under the covers are just action invocations against a domain service) are always rendered eagerly.
 
 Also, if a xref:rgant.adoc#_rgant-CollectionLayout_defaultView[`@CollectionLayout#defaultView()`] attribute has been specified then that will take precedence over the value of the `render()` attribute.
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_sortedBy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_sortedBy.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_sortedBy.adoc
index 2d39a71..2083be4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_sortedBy.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_sortedBy.adoc
@@ -46,7 +46,7 @@ Without this annotation, the order would have been inverted (because the natural
 
 
 
-As an alternative to using the annotation, the dynamic xref:ug.adoc#_ug_object-layout_dynamic[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgant-Collection_hidden.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-Collection_hidden.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-Collection_hidden.adoc
index 66d4f69..c16c14a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-Collection_hidden.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-Collection_hidden.adoc
@@ -9,7 +9,7 @@ Collections can be hidden at the domain-level, indicating that they are not visi
 
 [TIP]
 ====
-It is also possible to use xref:rgant.adoc#_rgant-CollectionLayout_hidden[`@CollectionLayout#hidden()`] or xref:ug.adoc#_ug_object-layout_dynamic[dynamic layouts] such that the collection can be hidden at the view layer. Both options are provided with a view that in the future the view-layer semantics may be under the control of (expert) users, whereas domain-layer semantics should never be overridden or modified by the user.
+It is also possible to use xref:rgant.adoc#_rgant-CollectionLayout_hidden[`@CollectionLayout#hidden()`] or xref:ug.adoc#_ugfun_object-layout_dynamic[dynamic layouts] such that the collection can be hidden at the view layer. Both options are provided with a view that in the future the view-layer semantics may be under the control of (expert) users, whereas domain-layer semantics should never be overridden or modified by the user.
 ====
 
 For example:

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout.adoc
index 0f5a3d3..e49a5f5 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout.adoc
@@ -109,7 +109,7 @@ public class ToDoItem {
 
 [NOTE]
 ====
-Note that there is (currently) no support for specifying UI hints for domain objects through the dynamic xref:ug.adoc#_ug_object-layout_dynamic[`.layout.json`] file (only for properties, collections and actions are supported).
+Note that there is (currently) no support for specifying UI hints for domain objects through the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`] file (only for properties, collections and actions are supported).
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainServiceLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainServiceLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainServiceLayout.adoc
index 78d799b..240951e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainServiceLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainServiceLayout.adoc
@@ -10,7 +10,7 @@ The `@DomainServiceLayout` annotation applies to domain services, collecting tog
 
 [TIP]
 ====
-You will also find some additional material in the xref:ug.adoc#_ug_object-layout_application-menu[object layout] chapter.
+You will also find some additional material in the xref:ug.adoc#_ugfun_object-layout_application-menu[object layout] chapter.
 ====
 
 
@@ -64,7 +64,7 @@ public class ToDoItems {
 
 [NOTE]
 ====
-Note that there is (currently) no support for specifying UI hints for domain services through the dynamic xref:ug.adoc#_ug_object-layout_dynamic[`.layout.json`] file (only for properties, collections and actions are supported).
+Note that there is (currently) no support for specifying UI hints for domain services through the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`] file (only for properties, collections and actions are supported).
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgant-HomePage.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-HomePage.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-HomePage.adoc
index c14ec11..159caae 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-HomePage.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-HomePage.adoc
@@ -45,7 +45,7 @@ public class ToDoAppDashboard {
     public Blob exportToWordDoc() { ... }  // <1>
 }
 ----
-<1> associated using xref:ug.adoc#_ug_object-layout_dynamic[dynamic layouts] with the `notYetComplete` collection.
+<1> associated using xref:ug.adoc#_ugfun_object-layout_dynamic[dynamic layouts] with the `notYetComplete` collection.
 
 The other two actions shown in the above screenshot -- `exportAsXml` and `downloadLayout` -- are actually contributed to the `ToDoAppDashboard` through various domain services, as is the `downloadLayout` action.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgant-Inject.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-Inject.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-Inject.adoc
index b2791ff..77dc434 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-Inject.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-Inject.adoc
@@ -27,7 +27,7 @@ public class Customer {
     OrderRepository orders;                    // <2>
 }
 ----
-<1> an alternative implementation would be to implement `findRecentOrders()` as a xref:ug.adoc#_ug_how-tos_contributed-members[contributed action].
+<1> an alternative implementation would be to implement `findRecentOrders()` as a xref:ug.adoc#_ugfun_how-tos_contributed-members[contributed action].
 <2> we recommend default (rather than `private`) visibility so that unit tests can easily mock out the service
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgant-MemberGroupLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-MemberGroupLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-MemberGroupLayout.adoc
index 353f3ca..f93af0d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-MemberGroupLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-MemberGroupLayout.adoc
@@ -16,5 +16,5 @@ The annotation defines two attributes, `name()` and `sequence()`.  Broadly speak
 
 [IMPORTANT]
 ====
-As this is an important topic, there is a xref:ug.adoc#_ug_object-layout[separate chapter] that discussed object layout in full.
+As this is an important topic, there is a xref:ug.adoc#_ugfun_object-layout[separate chapter] that discussed object layout in full.
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgant-MemberOrder.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-MemberOrder.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-MemberOrder.adoc
index 01f1fb0..c642d84 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-MemberOrder.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-MemberOrder.adoc
@@ -21,7 +21,7 @@ Collections are always rendered in the "last" column.  This can appear either be
 
 [IMPORTANT]
 ====
-As this is an important topic, there is a xref:ug.adoc#_ug_object-layout[separate chapter] that discussed object layout in full.
+As this is an important topic, there is a xref:ug.adoc#_ugfun_object-layout[separate chapter] that discussed object layout in full.
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgant-ParameterLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-ParameterLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-ParameterLayout.adoc
index 09fc3e7..fd7cc1c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-ParameterLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-ParameterLayout.adoc
@@ -96,7 +96,7 @@ public class ToDoItem {
 
 [NOTE]
 ====
-Note that there is (currently) no support for specifying UI hints for domain services through the dynamic xref:ug.adoc#_ug_object-layout_dynamic[`.layout.json`] file (only for properties, collections and actions are supported).
+Note that there is (currently) no support for specifying UI hints for domain services through the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`] file (only for properties, collections and actions are supported).
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgant-PostConstruct.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-PostConstruct.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-PostConstruct.adoc
index bf2eb25..c7d216f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-PostConstruct.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-PostConstruct.adoc
@@ -7,7 +7,7 @@
 
 The `@javax.annotation.PostConstruct` annotation, as defined in link:https://jcp.org/en/jsr/detail?id=250[JSR-250],  is recognized by Apache Isis as a callback method on domain services to be called just after they have been constructed, in order that they initialize themselves.
 
-It is also recognized for xref:ug.adoc#http://localhost:4000/guides/ug.html#_ugbtb_more-advanced_view-models[view models] (eg annotated with xref:rgant.adoc#_rgant-ViewModel[`@ViewModel`]).
+It is also recognized for xref:ugbtb.adoc#_ugbtb_more-advanced_view-models[view models] (eg annotated with xref:rgant.adoc#_rgant-ViewModel[`@ViewModel`]).
 
 For the default application-scoped (singleton) domain services, this means that the method, if present, is called during the bootstrapping of the application.  For xref:rgant.adoc#_rgant-RequestScoped[`@RequestScoped`] domain services, the method is called at the beginning of the request.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout.adoc
index 4ab9658..9687634 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout.adoc
@@ -102,7 +102,7 @@ It is also possible to apply the annotation to actions of domain services that a
 
 
 
-As an alternative to using the `@PropertyLayout` annotation, a dynamic layout using  xref:ug.adoc#_ug_object-layout_dynamic[`.layout.json`] file can be specified; for example:
+As an alternative to using the `@PropertyLayout` annotation, a dynamic layout using  xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`] file can be specified; for example:
 
 [source,javascript]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_cssClass.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_cssClass.adoc
index a522810..0c31226 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_cssClass.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_cssClass.adoc
@@ -23,7 +23,7 @@ public class ToDoItem {
 
 
 
-As an alternative to using the annotation, the dynamic xref:ug.adoc#_ug_object-layout_dynamic[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_describedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_describedAs.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_describedAs.adoc
index f93ac69..8c63f37 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_describedAs.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_describedAs.adoc
@@ -20,7 +20,7 @@ public class Customer {
 ----
 
 
-As an alternative to using the annotation, the dynamic xref:ug.adoc#_ug_object-layout_dynamic[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_hidden.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_hidden.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_hidden.adoc
index 72c2f6e..2e83211 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_hidden.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_hidden.adoc
@@ -10,7 +10,7 @@ The `hidden()` attribute indicates where (in the UI) the property should be hidd
 
 [TIP]
 ====
-It is also possible to use xref:rgant.adoc#_rgant-PropertyLayout_hidden[`@PropertyLayout#hidden()`] or xref:ug.adoc#_ug_object-layout_dynamic[dynamic layouts] such that the property can be hidden at the view layer. Both options are provided with a view that in the future the view-layer semantics may be under the control of (expert) users, whereas domain-layer semantics should never be overridden or modified by the user.
+It is also possible to use xref:rgant.adoc#_rgant-PropertyLayout_hidden[`@PropertyLayout#hidden()`] or xref:ug.adoc#_ugfun_object-layout_dynamic[dynamic layouts] such that the property can be hidden at the view layer. Both options are provided with a view that in the future the view-layer semantics may be under the control of (expert) users, whereas domain-layer semantics should never be overridden or modified by the user.
 ====
 
 
@@ -67,7 +67,7 @@ The xref:ugvro.adoc#[RestfulObjects viewer] has only partial support for these `
 ====
 
 
-As an alternative to using the annotation, the dynamic xref:ug.adoc#_ug_object-layout_dynamic[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_labelPosition.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_labelPosition.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_labelPosition.adoc
index f711de9..7eef03e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_labelPosition.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_labelPosition.adoc
@@ -58,7 +58,7 @@ image::{_imagesdir}reference-annotations/PropertyLayout/labelPosition-boolean-RI
 
 
 
-As an alternative to using the annotation, the dynamic xref:ug.adoc#_ug_object-layout_dynamic[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_multiLine.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_multiLine.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_multiLine.adoc
index c6d92a0..f506d24 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_multiLine.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_multiLine.adoc
@@ -25,7 +25,7 @@ Here the `stepsToReproduce` will be displayed in a text area of 10 rows.
 
 
 
-As an alternative to using the annotation, the dynamic xref:ug.adoc#_ug_object-layout_dynamic[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_named.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_named.adoc
index 8d63fd6..43fc46d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_named.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_named.adoc
@@ -31,7 +31,7 @@ public class ToDoItem {
 
 
 
-As an alternative to using the annotation, the dynamic xref:ug.adoc#_ug_object-layout_dynamic[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_renderedAsDayBefore.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_renderedAsDayBefore.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_renderedAsDayBefore.adoc
index aded30d..d041d5a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_renderedAsDayBefore.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_renderedAsDayBefore.adoc
@@ -32,7 +32,7 @@ public class Tenancy {
 
 
 
-As an alternative to using the annotation, the dynamic xref:ug.adoc#_ug_object-layout_dynamic[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgant-ViewModelLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-ViewModelLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-ViewModelLayout.adoc
index ca7efaf..a7406c1 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-ViewModelLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-ViewModelLayout.adoc
@@ -82,7 +82,7 @@ public class CategoryPieChart { ... }
 
 [NOTE]
 ====
-Note that there is (currently) no support for specifying UI hints for view models through the dynamic xref:ug.adoc#_ug_object-layout_dynamic[`.layout.json`] file (only for properties, collections and actions are supported).
+Note that there is (currently) no support for specifying UI hints for view models through the dynamic xref:ug.adoc#_ugfun_object-layout_dynamic[`.layout.json`] file (only for properties, collections and actions are supported).
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgant-XmlRootElement.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-XmlRootElement.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-XmlRootElement.adoc
index d5874f1..3169161 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-XmlRootElement.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-XmlRootElement.adoc
@@ -42,7 +42,7 @@ The memento string for view models is converted into a form compatible with use
 xref:rgsvc.adoc#_rgsvc-spi_UrlEncodingService[`UrlEncodingService`], the default implementation of which
 simply encodes to base 64.  If the view model XML graph is too large to be serialized to a string, then an alternative
 implementation (eg which maps XML strings to a GUID, say) can be configured using the technique described in
-xref:rg.adoc#_ug_how-tos_replacing-default-service-implementations[here] in the user guide.
+xref:rg.adoc#_ugfun_how-tos_replacing-default-service-implementations[here] in the user guide.
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgant_aaa_deprecated.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant_aaa_deprecated.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant_aaa_deprecated.adoc
index d90dcae..b40bdeb 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant_aaa_deprecated.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant_aaa_deprecated.adoc
@@ -19,7 +19,7 @@ The annotations listed in the table below are still supported by Apache Isis, bu
 |Purpose
 |Use instead
 |Layer
-|xref:ug.adoc#_ug_object-layout_dynamic[Dynamic layout]?
+|xref:ug.adoc#_ugfun_object-layout_dynamic[Dynamic layout]?
 
 |`@ActionOrder`
 |Order of buttons and menu items representing actions.

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgant_aaa_jee.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant_aaa_jee.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant_aaa_jee.adoc
index 3e7f6ab..a68682c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant_aaa_jee.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant_aaa_jee.adoc
@@ -16,7 +16,7 @@ The table below lists the JEE annotations currently recognized.  Expect to see m
 |Annotation
 |Purpose
 |Layer
-|xref:ug.adoc#_ug_object-layout_dynamic[Dynamic layout]?
+|xref:ug.adoc#_ugfun_object-layout_dynamic[Dynamic layout]?
 
 |xref:rgant.adoc#_rgant-Digits[`@javax.validation.` +
 `constraints.` +

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgant_aaa_main.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant_aaa_main.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant_aaa_main.adoc
index 6dd8bfb..42a19f5 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant_aaa_main.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant_aaa_main.adoc
@@ -11,7 +11,7 @@ For each of these domain types and members there are two annotations.  One cover
 
 [TIP]
 ====
-Most UI semantics can also be specified using xref:ug.adoc#_ug_object-layout_dynamic[dynamic object layout].
+Most UI semantics can also be specified using xref:ug.adoc#_ugfun_object-layout_dynamic[dynamic object layout].
 ====
 
 
@@ -24,7 +24,7 @@ The table below summarizes these most commonly used annotations in Apache Isis.
 |Annotation
 |Purpose
 |Layer
-|xref:ug.adoc#_ug_object-layout_dynamic[Dynamic layout]?
+|xref:ug.adoc#_ugfun_object-layout_dynamic[Dynamic layout]?
 
 |xref:rgant.adoc#_rgant-Action[`@Action`]
 |Domain semantics for actions

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgant_aaa_other.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant_aaa_other.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant_aaa_other.adoc
index 6ce4bc5..824d77b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant_aaa_other.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant_aaa_other.adoc
@@ -13,7 +13,7 @@ These annotations are also commonly used, but relate _not_ to objects or object
 |Annotation
 |Purpose
 |Layer
-|xref:ug.adoc#_ug_object-layout_dynamic[Dynamic layout]?
+|xref:ug.adoc#_ugfun_object-layout_dynamic[Dynamic layout]?
 
 |xref:rgant.adoc#_rgant-Facets[`@Facets`]
 |Install arbitrary facets within the Apache Isis metamodel.

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-core.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-core.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-core.adoc
index 4462047..224be40 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-core.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-core.adoc
@@ -55,14 +55,14 @@ Only intended for "emergency use" as a workaround while pending fix/patch to Apa
 |regex:css1, regex2:css2,...
 |Comma separated list of key:value pairs, where the key is a regex matching action names (eg `delete.*`) and the value is a link:http://getbootstrap.com/css/[Bootstrap] CSS button class (eg `btn-warning) to be applied (as per `@CssClass()`) to all action members matching the regex. +
 
-See xref:ug.adoc#_ug_how-tos_ui-hints_action-icons-and-css[UI hints] for more details.
+See xref:ug.adoc#_ugfun_how-tos_ui-hints_action-icons-and-css[UI hints] for more details.
 
 |`isis.reflector.facet.` +
 `cssClassFa.patterns`
 |regex:fa-icon,regex2:fa-icon2,...
 |Comma separated list of key:value pairs, where the key is a regex matching action names (eg `create.*`) and the value is a link:http://fortawesome.github.io/Font-Awesome/icons/[font-awesome] icon name (eg `fa-plus`) to be applied (as per `@CssClassFa()`) to all action members matching the regex. +
 
-See xref:ug.adoc#_ug_how-tos_ui-hints_action-icons-and-css[UI hints] for more details.
+See xref:ug.adoc#_ugfun_how-tos_ui-hints_action-icons-and-css[UI hints] for more details.
 
 |`isis.reflector.facet.` +
 `domainObjectAnnotation.` +
@@ -189,7 +189,7 @@ See xref:ugbtb.adoc#_ugbtb_programming-model_finetuning[finetuning the programmi
 |`isis.reflector.` +
 `layoutMetadataReaders`
 |`FQCN`,`FQCN2`,...
-|Fully qualified class names of classes to be instantiated to read layout metadata, as used in for xref:ug.adoc#_ug_object-layout_dynamic[dynamic layout]s. +
+|Fully qualified class names of classes to be instantiated to read layout metadata, as used in for xref:ug.adoc#_ugfun_object-layout_dynamic[dynamic layout]s. +
 
 See xref:ugbtb.adoc#_ugbtb_programming-model_layout-metadata-reader[Layout Metadata Reader] for more information.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_disabling-persistence-by-reachability.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_disabling-persistence-by-reachability.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_disabling-persistence-by-reachability.adoc
index afc22c0..fa994ce 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_disabling-persistence-by-reachability.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_disabling-persistence-by-reachability.adoc
@@ -23,7 +23,7 @@ We therefore recommend that you disable persistence-by-reachability by adding th
 isis.persistor.datanucleus.impl.datanucleus.persistenceByReachabilityAtCommit=false
 ----
 
-This change has been made to the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype]
+This change has been made to the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]
 
 If you do disable this feature, then you will (of course) need to ensure that you explicitly persist all entities using the `DomainObjectContainer#persist(.)` or `DomainObjectContainer#persistIfNotAlready(.)` methods.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgcfg_specifying-components.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_specifying-components.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_specifying-components.adoc
index a984e9f..ad20bb1 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_specifying-components.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_specifying-components.adoc
@@ -27,7 +27,7 @@ To specify the `AppManifest` as a configuration property, use:
 |`FQCN`
 |`o.a.i.applib.AppManifest` +
 
-By convention this implementation resides in an `myapp-app` Maven module (as opposed to `myapp-dom` or `myapp-fixture`).  See the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype] for details.
+By convention this implementation resides in an `myapp-app` Maven module (as opposed to `myapp-dom` or `myapp-fixture`).  See the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] for details.
 
 |===
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes.adoc
index 72964eb..071d8b6 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-This chapter describes the usage of various classes and interfaces that are not otherwise associated with xref:rgsvc.adoc#_rgsvc-api[domain] xref:rgsvc.adoc#_rgsvc-spi[services], xref:ug.adoc#_ug_object-layout[object layout] or xref:rgcfg.adoc#_rgcfg[configuration].
+This chapter describes the usage of various classes and interfaces that are not otherwise associated with xref:rgsvc.adoc#_rgsvc-api[domain] xref:rgsvc.adoc#_rgsvc-spi[services], xref:ug.adoc#_ugfun_object-layout[object layout] or xref:rgcfg.adoc#_rgcfg[configuration].
 
 
 include::_rgcms_classes_AppManifest-bootstrapping.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_AppManifest-bootstrapping.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_AppManifest-bootstrapping.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_AppManifest-bootstrapping.adoc
index 25fd561..19a4e4f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_AppManifest-bootstrapping.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_AppManifest-bootstrapping.adoc
@@ -183,7 +183,7 @@ What then remains is to update the bootstrapping code itself.
 
 Bootstrapping integration tests is still performed using the `IsisSystemForTest.Builder`, but very often the bootstrapping code can be substantially simplified (compared to not using an `AppManifest`, that is).
 
-For example, this is the bootstrapping code for the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype] looks something like:
+For example, this is the bootstrapping code for the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] looks something like:
 
 [source,java]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_choices.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_choices.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_choices.adoc
index e20a470..eefc9ba 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_choices.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_choices.adoc
@@ -60,7 +60,7 @@ image::{_imagesdir}reference-methods/prefixes/choices/dependent.png[width="800px
 
 
 
-This functionality is actually implemented as a xref:ug.adoc#_ug_how-tos_contributed-members[contributed action], so the code for this is:
+This functionality is actually implemented as a xref:ug.adoc#_ugfun_how-tos_contributed-members[contributed action], so the code for this is:
 
 [source,java]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_default.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_default.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_default.adoc
index 36b18de..037538a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_default.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_default.adoc
@@ -58,7 +58,7 @@ public class ShoppingCartItem {
 
 
 
-Defaults are also supported (of course) for xref:ug.adoc#_ug_how-tos_contributed-members[contributed actions].  For example, here is a contributed action for updating category/subcategory of the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp]:
+Defaults are also supported (of course) for xref:ug.adoc#_ugfun_how-tos_contributed-members[contributed actions].  For example, here is a contributed action for updating category/subcategory of the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp]:
 
 [source,java]
 ----


[15/52] [abbrv] isis git commit: ISIS-1243: removing manpage from .adoc file names.

Posted by mg...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_FixtureScript.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_FixtureScript.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_FixtureScript.adoc
new file mode 100644
index 0000000..ca653ec
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_FixtureScript.adoc
@@ -0,0 +1,21 @@
+[[_rgcms_classes_super_FixtureScript]]
+= `FixtureScript`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+The `FixtureScript` class is an abstract class defining an API to set up data within the object store, either for integration tests or while demoing/prototyping.
+
+The primary method that subclasses must implement is:
+
+[source,java]
+----
+protected abstract void execute(final ExecutionContext executionContext);
+----
+
+In this method the fixture script can in theory do anything, but in practice it is recommended that it uses injected
+domain services to set up data.  The provided `ExecutionContext` is used to invoke child fixture scripts, and alsocan be used to store references to any created objects (so that the calling test can access these objects/so that they are rendered in the view model).
+
+See the see the xref:ugtst.adoc#_ugtst_fixture-scripts[user guide's testing chapter] for further discussion on the use of fixture scripts, in particular xref:ugtst.adoc#_ugtst_fixture-scripts_api-and-usage[fixture scripts' API and usage].
+

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_FixtureScripts.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_FixtureScripts.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_FixtureScripts.adoc
new file mode 100644
index 0000000..2f1cb42
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_FixtureScripts.adoc
@@ -0,0 +1,12 @@
+[[_rgcms_classes_super_FixtureScripts]]
+= `FixtureScripts`
+: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 abstract class is intended to allow a domain service that can execute xref:rgcms.adoc#_rgcms_classes_super_FixtureScript[`FixtureScript`]s to be easily written.
+
+However, it has now been deprecated; instead we recommend that the xref:rgsvc.adoc#_rgsvc-spi_FixtureScriptsSpecificationProvider[`FixtureScriptsSpecificationProvider`] service is
+implemented instead.  The framework will then automatically use xref:rgsvc.adoc#_rgsvc-api_FixtureScriptsDefault[`FixtureScriptsDefault`] as a fallback implementation of this class.
+
+See the see the xref:ugtst.adoc#_ugtst_fixture-scripts[user guide's testing chapter] for further discussion on the use of fixture scripts, in particular xref:ugtst.adoc#_ugtst_fixture-scripts_api-and-usage[fixture scripts' API and usage].

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractContainedObject.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractContainedObject.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractContainedObject.adoc
deleted file mode 100644
index df8aaf9..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractContainedObject.adoc
+++ /dev/null
@@ -1,32 +0,0 @@
-[[_rgcms_classes_super_manpage-AbstractContainedObject]]
-= `AbstractContainedObject`
-: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 class is a convenience superclass for domain objects and services, providing general purpose methods for interacting with the framework.  These include:
-
-* `allMatches(Query)` - search for all objects matching the specified `Query`. +
-+
-+ Note that this, and other similar methods (eg `firstMatch(...)`, `uniqueMatch(...)`) will automatically flush the
-current transactoin.
-
-* `newTransientInstance(Class)` - to create a new instance of an object, with any services injected into it
-
-* `persistIfNotAlready(Object)` - to persist an object +
-+
-In fact, the object is queued up to be persisted, and is only actually persisted either when the transaction commits, or
-when the transaction is flushed (typically when a query is performed).
-
-* `warnUser(String)` - generate a warning to the user
-
-* `getContainer()` - which returns the `DomainObjectContainer`
-
-Each of these methods simply delegates to an equivalent method in xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer[`DomainObjectContainer`].
-
-[TIP]
-====
-In practice we find that there's little to gain from subclassing; it's easier/less obscure to simply inject xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer[`DomainObjectContainer`] into a simple pojo class.
-====
-

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractDomainObject.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractDomainObject.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractDomainObject.adoc
deleted file mode 100644
index 064b3ed..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractDomainObject.adoc
+++ /dev/null
@@ -1,14 +0,0 @@
-[[_rgcms_classes_super_manpage-AbstractDomainObject]]
-= `AbstractDomainObject`
-: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 class extends xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractContainedObject[`AbstractContainedObject`], adding
-in convenience methods for managing the persistence lifecycle of the object instance.
-
-Each of these methods, eg `isPersistent(...)`, delegates to an equivalent method in
-xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer[`DomainObjectContainer`].
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractFactoryAndRepository.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractFactoryAndRepository.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractFactoryAndRepository.adoc
deleted file mode 100644
index 3403756..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractFactoryAndRepository.adoc
+++ /dev/null
@@ -1,15 +0,0 @@
-[[_rgcms_classes_super_manpage-AbstractFactoryAndRepository]]
-= `AbstractFactoryAndRepository`
-: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 class extends xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractContainedObject[`AbstractContainedObject`].  Its
-intent was to be a convenience subclass for services acting as either a repository or a factory, however note that
- all of the methods that it defines are now deprecated.
-
-Instead, indicate that a service is repository using the xref:rgant.adoc#_rgant-DomainService_repositoryFor[`@DomainService#repositoryFor()`] attribute.
-
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractService.adoc
deleted file mode 100644
index fa9207a..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractService.adoc
+++ /dev/null
@@ -1,10 +0,0 @@
-[[_rgcms_classes_super_manpage-AbstractService]]
-= `AbstractService`
-: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 class extends xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractContainedObject[`AbstractContainedObject`], adding
-in an implementation of `getId()` based upon the classes name.
-
-In practice there is little to gain from subclassing; simply inject xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer[`DomainObjectContainer`] for broadly equivalent functionality.

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractSubscriber.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractSubscriber.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractSubscriber.adoc
deleted file mode 100644
index 4a715e4..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractSubscriber.adoc
+++ /dev/null
@@ -1,18 +0,0 @@
-[[_rgcms_classes_super_manpage-AbstractSubscriber]]
-= `AbstractSubscriber`
-: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 convenience superclass for creating subscriber domain services on the xref:rgsvc.adoc#_rgsvc-api_EventBusService[`EventBusService`].  It uses xref:rgant.adoc#_rgant-PostConstruct[`@PostConstruct`] and
-xref:rgant.adoc#_rgant-PreDestroy[`@PreDestroy`] callbacks to automatically register/unregister itself
-with the `EventBusService`.
-
-It's important that subscribers register before any domain services that might emit events on the
-xref:rgsvc.adoc#_rgsvc-api_EventBusService[`EventBusService`].  For example, the (non-ASF) http://github.com/isisaddons/isis-module-security[Isis addons' security] module provides a domain service that automatically
-seeds certain domain entities; these will generate xref:rgcms.adoc#_rgcms_classes_lifecycleevent[lifecycle events] and so
-any subscribers must be registered before such seed services.  The easiest way to do this is to use the
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] attribute.
-
-As a convenience, (as of `1.11.0-SNAPSHOT`) the `AbstractSubscriber` specifies this attribute.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractViewModel.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractViewModel.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractViewModel.adoc
deleted file mode 100644
index b77460d..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractViewModel.adoc
+++ /dev/null
@@ -1,15 +0,0 @@
-[[_rgcms_classes_super_manpage-AbstractViewModel]]
-= `AbstractViewModel`
-: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 class extends xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractContainedObject[`AbstractContainedObject`], also
-implementing the xref:rgcms.adoc#_rgcms_classes_super_manpage-ViewModel[`ViewModel`] interface.  In and of itself it provides no new behaviour.
-
-[TIP]
-====
-As an alternative, consider simply annotating the view model class with {@link org.apache.isis.applib.annotation.ViewModel}.
-====
-

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-FixtureScript.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-FixtureScript.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-FixtureScript.adoc
deleted file mode 100644
index d4cf98a..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-FixtureScript.adoc
+++ /dev/null
@@ -1,21 +0,0 @@
-[[_rgcms_classes_super_manpage-FixtureScript]]
-= `FixtureScript`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-The `FixtureScript` class is an abstract class defining an API to set up data within the object store, either for integration tests or while demoing/prototyping.
-
-The primary method that subclasses must implement is:
-
-[source,java]
-----
-protected abstract void execute(final ExecutionContext executionContext);
-----
-
-In this method the fixture script can in theory do anything, but in practice it is recommended that it uses injected
-domain services to set up data.  The provided `ExecutionContext` is used to invoke child fixture scripts, and alsocan be used to store references to any created objects (so that the calling test can access these objects/so that they are rendered in the view model).
-
-See the see the xref:ugtst.adoc#_ugtst_fixture-scripts[user guide's testing chapter] for further discussion on the use of fixture scripts, in particular xref:ugtst.adoc#_ugtst_fixture-scripts_api-and-usage[fixture scripts' API and usage].
-

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-FixtureScripts.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-FixtureScripts.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-FixtureScripts.adoc
deleted file mode 100644
index a562aea..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-FixtureScripts.adoc
+++ /dev/null
@@ -1,12 +0,0 @@
-[[_rgcms_classes_super_manpage-FixtureScripts]]
-= `FixtureScripts`
-: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 abstract class is intended to allow a domain service that can execute xref:rgcms.adoc#_rgcms_classes_super_manpage-FixtureScript[`FixtureScript`]s to be easily written.
-
-However, it has now been deprecated; instead we recommend that the xref:rgsvc.adoc#_rgsvc-spi_FixtureScriptsSpecificationProvider[`FixtureScriptsSpecificationProvider`] service is
-implemented instead.  The framework will then automatically use xref:rgsvc.adoc#_rgsvc-api_FixtureScriptsDefault[`FixtureScriptsDefault`] as a fallback implementation of this class.
-
-See the see the xref:ugtst.adoc#_ugtst_fixture-scripts[user guide's testing chapter] for further discussion on the use of fixture scripts, in particular xref:ugtst.adoc#_ugtst_fixture-scripts_api-and-usage[fixture scripts' API and usage].

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_uievent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_uievent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_uievent.adoc
index 91ade0f..ddc6016 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_uievent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_uievent.adoc
@@ -23,32 +23,32 @@ Impl'n (g: a:)
 |Notes
 
 
-|xref:rgcms.adoc#_rgcms_classes_uievent_manpage-TitleUiEvent[`o.a.i.applib.` +
+|xref:rgcms.adoc#_rgcms_classes_uievent_TitleUiEvent[`o.a.i.applib.` +
 `TitleUiEvent`]
 |``o.a.i.core`` +
 ``services.eventbus`` +
 ``isis-core-applib``
 |(abstract class). +
 `TitleUiEvent.Default` is the concrete implementation used if no `@DomainObjectLayout#titleUiEvent` attribute is specified
-|Broadcast whenever there is a requirement to obtain a title for a domain object.  Note that if the domain object defines its own xref:rgcms.adoc#_rgcms_methods_reserved_manpage-title[`title()`] supporting method, or has xref:rgant.adoc#_rgant-Title[`@Title`] annotation(s) on its properties, then these will take precedence.
+|Broadcast whenever there is a requirement to obtain a title for a domain object.  Note that if the domain object defines its own xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`] supporting method, or has xref:rgant.adoc#_rgant-Title[`@Title`] annotation(s) on its properties, then these will take precedence.
 
-|xref:rgcms.adoc#_rgcms_classes_uievent_manpage-IconUiEvent[`o.a.i.applib.` +
+|xref:rgcms.adoc#_rgcms_classes_uievent_IconUiEvent[`o.a.i.applib.` +
 `IconUiEvent`]
 |``o.a.i.core`` +
 ``services.eventbus`` +
 ``isis-core-applib``
 |(abstract class). +
 `IconUiEvent.Default` is the concrete implementation used if no `@DomainObjectLayout#iconUiEvent` attribute is specified
-|Broadcast whenever there is a requirement to obtain an icon (or rather, the name of an icon) for a domain object.  Note that if the domain object defines its own xref:rgcms.adoc#_rgcms_methods_reserved_manpage-iconName[`iconName()`] supporting method, or if it has the xref:rgant.adoc#_rgant-DomainObjectLayout#cssClassFa[`@DomainObjectLayout#cssClassFa()`] attribute, then these will take precedence.
+|Broadcast whenever there is a requirement to obtain an icon (or rather, the name of an icon) for a domain object.  Note that if the domain object defines its own xref:rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`] supporting method, or if it has the xref:rgant.adoc#_rgant-DomainObjectLayout#cssClassFa[`@DomainObjectLayout#cssClassFa()`] attribute, then these will take precedence.
 
-|xref:rgcms.adoc#_rgcms_classes_uievent_manpage-CssClassUiEvent[`o.a.i.applib.` +
+|xref:rgcms.adoc#_rgcms_classes_uievent_CssClassUiEvent[`o.a.i.applib.` +
 `CssClassUiEvent`]
 |``o.a.i.core`` +
 ``services.eventbus`` +
 ``isis-core-applib``
 |(abstract class). +
 `CssClassUiEvent.Default` is the concrete implementation used if no `@DomainObjectLayout#cssClassUiEvent` attribute is specified
-|Broadcast whenever there is a requirement to obtain a CSS class hint for a domain object.  Note that if the domain object defines its own xref:rgcms.adoc#_rgcms_methods_reserved_manpage-cssClass[`cssClass()`] supporting method then this
+|Broadcast whenever there is a requirement to obtain a CSS class hint for a domain object.  Note that if the domain object defines its own xref:rgcms.adoc#_rgcms_methods_reserved_cssClass[`cssClass()`] supporting method then this
 will take precedence.
 
 |===
@@ -56,7 +56,7 @@ will take precedence.
 
 
 
-include::_rgcms_classes_uievent_manpage-TitleUiEvent.adoc[leveloffset=+1]
-include::_rgcms_classes_uievent_manpage-IconUiEvent.adoc[leveloffset=+1]
-include::_rgcms_classes_uievent_manpage-CssClassUiEvent.adoc[leveloffset=+1]
+include::_rgcms_classes_uievent_TitleUiEvent.adoc[leveloffset=+1]
+include::_rgcms_classes_uievent_IconUiEvent.adoc[leveloffset=+1]
+include::_rgcms_classes_uievent_CssClassUiEvent.adoc[leveloffset=+1]
 

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_uievent_CssClassUiEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_uievent_CssClassUiEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_uievent_CssClassUiEvent.adoc
new file mode 100644
index 0000000..d40c85d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_uievent_CssClassUiEvent.adoc
@@ -0,0 +1,22 @@
+[[_rgcms_classes_uievent_CssClassUiEvent]]
+= `CssClassUiEvent`  (`1.11.0-SNAPSHOT`)
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+This event class represents a request to obtain the a CSS class hint of a domain object.  The class has a number of
+responsibilities:
+
+* capture the target object being interacted with
+
+* capture the CSS class, if any, as specified to one of the subscribers
+
+The class itself is instantiated automatically by the framework whenever interacting with a rendered object's action.
+
+
+[NOTE]
+====
+if the domain object defines its own xref:rgcms.adoc#_rgcms_methods_reserved_cssClass[`cssClass()`] supporting
+method then this will take precedence.
+====

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_uievent_IconUiEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_uievent_IconUiEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_uievent_IconUiEvent.adoc
new file mode 100644
index 0000000..e577401
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_uievent_IconUiEvent.adoc
@@ -0,0 +1,23 @@
+[[_rgcms_classes_uievent_IconUiEvent]]
+= `TitleUiEvent` (`1.11.0-SNAPSHOT`)
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+This event class represents a request to obtain the icon (or rather, name of icon) of a domain object.  The class has a number of responsibilities:
+
+* capture the target object being interacted with
+
+* capture the icon (name), if any, as specified to one of the subscribers
+
+The class itself is instantiated automatically by the framework whenever interacting with a rendered object's action.
+
+
+[NOTE]
+====
+If the domain object defines its own xref:rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`] supporting method,
+or if it has the
+xref:rgant.adoc#_rgant-DomainObjectLayout#cssClassFa[`@DomainObjectLayout#cssClassFa()`] attribute, then
+these will take precedence.
+====

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_uievent_TitleUiEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_uievent_TitleUiEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_uievent_TitleUiEvent.adoc
new file mode 100644
index 0000000..ec4a5e4
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_uievent_TitleUiEvent.adoc
@@ -0,0 +1,22 @@
+[[_rgcms_classes_uievent_TitleUiEvent]]
+= `TitleUiEvent`  (`1.11.0-SNAPSHOT`)
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+This event class represents a request to obtain the title of a domain object.  The class has a number of responsibilities:
+
+* capture the target object being interacted with
+
+* capture the title, if any, as specified to one of the subscribers
+
+The class itself is instantiated automatically by the framework whenever interacting with a rendered object's action.
+
+
+[NOTE]
+====
+If the domain object defines its own xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`] supporting method, or
+has xref:rgant.adoc#_rgant-Title[`@Title`] annotation(s) on its properties, then these will take
+precedence.
+====

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_uievent_manpage-CssClassUiEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_uievent_manpage-CssClassUiEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_uievent_manpage-CssClassUiEvent.adoc
deleted file mode 100644
index 30b8f5b..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_uievent_manpage-CssClassUiEvent.adoc
+++ /dev/null
@@ -1,22 +0,0 @@
-[[_rgcms_classes_uievent_manpage-CssClassUiEvent]]
-= `CssClassUiEvent`  (`1.11.0-SNAPSHOT`)
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-This event class represents a request to obtain the a CSS class hint of a domain object.  The class has a number of
-responsibilities:
-
-* capture the target object being interacted with
-
-* capture the CSS class, if any, as specified to one of the subscribers
-
-The class itself is instantiated automatically by the framework whenever interacting with a rendered object's action.
-
-
-[NOTE]
-====
-if the domain object defines its own xref:rgcms.adoc#_rgcms_methods_reserved_manpage-cssClass[`cssClass()`] supporting
-method then this will take precedence.
-====

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_uievent_manpage-IconUiEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_uievent_manpage-IconUiEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_uievent_manpage-IconUiEvent.adoc
deleted file mode 100644
index 20fdbbc..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_uievent_manpage-IconUiEvent.adoc
+++ /dev/null
@@ -1,23 +0,0 @@
-[[_rgcms_classes_uievent_manpage-IconUiEvent]]
-= `TitleUiEvent` (`1.11.0-SNAPSHOT`)
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-This event class represents a request to obtain the icon (or rather, name of icon) of a domain object.  The class has a number of responsibilities:
-
-* capture the target object being interacted with
-
-* capture the icon (name), if any, as specified to one of the subscribers
-
-The class itself is instantiated automatically by the framework whenever interacting with a rendered object's action.
-
-
-[NOTE]
-====
-If the domain object defines its own xref:rgcms.adoc#_rgcms_methods_reserved_manpage-iconName[`iconName()`] supporting method,
-or if it has the
-xref:rgant.adoc#_rgant-DomainObjectLayout#cssClassFa[`@DomainObjectLayout#cssClassFa()`] attribute, then
-these will take precedence.
-====

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_uievent_manpage-TitleUiEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_uievent_manpage-TitleUiEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_uievent_manpage-TitleUiEvent.adoc
deleted file mode 100644
index 8b76b05..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_uievent_manpage-TitleUiEvent.adoc
+++ /dev/null
@@ -1,22 +0,0 @@
-[[_rgcms_classes_uievent_manpage-TitleUiEvent]]
-= `TitleUiEvent`  (`1.11.0-SNAPSHOT`)
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-This event class represents a request to obtain the title of a domain object.  The class has a number of responsibilities:
-
-* capture the target object being interacted with
-
-* capture the title, if any, as specified to one of the subscribers
-
-The class itself is instantiated automatically by the framework whenever interacting with a rendered object's action.
-
-
-[NOTE]
-====
-If the domain object defines its own xref:rgcms.adoc#_rgcms_methods_reserved_manpage-title[`title()`] supporting method, or
-has xref:rgant.adoc#_rgant-Title[`@Title`] annotation(s) on its properties, then these will take
-precedence.
-====

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility.adoc
index fd35ffc..440409b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility.adoc
@@ -8,9 +8,9 @@ The `org.apache.isis.applib.util` package has a number of simple utility
 classes designed to simplify the coding of some common tasks.
 
 
-include::_rgcms_classes_utility_manpage-Enums.adoc[leveloffset=+1]
-include::_rgcms_classes_utility_manpage-ObjectContracts.adoc[leveloffset=+1]
-include::_rgcms_classes_utility_manpage-Reasons.adoc[leveloffset=+1]
-include::_rgcms_classes_utility_manpage-TitleBuffer.adoc[leveloffset=+1]
+include::_rgcms_classes_utility_Enums.adoc[leveloffset=+1]
+include::_rgcms_classes_utility_ObjectContracts.adoc[leveloffset=+1]
+include::_rgcms_classes_utility_Reasons.adoc[leveloffset=+1]
+include::_rgcms_classes_utility_TitleBuffer.adoc[leveloffset=+1]
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_Enums.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_Enums.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_Enums.adoc
new file mode 100644
index 0000000..fa688ae
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_Enums.adoc
@@ -0,0 +1,8 @@
+[[_rgcms_classes_utility_Enums]]
+= `Enums`
+: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/
+
+
+NOTE: TODO

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_ObjectContracts.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_ObjectContracts.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_ObjectContracts.adoc
new file mode 100644
index 0000000..beac5e2
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_ObjectContracts.adoc
@@ -0,0 +1,107 @@
+[[_rgcms_classes_utility_ObjectContracts]]
+= `ObjectContracts`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+The `ObjectContracts` test provides a series of methods to make it easy for your domain objects to:
+
+* implement `Comparable` (eg so can be stored in ``java.util.SortedSet``s)
+* implement `toString()`
+* implement `equals()`
+* implement `hashCode()`
+
+For example:
+
+[source,java]
+----
+public class ToDoItem implements Comparable<ToDoItem> {
+
+    public boolean isComplete() { ... }
+    public LocalDate getDueBy() { ... }
+    public String getDescription() { ... }
+    public String getOwnedBy() { ... }
+
+    public int compareTo(final ToDoItem other) {
+        return ObjectContracts.compare(this, other, "complete","dueBy","description");
+    }
+
+    public String toString() {
+        return ObjectContracts.toString(this, "description","complete","dueBy","ownedBy");
+    }
+}
+----
+
+[WARNING]
+====
+Note that `ObjectContracts` makes heavy use of Java Reflection.  While it's great to get going quickly in prototyping, we recommend you use your IDE to code generate implementations of these methods for production code.
+
+Moreover (and perhaps even more importantly) `ObjectContracts` implementation can cause DataNucleus to recursively rehydrate a larger number of associated entities (More detail below).
+
+We therefore recommend that you disable persistence-by-reachability by adding:
+
+[source,ini]
+.persistor_datanucleus.properties
+----
+isis.persistor.datanucleus.impl.datanucleus.persistenceByReachabilityAtCommit=false
+----
+
+====
+
+== The issue in more detail
+
+Consider the link:http://yuml.me/edit/742ad446[entities]:
+
+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.
+
+All these entities implement `Comparable` using `ObjectContracts`, so that the implementation of ``AgreementRole``'s (simplified) is:
+
+[source,java]
+----
+public class AgreementRole {
+    ...
+    public int compareTo(AgreementRole other) {
+        return ObjectContracts.compareTo(this, other, "agreement","startDate","party");
+    }
+    ...
+}
+----
+
+while ``Agreement``'s is implemented as:
+
+[source,java]
+----
+    public class Agreement {
+        ...
+        public int compareTo(Agreement other) {
+            return ObjectContracts.compareTo(this, other, "reference");
+        }
+        ...
+    }
+----
+
+and ``Party``'s is similarly implemented as:
+
+[source,java]
+----
+public class Party {
+    ...
+    public int compareTo(Party other) {
+        return ObjectContracts.compareTo(this, other, "reference");
+    }
+    ...
+}
+----
+
+DataNucleus's persistence-by-reachability algorithm adds the ``AgreementRole``s into a `SortedSet`, which causes `AgreementRole#compareTo()` to fire:
+
+* the evaluation of the "agreement" property delegates back to the `Agreement`, whose own `Agreement#compareTo()` uses the scalar `reference` property.  As the `Agreement` is already in-memory, this does not trigger any further database queries
+
+* the evaluation of the "startDate" property is just a scalar property of the `AgreementRole`, so will already in-memory
+
+* the evaluation of the "party" property delegates back to the `Party`, whose own `Party#compareTo()` requires the uses the scalar `reference` property.  However, since the `Party` is not yet in-memory, using the `reference` property triggers a database query to "rehydrate" the `Party` instance.
+
+In other words, figuring out whether `AgreementRole` is comparable requires the persistence-by-reachability algorithm to run, causing the adjacent associated entity `Party` to also be retrieved.

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_Reasons.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_Reasons.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_Reasons.adoc
new file mode 100644
index 0000000..71a7e0c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_Reasons.adoc
@@ -0,0 +1,31 @@
+[[_rgcms_classes_utility_Reasons]]
+= `Reasons`
+: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/
+
+
+
+There are two different classes provided to help build reasons returned
+by `disableXxX()` and `validateXxx()` methods:
+
+* the `org.apache.isis.applib.util.ReasonBuffer` helper class
+* the `org.apache.isis.applib.util.Reasons` helper class
+
+For example:
+
+[source,java]
+----
+public class Customer {
+    ...
+    public String validatePlaceOrder(Product p, int quantity) {
+        return Reasons.coalesce(
+            whetherCustomerBlacklisted(this),
+            whetherProductOutOfStock(p)
+        );
+    }
+}
+----
+
+Which you use (if any) is up to you.
+

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_TitleBuffer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_TitleBuffer.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_TitleBuffer.adoc
new file mode 100644
index 0000000..ec5ad0e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_TitleBuffer.adoc
@@ -0,0 +1,13 @@
+[[_rgcms_classes_utility_TitleBuffer]]
+= `TitleBuffer`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+The `TitleBuffer` utility class is intended to make it easy to construct title strings (returned from the xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`] method).
+
+For example, it has overloaded versions of methods called `append()` and `concat()`.
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_manpage-Enums.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_manpage-Enums.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_manpage-Enums.adoc
deleted file mode 100644
index 064b423..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_manpage-Enums.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-[[_rgcms_classes_utility_manpage-Enums]]
-= `Enums`
-: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/
-
-
-NOTE: TODO

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_manpage-ObjectContracts.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_manpage-ObjectContracts.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_manpage-ObjectContracts.adoc
deleted file mode 100644
index 41723cb..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_manpage-ObjectContracts.adoc
+++ /dev/null
@@ -1,107 +0,0 @@
-[[_rgcms_classes_utility_manpage-ObjectContracts]]
-= `ObjectContracts`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-The `ObjectContracts` test provides a series of methods to make it easy for your domain objects to:
-
-* implement `Comparable` (eg so can be stored in ``java.util.SortedSet``s)
-* implement `toString()`
-* implement `equals()`
-* implement `hashCode()`
-
-For example:
-
-[source,java]
-----
-public class ToDoItem implements Comparable<ToDoItem> {
-
-    public boolean isComplete() { ... }
-    public LocalDate getDueBy() { ... }
-    public String getDescription() { ... }
-    public String getOwnedBy() { ... }
-
-    public int compareTo(final ToDoItem other) {
-        return ObjectContracts.compare(this, other, "complete","dueBy","description");
-    }
-
-    public String toString() {
-        return ObjectContracts.toString(this, "description","complete","dueBy","ownedBy");
-    }
-}
-----
-
-[WARNING]
-====
-Note that `ObjectContracts` makes heavy use of Java Reflection.  While it's great to get going quickly in prototyping, we recommend you use your IDE to code generate implementations of these methods for production code.
-
-Moreover (and perhaps even more importantly) `ObjectContracts` implementation can cause DataNucleus to recursively rehydrate a larger number of associated entities (More detail below).
-
-We therefore recommend that you disable persistence-by-reachability by adding:
-
-[source,ini]
-.persistor_datanucleus.properties
-----
-isis.persistor.datanucleus.impl.datanucleus.persistenceByReachabilityAtCommit=false
-----
-
-====
-
-== The issue in more detail
-
-Consider the link:http://yuml.me/edit/742ad446[entities]:
-
-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.
-
-All these entities implement `Comparable` using `ObjectContracts`, so that the implementation of ``AgreementRole``'s (simplified) is:
-
-[source,java]
-----
-public class AgreementRole {
-    ...
-    public int compareTo(AgreementRole other) {
-        return ObjectContracts.compareTo(this, other, "agreement","startDate","party");
-    }
-    ...
-}
-----
-
-while ``Agreement``'s is implemented as:
-
-[source,java]
-----
-    public class Agreement {
-        ...
-        public int compareTo(Agreement other) {
-            return ObjectContracts.compareTo(this, other, "reference");
-        }
-        ...
-    }
-----
-
-and ``Party``'s is similarly implemented as:
-
-[source,java]
-----
-public class Party {
-    ...
-    public int compareTo(Party other) {
-        return ObjectContracts.compareTo(this, other, "reference");
-    }
-    ...
-}
-----
-
-DataNucleus's persistence-by-reachability algorithm adds the ``AgreementRole``s into a `SortedSet`, which causes `AgreementRole#compareTo()` to fire:
-
-* the evaluation of the "agreement" property delegates back to the `Agreement`, whose own `Agreement#compareTo()` uses the scalar `reference` property.  As the `Agreement` is already in-memory, this does not trigger any further database queries
-
-* the evaluation of the "startDate" property is just a scalar property of the `AgreementRole`, so will already in-memory
-
-* the evaluation of the "party" property delegates back to the `Party`, whose own `Party#compareTo()` requires the uses the scalar `reference` property.  However, since the `Party` is not yet in-memory, using the `reference` property triggers a database query to "rehydrate" the `Party` instance.
-
-In other words, figuring out whether `AgreementRole` is comparable requires the persistence-by-reachability algorithm to run, causing the adjacent associated entity `Party` to also be retrieved.

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_manpage-Reasons.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_manpage-Reasons.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_manpage-Reasons.adoc
deleted file mode 100644
index 7711542..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_manpage-Reasons.adoc
+++ /dev/null
@@ -1,31 +0,0 @@
-[[_rgcms_classes_utility_manpage-Reasons]]
-= `Reasons`
-: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/
-
-
-
-There are two different classes provided to help build reasons returned
-by `disableXxX()` and `validateXxx()` methods:
-
-* the `org.apache.isis.applib.util.ReasonBuffer` helper class
-* the `org.apache.isis.applib.util.Reasons` helper class
-
-For example:
-
-[source,java]
-----
-public class Customer {
-    ...
-    public String validatePlaceOrder(Product p, int quantity) {
-        return Reasons.coalesce(
-            whetherCustomerBlacklisted(this),
-            whetherProductOutOfStock(p)
-        );
-    }
-}
-----
-
-Which you use (if any) is up to you.
-

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_manpage-TitleBuffer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_manpage-TitleBuffer.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_manpage-TitleBuffer.adoc
deleted file mode 100644
index 800f1cb..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_manpage-TitleBuffer.adoc
+++ /dev/null
@@ -1,13 +0,0 @@
-[[_rgcms_classes_utility_manpage-TitleBuffer]]
-= `TitleBuffer`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-The `TitleBuffer` utility class is intended to make it easy to construct title strings (returned from the xref:rgcms.adoc#_rgcms_methods_reserved_manpage-title[`title()`] method).
-
-For example, it has overloaded versions of methods called `append()` and `concat()`.
-
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types.adoc
index 3c6e3d8..f73650f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types.adoc
@@ -112,8 +112,8 @@ NOTE: TODO
 
 
 
-include::_rgcms_classes_value-types_manpage-Blob.adoc[leveloffset=+1]
-include::_rgcms_classes_value-types_manpage-Clob.adoc[leveloffset=+1]
-include::_rgcms_classes_value-types_manpage-Color.adoc[leveloffset=+1]
-include::_rgcms_classes_value-types_manpage-Money.adoc[leveloffset=+1]
-include::_rgcms_classes_value-types_manpage-Password.adoc[leveloffset=+1]
+include::_rgcms_classes_value-types_Blob.adoc[leveloffset=+1]
+include::_rgcms_classes_value-types_Clob.adoc[leveloffset=+1]
+include::_rgcms_classes_value-types_Color.adoc[leveloffset=+1]
+include::_rgcms_classes_value-types_Money.adoc[leveloffset=+1]
+include::_rgcms_classes_value-types_Password.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_Blob.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_Blob.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_Blob.adoc
new file mode 100644
index 0000000..1bccd43
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_Blob.adoc
@@ -0,0 +1,8 @@
+[[_rgcms_classes_value-types_Blob]]
+= `Blob`
+: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/
+
+
+NOTE: TODO - the `org.apache.isis.applib.value.Blob` class.

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_Clob.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_Clob.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_Clob.adoc
new file mode 100644
index 0000000..f992787
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_Clob.adoc
@@ -0,0 +1,8 @@
+[[_rgcms_classes_value-types_Clob]]
+= `Clob`
+: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/
+
+
+NOTE: TODO - the `org.apache.isis.applib.value.Clob` class.

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_Color.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_Color.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_Color.adoc
new file mode 100644
index 0000000..e04cc6e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_Color.adoc
@@ -0,0 +1,8 @@
+[[_rgcms_classes_value-types_Color]]
+= `Color`
+: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/
+
+
+NOTE: TODO - the `org.apache.isis.applib.value.Color` class.

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_Money.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_Money.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_Money.adoc
new file mode 100644
index 0000000..7f8bdf3
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_Money.adoc
@@ -0,0 +1,8 @@
+[[_rgcms_classes_value-types_Money]]
+= `Money`
+: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/
+
+
+NOTE: TODO - the `org.apache.isis.applib.value.Money` class.

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_Password.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_Password.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_Password.adoc
new file mode 100644
index 0000000..f70ebc5
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_Password.adoc
@@ -0,0 +1,8 @@
+[[_rgcms_classes_value-types_Password]]
+= `Password`
+: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/
+
+
+NOTE: TODO

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_manpage-Blob.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_manpage-Blob.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_manpage-Blob.adoc
deleted file mode 100644
index c254bd3..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_manpage-Blob.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-[[_rgcms_classes_value-types_manpage-Blob]]
-= `Blob`
-: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/
-
-
-NOTE: TODO - the `org.apache.isis.applib.value.Blob` class.

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_manpage-Clob.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_manpage-Clob.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_manpage-Clob.adoc
deleted file mode 100644
index ffd405d..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_manpage-Clob.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-[[_rgcms_classes_value-types_manpage-Clob]]
-= `Clob`
-: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/
-
-
-NOTE: TODO - the `org.apache.isis.applib.value.Clob` class.

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_manpage-Color.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_manpage-Color.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_manpage-Color.adoc
deleted file mode 100644
index 7bbb02b..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_manpage-Color.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-[[_rgcms_classes_value-types_manpage-Color]]
-= `Color`
-: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/
-
-
-NOTE: TODO - the `org.apache.isis.applib.value.Color` class.

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_manpage-Money.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_manpage-Money.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_manpage-Money.adoc
deleted file mode 100644
index aaf61cc..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_manpage-Money.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-[[_rgcms_classes_value-types_manpage-Money]]
-= `Money`
-: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/
-
-
-NOTE: TODO - the `org.apache.isis.applib.value.Money` class.

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_manpage-Password.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_manpage-Password.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_manpage-Password.adoc
deleted file mode 100644
index a4c11ec..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_value-types_manpage-Password.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-[[_rgcms_classes_value-types_manpage-Password]]
-= `Password`
-: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/
-
-
-NOTE: TODO

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle.adoc
index c1072b7..89e7a7b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle.adoc
@@ -28,28 +28,28 @@ The lifecycle callback methods supported by Isis are:
 |Method
 |Description
 
-|xref:rgcms.adoc#_rgcms_methods_lifecycle_manpage-created[`created()`]
+|xref:rgcms.adoc#_rgcms_methods_lifecycle_created[`created()`]
 |called when an object has just been created using xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer[`newTransientInstance()`]
 
-|xref:rgcms.adoc#_rgcms_methods_lifecycle_manpage-loaded[`loaded()`]
+|xref:rgcms.adoc#_rgcms_methods_lifecycle_loaded[`loaded()`]
 |called when a (persistent) object has just been loaded from the object store.
 
-|xref:rgcms.adoc#_rgcms_methods_lifecycle_manpage-persisted[`persisted()`]
+|xref:rgcms.adoc#_rgcms_methods_lifecycle_persisted[`persisted()`]
 |called when object has just been persisted from the object store.
 
-|xref:rgcms.adoc#_rgcms_methods_lifecycle_manpage-persisting[`persisting()`]
+|xref:rgcms.adoc#_rgcms_methods_lifecycle_persisting[`persisting()`]
 |called when a (not-yet-persistent) object is just about to be persisted from the object store
 
-|xref:rgcms.adoc#_rgcms_methods_lifecycle_manpage-removed[`removed()`]
+|xref:rgcms.adoc#_rgcms_methods_lifecycle_removed[`removed()`]
 |called when a (persistent) object has just been deleted from the object store
 
-|xref:rgcms.adoc#_rgcms_methods_lifecycle_manpage-removing[`removing()`]
+|xref:rgcms.adoc#_rgcms_methods_lifecycle_removing[`removing()`]
 |called when a (persistent) object is just about to be deleted from the object store
 
-|xref:rgcms.adoc#_rgcms_methods_lifecycle_manpage-updated[`updated()`]
+|xref:rgcms.adoc#_rgcms_methods_lifecycle_updated[`updated()`]
 |called when a (persistent) object has just been updated in the object store
 
-|xref:rgcms.adoc#_rgcms_methods_lifecycle_manpage-updating[`updating()`]
+|xref:rgcms.adoc#_rgcms_methods_lifecycle_updating[`updating()`]
 |called when a (persistent) object is just about to be updated in the object store
 
 |===
@@ -66,10 +66,10 @@ Some lifecycle methods have been deprecated:
 |Notes
 
 |`deleted()`
-|Replaced by xref:rgcms.adoc#_rgcms_methods_lifecycle_manpage-removed[`removed()`]
+|Replaced by xref:rgcms.adoc#_rgcms_methods_lifecycle_removed[`removed()`]
 
 |`deleting()`
-|Replaced by xref:rgcms.adoc#_rgcms_methods_lifecycle_manpage-removing[`removing()`]
+|Replaced by xref:rgcms.adoc#_rgcms_methods_lifecycle_removing[`removing()`]
 
 |`loading()`
 |callback for when the (persistent) object is just about to be loaded from the object store. +
@@ -80,23 +80,23 @@ This method is never called.
 ====
 
 |`saved()`
-|Replaced by xref:rgcms.adoc#_rgcms_methods_lifecycle_manpage-persisted[`persisted()`]
+|Replaced by xref:rgcms.adoc#_rgcms_methods_lifecycle_persisted[`persisted()`]
 
 |`saving()`
-|Replaced by xref:rgcms.adoc#_rgcms_methods_lifecycle_manpage-persisting[`persisting()`]
+|Replaced by xref:rgcms.adoc#_rgcms_methods_lifecycle_persisting[`persisting()`]
 
 |===
 
 
 
 
-include::_rgcms_methods_lifecycle_manpage-created.adoc[leveloffset=+1]
-include::_rgcms_methods_lifecycle_manpage-loaded.adoc[leveloffset=+1]
-include::_rgcms_methods_lifecycle_manpage-persisted.adoc[leveloffset=+1]
-include::_rgcms_methods_lifecycle_manpage-persisting.adoc[leveloffset=+1]
-include::_rgcms_methods_lifecycle_manpage-removed.adoc[leveloffset=+1]
-include::_rgcms_methods_lifecycle_manpage-removing.adoc[leveloffset=+1]
-include::_rgcms_methods_lifecycle_manpage-updated.adoc[leveloffset=+1]
-include::_rgcms_methods_lifecycle_manpage-updating.adoc[leveloffset=+1]
+include::_rgcms_methods_lifecycle_created.adoc[leveloffset=+1]
+include::_rgcms_methods_lifecycle_loaded.adoc[leveloffset=+1]
+include::_rgcms_methods_lifecycle_persisted.adoc[leveloffset=+1]
+include::_rgcms_methods_lifecycle_persisting.adoc[leveloffset=+1]
+include::_rgcms_methods_lifecycle_removed.adoc[leveloffset=+1]
+include::_rgcms_methods_lifecycle_removing.adoc[leveloffset=+1]
+include::_rgcms_methods_lifecycle_updated.adoc[leveloffset=+1]
+include::_rgcms_methods_lifecycle_updating.adoc[leveloffset=+1]
 
 include::_rgcms_methods_lifecycle_jdo-api.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_created.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_created.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_created.adoc
new file mode 100644
index 0000000..ca9e3e4
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_created.adoc
@@ -0,0 +1,17 @@
+[[_rgcms_methods_reserved_created]]
+= `created()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+The `created()` lifecycle callback method is called when an object has just been created using xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer[`newTransientInstance()`]
+
+
+[TIP]
+====
+Alternatively, consider using a xref:rgsvc.adoc#_rgsvc-api_EventBusService[event bus] xref:rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscriber] on the xref:rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectCreatedEvent[`ObjectCreatedEvent`].
+====
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_loaded.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_loaded.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_loaded.adoc
new file mode 100644
index 0000000..41fa351
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_loaded.adoc
@@ -0,0 +1,15 @@
+[[_rgcms_methods_reserved_loaded]]
+= `loaded()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The `loaded()` lifecycle callback method is called when a (persistent) object has just been loaded from the object store.
+
+
+[TIP]
+====
+Alternatively, consider using a xref:rgsvc.adoc#_rgsvc-api_EventBusService[event bus] xref:rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscriber] on the xref:rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectLoadedEvent[`ObjectLoadedEvent`].
+====

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-created.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-created.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-created.adoc
deleted file mode 100644
index 38b62a4..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-created.adoc
+++ /dev/null
@@ -1,17 +0,0 @@
-[[_rgcms_methods_reserved_manpage-created]]
-= `created()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-The `created()` lifecycle callback method is called when an object has just been created using xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer[`newTransientInstance()`]
-
-
-[TIP]
-====
-Alternatively, consider using a xref:rgsvc.adoc#_rgsvc-api_EventBusService[event bus] xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractSubscriber[subscriber] on the xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-ObjectCreatedEvent[`ObjectCreatedEvent`].
-====
-
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-loaded.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-loaded.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-loaded.adoc
deleted file mode 100644
index 0c339b4..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_lifecycle_manpage-loaded.adoc
+++ /dev/null
@@ -1,15 +0,0 @@
-[[_rgcms_methods_reserved_manpage-loaded]]
-= `loaded()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `loaded()` lifecycle callback method is called when a (persistent) object has just been loaded from the object store.
-
-
-[TIP]
-====
-Alternatively, consider using a xref:rgsvc.adoc#_rgsvc-api_EventBusService[event bus] xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractSubscriber[subscriber] on the xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-ObjectLoadedEvent[`ObjectLoadedEvent`].
-====


[19/52] [abbrv] isis git commit: ISIS-1243: renamed ug.adoc to ugfun.adoc. Added standard section to each of the guides so can navigate between each easily.

Posted by mg...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_domain-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_domain-services.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_domain-services.adoc
new file mode 100644
index 0000000..0acd13e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_domain-services.adoc
@@ -0,0 +1,313 @@
+[[_ugfun_how-tos_domain-services]]
+= Domain 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/
+
+
+
+
+In Apache Isis domain services have several responsibilities:
+
+- to expose actions to be rendered in the menu
+- to provide actions that are rendered as contributed actions/properties/collections on the contributee domain object
+- they act as subscribers to the event bus
+- they act as repositories (find existing objects) or as factories (create new objects)
+- they provide other services (eg performing calculations, attach a barcode, send an email etc).
+- to implement an SPI of the framework, most notably cross-cutting concerns such as security, command profiling, auditing and publishing.
+
+It's worth extending the xref:ug.adoc#_ugfun_core-concepts_philosophy_hexagonal-architecture[Hexagonal Architecture] to show where domain services -- and in particular the domain services provided by link:http://www.isisaddons.org[Isis Addons] (non-ASF) -- fit in:
+
+.The hexagonal architecture with Isis addons
+image::{_imagesdir}how-tos/domain-services/hexagonal-architecture-addons.png[width="700px"]
+
+The (non-ASF) link:http://isisaddons.org[Isis Addons] are a good source of domain services, providing SPI implementations of the common cross-cutting concerns, and also a number of APIs for domain objects to invoke (eg tags, excel, settings).  Of course, you can also write your own domain services as well, for example to interface with some external CMS system, say.
+
+The Apache Isis framework also provides numerous in-built domain services.  These are catalogued in the reference guide, see xref:rgsvc.adoc#_rgsvc-api[here] and xref:rgsvc.adoc#_rgsvc-spi[here].
+
+
+
+[[_ugfun_how-tos_domain-services_organizing-services]]
+== Organizing Services
+
+In larger applications we have found it worthwhile to ensure that our domain services only act aligned with these responsibilities, employing a naming convention so that it is clear what the responsibilities of each domain service is.
+
+The application provides the `@DomainService(nature=...)` annotation that helps distinguish some of these responsibilities:
+
+- `VIEW` indicates that the actions should appear both on the menu and also be used as contributions
+- `VIEW_MENU_ONLY` indicates that the actions should appear on the menu
+- `VIEW_CONTRIBUTED_ONLY` indicates that the actions should appear on the menu
+- `DOMAIN` indicates that the actions are for other domain objects to invoke (either directly or indirectly through the event bus), but in any case should not be rendered at all in the UI
+
+Pulling all the above together, here are our suggestions as to how you should organize your domain services.
+
+
+=== Factory and Repository
+
+The factory/repository uses an injected `DomainObjectContainer` to both instantiate new objects and to query the database for existing objects of a given entity type.  It is not visible in UI, rather other services delegate to it.
+
+We suggest naming such classes `XxxRepository`, eg:
+
+
+[source,java]
+----
+@DomainService(
+    nature=NatureOfService.DOMAIN                               // <1>
+)
+public CustomerRepository {
+    public List<Customer> findCustomerBy...(...) {
+        return allMatches(...);
+    }
+    public Customer newCustomer(...) {
+        Customer Customer = container.newTransientInstance(Customer.class);
+        ...
+        persistIfNotAlready(Customer);
+        return Customer;
+    }
+    public List<Customer> allCustomers() {
+        return container.allInstances(Customer.class);
+    }
+    @Inject
+    DomainObjectContainer container;
+}
+----
+<1> interacted with only programmatically by other objects in the domain layer.
+
+There is no need to annotate the actions; they are implicitly hidden because of the domain service's nature.
+
+
+
+=== Menu
+
+Menu services provide actions to be rendered on the menu.
+
+For the Wicket viewer, each service's actions appear as a collection of menu items of a named menu, and this menu is on one of the three menu bars provided by the Wicket viewer.  It is possible for more than one menu service's actions to appear on the same menu; a separator is shown between each.
+
+For the Restful Objects viewer, all menu services are shown in the services representation.
+
+We suggest naming such classes `XxxMenu`, eg:
+
+
+[source,java]
+----
+@DomainService(
+    nature = NatureOfService.VIEW_MENU_ONLY                     // <1>
+)
+@DomainServiceLayout(
+        named = "Customers",                                    // <2>
+        menuBar = DomainServiceLayout.MenuBar.PRIMARY,
+        menuOrder = "10"
+)
+public class CustomerMenu {
+    @Action(
+            semantics = SemanticsOf.SAFE
+    )
+    @MemberOrder( sequence = "1" )
+    public List<Customer> findCustomerBy...(...) {
+        return CustomerRepository.findCustomerBy(...);          // <3>
+    }
+
+    @Action(
+            semantics = SemanticsOf.NON_IDEMPOTENT
+    )
+    @MemberOrder( sequence = "3" )
+    public Customer newCustomer(...) {
+        return CustomerRepository.newCustomer(...);
+    }
+
+    @Action(
+            semantics = SemanticsOf.SAFE,
+            restrictTo = RestrictTo.PROTOTYPING
+    )
+    @MemberOrder( sequence = "99" )
+    public List<Customer> allCustomers() {
+        return CustomerRepository.allBankMandates();
+    }
+
+    @Inject
+    protected CustomerRepository customerRepository;
+}
+----
+<1> the service's actions should be rendered as menu items
+<2> specifies the menu name.  All services with the same menu name will be displayed on the same menu, with separators between
+<3> delegates to an injected repository.
+
+Not every action on the repository need to be delegated to of course (the above example does but only because it is very simple).
+
+[TIP]
+====
+Note also that while there's nothing to stop `VIEW_MENU` domain services being injected into other domain objects and interacted with programmatically, we recommend against it.  Instead, inject the underlying repository.  If there is additional business logic, then consider introducing a further `DOMAIN`-scoped service and call that instead.
+====
+
+
+
+=== Contributions
+
+Services can contribute either actions, properties or collections, based on the type of their parameters.
+
+We suggest naming such classes `XxxContributions`, eg:
+
+[source,java]
+----
+@DomainService(
+    nature=NatureOfService.VIEW_CONTRIBUTIONS_ONLY              // <1>
+)
+@DomainServiceLayout(
+    menuOrder="10",
+    name="...",
+}
+public OrderContributions {
+    @Action(semantics=SemanticsOf.SAFE)
+    @ActionLayout(contributed=Contributed.AS_ASSOCIATION)       // <2>
+    @CollectionLayout(render=RenderType.EAGERLY)
+    public List<Order> orders(Customer customer) {              // <3>
+        return container.allMatches(...);
+    }
+
+    @Inject
+    CustomerRepository customerRepository;
+}
+----
+<1> the service's actions should be contributed to the entities of the parameters of those actions
+<2> contributed as an association, in particular as a collection because returns a `List<T>`.
+<3> Only actions with a single argument can be contributed as associations
+
+More information about contributions can be found xref:ug.adoc#_ugfun_how-tos_contributed-members[here].  More information
+about using contributions and mixins to keep your domain application decoupled can be found xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling_contributions[here] and xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling_mixins[here].
+
+
+=== Event Subscribers
+
+Event subscribers can both veto interactions (hiding members, disabling members or validating changes), or can react to interactions (eg action invocation or property edit).
+
+We suggest naming such classes `XxxSubscriptions`, eg:
+
+[source,java]
+----
+@DomainService(
+    nature=NatureOfService.DOMAIN                       // <1>
+)
+@DomainServiceLayout(
+    menuOrder="10",
+    name="...",
+}
+public CustomerOrderSubscriptions {
+    @com.google.common.eventbus.Subscribe
+    public void on(final Customer.DeletedEvent ev) {
+        Customer customer = ev.getSource();
+        orderRepository.delete(customer);
+    }
+    @Inject
+    OrderRepository orderRepository;
+}
+----
+<1> subscriptions do not appear in the UI at all, so should use the domain nature of service
+
+
+
+== Prototyping
+
+While for long-term maintainability we do recommend the naming conventions described xref:ug.adoc#_ugfun_how-tos_domain-services_organizing-services[above], you can get away with far fewer services when just prototyping a domain.
+
+If the domain service nature is not specified (or is left to its default, `VIEW`), then the service's actions will
+appear in the UI both as menu items _and_ as contributions (and the service can of course be injected into other domain objects for programmatic invocation).
+
+Later on it is easy enough to refactor the code to tease apart the different responsibilities.
+
+
+
+
+== Scoped services
+
+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 xref:rgant.adoc#_rgant-RequestScoped[`@javax.enterprise.context.RequestScoped`] is used to indicate this fact:
+
+[source,java]
+----
+@javax.enterprise.context.RequestScoped
+public class MyService extends AbstractService {
+    ...
+}
+----
+
+The framework provides a number of request-scoped services, include a scratchpad service, query results caching, and support for co-ordinating bulk actions.  See xref:rgsvc.adoc#_rgsvc-api[here] and xref:rgsvc.adoc#_rgsvc-spi[here] for further details.
+
+
+
+
+== Registering domain services
+
+The easiest way to register domain services is using xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`] to specify the modules
+which contain xref:rgant.adoc#_rgant-DomainService[`@DomainService`]-annotated classes.
+
+For example:
+
+[source,ini]
+----
+public class MyAppManifest implements AppManifest {
+    public List<Class<?>> getModules() {
+        return Arrays.asList(
+                ToDoAppDomainModule.class,
+                ToDoAppFixtureModule.class,
+                ToDoAppAppModule.class,
+                org.isisaddons.module.audit.AuditModule.class);
+    }
+    ...
+}
+----
+
+will load all services in the packages underneath the four modules listed.
+
+An alternative (older) mechanism is to registered domain services in the `isis.properties` configuration file, under `isis.services` key (a comma-separated list); for example:
+
+[source,ini]
+----
+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,ini]
+----
+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) include clock, auditing, publishing, exception handling, view model support, snapshots/mementos, and user/application settings management; see the xref:rgsvc.adoc#_rgsvc-api[here] and _rgsvc-spi[here] for further details.
+
+
+
+
+== Initialization
+
+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 Apache Isis session _is_ available when initialization occurs (so services can interact with the object store, for example).
+
+
+The framework will call any `public` method annotated with xref:rgant.adoc#_rgant-PostConstruct[`@PostConstruct`] 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 is similar; the framework will call any method annotated with xref:rgant.adoc#_rgant-PreDestroy[`@PreDestroy`].
+
+
+
+== The getId() method
+
+Optionally, a service may provide a xref:rgcms.adoc#_rgcms_methods_reserved_getId[`getId()`] method.  This method returns a logical identifier for a service, independent of its implementation.
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_drop-downs-and-defaults.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_drop-downs-and-defaults.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_drop-downs-and-defaults.adoc
new file mode 100644
index 0000000..396f88c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_drop-downs-and-defaults.adoc
@@ -0,0 +1,65 @@
+[[_ugfun_how-tos_drop-downs-and-defaults]]
+= 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/
+
+NOTE: TODO
+
+
+== For Properties
+
+NOTE: TODO
+
+### Choices for Property
+
+NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`]
+
+### Auto-complete for property
+
+NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`]
+
+### Default for property
+
+NOTE: TODO -  xref:rgcms.adoc#_rgcms_methods_prefixes_default[`default...()`]
+
+
+
+
+== For Action Parameters
+
+NOTE: TODO
+
+### Choices for action parameter
+
+NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`]
+
+### Dependent choices for action params
+
+NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`]
+
+### Auto-complete for action param
+
+NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`]
+
+### Default for action param
+
+NOTE: TODO -  xref:rgcms.adoc#_rgcms_methods_prefixes_default[`default...()`]
+
+
+
+
+
+== For both Properties and Action Parameters
+
+NOTE: TODO
+
+
+### Drop-down for limited number of instances
+
+NOTE: TODO - xref:rgant.adoc#_rgant-DomainObject_bounded[`@DomainObject#bounded()`]
+
+
+### Auto-complete (repository-based)
+
+xref:rgant.adoc#_rgant-DomainObject_autoCompleteRepository[`@DomainObject#autoCompleteRepository()`]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_entity-relationships.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_entity-relationships.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_entity-relationships.adoc
new file mode 100644
index 0000000..b03cd80
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_entity-relationships.adoc
@@ -0,0 +1,15 @@
+[[_ugfun_how-tos_entity-relationships]]
+= 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/
+
+
+NOTE: TODO
+
+== Mandatory and Optional
+
+NOTE: TODO
+
+
+include::_ugfun_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships.adoc
new file mode 100644
index 0000000..97e2160
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships.adoc
@@ -0,0 +1,59 @@
+[[_ugfun_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships]]
+= 1-m bidir 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/
+
+
+
+When an object is added to a 1:m bidirectional relationship, the child object must refer to the parent and the child must be added to the parent's children collection.
+
+If there were no database involved then we would have recommended that you use the link:http://www.two-sdg.demon.co.uk/curbralan/papers/MutualRegistration.pdf[mutual registration] pattern to ensure that both the parent and child are updated correctly.  (The  xref:rgcms.adoc#_rgcms_methods_prefixes_modify[`modify...()`] and xref:rgcms.adoc#_rgcms_methods_prefixes_clear[`clear...()`] supporting methods were introduced in the framework primarily to help support implement the mutual registration pattern.
+
+However, in a relational database, these two operations in the domain object model correspond simply to updating the foreign key of the child table to reference the parent's primary key.
+
+So long as the parent's children collection is a `java.util.Set` (rather than a `Collection` or a `List`), the JDO Objectstore will automatically maintain both sides of the relationship. All that is necessary is to set the child to refer to the parent.
+
+For example, all you need write is:
+
+[source,java]
+----
+public class Department {
+    @javax.jdo.annotations.Persistent(mappedBy="department") // <1>
+    private SortedSet<Employee> employees = new TreeSet<Employee>();
+
+    public SortedSet<Employee> getEmployees() { ... }
+    public void setEmployees(SortedSet<Employee> employees) { ... }
+    ...
+}
+public class Employee {
+    private Department department;
+    public Department getDepartment() { ... }
+    public void setDepartment(Department department) { ... }
+    ...
+}
+----
+<1> it's the `mappedBy` attribute that tells DataNucleus this is a bidirectional relationship.  The value "department" refers to the Employee#department property.
+
+Moreover, when maintaining a bidirectional 1-n relationship that is automatically managed by DataNucleus, it's preferred to "add" to the parent's child collection, don't set the parent on the child.
+
+
+[WARNING]
+====
+If you don't do this then you may hit a `NullPointerException`. The above idiom fixes the issue.
+
+For more information, see http://isis.markmail.org/thread/ipu2lzqqikqdglox[this thread] on the Apache Isis users
+mailing list, including this http://markmail.org/message/hblptpw675mlw723[message] with the above recommendation.
+====
+
+
+[WARNING]
+====
+In fact, not only do you not need to manually maintain the relationship, we have noted on at least http://markmail.org/message/agnwmzocvdfht32f[one occasion] a subtle error if the code is programmatically added.
+
+The error in that case was that the same object was contained in the parents collection. This of course should not happen for a `TreeSet`. However, JDO/DataNucleus replaces the `TreeSet` with its own implementation, and (either by design or otherwise) this does not enforce `Set` semantics.
+
+The upshot is that you should NEVER programmatically add the child object to the parent's collection if using JDO Objectstore.
+====
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_render-all-properties-in-tables.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_render-all-properties-in-tables.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_render-all-properties-in-tables.adoc
new file mode 100644
index 0000000..f5c14bb
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_render-all-properties-in-tables.adoc
@@ -0,0 +1,49 @@
+[[_ugfun_how-tos_render-all-properties-in-tables]]
+= Subclass properties in tables
+: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/
+
+
+
+Suppose you have a hierarchy of classes where a property is derived and abstract in the superclass, concrete implementations in the subclasses. For example:
+
+[source,java]
+----
+public abstract class LeaseTerm {
+    public abstract BigDecimal getEffectiveValue();
+    ...
+}
+
+public class LeaseTermForIndexableTerm extends LeaseTerm {
+    public BigDecimal getEffectveValue() { ... }
+    ...
+}
+----
+
+Currently the Wicket viewer will not render the property in tables (though the property is correctly rendered in views).
+
+[NOTE]
+====
+For more background on this workaround, see https://issues.apache.org/jira/browse/ISIS-582[ISIS-582].
+====
+
+The work-around is simple enough; make the method concrete in the superclass and return a dummy implementation, eg:
+
+[source,java]
+----
+public abstract class LeaseTerm {
+    public BigDecimal getEffectiveValue() {
+        return null;        // workaround for ISIS-582
+    }
+    ...
+}
+----
+
+
+Alternatively the implementation could throw a `RuntimeException`, eg
+
+[source,java]
+----
+throw new RuntimeException("never called; workaround for ISIS-582");
+----
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_simulating-collections-of-values.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_simulating-collections-of-values.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_simulating-collections-of-values.adoc
new file mode 100644
index 0000000..9b98a01
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_simulating-collections-of-values.adoc
@@ -0,0 +1,23 @@
+[[_ugfun_how-tos_simulating-collections-of-values]]
+= Collections of values
+: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/
+
+
+
+Although in Apache Isis you can have properties of either values (string, number, date etc) or of (references to other) entities, with collections the framework (currently) only supports collections of (references to) entities.  That is, collections of values (a bag of numbers, say) are not supported.
+
+However, it is possible to simulate a bag of numbers using view models.
+
+
+== View Model
+
+NOTE: TODO
+
+
+
+== Persistence Concerns
+
+NOTE: TODO -  easiest to simply store using DataNucleus' support for collections, marked as xref:rgant.adoc#_rgant-Programmatic[`@Programmatic`] so that it is ignored by Apache Isis.  Alternatively can store as json/xml in a varchar(4000) or clob and manually unpack.
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_ui-hints.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_ui-hints.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_ui-hints.adoc
new file mode 100644
index 0000000..147d09e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_ui-hints.adoc
@@ -0,0 +1,15 @@
+[[_ugfun_how-tos_ui-hints]]
+= UI Hints
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+The Apache Isis programming model includes several mechanisms for a domain object to provide UI hints.  These range from their title (so an end-user can distinguish one object from another) through to hints that can impact their CSS styling.
+
+include::_ugfun_how-tos_ui-hints_object-titles-and-icons.adoc[leveloffset=+1]
+include::_ugfun_how-tos_ui-hints_names-and-descriptions.adoc[leveloffset=+1]
+include::_ugfun_how-tos_ui-hints_layout.adoc[leveloffset=+1]
+include::_ugfun_how-tos_ui-hints_eager-rendering.adoc[leveloffset=+1]
+include::_ugfun_how-tos_ui-hints_action-icons-and-css.adoc[leveloffset=+1]
+include::_ugfun_how-tos_ui_are-you-sure.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_ui-hints_action-icons-and-css.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_ui-hints_action-icons-and-css.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_ui-hints_action-icons-and-css.adoc
new file mode 100644
index 0000000..859e2ca
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_ui-hints_action-icons-and-css.adoc
@@ -0,0 +1,58 @@
+[[_ugfun_how-tos_ui-hints_action-icons-and-css]]
+= Action Icons and CSS
+: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 allows link:http://fortawesome.github.io/Font-Awesome/icons/[font awesome] icons to be associated with each action, and for link:http://getbootstrap.com/css/#buttons[Bootstrap CSS] to be applied to action rendered as buttons.
+
+These UI hint can be applied either to individual actions, or can be applied en-masse using pattern matching.
+
+== Per action
+
+NOTE: TODO - xref:rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`] and xref:rgant.adoc#_rgant-ActionLayout_cssClassFa[`@ActionLayout#cssClassFa()`]
+
+
+Alternatively, you can specify these hints dynamically in the xref:ug.adoc#_ugfun_object-layout[`Xxx.layout.json`] for the entity.
+
+
+== Per pattern matching
+
+Rather than annotating every action with xref:rgant.adoc#_rgant-ActionLayout_cssClassFa[`@ActionLayout#cssClassFa()`] and xref:rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`] you can instead specify the UI hint globally using regular expressions.
+
+The xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.reflector.facet.cssClassFa.patterns` is a comma separated list of key:value pairs, eg:
+
+[source,ini]
+----
+isis.reflector.facet.cssClassFa.patterns=\
+                        new.*:fa-plus,\
+                        add.*:fa-plus-square,\
+                        create.*:fa-plus,\
+                        list.*:fa-list, \
+                        all.*:fa-list, \
+                        download.*:fa-download, \
+                        upload.*:fa-upload, \
+                        execute.*:fa-bolt, \
+                        run.*:fa-bolt
+----
+
+where the key is a regex matching action names (eg `create.*`) and the value is a link:http://fortawesome.github.io/Font-Awesome/icons/[font-awesome] icon name (eg `fa-plus`) to be applied (as per `@CssClassFa()`) to all action members matching the regex.
+
+
+Similarly, the xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.reflector.facet.cssClass.patterns` is a comma separated list of key:value pairs, eg:
+
+[source,ini]
+----
+isis.reflector.facet.cssClass.patterns=\
+                        delete.*:btn-warning
+----
+
+where (again)the key is a regex matching action names (eg `delete.*`) and the value is a link:http://getbootstrap.com/css/[Bootstrap] CSS button class (eg `btn-warning) to be applied (as per `@CssClass()`) to all action members matching the regex.
+
+[TIP]
+====
+We strongly recommend that you use this technique rather than annotating each action with xref:rgant.adoc#_rgant-ActionLayout_cssClassFa[`@ActionLayout#cssClassFa()`] or xref:rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`].  Not only is the code more maintainable, you'll also find that it forces you to be consistent in your action names.
+====
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_ui-hints_eager-rendering.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_ui-hints_eager-rendering.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_ui-hints_eager-rendering.adoc
new file mode 100644
index 0000000..304a20c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_ui-hints_eager-rendering.adoc
@@ -0,0 +1,58 @@
+[[_ugfun_how-tos_ui-hints_eager-rendering]]
+= Eager rendering
+: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/
+
+
+By default, collections all rendered lazily, in other words in a "collapsed" table view:
+
+NOTE: TODO - screenshot here
+
+For the more commonly used collections we want to show the table expanded:
+
+NOTE: TODO - screenshot here
+
+For this we annotate the collection using the `@CollectionLayout(render=RenderType.EAGERLY`; for example
+
+[source,java]
+----
+@javax.jdo.annotations.Persistent(table="ToDoItemDependencies")
+private Set<ToDoItem> dependencies = new TreeSet<>();
+@Collection
+@CollectionLayout(
+    render = RenderType.EAGERLY
+)
+public Set<ToDoItem> getDependencies() {
+    return dependencies;
+}
+----
+
+Alternatively, it can be specified the `Xxx.layout.json` file:
+
+[source,javascript]
+----
+"dependencies": {
+    "collectionLayout": {
+        "render": "EAGERLY"
+    },
+}
+----
+
+[WARNING]
+====
+It might be thought that collections that are eagerly rendered should also be eagerly loaded from the database by enabling the `defaultFetchGroup` attribute:
+
+[source,java]
+----
+@javax.jdo.annotations.Persistent(table="ToDoItemDependencies", defaultFetchGroup="true")
+private Set<ToDoItem> dependencies = new TreeSet<>();
+...
+----
+
+While this can be done, it's likely to be a bad idea, because doing so will cause DataNucleus to query for more data than required even if the object is being rendered within some referencing object's table.
+
+Of course, your mileage may vary, so don't think you can't experiment.
+====
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_ui-hints_layout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_ui-hints_layout.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_ui-hints_layout.adoc
new file mode 100644
index 0000000..390a69d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_ui-hints_layout.adoc
@@ -0,0 +1,9 @@
+[[_ugfun_how-tos_ui-hints_layout]]
+= Layout
+: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/
+
+
+See the xref:ug.adoc#_ugfun_object-layout[object layout] chapter.
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_ui-hints_names-and-descriptions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_ui-hints_names-and-descriptions.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_ui-hints_names-and-descriptions.adoc
new file mode 100644
index 0000000..7977e5e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_ui-hints_names-and-descriptions.adoc
@@ -0,0 +1,47 @@
+[[_ugfun_how-tos_ui-hints_names-and-descriptions]]
+= Names and Descriptions
+: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/
+
+NOTE: TODO
+
+
+
+NOTE: see also xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[Internationalization]
+
+== Class (object)
+
+NOTE: TODO - xref:rgant.adoc#_rgant-DomainObjectLayout_named[`@DomainObjectLayout#named()`], xref:rgant.adoc#_rgant-DomainObjectLayout_describedAs[`@DomainObjectLayout#describedAs()`]
+
+
+== Property
+
+NOTE: TODO - xref:rgant.adoc#_rgant-PropertyLayout_named[`@PropertyLayout#named()`], xref:rgant.adoc#_rgant-PropertyLayout_describedAs[`@PropertyLayout#describedAs()`]
+
+
+
+== Collections
+
+NOTE: TODO - xref:rgant.adoc#_rgant-CollectionLayout_named[`@CollectionLayout#named()`], xref:rgant.adoc#_rgant-CollectionLayout_describedAs[`@CollectionLayout#describedAs()`]
+
+
+
+== Actions
+
+NOTE: TODO - xref:rgant.adoc#_rgant-ActionLayout_named[`@ActionLayout#named()`], xref:rgant.adoc#_rgant-ActionLayout_describedAs[`@ActionLayout#describedAs()`]
+
+
+== Action Parameters
+
+NOTE: TODO - xref:rgant.adoc#_rgant-ParameterLayout_named[`@ParameterLayout#named()`], xref:rgant.adoc#_rgant-ParameterLayout_describedAs[`@ParameterLayout#describedAs()`]
+
+
+[TIP]
+====
+If you're running on Java 8, then note that it's possible to write Isis applications without using `@ParameterLayout(named=...)` annotation.  Support for this can be found in the link:http://github.com/isisaddons/isis-metamodel-paraname8[Isis addons' paraname8] metamodel extension (non-ASF).  (In the future we'll fold this into core).  See also our guidance on xref:release-notes.adoc#_migration-notes_1.8.0-to-1.9.0_upgrading-to-java8[upgrading to Java 8].
+====
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_ui-hints_object-titles-and-icons.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_ui-hints_object-titles-and-icons.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_ui-hints_object-titles-and-icons.adoc
new file mode 100644
index 0000000..7ef5325
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_ui-hints_object-titles-and-icons.adoc
@@ -0,0 +1,97 @@
+[[_ugfun_how-tos_ui-hints_object-titles-and-icons]]
+= Object Titles and Icons
+: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/
+
+
+In Apache Isis every object is identified to the user by a title (label) and an icon.  This is shown in several places: as the main heading for an object; as a link text for an object referencing another object, and also in tables representing collections of objects.
+
+The icon is often the same for all instances of a particular class, but it's also possible for an individual instance to return a custom icon.  This could represent the state of that object (eg a shipped order, say, or overdue library book).
+
+It is also possible for an object to provide a CSS class hint.  In conjunction with xref:ugvw.adoc#_ugvw_customisation_tweaking-css-classes[customized CSS] this can be used to apply arbitrary styling; for example each object could be rendered in a page with a different background colour.
+
+
+== Object Title
+
+The object title is a label to identify an object to the end-user.  Generally the object title is a label to identify an object to the end-user.  There is no requirement for it to be absolutely unique, but it should be "unique enough" to distinguish the object from other object's likely to be rendered on the same page.
+
+The title is always shown with an icon, so there is generally no need for the title to include information about the object's type.  For example the title of a customer object shouldn't include the literal string "Customer"; it can just have the customer's name, reference or some other meaningful business identifier.
+
+
+=== Declarative style
+
+The xref:rgant.adoc#_rgant-Title[`@Title`] annotation can be used build up the title of an object from its constituent parts.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+    @Title(sequence="1", append=" ")
+    public String getFirstName() { ... }
+    @Title(sequence="2")
+    public Product getLastName() { ... }
+    ...
+}
+----
+
+might return "Arthur Clarke", while:
+
+[source,java]
+----
+public class CustomerAlt {
+    @Title(sequence="2", prepend=", ")
+    public String getFirstName() { ... }
+
+    @Title(sequence="1")
+    public Product getLastName() { ... }
+    ...
+}
+----
+
+could return "Clarke, Arthur".
+
+Note that the sequence is in Dewey Decimal Format.  This allows a subclass to intersperse information within the title.  For example (please forgive this horrible domain modelling (!)):
+
+
+[source,java]
+----
+public class Author extends Customer {
+    @Title(sequence="1.5", append=". ")
+    public String getMiddleInitial() { ... }
+    ...
+}
+----
+
+could return "Arthur C. Clarke".
+
+
+[TIP]
+====
+Titles can sometimes get be long and therefore rather cumbersome in "parented" tables.  If `@Title` has been used then the Wicket viewer will automatically exclude portions of the title belonging to the owning object.
+====
+
+
+=== Imperative style
+
+NOTE: TODO - see xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`]
+
+
+
+
+== Object Icon
+
+The icon is often the same for all instances of a particular class, but it's also possible for an individual instance to return a custom icon.  This could represent the state of that object (eg a shipped order, say, or overdue library book).
+
+NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`], xref:rgant.adoc#_rgant-DomainObjectLayout_cssClassFa[`@DomainObjectLayout#cssClassFa()`]
+
+
+
+
+== Object CSS Styling
+
+
+It is also possible for an object to return a xref:rgcms.adoc#_rgcms_methods_reserved_cssClass[CSS class].  In conjunction with xref:ugvw.adoc#_ugvw_customisation_tweaking-css-classes[customized CSS] this can be used to apply arbitrary styling; for example each object could be rendered in a page with a different background colour.
+
+NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_reserved_cssClass[`cssClass()`], xref:rgant.adoc#_rgant-DomainObjectLayout_cssClass[`@DomainObjectLayout#cssClass()`] xref:rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`], xref:rgant.adoc#_rgant-PropertyLayout_cssClass[`@PropertyLayout#cssClass()`], xref:rgant.adoc#_rgant-CollectionLayout_cssClass[`@CollectionLayout#cssClass()`]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_ui_are-you-sure.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_ui_are-you-sure.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_ui_are-you-sure.adoc
new file mode 100644
index 0000000..2b17ce6
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_ui_are-you-sure.adoc
@@ -0,0 +1,76 @@
+[[_ugfun_how-tos_ui_are-you-sure]]
+= 'Are you sure?' idiom
+: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/
+
+
+Sometimes an action might perform irreversible changes.  In such a case it's probably a good idea for the UI to require that the
+end-user explicitly confirms that they intended to invoke the action.
+
+== Using action semantics
+
+One way to meet this requirement is using the framework's built-in xref:rgant.adoc#_rgant-Action_semantics[`@Action#semantics()`] attribute:
+
+[source,java]
+----
+@Action(
+        semantics = SemanticsOf.IDEMPOTENT_ARE_YOU_SURE
+)
+public SimpleObject updateName(
+        @Parameter(maxLength = NAME_LENGTH)
+        @ParameterLayout(named = "New name")
+        final String name) {
+    setName(name);
+    return this;
+}
+----
+
+
+This will render as:
+
+image::{_imagesdir}/how-tos/tips-n-tricks/action-semantics-are-you-sure.png[]
+
+
+== Using a checkbox
+
+An alternative approach (for all versions of the framework) is to require the end-user to check a dummy checkbox parameter (and prevent the action from being invoked if the user hasn't checked that parameter).
+
+For example:
+
+image::{_imagesdir}/how-tos/tips-n-tricks/are-you-sure.png[]
+
+[NOTE]
+====
+Note that these screenshots shows an earlier version of the xref:ugvw.adoc#[Wicket viewer] UI (specifically, pre 1.8.0).
+====
+
+If the user checks the box:
+
+image::{_imagesdir}/how-tos/tips-n-tricks/are-you-sure-happy-case.png[]
+
+then the action will complete.
+
+However, if the user fails to check the box, then a validation message is shown:
+
+image::{_imagesdir}/how-tos/tips-n-tricks/are-you-sure-sad-case.png[]
+
+
+
+The code for this is pretty simple:
+
+[source,java]
+----
+public List<ToDoItem> delete(@Named("Are you sure?") boolean areYouSure) {
+    container.removeIfNotAlready(this);
+    container.informUser("Deleted " + container.titleOf(this));
+    return toDoItems.notYetComplete();          // <1>
+}
+public String validateDelete(boolean areYouSure) {
+    return areYouSure? null: "Please confirm you are sure";
+}
+----
+<1> invalid to return `this` (cannot render a deleted object)
+
+Note that the action itself does not use the boolean parameter, it is only
+used by the supporting xref:rgcms.adoc#_rgcms_methods_prefixes_validate[`validate...()`] method.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout.adoc
new file mode 100644
index 0000000..add6b42
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout.adoc
@@ -0,0 +1,18 @@
+[[_ugfun_object-layout]]
+= Object Layout
+: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/
+
+
+In implementing the http://en.wikipedia.org/wiki/Naked_objects[naked objects pattern], Apache Isis aims to infer as much information from the domain classes as possible.  Nevertheless, some metadata relating solely to the UI is inevitably required.
+
+
+This chapter describes how this is done both for domain objects -- statically or dynamically -- and for the application menu bar (containing domain service' actions).
+
+include::_ugfun_object-layout_static.adoc[leveloffset=+1]
+include::_ugfun_object-layout_dynamic.adoc[leveloffset=+1]
+include::_ugfun_object-layout_application-menu.adoc[leveloffset=+1]
+include::_ugfun_object-layout_static-vs-dynamic.adoc[leveloffset=+1]
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_application-menu.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_application-menu.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_application-menu.adoc
new file mode 100644
index 0000000..0467972
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_application-menu.adoc
@@ -0,0 +1,171 @@
+[[_ugfun_object-layout_application-menu]]
+= Application Menu Layout
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The actions of domain services are made available as an application menu bar. By default each domain service
+corresponds to a single menu on this menu bar, with its actions as the drop-down menu items. This is rarely exactly
+what is required, however. The `@MemberOrder` and `@DomainServiceLayout` annotations can be used to rearrange the
+placement of menu items.
+
+The screenshots below are taken from http://github.com/estatio/estatio[Estatio], an open source estate management
+application built using Apache Isis.
+
+== @DomainServiceLayout
+
+Menus for domain services can be placed either on a primary, secondary or tertiary menu bar.
+
+image::{_imagesdir}wicket-viewer/application-menu/layout-menus.png[width="800px",link="{_imagesdir}wicket-viewer/application-menu/layout-menus.png"]
+
+Within a single top-level menu (eg "Fixed Assets") there can be actions from multiple services. The Wicket viewer
+automatically adds a divider between each:
+
+image::{_imagesdir}wicket-viewer/application-menu/dividers.png[width="400px",link="{_imagesdir}wicket-viewer/application-menu/dividers.png"]
+
+In the example above the top-level menu combines the actions from the `Properties`, `Units` and `FixedAssetRegistrations`
+services. The `Properties` service is annotated:
+
+[source,java]
+----
+@DomainServiceLayout(
+        named="Fixed Assets",
+        menuBar = DomainServiceLayout.MenuBar.PRIMARY,
+        menuOrder = "10.1"
+)
+public class Properties ... { ... }
+----
+
+while the `Units` service is annotated:
+
+[source,java]
+----
+@DomainServiceLayout(
+        named="Fixed Assets",
+        menuBar = DomainServiceLayout.MenuBar.PRIMARY,
+        menuOrder = "10.2"
+)
+public class Units ... { ... }
+----
+
+and similarly `FixedAssetRegistrations` is annotated:
+
+[source,java]
+----
+@DomainServiceLayout(
+        named="Fixed Assets",
+        menuBar = DomainServiceLayout.MenuBar.PRIMARY,
+        menuOrder = "10.3"
+)
+public class FixedAssetRegistrations ... { ... }
+----
+
+Note that in all three cases the value of the `named` attribute and the `menuBar` attribute is the same: "Fixed Assets"
+and PRIMARY. This means that all will appear on a "Fixed Assets" menu in the primary menu bar.
+
+Meanwhile the value of `menuOrder` attribute is significant for two reasons:
+
+* for these three services on the same ("Fixed Assets") top-level menu, it determines the relative order of their sections (`Properties` first, then `Units`, then `FixedAssetRegistrations`)
+* it determines the placement of the top-level menu itself ("Fixed Assets") with respect to other top-level menus on the menu bar.
+
+To illustrate this latter point, the next top-level menu on the menu bar, "Parties", is placed after "Fixed Assets"
+ because the `menuOrder` of the first of its domain services, namely the `Parties` service, is higher than that for
+ "Fixed Assets":
+
+[source,java]
+----
+@DomainServiceLayout(
+        named="Parties",
+        menuBar = DomainServiceLayout.MenuBar.PRIMARY,
+        menuOrder = "20.1"
+)
+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 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:
+
+[source,java]
+----
+public class Units extends EstatioDomainService<Unit> {
+
+    @MemberOrder(sequence = "1")
+    public Unit newUnit( ... ) { ... }
+
+    @MemberOrder(sequence = "2")
+    public List<Unit> findUnits( ... ) { ... }
+
+    @ActionLayout( prototype = true )
+    @MemberOrder(sequence = "99")
+    public List<Unit> allUnits() { ... }
+    ...
+}
+----
+
+Note that the last is also a prototype action (meaning it is only displayed in SERVER_PROTOTYPE (=Wicket Development) mode).
+In the UI it is rendered in italics.
+
+(It is possible to override this place of a given action by specifying `@MemberOrder(name=&quot;...&quot;)` where the name is
+that of a top-level menu. Prior to 1.8.0 this was the only way of doing things, as of 1.8.0 its use
+is not recommended).
+
+== Tertiary menubar
+
+The tertiary menu bar consists of a single unnamed menu, rendered underneath the user's login, top right. This is
+intended primarily for actions pertaining to the user themselves, eg their account, profile or settings:
+
+image::{_imagesdir}wicket-viewer/application-menu/tertiary.png[width="300px",link="{_imagesdir}wicket-viewer/application-menu/tertiary.png"]
+
+Domain services' actions can be associated with the tertiary menu using the same `@DomainServiceLayout` annotation. For
+example, the `updateEpochDate(...)` and `listAllSettings(...)` actions come from the following service:
+
+[source,java]
+----
+@DomainServiceLayout(
+        menuBar = DomainServiceLayout.MenuBar.TERTIARY,
+        menuOrder = "10.1"
+)
+public class EstatioAdministrationService ... {
+
+    @MemberOrder(sequence = "1")
+    public void updateEpochDate( ... ) { ... }
+
+    @MemberOrder(sequence = "2")
+    public List<ApplicationSetting> listAllSettings() { ... }
+    ...
+}
+----
+
+Because the number of items on the tertiary menu is expected to be small and most will pertain to the current user, the
+viewer does _not_ place dividers between actions from different services on the tertiary menu.
+
+
+== Isis Add-on modules
+
+Some of the (non-ASF) link:http://isisaddons.org[Isis Addons] modules also provide services whose actions appear in top-level menus.
+
+The http://github.com/isisaddons/isis-module-security[security]'s module places its domain service menus in three
+top-level menus:
+
+* its `ApplicationUsers`, `ApplicationRoles`, `ApplicationPermission`, `ApplicationFeatureViewModels` and
+ `ApplicationTenancies` domain services are all grouped together in a single "Security" top-level menu, on the
+ SECONDARY menu bar
+
+* its `SecurityModuleAppFixturesService` domain service, which allows the security modules' fixture scripts to be run,
+ is placed on a "Prototyping" top-level menu, also on the SECONDARY menu bar
+
+* its `MeService` domain service, which provides the `me()` action, is placed on the TERTIARY menu bar.
+
+Meanwhile the http://github.com/isisaddons/isis-module-devutils[devutils] module places its actions - to download layouts and
+so forth - on a "Prototyping" top-level menu, on the SECONDARY menu bar.
+
+Currently there is no facility to alter the placement of these services. However, their UI can be suppressed
+using security or using a xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling_vetoing-visibility[vetoing subscriber].
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_dynamic.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_dynamic.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_dynamic.adoc
new file mode 100644
index 0000000..a0bdb51
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_dynamic.adoc
@@ -0,0 +1,113 @@
+[[_ugfun_object-layout_dynamic]]
+= Dynamic Object Layout
+: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/
+
+
+
+Metadata providing UI hints can be specified either statically, using annotations, or dynamically, using a `.layout.json` file.  This section describes the dynamic approach, using the file.
+
+
+== JSON layout file
+
+The JSON layout file for class `Xxx` takes the name `Xxx.layout.json`, and resides in the same package as the class.
+The format of the file is:
+
+[source,javascript]
+----
+{
+  "columns": [                                // list of columns
+    {
+      "span": 6,                              // span of the left-hand property column
+      "memberGroups": {                       // ordered map of member (property) groups
+        "General": {                          // member group name
+          "members": {
+            "description": {                  // property, no associated actions, but with UI hint
+              "propertyLayout": {
+                "typicalLength": 50           // UI hint for size of field (no longer used in ISIS 1.8.0)
+              }
+            },
+            "category": {},
+            "complete": {                     // property, with associated actions
+              "propertyLayout": {
+                "describedAs": "Whether this todo item has been completed"
+              },
+              "actions": {
+                "completed": {
+                  "actionLayout": {
+                    "named": "Done",          // naming UI hint
+                    "cssClass": "x-highlight" // CSS UI hint
+                  }
+                },
+                "notYetCompleted": {
+                  "actionLayout": {
+                    "named": "Not done"
+                  }
+                }
+              }
+            }
+          },
+          "Misc": {
+            "members": {
+              "notes": {
+                "propertyLayout": {
+                  "multiLine": 5              // UI hint for text area
+                }
+              },
+              "versionSequence": {}
+            }
+          }
+        }
+      }
+    },
+    {
+      "span": 6,                              // span of the middle property column
+      "memberGroups": { ... }
+    },
+    {
+      "span": 0                               // span of the right property column (if any)
+    },
+    {
+      "span": 6,
+      "collections": {                        // ordered map of collections
+        "dependencies": {                     // collection, with associated actions
+          "collectionLayout": {
+            "paged": 10,                      // pagination UI hint
+            "render": "EAGERLY"               // lazy-loading UI hint
+          },
+          "actions": {
+            "add":{},
+            "delete": {}
+          },
+        },
+        "similarItems": {}                    // collection, no associated actions
+      }
+    }
+  ],
+  "actions": {                                // actions not associated with any member
+    "delete": {},
+    "duplicate": {
+      "actionLayout": {
+        "named": {
+          "value": "Clone"
+        }
+      }
+    }
+  }
+}
+----
+
+Although advisable, it is not necessary to list all class members in this file. Any members not listed with be
+ordered according either to annotations (if present) or fallback/default values.
+
+Note also that the layout file may contain entries for xref:ug.adoc#_ugfun_how-tos_contributed-members[contributed associations and actions]; this allows each contributee classes to define their own layout for their contributions, possibly overriding any static metadata on the original domain service contributor.
+
+
+
+== 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/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_static-vs-dynamic.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_static-vs-dynamic.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_static-vs-dynamic.adoc
new file mode 100644
index 0000000..f5cfb98
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_static-vs-dynamic.adoc
@@ -0,0 +1,26 @@
+[[_ugfun_object-layout_static-vs-dynamic]]
+= Static vs Dynamic Layouts
+: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/
+
+
+
+
+Using xref:ug.adoc#_ugfun_object-layout_dynamic[dynamic object layout]s using JSON has the huge benefit that the layout can be updated without requiring a recompile of the code and redeploy of the app.  Many developers also find it easier to rationalize about layout when all the hints are collated together in a single place (rather than scattered across the class members as annotations).
+
+Another benefit of dynamic layout is that UI hints can be provided for xref:ug.adoc#_ugfun_how-tos_contributed-members[contributed associations and actions] that are synthesised at runtime.
+
+The main downsides of using dynamic layouts are a lack of typesafety (a typo will result in the metadata not being picked up for the element) and syntactic fragility (an invalid JSON document will result in no metadata for the entire class).
+
+Also, dynamic layouts have no notion of inheritance, whereas the dewey-decimal format `@MemberOrder` annotation allows the metadata of the subclass its superclasses to fit together relatively seamlessly.
+
+
+
+== Best of both worlds?
+
+Using the (non-ASF) link:http://github.com/isisaddons/isis-jrebel-plugin[Isis addons' jrebel] plugin comes close to getting the best of both words: metadata is specified in a type-safe way using annotations, but can be reloaded automatically.
+
+The downsides are licensing cost, and also the fact that metadata for contributed actions in the contributee class cannot be specified.
+
+Another open source alternative that you might also like to explore is DCEVM; there's a good write-up on the link:http://blog.jetbrains.com/idea/2013/07/get-true-hot-swap-in-java-with-dcevm-and-intellij-idea/[IntelliJ blog].
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_static.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_static.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_static.adoc
new file mode 100644
index 0000000..487abb8
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_static.adoc
@@ -0,0 +1,159 @@
+[[_ugfun_object-layout_static]]
+= Static Object Layout
+: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/
+
+
+Metadata providing UI hints can be specified either statically, using annotations, or dynamically, using a `.layout.json` file.  This section describes the static approach, using annotations.
+
+
+
+== `@MemberOrder`
+
+The `@MemberOrder` annotation is used to specify the relative order of domain class properties, collections and actions.
+
+The annotation defines two attributes, `name()` and `sequence()`.  Their usage depends on the member type:
+
+* for properties, the `name()` is used to group properties together.  The `sequence()` then orders properties within these groups. If no `name()` is specified then the property is placed in a fallback "General" group, called "General". +
++
+The name of these "member groups" are then referenced by xref:rgant.adoc#_rgant-MemberGroupLayout[`@MemberGroupLayout`].
+
+* for collections, the `name()` attribute is (currently) unused.  The `sequence()` orders collections relative to one another
+
+* for actions, the `name()` attribute associates an action with either a property or with a collection. +
++
+If the `name()` attribute matches a property name, then the action's button is rendered close to the property, according to xref:rgant.adoc#_rgant-ActionLayout_position[`@ActionLayout#position()`] attribute. +
++
+On the other hand if the `name() attribute matches a collection name, then the action's button is rendered on the collection's header. +
++
+If there is no `name()` value, then the action is considered to pertain to the object as a whole, and its button is rendered close to the object's icon and title.
++
+Within any of these, the `sequence()` then determines the relative ordering of the action with respect to other actions that have been similarly associated with properties/collections or left as "free-standing".
+
+
+For example:
+
+[source,java]
+----
+public class ToDoItem {
+    @MemberOrder(sequence="1")
+    public String getDescription() { ... }
+    @MemberOrder(sequence="2")
+    public String getCategory() { ... }
+    @MemberOrder(sequence="3")
+    public boolean isComplete() { ... }
+    @MemberOrder(name="Detail", sequence="1")
+    public LocalDate getDueBy() { ... }
+    @MemberOrder(name="Detail", sequence="2")
+    public BigDecimal getCost() { ... }
+    @MemberOrder(name="Detail", sequence="4")
+    public String getNotes() { ... }
+    @MemberOrder(name="Misc", sequence="99")
+    public Long getVersionSequence() { ... }
+    ...
+}
+----
+
+This defines three property (or member) groups, "General", "Detail" and "Misc"; "General" is the default if no `name` attribute is specified. Properties in the same member group are rendered together, as a fieldset.
+
+In addition, actions can optionally be associated (rendered close to) either properties or actions. This is done by overloading the `@MemberOrder`'s `name` attribute, holding the value of the property or collection.
+
+For example:
+
+[source,java]
+----
+public class ToDoItem {
+    @MemberOrder(sequence="3")
+    public boolean isComplete() { ... }
+    @MemberOrder(name="complete", sequence="1")
+    public ToDoItem completed() { ...}
+    @MemberOrder(name="complete", sequence="2")
+    public ToDoItem notYetCompleted() { ...}
+
+    @MemberOrder(sequence="1")
+    public SortedSet<ToDoItem> getDependencies() { ... }
+    @MemberOrder(name="dependencies", sequence="1")
+    public ToDoItem add(ToDoItem t) { ...}
+    @MemberOrder(name="dependencies", sequence="2")
+    public ToDoItem remove(ToDoItem t) { ...}
+    ...
+}
+----
+
+will associate the `completed()` and `notYetCompleted()` actions with the `complete` property, and will associate the `add()` and `remove()` actions with the `dependencies` collection.
+
+
+The value of `sequence()` is a string.  The simplest convention (as shown in the example above) is to use numbers -- 1, 2, 3 -- though it is a better idea to leave gaps in the numbers -- 10, 20, 30 perhaps -- such that a new member may be added without having to edit existing numbers.  A useful alternative is to adopt the 'dewey-decimal' notation -- 1, 1.1, 1.2, 2, 3, 5.1.1, 5.2.2, 5.2, 5.3 -- which allows for an indefinite amount of future insertion.  It also allows subclasses to insert their class members as required.
+
+
+
+
+== `@MemberGroupLayout`
+
+The `@MemberGroupLayout` annotation specifies the relative positioning of property groups as being either in a left column, a middle column or in a right column.  The annotation also specifies the relative width of the columns.
+
+The property groups in this case are those that are inferred from the `@MemberOrder#name()` attribute.
+
+For example:
+
+[source,java]
+----
+@MemberGroupLayout(
+     columnSpans={3,3,0,6},
+     left={"General", "Misc"},
+     middle="Detail"
+ )
+public class ToDoItem {
+    ...
+}
+----
+
+Four values are given in the `columnSpans` attribute. The first three are the relative widths of the three columns of property groups. The fourth, meanwhile, indicates the width of a final column that holds all the collections of the object.
+
+The values of these spans are taken as proportions of 12 virtual columns across the page (this taken from the link:http://getbootstrap.com/2.3.2/[Bootstrap] library).
+
+For example:
+
+* `{3,3,0,6}` indicates:
+** a left column of properties taking up 25% of the width
+** a middle column of properties taking up 25% of the width
+** a right column of collections taking up 50% of the width
+* `{2,6,0,4}` indicates:
+** a left column of properties taking up ~16% of the width
+** a middle column of properties taking up 50% of the width
+** a right column of collections taking up ~33% of the width
+* `{2,3,3,4}` indicates:
+** a left column of properties taking up ~16% of the width
+** a middle column of properties taking up 25% of the width
+** a right column of properties taking up 25% of the width
+** a far right column of collections taking up ~33% of the width
+
+If the sum of all the columns exceeds 12, then the collections are placed underneath the properties, taking up the full span. For example:
+
+* {4,4,4,12} indicates:
+** a left column of properties taking up ~33% of the width
+** a middle column of properties taking up ~33% of the width
+** a right column of properties taking up ~33% of the width
+** the collections underneath the property columns, taking up the full width
+
+== Example Layouts
+
+Below are sketches for the layout of the https://github.com/apache/isis/blob/f38fdb92941172eabb12e0943509f239e6d5925f/example/application/quickstart_wicket_restful_jdo/dom/src/main/java/dom/todo/ToDoItem.java[ToDoItem] class of the Isis addons example https://github.com/isisaddons/isis-app-todoapp/[todoapp] (not ASF):
+
+The first divides the properties into two equal sized columns (6-6-0) and puts the collections underneath (12):
+
+image::{_imagesdir}reference-layout/6-6-0-12.png[width="720px",link="{_imagesdir}reference-layout/6-6-0-12.png"]
+
+The next divides the collections into three equal sized columns (4-4-4) and again puts the collections underneath (12):
+
+image::{_imagesdir}reference-layout/4-4-4-12.png[width="720px",link="{_imagesdir}reference-layout/4-4-4-12.png"]
+
+The last puts the properties into a single column (4-0) and places the collections into the other larger column (8-0):
+
+image::{_imagesdir}reference-layout/4-0-8-0.png[width="720px",link="{_imagesdir}reference-layout/4-0-8-0.png"]
+
+
+== Other Annotations
+
+As of 1.8.0, all the layout annotations have been consolidated into the various `XxxLayout` annotations: xref:rgant.adoc#_rgant-ActionLayout, [`@ActionLayout`] xref:rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`],  xref:rgant.adoc#_rgant-DomainObjectLayout[`@DomainObjectLayout`],  xref:rgant.adoc#_rgant-DomainServiceLayout[`@DomainServiceLayout`],  xref:rgant.adoc#_rgant-ParameterLayout[`@ParameterLayout`], xref:rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`], and xref:rgant.adoc#_rgant-ViewModelLayout[`@ViewModelLayout`]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugsec_configuring-isis-to-use-shiro.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugsec_configuring-isis-to-use-shiro.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugsec_configuring-isis-to-use-shiro.adoc
index 382bc03..62c565d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugsec_configuring-isis-to-use-shiro.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugsec_configuring-isis-to-use-shiro.adoc
@@ -9,7 +9,7 @@ Apache Isis' security mechanism is configurable, specifying an `Authenticator` a
 
 [TIP]
 ====
-The xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype] is pre-configured to use Apache Shiro, so much of what follows is set up already.
+The xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] is pre-configured to use Apache Shiro, so much of what follows is set up already.
 ====
 
 == Telling Apache Isis to use Shiro

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugsec_shiro-ini-realm.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugsec_shiro-ini-realm.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugsec_shiro-ini-realm.adoc
index 315e1fb..623dfe4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugsec_shiro-ini-realm.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugsec_shiro-ini-realm.adoc
@@ -7,7 +7,7 @@
 
 Probably the simplest realm to use is Shiro's built-in `IniRealm`, which reads from the (same) `WEB-INF/shiro.ini` file.
 
-This is suitable for prototyping, but isn't intended for production use, if only because user/password credentials are stored in plain text.  Nevertheless, it's a good starting point.  The app generated by the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype] is configured to use this realm.
+This is suitable for prototyping, but isn't intended for production use, if only because user/password credentials are stored in plain text.  Nevertheless, it's a good starting point.  The app generated by the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] is configured to use this realm.
 
 The diagram below shows the Isis and components involved:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugtst_bdd-spec-support_maven-configuration.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugtst_bdd-spec-support_maven-configuration.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugtst_bdd-spec-support_maven-configuration.adoc
index a1d15a1..edc20e3 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugtst_bdd-spec-support_maven-configuration.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugtst_bdd-spec-support_maven-configuration.adoc
@@ -7,7 +7,7 @@
 
 
 
-Apache Isis' BDD spec support is automatically configured if you use the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype].  To set it up manually, update the `pom.xml` of your domain object model module:
+Apache Isis' BDD spec support is automatically configured if you use the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].  To set it up manually, update the `pom.xml` of your domain object model module:
 
 [source,xml]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugtst_bdd-spec-support_writing-a-bdd-spec.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugtst_bdd-spec-support_writing-a-bdd-spec.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugtst_bdd-spec-support_writing-a-bdd-spec.adoc
index 33e26d7..b8e483c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugtst_bdd-spec-support_writing-a-bdd-spec.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugtst_bdd-spec-support_writing-a-bdd-spec.adoc
@@ -24,7 +24,7 @@ The `glue` attribute of the Cucumber-JVM JUnit runner eallows you to indicate wh
 * a system initializer class.  You can reuse the  system initializer from any integration tests (as described in xref:ugtst.adoc#_ugtst_integ-test-support[Integration Test Support], bootstrapping section).
 
 
-Here's an example of a feature from the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype]:
+Here's an example of a feature from the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]:
 
 [source,java]
 ----
@@ -49,7 +49,7 @@ Apache Isis does also support running BDD specs in unit test mode; by annotating
 
 To support unit testing scope Apache Isis provides the `InMemoryDB` class; a glorified hashmap of "persisted" objects.  Use of this utility class is optional.
 
-Writing a BDD spec that supports both modes of operation therefore takes more effort and we expect most users interested in BDD will use integration-testing scope; for these reasons we have chosen _not_ to include unit-testing support in the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype].  For those who do require faster-executing test suite, it's worthwhile knowing that Apache Isis can support this.
+Writing a BDD spec that supports both modes of operation therefore takes more effort and we expect most users interested in BDD will use integration-testing scope; for these reasons we have chosen _not_ to include unit-testing support in the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].  For those who do require faster-executing test suite, it's worthwhile knowing that Apache Isis can support this.
 
 ====
 
@@ -72,7 +72,7 @@ public class RunSpecs {
 }
 ----
 
-The JSON formatter allows integration with enhanced reports, for example as provided by http://www.masterthought.net/section/cucumber-reporting[Masterthought.net] (screenshots at end of page). (Commented out) configuration for this is provided in the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype].
+The JSON formatter allows integration with enhanced reports, for example as provided by http://www.masterthought.net/section/cucumber-reporting[Masterthought.net] (screenshots at end of page). (Commented out) configuration for this is provided in the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
 
 The bootstrapping of Apache Isis can be moved into a `BootstrappingGlue` step definition:
 


[03/52] [abbrv] isis git commit: ISIS-1234: extracted configuration guide from rg.adoc.

Posted by mg...@apache.org.
ISIS-1234: extracted configuration guide from rg.adoc.


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/1409af28
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/1409af28
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/1409af28

Branch: refs/heads/ISIS-1224-select2-v4
Commit: 1409af28ad6538ee5dd4cbac9079c7036f1f7b3a
Parents: f4f2631
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Thu Dec 3 17:23:45 2015 +0000
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Dec 3 17:23:45 2015 +0000

----------------------------------------------------------------------
 ...tes_1.8.0-to-1.9.0_exception-recognizer.adoc |   2 +-
 .../src/main/asciidoc/documentation.adoc        |   4 +-
 .../asciidoc/guides/_cg_asciidoc-templates.adoc |   8 +-
 .../src/main/asciidoc/guides/_rg_classes.adoc   |   2 +-
 .../asciidoc/guides/_rg_methods_reserved.adoc   |   2 +-
 .../_rg_methods_reserved_manpage-cssClass.adoc  |   4 +-
 .../src/main/asciidoc/guides/_rg_runtime.adoc   |  28 --
 .../_rg_runtime_application-specific.adoc       |  13 -
 ...me_application-specific_application-css.adoc |   8 -
 ...ime_application-specific_application-js.adoc |   9 -
 .../guides/_rg_runtime_configuration-files.adoc |  40 --
 .../guides/_rg_runtime_configuring-core.adoc    | 455 -------------------
 .../_rg_runtime_configuring-datanucleus.adoc    |  18 -
 ...s_disabling-persistence-by-reachability.adoc |  88 ----
 ...atanucleus_eagerly-registering-entities.adoc |  23 -
 ...configuring-datanucleus_persistence-xml.adoc |  10 -
 ...time_configuring-datanucleus_properties.adoc |  66 ---
 ...ring-datanucleus_using-jndi-data-source.adoc |  75 ---
 .../guides/_rg_runtime_deployment-types.adoc    | 111 -----
 .../_rg_runtime_specifying-components.adoc      | 110 -----
 .../asciidoc/guides/_rgant-ActionLayout.adoc    |   2 +-
 .../guides/_rgant-ActionLayout_cssClass.adoc    |   2 +-
 .../asciidoc/guides/_rgant-Action_command.adoc  |   2 +-
 .../guides/_rgant-Action_publishing.adoc        |   2 +-
 .../guides/_rgant-Action_restrictTo.adoc        |   2 +-
 .../guides/_rgant-CollectionLayout.adoc         |   2 +-
 .../_rgant-CollectionLayout_cssClass.adoc       |   2 +-
 .../guides/_rgant-CollectionLayout_paged.adoc   |   2 +-
 .../guides/_rgant-Collection_editing.adoc       |   2 +-
 .../guides/_rgant-DomainObjectLayout.adoc       |   2 +-
 .../_rgant-DomainObjectLayout_cssClass.adoc     |   2 +-
 .../guides/_rgant-DomainObjectLayout_paged.adoc |   2 +-
 .../guides/_rgant-DomainObject_auditing.adoc    |   2 +-
 .../guides/_rgant-DomainObject_editing.adoc     |   2 +-
 .../guides/_rgant-DomainObject_publishing.adoc  |   2 +-
 .../asciidoc/guides/_rgant-ParameterLayout.adoc |   2 +-
 .../guides/_rgant-ParameterLayout_cssClass.adoc |   2 +-
 .../asciidoc/guides/_rgant-PostConstruct.adoc   |   2 +-
 .../asciidoc/guides/_rgant-PropertyLayout.adoc  |   4 +-
 .../guides/_rgant-PropertyLayout_cssClass.adoc  |   2 +-
 .../_rgant-PropertyLayout_labelPosition.adoc    |   2 +-
 .../guides/_rgant-Property_editing.adoc         |   2 +-
 .../asciidoc/guides/_rgant-ViewModelLayout.adoc |   2 +-
 .../guides/_rgant-ViewModelLayout_cssClass.adoc |   2 +-
 .../guides/_rgant-ViewModelLayout_paged.adoc    |   2 +-
 .../guides/_rgcfg_configuration-files.adoc      |  40 ++
 .../guides/_rgcfg_configuring-core.adoc         | 455 +++++++++++++++++++
 .../guides/_rgcfg_configuring-datanucleus.adoc  |  18 +
 ...s_disabling-persistence-by-reachability.adoc |  88 ++++
 ...atanucleus_eagerly-registering-entities.adoc |  23 +
 ...configuring-datanucleus_persistence-xml.adoc |  10 +
 ...gcfg_configuring-datanucleus_properties.adoc |  66 +++
 ...ring-datanucleus_using-jndi-data-source.adoc |  75 +++
 .../guides/_rgcfg_deployment-types.adoc         | 111 +++++
 .../guides/_rgcfg_specifying-components.adoc    | 110 +++++
 .../guides/_rgsvc-api_ClockService.adoc         |   4 +-
 .../guides/_rgsvc-api_CommandContext.adoc       |   2 +-
 ...nObjectContainer_object-persistence-api.adoc |   2 +-
 ...pi_DomainObjectContainer_properties-api.adoc |   2 +-
 .../guides/_rgsvc-api_EmailService.adoc         |   2 +-
 .../guides/_rgsvc-api_EventBusService.adoc      |   2 +-
 .../_rgsvc-api_FixtureScriptsDefault.adoc       |   2 +-
 .../_rgsvc-spi_ContentNegotiationService.adoc   |   4 +-
 .../guides/_rgsvc-spi_ExceptionRecognizer.adoc  |   2 +-
 .../_rgsvc-spi_UserRegistrationService.adoc     |   2 +-
 ...g_how-tos_ui-hints_action-icons-and-css.adoc |   4 +-
 ...b_deployment_externalized-configuration.adoc |   2 +-
 .../guides/_ugbtb_deployment_tomcat.adoc        |   2 +-
 ...btb_more-advanced_decoupling_db-schemas.adoc |   2 +-
 .../guides/_ugbtb_more-advanced_i18n.adoc       |   4 +-
 .../main/asciidoc/guides/_ugbtb_web-xml.adoc    |   2 +-
 .../guides/_ugsec_usage-by-isis-viewers.adoc    |   2 +-
 .../asciidoc/guides/_ugvro_hints-and-tips.adoc  |   2 +-
 .../guides/_ugvw_customisation_brand-logo.adoc  |   2 +-
 ...ugvw_customisation_tweaking-css-classes.adoc |   4 +-
 .../src/main/asciidoc/guides/_ugvw_layout.adoc  |   2 +-
 .../src/main/asciidoc/guides/rg.adoc            |  12 +-
 .../src/main/asciidoc/guides/rgcfg.adoc         |  32 ++
 .../src/main/asciidoc/guides/ug.adoc            |  16 +-
 79 files changed, 1112 insertions(+), 1124 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_exception-recognizer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_exception-recognizer.adoc b/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_exception-recognizer.adoc
index 79f6a89..11683ab 100644
--- a/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_exception-recognizer.adoc
+++ b/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_exception-recognizer.adoc
@@ -42,7 +42,7 @@ public class EstatioIntegTestBuilder extends IsisSystemForTest.Builder {
 
 If you fail to do this you will get an exception to the effect of duplicate service Ids being registered.
 
-Now that the `ExceptionRecognizerCompositeForJdoObjectStore` no longer needs to be explicitly registered, you might (very rarely) require the opposite situation, namely to disable the service.  As this can't be done by just removing it from `isis.poperties`, you instead can set a new xref:rg.adoc#_rg_runtime_configuring-core[configuration property] `isis.services.ExceptionRecognizerCompositeForJdoObjectStore.disable`:
+Now that the `ExceptionRecognizerCompositeForJdoObjectStore` no longer needs to be explicitly registered, you might (very rarely) require the opposite situation, namely to disable the service.  As this can't be done by just removing it from `isis.poperties`, you instead can set a new xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.services.ExceptionRecognizerCompositeForJdoObjectStore.disable`:
 
 [source,ini]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/documentation.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/documentation.adoc b/adocs/documentation/src/main/asciidoc/documentation.adoc
index 90e7fef..d119f8c 100644
--- a/adocs/documentation/src/main/asciidoc/documentation.adoc
+++ b/adocs/documentation/src/main/asciidoc/documentation.adoc
@@ -69,9 +69,11 @@ pass:[<br/>]
 
 |*Reference Guides:*
 
-* link:./guides/rg.html[Reference Guide^]
 * link:./guides/rgant.html[Annotations^]
 * link:./guides/rgsvc.html[Domain Services^]
+* link:./guides/rgcfg.html[Configuration Properties^]
+* link:./guides/rg.html[Classes, Methods and Schema^]
+
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_cg_asciidoc-templates.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_asciidoc-templates.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_asciidoc-templates.adoc
index 04ebf6f..9b2cc8c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_cg_asciidoc-templates.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_asciidoc-templates.adoc
@@ -201,18 +201,18 @@ a hyperlink to a level 3 (chapter, section, subsection) within the reference gui
 
 for example:
 
-pass:[<pre>xref:rg.adoc#_rg_runtime_application-specific_application-css[Application-specific CSS\]</pre>]
+pass:[<pre>xref:rgcfg.adoc#_rgcfg_application-specific_application-css[Application-specific CSS\]</pre>]
 
-|xref:rg.adoc#_rg_runtime_application-specific_application-css[Application-specific CSS]
+|xref:rgcfg.adoc#_rgcfg_application-specific_application-css[Application-specific CSS]
 
 
 
 |`adrgcfg`
-|pass:[<pre>xref:rg.adoc#_rg_runtime_configuring-core[configuration properties]</pre>]
+|pass:[<pre>xref:rgcfg.adoc#_rgcfg_configuring-core[configuration properties]</pre>]
 
 a hyperlink to the reference guide's catalogue of the Apache Isis configuration properties.
 
-|xref:rg.adoc#_rg_runtime_configuring-core[configuration properties]
+|xref:rgcfg.adoc#_rgcfg_configuring-core[configuration properties]
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rg_classes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes.adoc
index 65d976f..0479db0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-This chapter describes the usage of various classes and interfaces that are not otherwise associated with xref:rgsvc.adoc#_rgsvc-api[domain] xref:rgsvc.adoc#_rgsvc-spi[services], xref:ug.adoc#_ug_object-layout[object layout] or xref:rg.adoc#_rg_runtime[configuration].
+This chapter describes the usage of various classes and interfaces that are not otherwise associated with xref:rgsvc.adoc#_rgsvc-api[domain] xref:rgsvc.adoc#_rgsvc-spi[services], xref:ug.adoc#_ug_object-layout[object layout] or xref:rgcfg.adoc#_rgcfg[configuration].
 
 
 include::_rg_classes_AppManifest-bootstrapping.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved.adoc
index 7d285c6..762a8bb 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved.adoc
@@ -16,7 +16,7 @@ The table below lists the reserved methods that are recognized as part of Apache
 |Description
 
 |xref:rg.adoc#_rg_methods_reserved_manpage-cssClass[`cssClass()`]
-|Provides a CSS class for this object instance.  In conjunction with xref:rg.adoc#_rg_runtime_application-specific_application-css[`application.css`], can therefore provide custom styling of an object instance wherever it is rendered. +
+|Provides a CSS class for this object instance.  In conjunction with xref:rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css`], can therefore provide custom styling of an object instance wherever it is rendered. +
 
 See also xref:rg.adoc#_rg_methods_reserved_manpage-title[`title()`] and xref:rg.adoc#_rg_methods_reserved_manpage-iconName[`iconName()`].
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-cssClass.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-cssClass.adoc
index fcc09f8..e0b388f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-cssClass.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-cssClass.adoc
@@ -10,7 +10,7 @@ The `cssClass()` returns a CSS class for a particular object instance.
 
 The xref:ugvw.adoc#[Wicket viewer] wraps the object's representation in a containing `<div>` with the class added.  This is done both for rendering the object either in a table or when rendering the object on its own page.
 
-In conjunction with xref:rg.adoc#_rg_runtime_application-specific_application-css[`application.css`], can therefore provide custom styling of an object instance wherever it is rendered. +
+In conjunction with xref:rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css`], can therefore provide custom styling of an object instance wherever it is rendered. +
 
 
 For example, the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] uses this technique to add a strikethrough for completed todo items.  This is shown on the home page:
@@ -30,7 +30,7 @@ public class ToDoItem ... {
 }
 ----
 
-In the xref:rg.adoc#_rg_runtime_application-specific_application-css[application.css], the following styles were then added:
+In the xref:rgcfg.adoc#_rgcfg_application-specific_application-css[application.css], the following styles were then added:
 
 [source,css]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/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
deleted file mode 100644
index 7577e68..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime.adoc
+++ /dev/null
@@ -1,28 +0,0 @@
-[[_rg_runtime]]
-= 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/
-
-
-Isis' own configuration properties are simple key-value pairs, typically held in the `WEBINF/isis.properties` file and other related files.  This chapter describes how to configure an Apache Isis application.
-
-[NOTE]
-====
-Configuration properties for the viewers can be found in the xref:ugvw.adoc#[Wicket Viewer] chapter and the xref:ugvro.adoc#[RestfulObjects viewer] chapter.  Likewise[details of configuring security (Apache Shiro) can be found in the xref:ugsec.adoc#[Security] chapter.
-
-Also, note that by default the configuration values are part of the built WAR file.  Details on how to override these configuration properties externally for different environments can be found in the xref:ugbtb.adoc#_ugbtb_deployment[Deployment] chapter.
-====
-
-
-include::_rg_runtime_deployment-types.adoc[leveloffset=+1]
-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_application-specific.adoc[leveloffset=+1]
-
-
-
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_application-specific.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_application-specific.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_application-specific.adoc
deleted file mode 100644
index 9f5be17..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_application-specific.adoc
+++ /dev/null
@@ -1,13 +0,0 @@
-[[_rg_runtime_application-specific]]
-= Application-specific CSS and JS
-: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/
-
-NOTE: TODO
-
-
-include::_rg_runtime_application-specific_application-css.adoc[leveloffset=+1]
-include::_rg_runtime_application-specific_application-js.adoc[leveloffset=+1]
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_application-specific_application-css.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_application-specific_application-css.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_application-specific_application-css.adoc
deleted file mode 100644
index 93100f1..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_application-specific_application-css.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-[[_rg_runtime_application-specific_application-css]]
-= `application.css`
-: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/
-
-NOTE: TODO - `WEB-INF/css/application.css`
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_application-specific_application-js.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_application-specific_application-js.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_application-specific_application-js.adoc
deleted file mode 100644
index 1699cf8..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_application-specific_application-js.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-[[_rg_runtime_application-specific_application-js]]
-= `application.js`
-: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/
-
-
-
-NOTE: TODO - `WEB-INF/scripts/application.js`

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_configuration-files.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_configuration-files.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_configuration-files.adoc
deleted file mode 100644
index 3d5d131..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_configuration-files.adoc
+++ /dev/null
@@ -1,40 +0,0 @@
-[[_rg_runtime_configuration-files]]
-= Configuration Files
-: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/
-
-
-When running an Apache Isis webapp, configuration properties are read from configuration files held in the `WEB-INF` directory.
-
-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 xref:ugvw.adoc#[Wicket viewer] is in use
-
-* `viewer_restfulobjects.properties` - if the xref:ugvro.adoc#[RestfulObjects viewer] is in use
-
-* `viewer.properties` - for any other viewer configuration (but there are none currently)
-
-* `persistor_datanucleus.properties` - assuming the JDO/DataNucleus objectstore is in use
-
-* `persistor.properties` - for any other objectstore configuration.  +
-+
-This typically is used to hold `JDBC` ``URL``s, which is arguably a slight violation of the file (because there's nothing in Apache Isis to say that persistors have to use `JDBC`.  However, it is generally convenient to put these `JDBC` settings into a single location.  If you want, they could reside inin any of `persistor_datanucleus.properties`, `persistor.properties` or (even) `isis.properties`
-
-* `authentication_shiro.properties`, `authorization_shiro.properties`
-+
-assuming the Shiro Security is in use (but there are no security-related config properties currently; use shiro.ini for Shiro config)
-
-* `authentication.properties`, `authorization.properties` +
-+
-for any other security-related config properties (but there are none currently).
-
-You can if you wish simply store all properties in the `isis.properties` file; but we think that breaking properties out into sections is preferable.
-
-
-
-
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_configuring-core.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_configuring-core.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_configuring-core.adoc
deleted file mode 100644
index 63b1f9c..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_configuring-core.adoc
+++ /dev/null
@@ -1,455 +0,0 @@
-[[_rg_runtime_configuring-core]]
-= Configuring Core
-: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 section lists the core/runtime configuration properties recognized by Apache Isis.
-
-[NOTE]
-====
-Configuration properties for the JDO/DataNucleus objectstore can be found in the xref:rg.adoc#_rg_runtime_configuring-datanucleus[Configuring DataNucleus] section later in this chapter, while configuration properties for the viewers can be found in the their respective chapters, xref:ugvw.adoc#_ugvw_configuration-properties[here for Wicket viewer], and xref:ugvro.adoc#_ugvro_configuration-properties[here for the Restful Objects viewer].
-====
-
-
-
-.Core Configuration Properties
-[cols="2a,1,3a", options="header"]
-|===
-|Property
-|Value +
-(default value)
-|Description
-
-|`isis.object.` +
-`editing`
-|`true`,`false` +
-(`true`)
-|Whether objects' properties and collections can be edited directly (for objects annotated with xref:rgant.adoc#_rgant-DomainObject_editing[`@DomainObject#editing()`]); see xref:rg.adoc#_rg_runtime_configuring-core_isis-objects-editing[below] for further discussion.
-
-
-|`isis.persistor.` +
-`disableConcurrencyChecking`
-|`true`,`false` +
-(`false`)
-| Disables concurrency checking globally.  +
-
-Only intended for "emergency use" as a workaround while pending fix/patch to Apache Isis itself.  (Note that there is no "datanucleus" in the property).
-
-|`isis.reflector.facet.` +
-`actionAnnotation.` +
-`domainEvent.postForDefault`
-|`true`,`false` +
-(`true`)
-|Whether an event should be posted if xref:rgant.adoc#_rgant-Action_domainEvent[`@Action#domainEvent()`] is not specified (is set to `ActionDomainEvent.Default`).
-
-|`isis.reflector.facet.` +
-`collectionAnnotation.` +
-`domainEvent.postForDefault`
-|`true`,`false` +
-(`true`)
-|Whether an event should be posted if xref:rgant.adoc#_rgant-Collection_domainEvent[`@Collection#domainEvent()`] is not specified (is set to `CollectionDomainEvent.Default`).
-
-|`isis.reflector.facet.` +
-`cssClass.patterns`
-|regex:css1, regex2:css2,...
-|Comma separated list of key:value pairs, where the key is a regex matching action names (eg `delete.*`) and the value is a link:http://getbootstrap.com/css/[Bootstrap] CSS button class (eg `btn-warning) to be applied (as per `@CssClass()`) to all action members matching the regex. +
-
-See xref:ug.adoc#_ug_how-tos_ui-hints_action-icons-and-css[UI hints] for more details.
-
-|`isis.reflector.facet.` +
-`cssClassFa.patterns`
-|regex:fa-icon,regex2:fa-icon2,...
-|Comma separated list of key:value pairs, where the key is a regex matching action names (eg `create.*`) and the value is a link:http://fortawesome.github.io/Font-Awesome/icons/[font-awesome] icon name (eg `fa-plus`) to be applied (as per `@CssClassFa()`) to all action members matching the regex. +
-
-See xref:ug.adoc#_ug_how-tos_ui-hints_action-icons-and-css[UI hints] for more details.
-
-|`isis.reflector.facet.` +
-`domainObjectAnnotation.` +
-`createdLifecycleEvent.` +
-`postForDefault` +
-(`1.11.0-SNAPSHOT`)
-|`true`,`false` +
-(`true`)
-|Whether an event should be posted if xref:rgant.adoc#_rgant-DomainObject_createdLifecycleEvent[`@DomainObject#createdLifecycleEvent()`] is not specified (is set to `ObjectCreatedEvent.Default`).
-
-|`isis.reflector.facet.` +
-`domainObjectAnnotation.` +
-`loadedLifecycleEvent.` +
-`postForDefault` +
-(`1.11.0-SNAPSHOT`)
-|`true`,`false` +
-(`true`)
-|Whether an event should be posted if xref:rgant.adoc#_rgant-DomainObject_loadedLifecycleEvent[`@DomainObject#loadedLifecycleEvent()`] is not specified (is set to `ObjectLoadedEvent.Default`).
-
-|`isis.reflector.facet.` +
-`domainObjectAnnotation.` +
-`persistingLifecycleEvent.` +
-`postForDefault` +
-(`1.11.0-SNAPSHOT`)
-|`true`,`false` +
-(`true`)
-|Whether an event should be posted if xref:rgant.adoc#_rgant-DomainObject_persistingLifecycleEvent[`@DomainObject#persistingLifecycleEvent()`] is not specified (is set to `ObjectPersistingEvent.Default`).
-
-|`isis.reflector.facet.` +
-`domainObjectAnnotation.` +
-`persistedLifecycleEvent.` +
-`postForDefault` +
-(`1.11.0-SNAPSHOT`)
-|`true`,`false` +
-(`true`)
-|Whether an event should be posted if xref:rgant.adoc#_rgant-DomainObject_persistedLifecycleEvent[`@DomainObject#persistedLifecycleEvent()`] is not specified (is set to `ObjectPersistedEvent.Default`).
-
-|`isis.reflector.facet.` +
-`domainObjectAnnotation.` +
-`removingLifecycleEvent.` +
-`postForDefault` +
-(`1.11.0-SNAPSHOT`)
-|`true`,`false` +
-(`true`)
-|Whether an event should be posted if xref:rgant.adoc#_rgant-DomainObject_removingLifecycleEvent[`@DomainObject#removingLifecycleEvent()`] is not specified (is set to `ObjectRemovingEvent.Default`).
-
-|`isis.reflector.facet.` +
-`domainObjectAnnotation.` +
-`updatingLifecycleEvent.` +
-`postForDefault` +
-(`1.11.0-SNAPSHOT`)
-|`true`,`false` +
-(`true`)
-|Whether an event should be posted if xref:rgant.adoc#_rgant-DomainObject_updatingLifecycleEvent[`@DomainObject#updatingLifecycleEvent()`] is not specified (is set to `ObjectUpdatingEvent.Default`).
-
-|`isis.reflector.facet.` +
-`domainObjectAnnotation.` +
-`updatedLifecycleEvent.` +
-`postForDefault` +
-(`1.11.0-SNAPSHOT`)
-|`true`,`false` +
-(`true`)
-|Whether an event should be posted if xref:rgant.adoc#_rgant-DomainObject_updatedLifecycleEvent[`@DomainObject#updatedLifecycleEvent()`] is not specified (is set to `ObjectUpdatedEvent.Default`).
-
-|`isis.reflector.facet.` +
-`domainObjectLayoutAnnotation.` +
-`cssClassUiEvent.postForDefault` +
-(`1.11.0-SNAPSHOT`)
-|`true`,`false` +
-(`true`)
-|Whether an event should be posted if xref:rgant.adoc#_rgant-DomainObjectLayout_cssClassUiEvent[`@DomainObjectLayout#cssClassUiEvent()`] is not specified (is set to `CssClassUiEvent.Default`).
-
-|`isis.reflector.facet.` +
-`domainObjectLayoutAnnotation.` +
-`iconUiEvent.postForDefault` +
-(`1.11.0-SNAPSHOT`)
-|`true`,`false` +
-(`true`)
-|Whether an event should be posted if xref:rgant.adoc#_rgant-DomainObjectLayout_iconUiEvent[`@DomainObjectLayout#iconUiEvent()`] is not specified (is set to `IconUiEvent.Default`).
-
-|`isis.reflector.facet.` +
-`domainObjectLayoutAnnotation.` +
-`titleUiEvent.postForDefault` +
-(`1.11.0-SNAPSHOT`)
-|`true`,`false` +
-(`true`)
-|Whether an event should be posted if xref:rgant.adoc#_rgant-DomainObjectLayout_titleUiEvent[`@DomainObjectLayout#titleUiEvent()`] is not specified (is set to `TitleUiEvent.Default`).
-
-|`isis.reflector.facet.` +
-`filterVisibility`
-|`true`,`false` +
-(`true`)
-|Whether objects should be filtered for visibility. +
-
-See xref:rg.adoc#_rg_runtime_configuring-core_filterVisibility[section below] for further discussion.
-
-|`isis.reflector.facet.` +
-`propertyAnnotation.` +
-`domainEvent.postForDefault`
-|`true`,`false` +
-(`true`)
-|Whether an event should be posted if xref:rgant.adoc#_rgant-Property_domainEvent[`@Property#domainEvent()`] is not specified (is set to `PropertyDomainEvent.Default`).
-
-|`isis.reflector.facets`
-|`FQCN`
-|Fully qualified class names of a custom implementation of `ProgrammingModel` interface. +
-
-See xref:ugbtb.adoc#_ugbtb_programming-model_finetuning[finetuning the programming model] for more details.
-
-|`isis.reflector.facets.` +
-`exclude`
-|`FQCN`,`FQCN2`,...
-|Fully qualified class names of (existing, built-in) facet factory classes to be included to the programming model. +
-
-See xref:ugbtb.adoc#_ugbtb_programming-model_finetuning[finetuning the programming model] for more details.
-
-|`isis.reflector.facets.` +
-`include`
-|`FQCN`,`FQCN2`,...
-|Fully qualified class names of (new, custom) facet factory classes to be included to the programming model. +
-See xref:ugbtb.adoc#_ugbtb_programming-model_finetuning[finetuning the programming model] for more details.
-
-
-|`isis.reflector.` +
-`layoutMetadataReaders`
-|`FQCN`,`FQCN2`,...
-|Fully qualified class names of classes to be instantiated to read layout metadata, as used in for xref:ug.adoc#_ug_object-layout_dynamic[dynamic layout]s. +
-
-See xref:ugbtb.adoc#_ugbtb_programming-model_layout-metadata-reader[Layout Metadata Reader] for more information.
-
-
-
-|`isis.reflector.validator`
-|`FQCN`
-|Custom implementation of `MetaModelValidator` (in the `org.apache.isis.core.metamodel.specloader.validator` package) +
-
-See xref:ugbtb.adoc#_ugbtb_programming-model_custom-validator[Custom Validator] to learn more.
-
-|`isis.reflector.validator.` +
-`allowDeprecated`
-|`true`,`false` +
-(`true`)
-| Whether deprecated annotations or naming conventions are tolerated or not.  If not, then a metamodel validation error will be triggered, meaning the app won't boot (fail-fast).
-
-
-|`isis.services`
-|`FQCN`,`FQCN2`,...
-|Fully qualified class names of classes to be instantiated as domain services.  +
-
-Each entry can be optionally prefixed by "n:" specifying the relative order on the menu (corresponds to xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`]).
-
-This property is IGNORED if the xref:rg.adoc#_rg_runtime_configuring-components[`isis.appManifest`] configuration property is specified, or if an xref:rg.adoc#_rg_classes_super_manpage-AppManifest[`AppManifest`] is provided programmatically.
-
-
-|`isis.services.` +
-`audit.objects`
-| `all`, `none` +
-(`all`)
-|Whether the changed properties of objects should be automatically audited (for objects annotated with xref:rgant.adoc#_rgant-DomainObject_auditing[`@DomainObject(auditing=Auditing.AS_CONFIGURED)`].
-
-|`isis.services.` +
-`command.actions`
-| `all`, `ignoreSafe`, `none` (`all`)
-|Whether actions should be automatically reified into commands (for actions annotated with xref:rgant.adoc#_rgant-Action_command[`@Action(command=CommandReification.AS_CONFIGURED)`].  +
-
-`ignoreQueryOnly` is an alias for `ignoreSafe`.
-
-
-|`isis.services.` +
-`container.disableAutoFlush`
-|`true`,`false` +
-(`false`)
-|Whether the `DomainObjectContainer` should automatically flush pending changes prior to querying (via `allMatches()`, `firstMatch()` and so on).
-
-|`isis.services.` +
-`container.disableAutoFlush`
-|`true`,`false` +
-(`false`)
-|Whether the `DomainObjectContainer` should automatically flush pending changes prior to querying (via `allMatches()`, `firstMatch()` and so on).
-
-
-
-|`isis.services.` +
-`ContentNegotiation-` +
-`ServiceXRoDomainType` +
-.prettyPrint
-| `true`,`false` +
-(depends)
-|If a domain object has been mapped to the specified JAXB `x-ro-domain-type`, then determines whether the result is pretty-printed or not. +
-+
-If no configuration property is available, then the defaults is determined by the xref:rg.adoc#_rg_runtime_deployment-types[deployment type]: production mode disables pretty printing, while prototype mode enables it.
-
-
-
-| `isis.service.` +
-`email.tls.enabled`
-|`true`,`false` +
-(`true`)
-|Whether to enable TLS for the email SMTP connection (used by xref:rgsvc.adoc#_rgsvc-api_EmailService[`EmailService`]).  +
-
-NB: note that the key is mis-spelt, (`isis.service.email` rather than `isis.services.email`)
-
-| `isis.service.` +
-`email.sender.hostname` +
-| host (`_smtp.gmail.com_`)
-|The hostname of the external SMTP provider (used by xref:rgsvc.adoc#_rgsvc-api_EmailService[`EmailService`]).  +
-
-NB: note that the key is mis-spelt, (`isis.service.email` rather than `isis.services.email`)
-
-| `isis.service.` +
-`email.port` +
-| port number (`_587_`)
-|The port number for the SMTP service on the the external SMTP host (used by xref:rgsvc.adoc#_rgsvc-api_EmailService[`EmailService`]).  +
-
-NB: note that the key is mis-spelt, (`isis.service.email` rather than `isis.services.email`)
-
-
-| `isis.service.` +
-`email.sender.address` +
-| email address
-|The email address to use for sending out email (used by xref:rgsvc.adoc#_rgsvc-api_EmailService[`EmailService`]).  *Mandatory*.  +
-
-NB: note that the key is mis-spelt, (`isis.service.email` rather than `isis.services.email`)
-
-| `isis.service.` +
-`email.sender.password` +
-| email password
-|The corresponding password for the email address to use for sending out email (used by xref:rgsvc.adoc#_rgsvc-api_EmailService[`EmailService`]).  *Mandatory*.  +
-
-NB: note that the key is mis-spelt, (`isis.service.email` rather than `isis.services.email`)
-
-
-| `isis.services.` +
-`eventbus.implementation` +
-| `guava`, `axon`, +
-FQCN (`_guava_`)
-|which implementation to use by the xref:rgsvc.adoc#_rgsvc-api_EventBusService[`EventBusService`] as the underlying event bus.
-
-| `isis.services.` +
-`eventbus.allowLateRegistration` +
-|`true`,`false` +
-(`false`)
-|whether a domain service can register with the xref:rgsvc.adoc#_rgsvc-api_EventBusService[`EventBusService`] after any events have posted. +
-
-Since this almost certainly constitutes a bug in application code, by default this is disallowed.
-
-
-| `isis.services.` +
-`exceprecog.logRecognizedExceptions` +
-|`true`,`false` +
-(`false`)
-|whether recognized exceptions should also be logged. +
-
-Generally a recognized exception is one that is expected (for example a uniqueness constraint violated in the database) and which does not represent an error condition.  This property logs the exception anyway, useful for debugging.
-
-
-| `isis.services.` +
-`ExceptionRecognizerComposite-` +
-`ForJdoObjectStore.disable` +
-|`true`,`false` +
-(`false`)
-|whether to disable the default recognizers registered by `ExceptionRecognizerCompositeForJdoObjectStore`. +
-
-This implementation provides a default set of recognizers to convert RDBMS constraints into user-friendly messages.  In the (probably remote) chance that this functionality isn't required, they can be disabled through this flag.
-
-
-|`isis.services.` +
-`publish.objects`
-| `all`, `none` +
-(`all`)
-|Whether changed objects should be automatically published (for objects annotated with xref:rgant.adoc#_rgant-DomainObject_publishing[`@DomainObject(publishing=Publishing.AS_CONFIGURED)`].
-
-|`isis.services.` +
-`publish.actions`
-| `all`, `ignoreSafe`, `none` (`all`)
-|Whether actions should be automatically published (for actions annotated with xref:rgant.adoc#_rgant-Action_publishing[`@Action(publishing=Publishing.AS_CONFIGURED)`]. +
-
-
-|`isis.services.` +
-`ServicesInstallerFromAnnotation.` +
-`packagePrefix`
-|fully qualified package names (CSV)
-|to search for domain services (including all subpackages).
-
-This property is IGNORED if the xref:rg.adoc#_rg_runtime_configuring-components[`isis.appManifest`] configuration property is specified, or if an xref:rg.adoc#_rg_classes_super_manpage-AppManifest[`AppManifest`] is provided programmatically.
-
-
-|`isis.services.` +
-`translation.po.mode`
-| `read`,`write`
-|Whether to force the `TranslationService` into either read or write mode. +
-
-See xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[i18n support] to learn more about the translation service.
-
-|`isis.viewers.` +
-`paged.parented`
-|positive integer (12)
-|Default page size for parented collections (as owned by an object, eg `Customer#getOrders()`)
-
-|`isis.viewers.` +
-`paged.standalone`
-|positive integer (25)
-|Default page size for standalone collections (as returned from an action invocation)
-
-
-|`isis.viewers.` +
-`propertyLayout.labelPosition`
-|`TOP`, `LEFT` +
-(`LEFT`)
-|Default for label position for all properties if not explicitly specified using xref:rgant.adoc#_rgant-PropertyLayout_labelPosition[`@PropertyLayout#labelPosition()`]
-
-|===
-
-
-
-[[_rg_runtime_configuring-core_filterVisibility]]
-== Filtering visibility
-
-The framework provides the `isis.reflector.facet.filterVisibility` configuration property that influences whether a returned object is visible to the end-user:
-
-* Action invocations: +
-
-If an action returns a collection that includes the object, then the object will be excluded from the list when rendered. If it returns a single object and the user does not have access to that object, then the action will seemingly return `null`
-
-* Collections: +
-
-If a parent object has a collection references another object to which the user does not have access, then (as for actions) the object will not be rendered in the list
-
-* Properties: +
-
-If an parent object has a (scalar) reference some other object to which the user does not have access, then the reference will be rendered as empty.
-
-* Choices and autoComplete lists: +
-
-If an object is returned in a list of choices or within an auto-complete list, and the user does not have access, then it is excluded from the rendered list.
-
-The original motivation for this feature was to transparently support such features as multi-tenancy (as per the (non-ASF) http://github.com/isisaddons/isis-module-security[Isis addons' security] module).  That is, if an entity is logically "owned" by a user, then the multi-tenancy support can be arranged to prevent some other user from viewing that object.
-
-By default this configuration property is enabled.  To disable the visibility filtering, set the appropriate configuration property to `false`:
-
-[source,ini]
-----
-isis.reflector.facet.filterVisibility=false
-----
-
-Filtering is supported by the Wicket viewer, and by the xref:rgsvc.adoc#_rgsvc-api_WrapperFactory[`WrapperFactory`] domain service (provided the wrapper's execution mode is _not_ "skip rules").  However the Restful Objects viewer does _not_ currently support filtering.
-
-[NOTE]
-====
-In order for the framework to perform this filtering of collections, be aware that the framework takes a _copy_ of the original collection, filters on the collection, and returns that filtered collection rather than the original.
-
-There are no major side-effects from this algorithm, other than the fact that the referenced objects will (most likely) need to be resolved in order to determine if they are visible.  This could conceivably have a performance impact in some cases.
-====
-
-
-[[_rg_runtime_configuring-core_isis-objects-editing]]
-== `objects.editing`
-
-This configuration property in effect allows editing to be disabled globally for an application:
-
-[source,ini]
-----
-isis.objects.editing=false
-----
-
-We recommend enabling this feature; it will help drive out the underlying business operations (processes and procedures) that require objects to change; these can then be captured as business actions.
-
-
-
-[[_rg_runtime_configuring-core_isis-viewers-propertyLayout-labelPosition]]
-== `propertyLayout.labelPosition`
-
-If you want a consistent look-n-feel throughout the app, eg all property labels to the top, then it'd be rather
-frustrating to have to annotate every property.
-
-Instead, a default can be specified in `isis.properties`:
-
-[source,ini]
-----
-isis.viewers.propertyLayout.labelPosition=TOP
-----
-
-or
-
-[source,ini]
-----
-isis.viewers.propertyLayout.labelPosition=LEFT
-----
-
-If these are not present then Apache Isis will render according to internal defaults. At the time of writing, this means labels are to the left for all datatypes except multiline strings.

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_configuring-datanucleus.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_configuring-datanucleus.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_configuring-datanucleus.adoc
deleted file mode 100644
index 8892b58..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_configuring-datanucleus.adoc
+++ /dev/null
@@ -1,18 +0,0 @@
-[[_rg_runtime_configuring-datanucleus]]
-= Configuring DataNucleus
-: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 programmatically configures DataNucleus; any Apache 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 for itself also and read the `META-INF/persistence.xml`; at a minimum this defines the name of the "persistence unit".  n theory it could also hold mappings, though in Apache Isis we tend to use annotations instead.
-
-Furthermore, DataNucleus will search for various other XML mapping files, eg `mappings.jdo`.  A full list can be found http://www.datanucleus.org/products/datanucleus/jdo/metadata.html[here].  The metadata in these XML can be used to override the annotations of annotated entities; see xref:ugbtb.adoc#_ugbtb_more-advanced_overriding-jdo-annotations[Overriding JDO Annotatons] for further discussion.
-
-
-include::_rg_runtime_configuring-datanucleus_properties.adoc[leveloffset=+1]
-include::_rg_runtime_configuring-datanucleus_persistence-xml.adoc[leveloffset=+1]
-include::_rg_runtime_configuring-datanucleus_eagerly-registering-entities.adoc[leveloffset=+1]
-include::_rg_runtime_configuring-datanucleus_disabling-persistence-by-reachability.adoc[leveloffset=+1]
-include::_rg_runtime_configuring-datanucleus_using-jndi-data-source.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_configuring-datanucleus_disabling-persistence-by-reachability.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_configuring-datanucleus_disabling-persistence-by-reachability.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_configuring-datanucleus_disabling-persistence-by-reachability.adoc
deleted file mode 100644
index ba690ef..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_configuring-datanucleus_disabling-persistence-by-reachability.adoc
+++ /dev/null
@@ -1,88 +0,0 @@
-[[_rg_runtime_configuring-datanucleus_disabling-persistence-by-reachability]]
-= Persistence by Reachability
-: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/
-
-By default, JDO/DataNucleus supports the concept of http://www.datanucleus.org/products/datanucleus/jdo/orm/cascading.html[persistence-by-reachability]. That is, if
-a non-persistent entity is associated with an already-persistent entity, then DataNucleus will detect this and will automatically persist the associated object. Put another way: there is no need to call Apache Isis' `DomainObjectContainer#persist(.)` or `DomainObjectContainer#persistIfNotAlready(.)` methods.
-
-However, convenient though this feature is, you may find that it causes performance issues.
-
-[WARNING]
-====
-DataNucleus' persistence-by-reachability may cause performance issues.  We strongly recommend that you disable it.
-====
-
-One scenario in particular where this performance issues can arise is if your entities implement the `java.lang.Comparable` interface, and you have used Apache Isis' xref:rg.adoc#_rg_classes_utility_manpage-ObjectContracts[`ObjectContracts`] utility class. The issue here is that `ObjectContracts` implementation can cause DataNucleus to recursively rehydrate a larger number of associated entities. (More detail below).
-
-We therefore recommend that you disable persistence-by-reachability by adding the following to `persistor_datanucleus.properties`:
-
-[source,ini]
-----
-isis.persistor.datanucleus.impl.datanucleus.persistenceByReachabilityAtCommit=false
-----
-
-This change has been made to the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype]
-
-If you do disable this feature, then you will (of course) need to ensure that you explicitly persist all entities using the `DomainObjectContainer#persist(.)` or `DomainObjectContainer#persistIfNotAlready(.)` methods.
-
-
-
-
-
-== The issue in more detail
-
-Consider these entities (http://yuml.me/edit/b8681268[yuml.me/b8681268]):
-
-image::{_imagesdir}runtime/configuring-datanucleus/disabling-persistence-by-reachability/party-agreementrole-agreement.png[width="750px"]
-
-
-
-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.
-
-All these entities implement `Comparable` using `ObjectContracts`, and the implementation of ``AgreementRole``'s (simplified) is:
-
-[source,java]
-----
-public class AgreementRole {
-    ...
-    public int compareTo(AgreementRole other) {
-        return ObjectContracts.compareTo(this, other, "agreement","startDate","party");
-    }
-}
-----
-
-while ``Agreement``'s is implemented as:
-
-[source,java]
-----
-public class Agreement {
-    ...
-    public int compareTo(Agreement other) {
-        return ObjectContracts.compareTo(this, other, "reference");
-    }
-}
-----
-
-and ``Party``'s is similarly implemented as:
-
-[source,java]
-----
-public class Party {
-    ...
-    public int compareTo(Party other) {
-        return ObjectContracts.compareTo(this, other, "reference");
-    }
-}
-----
-
-DataNucleus's persistence-by-reachability algorithm adds the `AgreementRole` instances into a `SortedSet`, which causes `AgreementRole#compareTo()` to fire:
-
-* the evaluation of the "agreement" property delegates back to the `Agreement`, whose own `Agreement#compareTo()` uses the scalar `reference` property. As the `Agreement` is already in-memory, this does not trigger any further database queries
-
-* the evaluation of the "startDate" property is just a scalar property of the `AgreementRole`, so will already in-memory
-
-* the evaluation of the "party" property delegates back to the `Party`, whose own `Party#compareTo()` requires the uses the scalar `reference` property. However, since the `Party` is not yet in-memory, using the `reference` property triggers a database query to "rehydrate" the `Party` instance.
-
-In other words, in figuring out whether `AgreementRole` requires the persistence-by-reachability algorithm to run, it causes the adjacent associated entity `Party` to also be retrieved.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_configuring-datanucleus_eagerly-registering-entities.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_configuring-datanucleus_eagerly-registering-entities.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_configuring-datanucleus_eagerly-registering-entities.adoc
deleted file mode 100644
index 3abeb61..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_configuring-datanucleus_eagerly-registering-entities.adoc
+++ /dev/null
@@ -1,23 +0,0 @@
-[[_rg_runtime_configuring-datanucleus_eagerly-registering-entities]]
-= Eagerly Registering Entities
-: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/
-
-
-
-Both Apache Isis and DataNucleus have their own metamodels of the domain entities. Apache Isis builds its metamodel by walking the graph of types of the domain services.  The JDO/DataNucleus objectstore then takes these types and registers them with DataNucleus.
-
-In some cases, though, not every entity type is discoverable from the API of the service actions. This is especially the case if you have lots of subtypes (where the action method specifies only the supertype). In such cases the Isis and JDO metamodels is built lazily, when an instance of that (sub)type is first encountered.
-
-Apache Isis is quite happy for the metamodel to be lazily created, and - to be fair - DataNucleus also works well in most cases. In some cases, though, we have found that the JDBC driver (eg HSQLDB) will deadlock if DataNucleus tries to submit some DDL (for a lazily discovered type) intermingled with DML (for updating).  In any case, it's probably not good practice to have DataNucleus work this way.
-
-The framework thus provide mechanisms to search for all `@PersistenceCapable` entities under specified package(s), and registers them all eagerly.  In fact there are two:
-
-* as of 1.9.0 the recommended (and simpler) approach is to specify an xref:rg.adoc#_rg_classes_super_manpage-AppManifest[`AppManifest`], either as a xref:rg.adoc#_rg_runtime_configuring-components[`isis.appManifest`] configuration property or programmatically.
-
-* for earlier versions the `isis.persistor.datanucleus.RegisterEntities.packagePrefix` configuration property can be specified.  To bootstrap as a webapp this is usually specified in `persistor_datanucleus.properties`.  (This is also supported in 1.9.0 if no `AppManifest` is specified.  For integration testing this can be specified programatically.
-
-Further discussion on specifying the package(s) in integration testing (for either approach) can be found in the xref:ugtst.adoc#_ugtst_integ-test-support_bootstrapping[user guide].
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_configuring-datanucleus_persistence-xml.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_configuring-datanucleus_persistence-xml.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_configuring-datanucleus_persistence-xml.adoc
deleted file mode 100644
index 9227513..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_configuring-datanucleus_persistence-xml.adoc
+++ /dev/null
@@ -1,10 +0,0 @@
-[[_rg_runtime_configuring-datanucleus_persistence-xml]]
-= `persistence.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/
-
-
-NOTE: TODO
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_configuring-datanucleus_properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_configuring-datanucleus_properties.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_configuring-datanucleus_properties.adoc
deleted file mode 100644
index ba21167..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_configuring-datanucleus_properties.adoc
+++ /dev/null
@@ -1,66 +0,0 @@
-[[_rg_runtime_configuring-datanucleus_properties]]
-= 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/
-
-
-These configuration properties are typically stored in `WEB-INF/persistor_datanucleus.properties`.  However, you can place all configuration properties into `WEB-INF/isis.properties` if you wish (the configuration properties from all config files are merged together).
-
-== Configuration Properties for Apache Isis itself
-
-
-.JDO/DataNucleus Objectstore Configuration Properties
-[cols="2a,1,3a", options="header"]
-|===
-|Property
-|Value +
-(_default value_)
-|Description
-
-|`isis.persistor.` +
-`datanucleus.` +
-`classMetadataLoadedListener`
-|`FQCN`
-|The default (`o.a.i.os.jdo.dn.CreateSchemaObjectFromClassMetadata`) creates a DB schema object
-
-
-|`isis.persistor.datanucleus.` +
-`RegisterEntities.packagePrefix`
-|fully qualified package names (CSV)
-|that specifies the entities early rather than allow DataNucleus to find the entities lazily.  Further xref:rg.adoc#_rg_runtime_configuring-datanucleus_eagerly-registering-entities[discussion below].
-
-This property is IGNORED if the xref:rg.adoc#_rg_runtime_configuring-components[`isis.appManifest`] configuration property is specified, or if an xref:rg.adoc#_rg_classes_super_manpage-AppManifest[`AppManifest`] is provided programmatically.
-
-
-|`isis.persistor.datanucleus.` +
-`PublishingService.serializedForm`
-| zipped
-|
-
-|===
-
-
-
-== Configuration Properties passed through directly to DataNucleus.
-
-.JDO/DataNucleus Objectstore Configuration Properties
-[cols="2a,1,3a", options="header"]
-|===
-|Property
-|Value +
-(_default value_)
-|Description
-
-|`isis.persistor.datanucleus.impl.*`
-|
-| Passed through directly to Datanucleus (with `isis.persistor.datanucleus.impl` prefix stripped)
-
-|`isis.persistor.datanucleus.impl.` +
-`datanucleus.persistenceByReachabilityAtCommit`
-|`false`
-|We recommend this setting is disabled.  +
-Further xref:rg.adoc#_rg_runtime_configuring-datanucleus_disabling-persistence-by-reachability[discussion below].
-
-|===
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_configuring-datanucleus_using-jndi-data-source.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_configuring-datanucleus_using-jndi-data-source.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_configuring-datanucleus_using-jndi-data-source.adoc
deleted file mode 100644
index 1cac414..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_configuring-datanucleus_using-jndi-data-source.adoc
+++ /dev/null
@@ -1,75 +0,0 @@
-[[_rg_runtime_configuring-datanucleus_using-jndi-data-source]]
-= Using JNDI DataSource
-: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/
-
-Isis' JDO objectstore can be configured either to connect to the database using its own connection pool, or by using a container-managed datasource.
-
-
-
-== Application managed
-
-Using a connection pool managed directly by the application (that is, by Apache Isis' JDO objectstore and ultimately by DataNucleus) requires a single set of configuration properties to be specified.
-
-In the `WEB-INF\persistor_datanucleus.properties` file, specify the connection driver, url, username and password.
-
-For example:
-
-[source,ini]
-----
-isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionDriverName=net.sf.log4jdbc.DriverSpy
-isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionURL=jdbc:log4jdbc:hsqldb:mem:test
-isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionUserName=sa
-isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionPassword=
-----
-
-Those configuration properties that start with the prefix `isis.persistor.datanucleus.impl.` are passed through directly to DataNucleus (with the prefix removed).
-
-
-
-
-
-== Container managed (JNDI)
-
-Using a datasource managed by the servlet container requires three separate bits of configuration.
-
-Firstly, specify the name of the datasource in the `WEB-INF\persistor_datanucleus.properties` file. For example:
-
-If connection pool settings are also present in this file, they will simply be ignored. Any other configuration properties that start with the prefix `isis.persistor.datanucleus.impl.` are passed through directly to DataNucleus (with the prefix removed).
-
-Secondly, in the `WEB-INF/web.xml`, declare the resource reference:
-
-[source,xml]
-----
-<resource-ref>
-    <description>db</description>
-    <res-ref-name>jdbc/simpleapp</res-ref-name>
-    <res-type>javax.sql.DataSource</res-type>
-    <res-auth>Container</res-auth>
-</resource-ref>
-----
-
-Finally, declare the datasource as required by the servlet container. For example, if using Tomcat 7, the datasource can be specified by adding the following to `$TOMCAT_HOME/conf/context.xml`:
-
-[source,xml]
-----
-<Resource name="jdbc/simpleapp"
-  auth="Container"
-  type="javax.sql.DataSource"
-  maxActive="100"
-  maxIdle="30"
-  maxWait="10000"
-  username="sa"
-  password="p4ssword"
-  driverClassName="com.microsoft.sqlserver.jdbc.SQLServerDriver"
-  url="jdbc:sqlserver://127.0.0.1:1433;instance=.;databaseName=simpleapp"/>
-----
-
-You will also need to make sure that the JDBC driver is on the servlet container's classpath. For Tomcat, this means copying the driver to `$TOMCAT_HOME/lib`.
-
-[NOTE]
-====
-According to Tomcat's documentation, it is supposedly possible to copy the `conf/context.xml` to the name of the webapp, eg `conf/mywebapp.xml`, and scope the connection to that webapp only.  I was unable to get this working, however.
-====
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/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
deleted file mode 100644
index a8ce098..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_deployment-types.adoc
+++ /dev/null
@@ -1,111 +0,0 @@
-[[_rg_runtime_deployment-types]]
-= Deployment Types
-: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 distinguishes between the application being run in development mode vs running in production mode.  The framework calls this the "deployment type" (corresponding internally to the `DeploymentType` class).
-
-(For mostly historical reasons) development mode is actually called `SERVER_PROTOTYPE`, while production mode is called just `SERVER`.  (There is also a deprecated mode called `SERVER_EXPLORATION`; for all intents and purposes this can considered as an alias of `SERVER_PROTOTYPE`).
-
-When running in development/prototyping mode, certain capabilities are enabled; most notably any actions restricted to prototyping mode (using xref:rgant.adoc#_rgant-Action_restrictTo[`@Action#restrictTo()`]) will be available.
-
-
-
-== Using the Wicket Viewer
-
-Most of the you're likely to run Apache Isis using the xref:ugvw.adoc#[Wicket viewer].  In this case Apache Isis' "deployment type" concept maps to Wicket's "configuration" concept:
-
-.Apache Isis' deployment type corresponds to Apache Wicket's configuration
-[cols="1,1,2", options="header"]
-|===
-| Apache Isis +
-(Deployment Type)
-| Apache Wicket +
-(Configuration)
-| Notes
-
-| `SERVER_PROTOTYPE`
-| `development`
-| running in development/prototyping mode
-
-| `SERVER`
-| `deployment`
-| running in production mode
-
-|===
-
-
-Wicket's mechanism for specifying the "configuration" is to use a context parameter in `web.xml`; Apache Isis automatically infers its own deployment type from this.  In other words:
-
-* to specify SERVER (production) mode, use: +
-+
-[source,xml]
-.`web.xml`
-----
-<context-param>
-    <param-name>configuration</param-name>
-    <param-value>deployment</param-value>
-</context-param>
-----
-
-* to specify `SERVER_PROTOTYPING` (development) mode, use: +
-+
-[source,xml]
-.`web.xml`
-----
-<context-param>
-    <param-name>configuration</param-name>
-    <param-value>deployment</param-value>
-</context-param>
-----
-
-
-== Restful Objects viewer only
-
-Most Apache Isis applications will consist of at least the xref:ugvw.adoc#[Wicket viewer] and optionally the xref:ugvro.adoc#[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:ugbtb.adoc#_ugbtb_web-xml_servlet-context-listeners[ `IsisWebAppBootstrapper`].
-
-In this case the deployment type is specified through an Apache Isis-specific context parameter, called `isis.deploymentType`:
-
-* to specify `SERVER` (production) mode, use: +
-+
-[source,xml]
-.`web.xml`
-----
-<context-param>
-    <param-name>isis.deploymentType</param-name>
-    <param-value>server</param-value>
-</context-param>
-----
-
-* to specify `SERVER_PROTOTYPE` (development) mode, use: +
-+
-[source,xml]
-.`web.xml`
-----
-<context-param>
-    <param-name>isis.deploymentType</param-name>
-    <param-value>server-prototype</param-value>
-</context-param>
-----
-
-
-
-== Overriding the deployment type
-
-If bootstrapping the application using Apache Isis' xref:ugbtb.adoc#_ugbtb_deployment_cmd-line[`org.apache.isis.WebServer`] then it is possible to override the deployment type using the `-t` (or `--type`) flag.
-
-For example:
-
-[source,bash]
-----
-java -jar ... org.apache.isis.WebServer -t SERVER
-----
-
-where "..." is the (usually rather long) list of JAR files and class directories that will make up your application.
-
-This works for both the xref:ugvw.adoc#[Wicket viewer] and the xref:ugvro.adoc#[RestfulObjects viewer].
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/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
deleted file mode 100644
index 2049ab2..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_specifying-components.adoc
+++ /dev/null
@@ -1,110 +0,0 @@
-[[_rg_runtime_configuring-components]]
-= Specifying components
-: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/
-
-
-
-Bootstrapping an Apache Isis application involves identifying both:
-
-* the major components (authentication, persistence mechanisms, viewers) of Apache Isis, and also
-* specifying the domain services and persistent entities that make up the application itself.
-
-As of 1.9.0 there are two different ways to perform this bootstrapping.  The recommended (newer) approach is to use an xref:rg.adoc#_rg_classes_super_manpage-AppManifest[`AppManifest`], specified either programmatically or through the configuration properties.  This allows the components, services and entities to be specified from a single class.  The alternative (and older, pre 1.9.0) approach is to specify this information individually, through configuration properties.
-
-To specify the `AppManifest` as a configuration property, use:
-
-.Core Configuration Properties (ignored if `isis.appManifest` is present)
-[cols="2a,1,3a", options="header"]
-|===
-|Property
-|Value +
-(_default value_)
-|Implements
-
-|`isis.appManifest`
-|`FQCN`
-|`o.a.i.applib.AppManifest` +
-
-By convention this implementation resides in an `myapp-app` Maven module (as opposed to `myapp-dom` or `myapp-fixture`).  See the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype] for details.
-
-|===
-
-From this the framework can determine the domain services, persistent entities and security (authentication and authorization) mechanisms to use.  Other configuration (including fixtures) can also be specified this way.
-
-
-If the `AppManifest` approach is _not_ being used, then the following configuration properties are used to specify the major components of Apache Isis to use:
-
-.Core Configuration Properties (ignored if `isis.appManifest` is present)
-[cols="2a,1,3a", options="header"]
-|===
-|Property
-|Value +
-(_default value_)
-|Implements
-
-|`isis.authentication`
-|`shiro`, `bypass`, `FQCN` +
-(`_shiro_`)
-|`o.a.i.core.runtime.authentication.` `AuthenticationManagerInstaller` +
-
-This property is IGNORED if the `isis.appManifest` configuration property is specified, or if an xref:rg.adoc#_rg_classes_super_manpage-AppManifest[`AppManifest`] is provided programmatically.
-
-
-|`isis.authorization`
-|`shiro`, `bypass`, `FQCN` +
-(`_shiro_`)
-|`o.a.i.core.runtime.authorization.` `AuthorizationManagerInstaller` +
-
-This property is IGNORED if the `isis.appManifest` configuration property is specified, or if an xref:rg.adoc#_rg_classes_super_manpage-AppManifest[`AppManifest`] is provided programmatically.
-
-|`isis.persistor`
-|`datanucleus`
-(`_datanucleus_`)
-|`o.a.i.core.runtime.installerregistry.installerapi.` `PersistenceMechanismInstaller`
-
-This property is IGNORED completely in 1.9.0+; the `datanucleus` implementation is always used.
-
-
-|`isis.services-installer`
-|`configuration`, `configuration-and-annotation`, `FQCN` +
-(`_configuration_`)
-|`org.apache.isis.core.runtime.services.` `ServicesInstaller` +
-
-The mechanism to discover and load domain services:
-
-* `configuration-and-annotation` will search for `@DomainService`-annotated classes and also read from `isis.services` configuration property
-
-* `configuration` will only read from the `isis.services` configuration property. +
-
-* Otherwise an alternative implementation of the `o.a.i.core.runtime.services.ServicesInstaller` internal API can be provided. +
-
-This property is IGNORED if the `isis.appManifest` configuration property is specified, or if an xref:rg.adoc#_rg_classes_super_manpage-AppManifest[`AppManifest`] is provided programmatically.
-
-
-|===
-
-[TIP]
-====
-The values `"shiro"`, `"bypass"` etc are actually aliases for concrete implementations listed in Apache Isis' `installer-registry.properties` file (in `isis-core-runtime.jar`).  It is -- at least in theory -- possible to specify a fully qualified class name to replace either of the two security components.
-====
-
-If the `AppManifest` is _not_ being used then there are number of other configuration properties that also must be specified: `isis.services`, `isis.services.ServicesInstallerFromAnnotation.packagePrefix` and `isis.persistor.datanucleus.RegisterEntities.packagePrefix` and `isis.fixtures`; these are listed in the sections below.
-
-
-
-== Viewer Configuration
-
-Viewers are specified by way of the filters and servlets in the xref:ugbtb.adoc#_ugbtb_web-xml[`web.xml`] file; these are not bootstrapped by the framework, rather it is the other way around.  However, we can also hint to the framework as to which viewers are in use by way of a context parameter:
-
-[source,xml]
-----
-<context-param>
-    <param-name>isis.viewers</param-name>
-    <param-value>wicket,restfulobjects</param-value>
-</context-param>
-----
-
-The net effect of this configuration is simply to ensure that the `viewer_wicket.properties` and/or the `viewer_restfulobjects.properties` files are read.
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout.adoc
index 96a368f..963c41c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout.adoc
@@ -34,7 +34,7 @@ For a domain service action to be contributed, the domain services must have a x
 
 |xref:rgant.adoc#_rgant-ActionLayout_cssClass[`cssClass()`]
 |Any string valid as a CSS class
-|an additional CSS class around the HTML that represents for the action, to allow targetted styling in xref:rg.adoc#_rg_runtime_application-specific_application-css[`application.css`]. +
+|an additional CSS class around the HTML that represents for the action, to allow targetted styling in xref:rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css`]. +
 
 Supported by the xref:ugvw.adoc#[Wicket viewer] but currently ignored by the xref:ugvro.adoc#[RestfulObjects viewer].
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_cssClass.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_cssClass.adoc
index 5404e16..fb090cf 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_cssClass.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-ActionLayout_cssClass.adoc
@@ -6,7 +6,7 @@
 
 
 
-The `cssClass()` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the action.   xref:rg.adoc#_rg_runtime_application-specific_application-css[Application-specific CSS] can then be used to target and adjust the UI representation of that particular element.
+The `cssClass()` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the action.   xref:rgcfg.adoc#_rgcfg_application-specific_application-css[Application-specific CSS] can then be used to target and adjust the UI representation of that particular element.
 
 This attribute can also be applied to xref:rgant.adoc#_rgant-DomainObjectLayout_cssClass[domain objects], xref:rgant.adoc#_rgant-ViewModelLayout_cssClass[view models],  xref:rgant.adoc#_rgant-PropertyLayout_cssClass[properties],  xref:rgant.adoc#_rgant-CollectionLayout_cssClass[collections] and xref:rgant.adoc#_rgant-ParameterLayout_cssClass[parameters].
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rgant-Action_command.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-Action_command.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-Action_command.adoc
index 7c7cb3a..3d870ee 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-Action_command.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-Action_command.adoc
@@ -30,7 +30,7 @@ If background ``Command``s are used, then an external scheduler, using xref:ugbt
 
 The `command()` attribute determines whether the action invocation should be reified into a `Command` object (by the xref:rgsvc.adoc#_rgsvc-api_CommandContext[`CommandContext`] service).
 
-The default is `AS_CONFIGURED`, meaning that the xref:rg.adoc#_rg_runtime_configuring-core[configuration property] `isis.services.command.actions` is used to determine the whether the action is reified:
+The default is `AS_CONFIGURED`, meaning that the xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.services.command.actions` is used to determine the whether the action is reified:
 
 * `all` +
 +

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rgant-Action_publishing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-Action_publishing.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-Action_publishing.adoc
index b0733ac..482ca93 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-Action_publishing.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-Action_publishing.adoc
@@ -10,7 +10,7 @@
 The `publishing()` attribute determines whether and how an action invocation is published via the registered implementation of a xref:rgsvc.adoc#_rgsvc-spi_PublishingService[`PublishingService`]).  This attribute is also supported for xref:rgant.adoc#_rgant-DomainObject_publishing[domain objects], where it controls whether changed objects are published as events.
 
 A common use case is to notify external "downstream" systems of changes in the state of the Isis application.
-The default value for the attribute is `AS_CONFIGURED`, meaning that the xref:rg.adoc#_rg_runtime_configuring-core[configuration property] `isis.services.publish.actions` is used to determine the whether the action is published:
+The default value for the attribute is `AS_CONFIGURED`, meaning that the xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.services.publish.actions` is used to determine the whether the action is published:
 
 * `all` +
 +

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rgant-Action_restrictTo.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-Action_restrictTo.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-Action_restrictTo.adoc
index 5225599..6a07c22 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-Action_restrictTo.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-Action_restrictTo.adoc
@@ -7,7 +7,7 @@
 
 
 
-By default actions are available irrespective of the xref:rg.adoc#_rg_runtime_deployment-types[deployment mode].  The `restrictTo()` attribute specifies whether the action should instead be restricted to only available in prototyping mode.
+By default actions are available irrespective of the xref:rgcfg.adoc#_rgcfg_deployment-types[deployment mode].  The `restrictTo()` attribute specifies whether the action should instead be restricted to only available in prototyping mode.
 
 For example:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout.adoc
index e227ebe..3362a94 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout.adoc
@@ -21,7 +21,7 @@ The table below summarizes the annotation's attributes.
 
 |xref:rgant.adoc#_rgant-CollectionLayout_cssClass[`cssClass()`]
 |Any string valid as a CSS class
-|the css class that a collection should have, to allow more targetted styling in xref:rg.adoc#_rg_runtime_application-specific_application-css[`application.css`]
+|the css class that a collection should have, to allow more targetted styling in xref:rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css`]
 
 
 |xref:rgant.adoc#_rgant-CollectionLayout_defaultView[`defaultView()`]

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_cssClass.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_cssClass.adoc
index 1bdae08..c8d3d19 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_cssClass.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_cssClass.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-The `cssClass()` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the collection.   xref:rg.adoc#_rg_runtime_application-specific_application-css[Application-specific CSS] can then be used to target and adjust the UI representation of that particular element.
+The `cssClass()` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the collection.   xref:rgcfg.adoc#_rgcfg_application-specific_application-css[Application-specific CSS] can then be used to target and adjust the UI representation of that particular element.
 
 This attribute can also be applied to xref:rgant.adoc#_rgant-DomainObjectLayout_cssClass[domain objects], xref:rgant.adoc#_rgant-ViewModelLayout_cssClass[view models], xref:rgant.adoc#_rgant-ActionLayout_cssClass[actions], xref:rgant.adoc#_rgant-PropertyLayout_cssClass[properties] and xref:rgant.adoc#_rgant-ParameterLayout_cssClass[parameters].
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_paged.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_paged.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_paged.adoc
index 3266bb9..f371d7a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_paged.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-CollectionLayout_paged.adoc
@@ -27,7 +27,7 @@ public class Order {
 ----
 
 
-It is also possible to specify a global default for the page size of standalone collections, using the xref:rg.adoc#_rg_runtime_configuring-core[configuration property] `isis.viewer.paged.parented`.
+It is also possible to specify a global default for the page size of standalone collections, using the xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.viewer.paged.parented`.
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rgant-Collection_editing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-Collection_editing.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-Collection_editing.adoc
index 870424c..ed198ea 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-Collection_editing.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-Collection_editing.adoc
@@ -21,7 +21,7 @@ Whether a collection is enabled or disabled depends upon these factors:
 
 * whether the domain object has been configured as immutable through the xref:rgant.adoc#_rgant-DomainObject_editing[`@DomainObject#editing()`] attribute
 
-* else (that is, if the domain object's editability is specified as being `AS_CONFIGURED`), then the value of the xref:rg.adoc#_rg_runtime_configuring-core[configuration property] `isis.objects.editing`.  If set to `false`, then the object's collections (and properties) are *not* editable
+* else (that is, if the domain object's editability is specified as being `AS_CONFIGURED`), then the value of the xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.objects.editing`.  If set to `false`, then the object's collections (and properties) are *not* editable
 
 * else, then the value of the `@Collection(editing=...)` attribute itself.
 


[46/52] [abbrv] isis git commit: ISIS-1237: factored out Generation context class to keep track of references vs definitions; factored out Tagger; factored out ClassExcluder.

Posted by mg...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/2efbf48f/core/metamodel/src/test/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGeneratorTest.java
----------------------------------------------------------------------
diff --git a/core/metamodel/src/test/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGeneratorTest.java b/core/metamodel/src/test/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGeneratorTest.java
deleted file mode 100644
index cbebd55..0000000
--- a/core/metamodel/src/test/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGeneratorTest.java
+++ /dev/null
@@ -1,69 +0,0 @@
-/*
- *  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.
- */
-package org.apache.isis.core.metamodel.services.swagger.internal;
-
-import org.junit.Test;
-
-import static org.hamcrest.CoreMatchers.equalTo;
-import static org.hamcrest.CoreMatchers.is;
-import static org.junit.Assert.assertThat;
-
-public class SwaggerSpecGeneratorTest {
-
-    public static class TagFor extends SwaggerSpecGeneratorTest {
-
-        @Test
-        public void fullyQualifiedClass() throws Exception {
-            String tag = SwaggerSpecGenerator.tagFor("foo.bar.Abc");
-            assertThat(tag, is(equalTo("bar")));
-        }
-
-        @Test
-        public void jaxb() throws Exception {
-            String tag = SwaggerSpecGenerator.tagFor("todoapp.app.viewmodels.todoitem.v1_0.ToDoItemDto");
-            assertThat(tag, is(equalTo("todoitem")));
-        }
-
-        @Test
-        public void schemaClass() throws Exception {
-            String tag = SwaggerSpecGenerator.tagFor("bar.Abc");
-            assertThat(tag, is(equalTo("bar")));
-        }
-
-        @Test
-        public void noPackage() throws Exception {
-            String tag = SwaggerSpecGenerator.tagFor("Abc");
-            assertThat(tag, is(equalTo("Abc")));
-        }
-
-        @Test
-        public void isisAddons() throws Exception {
-            String tag = SwaggerSpecGenerator.tagFor("org.isisaddons.module.security.app.feature.ApplicationClass");
-            assertThat(tag, is(equalTo("isisaddons security")));
-        }
-
-        @Test
-        public void applib() throws Exception {
-            String tag = SwaggerSpecGenerator.tagFor("org.apache.isis.applib.fixturescripts.FixtureResult");
-            assertThat(tag, is(equalTo("> apache isis internals")));
-        }
-
-    }
-
-}
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/2efbf48f/core/metamodel/src/test/java/org/apache/isis/core/metamodel/services/swagger/internal/TaggerTest.java
----------------------------------------------------------------------
diff --git a/core/metamodel/src/test/java/org/apache/isis/core/metamodel/services/swagger/internal/TaggerTest.java b/core/metamodel/src/test/java/org/apache/isis/core/metamodel/services/swagger/internal/TaggerTest.java
new file mode 100644
index 0000000..945d73e
--- /dev/null
+++ b/core/metamodel/src/test/java/org/apache/isis/core/metamodel/services/swagger/internal/TaggerTest.java
@@ -0,0 +1,69 @@
+/*
+ *  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.
+ */
+package org.apache.isis.core.metamodel.services.swagger.internal;
+
+import org.junit.Test;
+
+import static org.hamcrest.CoreMatchers.equalTo;
+import static org.hamcrest.CoreMatchers.is;
+import static org.junit.Assert.assertThat;
+
+public class TaggerTest {
+
+    public static class TagFor extends TaggerTest {
+
+        @Test
+        public void fullyQualifiedClass() throws Exception {
+            String tag = new Tagger().tagFor("foo.bar.Abc", null);
+            assertThat(tag, is(equalTo("bar")));
+        }
+
+        @Test
+        public void jaxb() throws Exception {
+            String tag = new Tagger().tagFor("todoapp.app.viewmodels.todoitem.v1_0.ToDoItemDto", null);
+            assertThat(tag, is(equalTo("todoitem")));
+        }
+
+        @Test
+        public void schemaClass() throws Exception {
+            String tag = new Tagger().tagFor("bar.Abc", null);
+            assertThat(tag, is(equalTo("bar")));
+        }
+
+        @Test
+        public void noPackage() throws Exception {
+            String tag = new Tagger().tagFor("Abc", null);
+            assertThat(tag, is(equalTo("Abc")));
+        }
+
+        @Test
+        public void isisAddons() throws Exception {
+            String tag = new Tagger().tagFor("org.isisaddons.module.security.app.feature.ApplicationClass", null);
+            assertThat(tag, is(equalTo("isisaddons security")));
+        }
+
+        @Test
+        public void applib() throws Exception {
+            String tag = new Tagger().tagFor("org.apache.isis.applib.fixturescripts.FixtureResult", null);
+            assertThat(tag, is(equalTo("> apache isis internals")));
+        }
+
+    }
+
+}
\ No newline at end of file


[23/52] [abbrv] isis git commit: ISIS-1243: renamed ug.adoc to ugfun.adoc. Added standard section to each of the guides so can navigate between each easily.

Posted by mg...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_getting-started_simpleapp-archetype.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_getting-started_simpleapp-archetype.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_getting-started_simpleapp-archetype.adoc
deleted file mode 100644
index c77328c..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_getting-started_simpleapp-archetype.adoc
+++ /dev/null
@@ -1,304 +0,0 @@
-[[_ug_getting-started_simpleapp-archetype]]
-= 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/
-
-
-The quickest way to get started with Apache Isis is to run the simple archetype.  This will generate a very simple one-class domain model, called `SimpleObject`, with a single property `name`.
-
-There is also a corresponding `SimpleObjectRepository` domain service.  From this you can easily rename these initial classes, and extend to build up your own Apache Isis domain application.
-
-
-
-== Generating the App
-
-Create a new directory, and `cd` into that directory.
-
-To build the app from the latest stable release, then run the following command:
-
-[source,bash]
-----
-mvn archetype:generate  \
-    -D archetypeGroupId=org.apache.isis.archetype \
-    -D archetypeArtifactId=simpleapp-archetype \
-    -D archetypeVersion=1.10.0 \
-    -D groupId=com.mycompany \
-    -D artifactId=myapp \
-    -D version=1.0-SNAPSHOT \
-    -B
-----
-
-where:
-
-- `groupId` represents your own organization, and
-- `artifactId` is a unique identifier for this app within your organization.
-- `version` is the initial (snapshot) version of your app
-
-The archetype generation process will then run; it only takes a few seconds.
-
-
-We also maintain the archetype for the most current `-SNAPSHOT`; an app generated with this archetype will contain the latest features of Apache Isis, but the usual caveats apply: some features still in development may be unstable.
-
-The process is almost identical to that for stable releases, however the `archetype:generate` goal is called with slightly different arguments:
-
-[source,bash]
-----
-mvn archetype:generate  \
-    -D archetypeGroupId=org.apache.isis.archetype \
-    -D archetypeArtifactId=simpleapp-archetype \
-    -D archetypeVersion=1.11.0-SNAPSHOT \
-    -D groupId=com.mycompany \
-    -D artifactId=myapp \
-    -D version=1.0-SNAPSHOT \
-    -D archetypeRepository=http://repository-estatio.forge.cloudbees.com/snapshot/ \
-    -B
-----
-
-where as before:
-
-- `groupId` represents your own organization, and
-- `artifactId` is a unique identifier for this app within your organization.
-- `version` is the initial (snapshot) version of your app
-
-but also:
-
-- `archetypeVersion` is the SNAPSHOT version of Apache Isis.
-- `archetypeRepository` specifies the location of our snapshot repo (hosted on link:http://www.cloudbees.com[CloudBees]), and
-
-The archetype generation process will then run; it only takes a few seconds.
-
-
-
-== Building the App
-
-Switch into the root directory of your newly generated app, and build your app:
-
-[source,bash]
-----
-cd myapp
-mvn clean install
-----
-
-where `myapp` is the `artifactId` entered above.
-
-
-
-
-== Running the App
-
-The `simpleapp` archetype generates a single WAR file, configured to run both the xref:ugvw.adoc#[Wicket viewer] and the xref:ugvro.adoc#[Restful Objects viewer].  The archetype also configures the DataNucleus/JDO Objectstore to use an in-memory HSQLDB connection.
-
-Once you've built the app, you can run the WAR in a variety of ways.
-
-
-=== Self-hosted
-
-The easiest way to run the app, at least while getting started, is to run the self-hosting version of the WAR.  With this style the app runs up its own internal instance of Jetty web server.
-
-For example:
-
-
-[source,bash]
-----
-java -jar webapp/target/myapp-webapp-1.0-SNAPSHOT-jetty-console.jar
-----
-
-
-This can also be accomplished using an embedded Ant target provided in the build script:
-
-[source,bash]
-----
-mvn -P self-host antrun:run
-----
-
-
-=== Using mvn Jetty plugin
-
-Alternatively, you could run the WAR in a Maven-hosted Jetty instance, though you need to `cd` into the `webapp` module:
-
-[source,bash]
-----
-cd webapp
-mvn jetty:run
-----
-
-If you use `mvn jetty:run`, then the context path changes; check the console output (eg link:http://localhost:8080/myapp-webapp [http://localhost:8080/myapp-webapp]).
-
-
-You can also provide a system property to change the port:
-
-[source,bash]
-----
-cd webapp
-mvn jetty:run -D jetty.port=9090
-----
-
-
-=== Using a regular servlet container
-
-You can also take the built WAR file and deploy it into a standalone servlet container such as [Tomcat](http://tomcat.apache.org).  The default configuration does not require any configuration of the servlet container; just drop the WAR file into the `webapps` directory.
-
-
-
-=== From within the IDE
-
-Most of the time, though, you'll probably want to run the app from within your IDE.  The mechanics of doing this will vary by IDE; see the xref:cg.adoc#_cg_ide[Contributors' Guide] for details of setting up Eclipse or IntelliJ IDEA.  Basically, though, it amounts to running `org.apache.isis.WebServer`, and ensuring that the xref:ug.adoc#_ug_getting-started_datanucleus-enhancer[DataNucleus enhancer] has properly processed all domain entities.
-
-Here's what the setup looks like in IntelliJ IDEA:
-
-image::{_imagesdir}getting-started/simpleapp-webapp.png[width="600px",link="{_imagesdir}getting-started/simpleapp-webapp.png"]
-
-
-
-== Running with Fixtures
-
-It is also possible to start the application with a pre-defined set of data; useful for demos or manual exploratory testing.  This is done by specifying a xref:ugtst.adoc#_ugtst_fixture-scripts[fixture script] on the command line.
-
-If running the self-hosted console, you can specify the fixtures using the `--initParam` flag:
-
-[source,bash]
-----
-java -jar webapp/target/myapp-webapp-1.0-SNAPSHOT-jetty-console.jar \
-     --initParam isis.persistor.datanucleus.install-fixtures=true  \
-     --initParam isis.fixtures=domainapp.fixture.scenarios.RecreateSimpleObjects
-----
-
-where (in the above example) `domainapp.fixture.scenarios.RecreateSimpleObjects` is the fully qualified class name of the fixture
-script to be run.
-
-If you are running the app from an IDE, then you can specify the fixture script using the `--fixture` flag:
-
-image::{_imagesdir}getting-started/simpleapp-webapp-with-fixtures.png[width="600px",link="{_imagesdir}getting-started/simpleapp-webapp-with-fixtures.png"]
-
-
-
-== Using the App
-
-When you start the app, you'll be presented with a welcome page from which you can access the webapp using either the xref:ugvw.adoc#[Wicket viewer] or the xref:ugvro.adoc#[Restful Objects viewer]:
-
-image::{_imagesdir}getting-started/using-simple-app/010-root-page.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/010-root-page.png"]
-
-
-The Wicket viewer provides a human usable web UI (implemented, as you might have guessed from its name, using link:http://wicket.apache.org[Apache Wicket]), so choose that and navigate to the login page:
-
-image::{_imagesdir}getting-started/using-simple-app/020-login-to-wicket-viewer.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/020-login-to-wicket-viewer.png"]
-
-The app itself is configured to run using xref:ugsec.adoc#[shiro security], as configured in the `WEB-INF/shiro.ini` config file.  You can login with:
-
-* username: _sven_
-* password: _pass_
-
-The application is configured to run with an in-memory database, and (unless you started the app with fixture scripts as described above), initially there is no data.  We can though run a fixture script from the app itself:
-
-image::{_imagesdir}getting-started/using-simple-app/030-home-page-run-fixture-scripts.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/030-home-page-run-fixture-scripts.png"]
-
-The fixture script creates three objects, and the action returns the first of these:
-
-image::{_imagesdir}getting-started/using-simple-app/040-first-object.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/040-first-object.png"]
-
-The application generated is deliberaetly very minimal; we don't want you to have to waste valuable time removing generated files.  The object contains a single "name" property, and a single action to update that property:
-
-image::{_imagesdir}getting-started/using-simple-app/050-update-name-prompt.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/050-update-name-prompt.png"]
-
-When you hit OK, the object is updated:
-
-image::{_imagesdir}getting-started/using-simple-app/060-object-updated.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/060-object-updated.png"]
-
-
-For your most signficant domain entities you'll likely have a domain service to retrieve or create instances of those obejcts.  In the generated app we have a "Simple Objects" domain service that lets us list all objects:
-
-image::{_imagesdir}getting-started/using-simple-app/070-list-all-prompt.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/070-list-all-prompt.png"]
-
-whereby we see the three objects created by the fixture script (one having been updated):
-
-image::{_imagesdir}getting-started/using-simple-app/080-list-all.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/080-list-all.png"]
-
-and we can also use the domain service to create new instances:
-
-image::{_imagesdir}getting-started/using-simple-app/090-create.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/090-create.png"]
-
-prompting us for the mandatory information (the name):
-
-image::{_imagesdir}getting-started/using-simple-app/100-create-prompt.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/100-create-prompt.png"]
-
-which, of course, returns the newly created object:
-
-image::{_imagesdir}getting-started/using-simple-app/110-object-created.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/110-object-created.png"]
-
-When we list all objects again, we can see that the object was indeed created:
-
-image::{_imagesdir}getting-started/using-simple-app/120-list-all.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/120-list-all.png"]
-
-Going back to the home page (link:http://localhost:8080[localhost:8080]) we can also access the Restful Objects viewer.  The generated application is configured to use HTTP Basic Auth:
-
-image::{_imagesdir}getting-started/using-simple-app/220-login-to-restful-viewer.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/220-login-to-restful-viewer.png"]
-
-The Restful Objects viewer provides a REST API for computer-to-computer interaction, but we can still interact with it from a browser:
-
-image::{_imagesdir}getting-started/using-simple-app/230-home-page.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/230-home-page.png"]
-
-[TIP]
-====
-Depending on your browser, you may need to install plugins.  For Chrome, we recommend json-view (which renders the JSON indented and automatically detects hyperlinks) and REST Postman.
-====
-
-The REST API is a complete hypermedia API, in other words you can follow the links to access all the behaviour exposed in the regular Wicket app.  For example, we can navigate to the `listAll/invoke` resource:
-
-image::{_imagesdir}getting-started/using-simple-app/240-list-all-invoke.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/240-list-all-invoke.png"]
-
-which when invoked (with an HTTP GET) will return a representation of the domain objects.
-
-image::{_imagesdir}getting-started/using-simple-app/250-list-all-results.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/250-list-all-results.png"]
-
-
-To log in, use `sven/pass`.
-
-
-
-
-
-== Modifying the App
-
-Once you are familiar with the generated app, you'll want to start modifying it.  There is plenty of guidance on this site; check out the 'programming model how-tos' section on the main link:../documentation.html[documentation] page first).
-
-If you use Eclipse or IntelliJ IDEA, do also install the xref:cg.adoc#_cg_ide-templates[IDE templates]; these will help you follow the Apache Isis naming conventions.
-
-
-
-
-
-== App Structure
-
-As noted above, the generated app is a very simple application consisting of a single domain object that can be easily renamed and extended. The intention is not to showcase all of Apache Isis' capabilities; rather it is to allow you to very easily modify the generated application (eg rename `SimpleObject` to `Customer`) without having to waste time deleting lots of generated code.
-
-
-
-[cols="1,3", options="header"]
-|===
-| Module
-| Description
-
-|`myapp`
-|The parent (aggregator) module
-
-|`myapp-app`
-|(1.9.0) The "app" module, containing the (optional) app manifest and any application-level services.
-
-|`myapp-dom`
-|The domain object model, consisting of `SimpleObject` and `SimpleObjects` (repository) domain service.
-
-|`myapp-fixture`
-|Domain object fixtures used for initializing the system when being demo'ed or for unit testing.
-
-|`myapp-integtests`
-|End-to-end xref:ugtst.adoc#_ugtst_integ-test-support[integration tests] that exercise from the UI through to the database
-
-|`myapp-webapp`
-|Run as a webapp (from `web.xml`) hosting the xref:ugvw.adoc#[Wicket viewer] and/or the xref:ugvro.adoc#[RestfulObjects viewer]
-
-|===
-
-
-
-If you run into issues, please don't hesitate to ask for help on the link:http://isis.apache.org/help.html[users mailing list].

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos.adoc
deleted file mode 100644
index 2ab5b65..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos.adoc
+++ /dev/null
@@ -1,22 +0,0 @@
-[[_ug_how-tos]]
-= 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/
-
-
-This chapter provides a grab bag of "how-to"s and tips to help you go about actually developing Apache Isis domain applications.
-
-include::_ug_how-tos_class-structure.adoc[leveloffset=+1]
-include::_ug_how-tos_ui-hints.adoc[leveloffset=+1]
-include::_ug_how-tos_domain-services.adoc[leveloffset=+1]
-include::_ug_how-tos_crud.adoc[leveloffset=+1]
-include::_ug_how-tos_entity-relationships.adoc[leveloffset=+1]
-include::_ug_how-tos_contributed-members.adoc[leveloffset=+1]
-include::_ug_how-tos_business-rules.adoc[leveloffset=+1]
-include::_ug_how-tos_derived-members.adoc[leveloffset=+1]
-include::_ug_how-tos_drop-downs-and-defaults.adoc[leveloffset=+1]
-include::_ug_how-tos_bulk-actions.adoc[leveloffset=+1]
-include::_ug_how-tos_simulating-collections-of-values.adoc[leveloffset=+1]
-include::_ug_how-tos_render-all-properties-in-tables.adoc[leveloffset=+1]
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_bulk-actions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_bulk-actions.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_bulk-actions.adoc
deleted file mode 100644
index fa40181..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_bulk-actions.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-[[_ug_how-tos_bulk-actions]]
-= Bulk Actions
-: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/
-
-NOTE: TODO - xref:rgant.adoc#_rgant-Action_invokeOn[`@Action#invokeOn()`]
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_business-rules.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_business-rules.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_business-rules.adoc
deleted file mode 100644
index 71794c6..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_business-rules.adoc
+++ /dev/null
@@ -1,72 +0,0 @@
-[[_ug_how-tos_business-rules]]
-= 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/
-
-NOTE: TODO
-
-
-
-== Visibility ("see it")
-
-NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_hide[`hide...()`]
-
-### Hide a Property
-
-### Hide a Collection
-
-### Hide an Action
-
-### Hide a Contributed Property, Collection or Action
-
-### All Members Hidden
-
-
-
-
-== Usability ("use it")
-
-NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_disable[`disable...()`]
-
-### 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")
-
-NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_validate[`validate...()`], xref:rgcms.adoc#_rgcms_methods_prefixes_validateAddTo[`validateAddTo...()`], xref:rgcms.adoc#_rgcms_methods_prefixes_validateRemoveFrom[`validateRemoveFrom...()`] and xref:rgcms.adoc#_rgcms_methods_reserved_validate[`validate()`]
-
-
-### 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
-
-NOTE: TODO - using xref:rgant.adoc#_rgant-Parameter_mustSatisfy[`@Parameter#mustSatisfy()`], xref:rgant.adoc#_rgant-Property_mustSatisfy[`@Property#mustSatisfy()`]
-
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure.adoc
deleted file mode 100644
index fdd5061..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure.adoc
+++ /dev/null
@@ -1,38 +0,0 @@
-[[_ug_how-tos_class-structure]]
-= 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/
-
-
-Apache Isis works by building a metamodel of the domain objects: entities, xref:ugbtb.adoc#_ugbtb_more-advanced_view-models[view model]s and services.  The class members of both entities and view models represent both state -- (single-valued) properties and (multi-valued) collections -- and behaviour -- actions.  The class members of domain services is simpler: just behaviour, ie actions.
-
-In the automatically generated UI a property is rendered as a field.  This can be either of a value type (a string, number, date, boolean etc) or can be a reference to another entity.  A collection is generally rendered as a table.
-
-In order for Apache Isis to build its metamodel the domain objects must follow some conventions: what we call the _Apache Isis Programming Model_.  This is just an extension of the pojo / JavaBean standard of yesteryear: properties and collections are getters/setters, while actions are simply any remaining `public` methods.
-
-Additional metamodel semantics are inferred both imperatively from _supporting methods_ and declaratively from annotations.
-
-In this section we discuss the mechanics of writing domain objects that comply with Apache Isis' programming model.
-
-[TIP]
-====
-In fact, the Apache Isis programming model is extensible; you can teach Apache Isis new programming conventions and you can remove existing ones; ultimately they amount to syntax.   The only real fundamental that can't be changed is the notion that objects consist of properties, collections and actions.
-
-You can learn more about extending Apache Isis programming model xref:ugbtb.adoc#_ugbtb_programming-model[here].
-====
-
-
-include::_ug_how-tos_class-structure_class-definition.adoc[leveloffset=+1]
-include::_ug_how-tos_class-structure_properties.adoc[leveloffset=+1]
-include::_ug_how-tos_class-structure_collections.adoc[leveloffset=+1]
-include::_ug_how-tos_class-structure_actions.adoc[leveloffset=+1]
-include::_ug_how-tos_class-structure_action-parameters.adoc[leveloffset=+1]
-include::_ug_how-tos_class-structure_inject-services.adoc[leveloffset=+1]
-
-include::_ug_how-tos_class-structure_properties-vs-parameters.adoc[leveloffset=+1]
-
-include::_ug_how-tos_class-structure_ignoring-methods.adoc[leveloffset=+1]
-
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_action-parameters.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_action-parameters.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_action-parameters.adoc
deleted file mode 100644
index 1e7a0f8..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_action-parameters.adoc
+++ /dev/null
@@ -1,26 +0,0 @@
-[[_ug_how-tos_class-structure_action-parameters]]
-= Action Parameters
-: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/
-
-
-NOTE: TODO
-
-
-
-== ``String``s (Length)
-
-NOTE: TODO
-
-
-== ``BigDecimal``s (Precision)
-
-NOTE: TODO
-
-
-== Optional
-
-NOTE: TODO
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_actions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_actions.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_actions.adoc
deleted file mode 100644
index 5e29c34..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_actions.adoc
+++ /dev/null
@@ -1,19 +0,0 @@
-[[_ug_how-tos_class-structure_actions]]
-= Actions
-: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/
-
-
-
-NOTE: TODO
-
-
-[NOTE]
-====
-While Apache 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 xref:ug.adoc#_ug_how-tos_class-structure_ignoring-methods[Ignoring Methods].  This ensures that the collection is ignored by Apache Isis.
-====
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_class-definition.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_class-definition.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_class-definition.adoc
deleted file mode 100644
index 444ff86..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_class-definition.adoc
+++ /dev/null
@@ -1,24 +0,0 @@
-[[_ug_how-tos_class-structure_class-definition]]
-= Class Definition
-: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/
-
-
-
-NOTE: TODO
-
-
-Classes are defined both to Isis and (if an 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.
-
-[TIP]
-====
-For more on this topic, see the topic discussing modules and xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling[decoupling].
-====
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_collections.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_collections.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_collections.adoc
deleted file mode 100644
index 455144e..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_collections.adoc
+++ /dev/null
@@ -1,26 +0,0 @@
-[[_ug_how-tos_class-structure_collections]]
-= Collections
-: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/
-
-
-NOTE: TODO
-
-
-[NOTE]
-====
-While Apache 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, Apache Isis has no default visualization.
-
-One workaround is to mark the collection as xref:rgant.adoc#_rgant-Programmatic[`@Programmatic`].  This ensures that the collection is ignored by Apache Isis.
-
-Another workaround is to wrap each value in a view model, as explained in this xref:ug.adoc#_ug_how-tos_simulating-collections-of-values[tip].
-====
-
-
-
-
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_ignoring-methods.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_ignoring-methods.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_ignoring-methods.adoc
deleted file mode 100644
index 9dcdae5..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_ignoring-methods.adoc
+++ /dev/null
@@ -1,16 +0,0 @@
-[[_ug_how-tos_class-structure_ignoring-methods]]
-= Ignoring Methods
-: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/
-
-
-
-NOTE: TODO
-
-
-Sometimes you want to define a `public` method on a domain object that is not intended to be rendered in Apache Isis' UI.
-
-To exclude such methods, use the xref:rgant.adoc#_rgant-Programmatic[`@Programmatic`] annotation.
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_inject-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_inject-services.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_inject-services.adoc
deleted file mode 100644
index 3ca16a6..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_inject-services.adoc
+++ /dev/null
@@ -1,83 +0,0 @@
-[[_ug_how-tos_class-structure_inject-services]]
-= Injecting 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/
-
-
-Apache Isis autowires (automatically injects) domain services into each entity, as well as into the domain services themselves, using either method injection or field injection. The applib `DomainObjectContainer` is also a service, so can be injected in exactly the same manner.
-
-
-[NOTE]
-====
-Isis currently does _not_ support qualified injection of services; the domain service of each type must be distinct from any other.
-
-If you find a requirement to inject two instances of type `SomeService`, say, then the work-around is to create trivial subclasses `SomeServiceA` and `SomeServiceB` and inject these instead.
-====
-
-
-== Field Injection
-
-Field injection is recommended, using the `@javax.inject.Inject` annotation. For example:
-
-[source,java]
-----
-public class Customer {
-    @javax.inject.Inject
-    OrderRepository orderRepository;
-    ...
-}
-----
-
-
-We recommend using default rather than `private` visibility so that the field can be mocked out within unit tests (placed in the same package as the code under test).
-
-
-
-
-== Method Injection
-
-Isis also supports two forms of method injection.  All that is required to inject a service into a entity/service is to provide an appropriate method or field. The name
-of the method does not matter, only that it is prefixed either `set` or `inject`, is
-public, and has a single parameter of the correct type.
-
-For example:
-
-[source,java]
-----
-public class Customer {
-    private OrderRepository orderRepository;
-    public void setOrderRepository(OrderRepository orderRepository) {
-        this.orderRepository = orderRepository;
-    }
-    ...
-}
-----
-
-or alternatively, using 'inject' as the prefix:
-
-[source,java]
-----
-public class Customer {
-    private OrderRepository orderRepository;
-    public void injectOrderRepository(OrderRepository orderRepository) {
-        this.orderRepository = orderRepository;
-    }
-    ...
-}
-----
-
-Note that the method name can be anything; it doesn't need to be related to the type being injected.
-
-
-
-
-== Constructor injection
-
-Simply to note that constructor injection is _not_ supported by Apache Isis (and is unlikely to be, because the JDO specification for entities requires a no-arg constructor).
-
-
-
-
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_properties-vs-parameters.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_properties-vs-parameters.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_properties-vs-parameters.adoc
deleted file mode 100644
index 75184e1..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_properties-vs-parameters.adoc
+++ /dev/null
@@ -1,45 +0,0 @@
-[[_ug_how-tos_class-structure_properties-vs-parameters]]
-= Properties vs Parameters
-: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/
-
-
-
-NOTE: TODO
-
-
-In many cases the value types of properties and of action parameters align. For example, a `Customer` entity might have a `surname` property, and there might also be corresponding `changeSurname`.  Ideally we want the surname property and surname action parameter to use the same value type.
-
-Having first-class support for this is a goal of Apache Isis, and it is already possible (by writing some plumbing and glue code using Isis and DataNucleus APIs) to get some way towards this ideal.  However, in the vast majority of cases it is much easier and more practical to simply use standard value types such as `java.lang.String`.
-
-However, the JDO/DataNucleus annotations for specifying semantics such as optionality or maximum length are restricted to only apply to fields and to methods; they cannot be applied to action parameters.  It is therefore necessary to use Apache Isis' equivalent annotations for action parameters.
-
-The table below summarises the equivalence of some of the most common cases.
-
-
-.Comparing annotations of Properties vs Action Parameters
-[cols="2,3,3", options="header"]
-|===
-|value type/semantic
-|property
-|action parameter
-
-|string (length)
-|
-|
-
-|big decimal (precision)
-|
-|
-
-|Isis blob
-|
-|
-
-|optional
-|`@Column(allowsNull="true")`
-|`ParameterLayout(optionality=Optionality.OPTIONAL`) or `@Optional`
-|===
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_properties.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_properties.adoc
deleted file mode 100644
index 5b5e983..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_properties.adoc
+++ /dev/null
@@ -1,299 +0,0 @@
-[[_ug_how-tos_class-structure_properties]]
-= Property
-: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/
-
-
-NOTE: TODO
-
-
-
-
-
-== Value vs Reference Types
-
-NOTE: TODO
-
-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 the xref:ug.adoc#_ug_how-tos_class-structure_properties-vs-parameters[Properties vs Parameters] section provides a handy reference of each.
-
-
-
-== Optional Properties
-
-JDO/DataNucleus' default is that a property is assumed to be mandatory if it is a primitive type (eg `int`, `boolean`), but optional if a reference type (eg `String`, `BigDecimal` etc).  To override optionality in JDO/DataNucleus the `@Column(allowsNull="...")` annotations is used.
-
-Apache Isis on the other hand assumes that all properties (and action parameters, for that matter) are mandatory, not optional.  These defaults can also be overridden using Apache Isis' own annotations, specifically `@Property(optionality=...)`.
-
-These different defaults can lead to incompatibilities between the two frameworks.  To counteract that, Apache Isis also recognizes and honours JDO's `@Column(allowsNull=...)`.
-
-For example, rather than:
-
-[source,java]
-----
-@javax.jdo.annotations.Column(allowNulls="true")
-private LocalDate date;
-@Property(optionality=Optionality.OPTIONAL)
-public LocalDate getDate() { ... }
-public void setDate(LocalDate d) { ... }
-----
-
-you should instead simply write:
-
-[source,java]
-----
-private LocalDate date;
-@javax.jdo.annotations.Column(allowNulls="true")
-public LocalDate getDate() { ... }
-public void setDate(LocalDate d) { ... }
-----
-
-[WARNING]
-====
-With JDO/DataNucleus it's valid for the `@Column` annotation to be placed on either the field or the getter.  Apache Isis (currently) only looks for annotations on the getter.  We therefore recommend that you always place `@Column` on the gettter.
-====
-
-In all cases the framework will search for any incompatibilities in optionality (whether specified explicitly or defaulted implicitly) between Isis' defaults and DataNucleus, and refuse to boot if any are found (fail fast).
-
-
-
-=== Handling Mandatory Properties in Subtypes
-
-If you have a hierarchy of classes then you need to decide which inheritance strategy to use.
-
-* "table per hierarchy", or "rollup" (`InheritanceStrategy.SUPERCLASS_TABLE`) +
-+
-whereby a single table corresponds to the superclass, and also holds the properties of the subtype (or subtypes) being rolled up
-
-* "table per class" (`InheritanceStrategy.NEW_TABLE`) +
-+
-whereby is a table for both superclass and subclass, in 1:1 correspondence
-
-* "rolldown" (`InheritanceStrategy.SUBCLASS_TABLE`) +
-+
-whereby a single table holds the properties of the subtype, and also holds the properties of its supertype
-
-In the first "rollup" case, we can have a situation where - logically speaking - the property is mandatory in the subtype - but it must be mapped as nullable in the database because it is n/a for any other subtypes that are rolled up.
-
-In this situation we must tell JDO that the column is optional, but to Apache Isis we want to enforce it being mandatory. This can be done using the `@Property(optionality=Optionality.MANDATORY)` annotation.
-
-For example:
-
-[source,java]
-----
-@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.SUPER_TABLE)
-public class SomeSubtype extends SomeSuperType {
-    private LocalDate date;
-    @javax.jdo.annotations.Column(allowNulls="true")
-    @Property(optionality=Optionality.MANDATORY)
-    public LocalDate getDate() { ... }
-    public void setDate(LocalDate d) { ... }
-}
-----
-
-[TIP]
-====
-The `@Property(optionality=...)` annotation is equivalent to the older but still supported `@Optional` annotation and `@Mandatory` annotations. Its benefit is that it lumps together all Apache Isis' property metadata in a single annotation.  Its downside is that it is rather verbose if the only semantic that needs to be specified -- as is often the case -- is optionality.
-====
-
-An alternative way to achieve this is to leave the JDO annotation on the field (where it is invisible to Apache Isis), and rely on Isis' default, eg:
-
-[source,java]
-----
-@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.SUPER_TABLE)
-public class SomeSubtype extends SomeSuperType {
-    @javax.jdo.annotations.Column(allowNulls="true")
-    private LocalDate date;
-    // mandatory in Apache Isis by default
-    public LocalDate getDate() { }
-    public void setDate(LocalDate d) { }
-}
-----
-
-We recommend the former mapping, though, using `@Property(optionality=Optionality.MANDATORY)`.
-
-
-
-
-
-== ``String``s (Length)
-
-NOTE: TODO
-
-
-
-
-
-[[_ug_how-tos_class-structure_properties_mapping-joda-dates]]
-== Mapping JODA Dates
-
-Isis' JDO objectstore bundles DataNucleus' http://www.datanucleus.org/documentation/products/plugins.html[built-in support] for Joda `LocalDate` and `LocalDateTime` datatypes, meaning that entity properties of these types will be persisted as appropriate data types in the database tables.
-
-It is, however, necessary to annotate your properties with `@javax.jdo.annotations.Persistent`, otherwise the data won't actually be persisted. See the http://db.apache.org/jdo/field_types.html[JDO docs] for more details on this.
-
-Moreover, these datatypes are _not_ in the default fetch group, meaning that JDO/DataNucleus will perform an additional `SELECT` query for each attribute. To avoid this extra query, the annotation should indicate that the property is in the default fetch group.
-
-For example, the `ToDoItem` (in the https://github.com/isisaddons/isis-app-todoapp[todoapp example app] (not ASF)) defines the `dueBy` property as follows:
-
-
-
-== ``BigDecimal``s (Precision)
-
-Working with `java.math.BigDecimal` properties takes a little care due to scale/precision issues.
-
-For example, suppose we have:
-
-[source,java]
-----
-private BigDecimal impact;
-public BigDecimal getImpact() {
-    return impact;
-}
-public void setImpact(final BigDecimal impact) {
-    this.impact = impact;
-}
-----
-
-JDO/DataNucleus creates, at least with HSQL, the table with the field type as NUMERIC(19). No decimal digits are admitted. (Further details http://hsqldb.org/doc/2.0/guide/sqlgeneral-chapt.html#sgc_numeric_types[here]).
-
-What this implies is that, when a record is inserted, a log entry similar to this one appears:
-
-[source,java]
-----
-INSERT INTO ENTITY(..., IMPACT, ....) VALUES (...., 0.5, ....)
-----
-
-But when that same record is retrieved, the log will show that a value of "0" is returned, instead of 0.5.
-
-The solution is to explicitly add the scale to the field like this:
-
-[source,java]
-----
-@javax.jdo.annotations.Column(scale=2)
-private BigDecimal impact;
-public BigDecimal getImpact() {
-    return impact;
-}
-public void setImpact(final BigDecimal impact) {
-    this.impact = impact;
-}
-----
-
-In addition, you should also set the scale of the `BigDecimal`, using `setScale(scale, roundingMode)`.
-
-More information can be found http://www.opentaps.org/docs/index.php/How_to_Use_Java_BigDecimal:_A_Tutorial[here] and http://www.tutorialspoint.com/java/math/bigdecimal_setscale_rm_roundingmode.htm[here].
-
-
-
-
-== Mapping Blobs and Clobs
-
-Apache Isis configures JDO/DataNucleus so that the properties of type `org.apache.isis.applib.value.Blob` and `org.apache.isis.applib.value.Clob` can also be persisted.
-
-As for xref:ug.adoc#_ug_how-tos_class-structure_properties_mapping-joda-dates[Joda dates], this requires the `@javax.jdo.annotations.Persistent` annotation. However, whereas for dates one would always expect this value to be retrieved eagerly, for blobs and clobs it is not so clear cut.
-
-=== Mapping Blobs
-
-For example, in the `ToDoItem` class (of the https://github.com/isisaddons/isis-app-todoapp/blob/61b8114a8e01dbb3c380b31cf09eaed456407570/dom/src/main/java/todoapp/dom/module/todoitem/ToDoItem.java#L475[todoapp example app] (non-ASF) the `attachment` property is as follows:
-
-[source,java]
-----
-@javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = {
-    @javax.jdo.annotations.Column(name = "attachment_name"),
-    @javax.jdo.annotations.Column(name = "attachment_mimetype"),
-    @javax.jdo.annotations.Column(name = "attachment_bytes", jdbcType="BLOB", sqlType = "LONGVARBINARY")
-})
-private Blob attachment;
-@Property(
-        optionality = Optionality.OPTIONAL
-)
-public Blob getAttachment() {
-    return attachment;
-}
-public void setAttachment(final Blob attachment) {
-    this.attachment = attachment;
-}
-----
-
-The three `@javax.jdo.annotations.Column` annotations are required because the mapping classes that Apache Isis provides (https://github.com/apache/isis/blob/isis-1.4.0/component/objectstore/jdo/jdo-datanucleus/src/main/java/org/apache/isis/objectstore/jdo/datanucleus/valuetypes/IsisBlobMapping.java#L59[IsisBlobMapping] and https://github.com/apache/isis/blob/isis-1.4.0/component/objectstore/jdo/jdo-datanucleus/src/main/java/org/apache/isis/objectstore/jdo/datanucleus/valuetypes/IsisClobMapping.java#L59[IsisClobMapping]) map to 3 columns. (It is not an error to omit these `@Column` annotations, but without them the names of the table columns are simply suffixed `_0`, `_1`, `_2` etc.
-
-If the `Blob` is mandatory, then use:
-
-[source,java]
-----
-@javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = {
-    @javax.jdo.annotations.Column(name = "attachment_name", allowsNull="false"),
-    @javax.jdo.annotations.Column(name = "attachment_mimetype", allowsNull="false"),
-    @javax.jdo.annotations.Column(name = "attachment_bytes",
-                                  jdbcType="BLOB", sqlType = "LONGVARBINARY",
-                                  allowsNull="false")
-})
-private Blob attachment;
-@Property(
-    optionality = Optionality.MANDATORY
-)
-public Blob getAttachment() {
-return attachment;
-}
-public void setAttachment(final Blob attachment) {
-this.attachment = attachment;
-}
-----
-
-[NOTE]
-====
-If specifying a `sqlType` of "LONGVARBINARY" does not work, try instead "BLOB".  There can be differences in behaviour between JDBC drivers.
-====
-
-
-=== Mapping Clobs
-
-Mapping `Clob`s works in a very similar way, but the `jdbcType` and `sqlType` attributes will, respectively, be `CLOB` and `LONGVARCHAR`:
-
-[source,java]
-----
-@javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = {
-    @javax.jdo.annotations.Column(name = "attachment_name"),
-    @javax.jdo.annotations.Column(name = "attachment_mimetype"),
-    @javax.jdo.annotations.Column(name = "attachment_chars",
-                                  jdbcType="CLOB", sqlType = "LONGVARCHAR")
-})
-private Clob doc;
-@Property(
-    optionality = Optionality.OPTIONAL
-)
-public Clob getDoc() {
-    return doc;
-}
-public void setDoc(final Clob doc) {
-    this.doc = doc;
-}
-----
-
-[NOTE]
-====
-If specifying a `sqlType` of "LONGVARCHAR" does not work, try instead "CLOB".  There can be differences in behaviour between JDBC drivers.
-====
-
-=== Mapping to VARBINARY or VARCHAR
-
-Instead of mapping to a sqlType of `LONGVARBINARY` (or perhaps `BLOB`), you might instead decide to map to a `VARBINARY`.  The difference is whether the binary data is held "on-row" or as a pointer "off-row"; with a `VARBINARY` the data is held on-row and so you will need to specify a length.
-
-For example:
-
-
-[source,java]
-----
-@javax.jdo.annotations.Column(name = "attachment_bytes", jdbcTypr="BLOB", sqlType = "VARBINARY", length=2048)
-----
-
-
-The same argument applies to `LONGVARCHAR` (or `CLOB`); you could instead map to a regular `VARCHAR`:
-
-
-[source,java]
-----
-@javax.jdo.annotations.Column(name = "attachment_chars", sqlType = "VARCHAR", length=2048)
-----
-
-Support and maximum allowed length will vary by database vendor.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_contributed-members.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_contributed-members.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_contributed-members.adoc
deleted file mode 100644
index 7763490..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_contributed-members.adoc
+++ /dev/null
@@ -1,69 +0,0 @@
-[[_ug_how-tos_contributed-members]]
-= 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/
-
-
-
-NOTE: TODO - generalize to discussion on contributed collections/properties; update to new annotations
-
-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,java]
-----
-public interface Library {
-    public Loan borrow(Loanable l, Borrower b);
-}
-----
-
-and the entities:
-
-[source,java]
-----
-public class Book implements Loanable { ... }
-----
-
-and
-
-[source,java]
-----
-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,java]
-----
-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`.
-
-
-## Contributed Action
-
-NOTE: TODO
-
-## Contributed Property
-
-NOTE: TODO
-
-## Contributed Collection
-
-NOTE: TODO
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_crud.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_crud.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_crud.adoc
deleted file mode 100644
index 353f468..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_crud.adoc
+++ /dev/null
@@ -1,29 +0,0 @@
-[[_ug_how-tos_crud]]
-= 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/
-
-NOTE: TODO
-
-
-## Instantiating and Persisting Objects
-
-NOTE: TODO - using ``DomainObjectContainer``'s support for  xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-creation-api[creation] and xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-persistence-api[persistence]
-
-## Finding Objects
-
-NOTE: TODO - using xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_generic-repository-api[`DomainObjectContainer`]
-
-### Using DataNucleus type-safe queries
-
-NOTE: TODO - as described xref:rgsvc.adoc#_rgsvc-api_IsisJdoSupport_type-safe-jdoql-queries[here]
-
-
-
-## Deleting Objects
-
-NOTE: TODO using ``DomainObjectContainer``'s support for  xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-persistence-api[persistence]
-
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_derived-members.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_derived-members.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_derived-members.adoc
deleted file mode 100644
index dea0b06..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_derived-members.adoc
+++ /dev/null
@@ -1,48 +0,0 @@
-[[_ug_how-tos_derived-members]]
-= 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/
-
-NOTE: TODO
-
-
-
-
-== Derived Property
-
-NOTE: TODO
-
-
-
-
-== Derived Collection
-
-NOTE: TODO
-
-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
-
-NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_modify[`modify...()`], xref:rgcms.adoc#_rgcms_methods_prefixes_clear[`clear...()`]
-
-
-
-== Trigger on collection change
-
-NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_addTo[`addTo...()`], xref:rgcms.adoc#_rgcms_methods_prefixes_removeFrom[`removeFrom...()`]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_domain-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_domain-services.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_domain-services.adoc
deleted file mode 100644
index eea9859..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_domain-services.adoc
+++ /dev/null
@@ -1,313 +0,0 @@
-[[_ug_how-tos_domain-services]]
-= Domain 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/
-
-
-
-
-In Apache Isis domain services have several responsibilities:
-
-- to expose actions to be rendered in the menu
-- to provide actions that are rendered as contributed actions/properties/collections on the contributee domain object
-- they act as subscribers to the event bus
-- they act as repositories (find existing objects) or as factories (create new objects)
-- they provide other services (eg performing calculations, attach a barcode, send an email etc).
-- to implement an SPI of the framework, most notably cross-cutting concerns such as security, command profiling, auditing and publishing.
-
-It's worth extending the xref:ug.adoc#_ug_core-concepts_philosophy_hexagonal-architecture[Hexagonal Architecture] to show where domain services -- and in particular the domain services provided by link:http://www.isisaddons.org[Isis Addons] (non-ASF) -- fit in:
-
-.The hexagonal architecture with Isis addons
-image::{_imagesdir}how-tos/domain-services/hexagonal-architecture-addons.png[width="700px"]
-
-The (non-ASF) link:http://isisaddons.org[Isis Addons] are a good source of domain services, providing SPI implementations of the common cross-cutting concerns, and also a number of APIs for domain objects to invoke (eg tags, excel, settings).  Of course, you can also write your own domain services as well, for example to interface with some external CMS system, say.
-
-The Apache Isis framework also provides numerous in-built domain services.  These are catalogued in the reference guide, see xref:rgsvc.adoc#_rgsvc-api[here] and xref:rgsvc.adoc#_rgsvc-spi[here].
-
-
-
-[[_ug_how-tos_domain-services_organizing-services]]
-== Organizing Services
-
-In larger applications we have found it worthwhile to ensure that our domain services only act aligned with these responsibilities, employing a naming convention so that it is clear what the responsibilities of each domain service is.
-
-The application provides the `@DomainService(nature=...)` annotation that helps distinguish some of these responsibilities:
-
-- `VIEW` indicates that the actions should appear both on the menu and also be used as contributions
-- `VIEW_MENU_ONLY` indicates that the actions should appear on the menu
-- `VIEW_CONTRIBUTED_ONLY` indicates that the actions should appear on the menu
-- `DOMAIN` indicates that the actions are for other domain objects to invoke (either directly or indirectly through the event bus), but in any case should not be rendered at all in the UI
-
-Pulling all the above together, here are our suggestions as to how you should organize your domain services.
-
-
-=== Factory and Repository
-
-The factory/repository uses an injected `DomainObjectContainer` to both instantiate new objects and to query the database for existing objects of a given entity type.  It is not visible in UI, rather other services delegate to it.
-
-We suggest naming such classes `XxxRepository`, eg:
-
-
-[source,java]
-----
-@DomainService(
-    nature=NatureOfService.DOMAIN                               // <1>
-)
-public CustomerRepository {
-    public List<Customer> findCustomerBy...(...) {
-        return allMatches(...);
-    }
-    public Customer newCustomer(...) {
-        Customer Customer = container.newTransientInstance(Customer.class);
-        ...
-        persistIfNotAlready(Customer);
-        return Customer;
-    }
-    public List<Customer> allCustomers() {
-        return container.allInstances(Customer.class);
-    }
-    @Inject
-    DomainObjectContainer container;
-}
-----
-<1> interacted with only programmatically by other objects in the domain layer.
-
-There is no need to annotate the actions; they are implicitly hidden because of the domain service's nature.
-
-
-
-=== Menu
-
-Menu services provide actions to be rendered on the menu.
-
-For the Wicket viewer, each service's actions appear as a collection of menu items of a named menu, and this menu is on one of the three menu bars provided by the Wicket viewer.  It is possible for more than one menu service's actions to appear on the same menu; a separator is shown between each.
-
-For the Restful Objects viewer, all menu services are shown in the services representation.
-
-We suggest naming such classes `XxxMenu`, eg:
-
-
-[source,java]
-----
-@DomainService(
-    nature = NatureOfService.VIEW_MENU_ONLY                     // <1>
-)
-@DomainServiceLayout(
-        named = "Customers",                                    // <2>
-        menuBar = DomainServiceLayout.MenuBar.PRIMARY,
-        menuOrder = "10"
-)
-public class CustomerMenu {
-    @Action(
-            semantics = SemanticsOf.SAFE
-    )
-    @MemberOrder( sequence = "1" )
-    public List<Customer> findCustomerBy...(...) {
-        return CustomerRepository.findCustomerBy(...);          // <3>
-    }
-
-    @Action(
-            semantics = SemanticsOf.NON_IDEMPOTENT
-    )
-    @MemberOrder( sequence = "3" )
-    public Customer newCustomer(...) {
-        return CustomerRepository.newCustomer(...);
-    }
-
-    @Action(
-            semantics = SemanticsOf.SAFE,
-            restrictTo = RestrictTo.PROTOTYPING
-    )
-    @MemberOrder( sequence = "99" )
-    public List<Customer> allCustomers() {
-        return CustomerRepository.allBankMandates();
-    }
-
-    @Inject
-    protected CustomerRepository customerRepository;
-}
-----
-<1> the service's actions should be rendered as menu items
-<2> specifies the menu name.  All services with the same menu name will be displayed on the same menu, with separators between
-<3> delegates to an injected repository.
-
-Not every action on the repository need to be delegated to of course (the above example does but only because it is very simple).
-
-[TIP]
-====
-Note also that while there's nothing to stop `VIEW_MENU` domain services being injected into other domain objects and interacted with programmatically, we recommend against it.  Instead, inject the underlying repository.  If there is additional business logic, then consider introducing a further `DOMAIN`-scoped service and call that instead.
-====
-
-
-
-=== Contributions
-
-Services can contribute either actions, properties or collections, based on the type of their parameters.
-
-We suggest naming such classes `XxxContributions`, eg:
-
-[source,java]
-----
-@DomainService(
-    nature=NatureOfService.VIEW_CONTRIBUTIONS_ONLY              // <1>
-)
-@DomainServiceLayout(
-    menuOrder="10",
-    name="...",
-}
-public OrderContributions {
-    @Action(semantics=SemanticsOf.SAFE)
-    @ActionLayout(contributed=Contributed.AS_ASSOCIATION)       // <2>
-    @CollectionLayout(render=RenderType.EAGERLY)
-    public List<Order> orders(Customer customer) {              // <3>
-        return container.allMatches(...);
-    }
-
-    @Inject
-    CustomerRepository customerRepository;
-}
-----
-<1> the service's actions should be contributed to the entities of the parameters of those actions
-<2> contributed as an association, in particular as a collection because returns a `List<T>`.
-<3> Only actions with a single argument can be contributed as associations
-
-More information about contributions can be found xref:ug.adoc#_ug_how-tos_contributed-members[here].  More information
-about using contributions and mixins to keep your domain application decoupled can be found xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling_contributions[here] and xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling_mixins[here].
-
-
-=== Event Subscribers
-
-Event subscribers can both veto interactions (hiding members, disabling members or validating changes), or can react to interactions (eg action invocation or property edit).
-
-We suggest naming such classes `XxxSubscriptions`, eg:
-
-[source,java]
-----
-@DomainService(
-    nature=NatureOfService.DOMAIN                       // <1>
-)
-@DomainServiceLayout(
-    menuOrder="10",
-    name="...",
-}
-public CustomerOrderSubscriptions {
-    @com.google.common.eventbus.Subscribe
-    public void on(final Customer.DeletedEvent ev) {
-        Customer customer = ev.getSource();
-        orderRepository.delete(customer);
-    }
-    @Inject
-    OrderRepository orderRepository;
-}
-----
-<1> subscriptions do not appear in the UI at all, so should use the domain nature of service
-
-
-
-== Prototyping
-
-While for long-term maintainability we do recommend the naming conventions described xref:ug.adoc#_ug_how-tos_domain-services_organizing-services[above], you can get away with far fewer services when just prototyping a domain.
-
-If the domain service nature is not specified (or is left to its default, `VIEW`), then the service's actions will
-appear in the UI both as menu items _and_ as contributions (and the service can of course be injected into other domain objects for programmatic invocation).
-
-Later on it is easy enough to refactor the code to tease apart the different responsibilities.
-
-
-
-
-== Scoped services
-
-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 xref:rgant.adoc#_rgant-RequestScoped[`@javax.enterprise.context.RequestScoped`] is used to indicate this fact:
-
-[source,java]
-----
-@javax.enterprise.context.RequestScoped
-public class MyService extends AbstractService {
-    ...
-}
-----
-
-The framework provides a number of request-scoped services, include a scratchpad service, query results caching, and support for co-ordinating bulk actions.  See xref:rgsvc.adoc#_rgsvc-api[here] and xref:rgsvc.adoc#_rgsvc-spi[here] for further details.
-
-
-
-
-== Registering domain services
-
-The easiest way to register domain services is using xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`] to specify the modules
-which contain xref:rgant.adoc#_rgant-DomainService[`@DomainService`]-annotated classes.
-
-For example:
-
-[source,ini]
-----
-public class MyAppManifest implements AppManifest {
-    public List<Class<?>> getModules() {
-        return Arrays.asList(
-                ToDoAppDomainModule.class,
-                ToDoAppFixtureModule.class,
-                ToDoAppAppModule.class,
-                org.isisaddons.module.audit.AuditModule.class);
-    }
-    ...
-}
-----
-
-will load all services in the packages underneath the four modules listed.
-
-An alternative (older) mechanism is to registered domain services in the `isis.properties` configuration file, under `isis.services` key (a comma-separated list); for example:
-
-[source,ini]
-----
-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,ini]
-----
-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) include clock, auditing, publishing, exception handling, view model support, snapshots/mementos, and user/application settings management; see the xref:rgsvc.adoc#_rgsvc-api[here] and _rgsvc-spi[here] for further details.
-
-
-
-
-== Initialization
-
-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 Apache Isis session _is_ available when initialization occurs (so services can interact with the object store, for example).
-
-
-The framework will call any `public` method annotated with xref:rgant.adoc#_rgant-PostConstruct[`@PostConstruct`] 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 is similar; the framework will call any method annotated with xref:rgant.adoc#_rgant-PreDestroy[`@PreDestroy`].
-
-
-
-== The getId() method
-
-Optionally, a service may provide a xref:rgcms.adoc#_rgcms_methods_reserved_getId[`getId()`] method.  This method returns a logical identifier for a service, independent of its implementation.
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_drop-downs-and-defaults.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_drop-downs-and-defaults.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_drop-downs-and-defaults.adoc
deleted file mode 100644
index 94891a7..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_drop-downs-and-defaults.adoc
+++ /dev/null
@@ -1,65 +0,0 @@
-[[_ug_how-tos_drop-downs-and-defaults]]
-= 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/
-
-NOTE: TODO
-
-
-== For Properties
-
-NOTE: TODO
-
-### Choices for Property
-
-NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`]
-
-### Auto-complete for property
-
-NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`]
-
-### Default for property
-
-NOTE: TODO -  xref:rgcms.adoc#_rgcms_methods_prefixes_default[`default...()`]
-
-
-
-
-== For Action Parameters
-
-NOTE: TODO
-
-### Choices for action parameter
-
-NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`]
-
-### Dependent choices for action params
-
-NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`]
-
-### Auto-complete for action param
-
-NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`]
-
-### Default for action param
-
-NOTE: TODO -  xref:rgcms.adoc#_rgcms_methods_prefixes_default[`default...()`]
-
-
-
-
-
-== For both Properties and Action Parameters
-
-NOTE: TODO
-
-
-### Drop-down for limited number of instances
-
-NOTE: TODO - xref:rgant.adoc#_rgant-DomainObject_bounded[`@DomainObject#bounded()`]
-
-
-### Auto-complete (repository-based)
-
-xref:rgant.adoc#_rgant-DomainObject_autoCompleteRepository[`@DomainObject#autoCompleteRepository()`]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_entity-relationships.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_entity-relationships.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_entity-relationships.adoc
deleted file mode 100644
index a41ad08..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_entity-relationships.adoc
+++ /dev/null
@@ -1,15 +0,0 @@
-[[_ug_how-tos_entity-relationships]]
-= 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/
-
-
-NOTE: TODO
-
-== Mandatory and Optional
-
-NOTE: TODO
-
-
-include::_ug_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships.adoc
deleted file mode 100644
index 0b1d64a..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships.adoc
+++ /dev/null
@@ -1,59 +0,0 @@
-[[_ug_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships]]
-= 1-m bidir 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/
-
-
-
-When an object is added to a 1:m bidirectional relationship, the child object must refer to the parent and the child must be added to the parent's children collection.
-
-If there were no database involved then we would have recommended that you use the link:http://www.two-sdg.demon.co.uk/curbralan/papers/MutualRegistration.pdf[mutual registration] pattern to ensure that both the parent and child are updated correctly.  (The  xref:rgcms.adoc#_rgcms_methods_prefixes_modify[`modify...()`] and xref:rgcms.adoc#_rgcms_methods_prefixes_clear[`clear...()`] supporting methods were introduced in the framework primarily to help support implement the mutual registration pattern.
-
-However, in a relational database, these two operations in the domain object model correspond simply to updating the foreign key of the child table to reference the parent's primary key.
-
-So long as the parent's children collection is a `java.util.Set` (rather than a `Collection` or a `List`), the JDO Objectstore will automatically maintain both sides of the relationship. All that is necessary is to set the child to refer to the parent.
-
-For example, all you need write is:
-
-[source,java]
-----
-public class Department {
-    @javax.jdo.annotations.Persistent(mappedBy="department") // <1>
-    private SortedSet<Employee> employees = new TreeSet<Employee>();
-
-    public SortedSet<Employee> getEmployees() { ... }
-    public void setEmployees(SortedSet<Employee> employees) { ... }
-    ...
-}
-public class Employee {
-    private Department department;
-    public Department getDepartment() { ... }
-    public void setDepartment(Department department) { ... }
-    ...
-}
-----
-<1> it's the `mappedBy` attribute that tells DataNucleus this is a bidirectional relationship.  The value "department" refers to the Employee#department property.
-
-Moreover, when maintaining a bidirectional 1-n relationship that is automatically managed by DataNucleus, it's preferred to "add" to the parent's child collection, don't set the parent on the child.
-
-
-[WARNING]
-====
-If you don't do this then you may hit a `NullPointerException`. The above idiom fixes the issue.
-
-For more information, see http://isis.markmail.org/thread/ipu2lzqqikqdglox[this thread] on the Apache Isis users
-mailing list, including this http://markmail.org/message/hblptpw675mlw723[message] with the above recommendation.
-====
-
-
-[WARNING]
-====
-In fact, not only do you not need to manually maintain the relationship, we have noted on at least http://markmail.org/message/agnwmzocvdfht32f[one occasion] a subtle error if the code is programmatically added.
-
-The error in that case was that the same object was contained in the parents collection. This of course should not happen for a `TreeSet`. However, JDO/DataNucleus replaces the `TreeSet` with its own implementation, and (either by design or otherwise) this does not enforce `Set` semantics.
-
-The upshot is that you should NEVER programmatically add the child object to the parent's collection if using JDO Objectstore.
-====
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_render-all-properties-in-tables.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_render-all-properties-in-tables.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_render-all-properties-in-tables.adoc
deleted file mode 100644
index 4b51613..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_render-all-properties-in-tables.adoc
+++ /dev/null
@@ -1,49 +0,0 @@
-[[_ug_how-tos_render-all-properties-in-tables]]
-= Subclass properties in tables
-: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/
-
-
-
-Suppose you have a hierarchy of classes where a property is derived and abstract in the superclass, concrete implementations in the subclasses. For example:
-
-[source,java]
-----
-public abstract class LeaseTerm {
-    public abstract BigDecimal getEffectiveValue();
-    ...
-}
-
-public class LeaseTermForIndexableTerm extends LeaseTerm {
-    public BigDecimal getEffectveValue() { ... }
-    ...
-}
-----
-
-Currently the Wicket viewer will not render the property in tables (though the property is correctly rendered in views).
-
-[NOTE]
-====
-For more background on this workaround, see https://issues.apache.org/jira/browse/ISIS-582[ISIS-582].
-====
-
-The work-around is simple enough; make the method concrete in the superclass and return a dummy implementation, eg:
-
-[source,java]
-----
-public abstract class LeaseTerm {
-    public BigDecimal getEffectiveValue() {
-        return null;        // workaround for ISIS-582
-    }
-    ...
-}
-----
-
-
-Alternatively the implementation could throw a `RuntimeException`, eg
-
-[source,java]
-----
-throw new RuntimeException("never called; workaround for ISIS-582");
-----
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_simulating-collections-of-values.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_simulating-collections-of-values.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_simulating-collections-of-values.adoc
deleted file mode 100644
index 32f38a2..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_simulating-collections-of-values.adoc
+++ /dev/null
@@ -1,23 +0,0 @@
-[[_ug_how-tos_simulating-collections-of-values]]
-= Collections of values
-: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/
-
-
-
-Although in Apache Isis you can have properties of either values (string, number, date etc) or of (references to other) entities, with collections the framework (currently) only supports collections of (references to) entities.  That is, collections of values (a bag of numbers, say) are not supported.
-
-However, it is possible to simulate a bag of numbers using view models.
-
-
-== View Model
-
-NOTE: TODO
-
-
-
-== Persistence Concerns
-
-NOTE: TODO -  easiest to simply store using DataNucleus' support for collections, marked as xref:rgant.adoc#_rgant-Programmatic[`@Programmatic`] so that it is ignored by Apache Isis.  Alternatively can store as json/xml in a varchar(4000) or clob and manually unpack.
-


[30/52] [abbrv] isis git commit: ISIS-1243: updating RO documentation

Posted by mg...@apache.org.
ISIS-1243: updating RO documentation


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/ff92fd0c
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/ff92fd0c
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/ff92fd0c

Branch: refs/heads/ISIS-1224-select2-v4
Commit: ff92fd0c68ba22a970598a9c69758fd17c0d6a9a
Parents: f6f60c7
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Fri Dec 4 14:06:14 2015 +0000
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Fri Dec 4 14:15:41 2015 +0000

----------------------------------------------------------------------
 adocs/documentation/publish.sh                  |   8 +-
 .../_tg_stop-scaffolding-start-coding.adoc      |   2 +-
 .../src/main/asciidoc/guides/_ugfun_faqs.adoc   |   1 +
 .../asciidoc/guides/_ugvro_architecture.adoc    |  57 +++++
 .../guides/_ugvro_configuration-properties.adoc |  57 ++---
 ...configuration-properties_honor-ui-hints.adoc |  27 ---
 ...erties_simplified-object-representation.adoc |  68 ------
 ...uration-properties_suppressing-elements.adoc |  39 ----
 .../main/asciidoc/guides/_ugvro_extending.adoc  |  51 -----
 .../main/asciidoc/guides/_ugvro_features.adoc   |  13 --
 .../asciidoc/guides/_ugvro_hints-and-tips.adoc  |   3 +
 .../main/asciidoc/guides/_ugvro_ro-spec.adoc    | 193 ++++++++++++++++-
 .../_ugvro_simplified-representations.adoc      | 146 +++++++++++++
 ...epresentations_configuration-properties.adoc | 135 ++++++++++++
 .../service-collaborations.png                  | Bin 10368 -> 28874 bytes
 .../service-collaborations.pptx                 | Bin 52460 -> 51472 bytes
 .../ro-spec-resources-and-representations.png   | Bin 0 -> 139796 bytes
 .../src/main/asciidoc/guides/rgcms.adoc         |   2 +-
 .../src/main/asciidoc/guides/ugvro.adoc         |  17 +-
 .../RepresentationServiceContentNegotiator.java | 215 +++++++++++++++++++
 .../RepresentationServiceForRestfulObjects.java | 201 +----------------
 21 files changed, 788 insertions(+), 447 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/ff92fd0c/adocs/documentation/publish.sh
----------------------------------------------------------------------
diff --git a/adocs/documentation/publish.sh b/adocs/documentation/publish.sh
index 42adcdc..1cfb9b3 100644
--- a/adocs/documentation/publish.sh
+++ b/adocs/documentation/publish.sh
@@ -1,2 +1,8 @@
 #!/usr/bin/env bash
-mvn clean install -D message="$1"
+if [ "$1" = "" ]; then
+	MSG=`git log -1 --pretty=%B`
+else
+	MSG=$1
+fi
+echo $MSG
+mvn clean install -D message="$MSG"

http://git-wip-us.apache.org/repos/asf/isis/blob/ff92fd0c/adocs/documentation/src/main/asciidoc/guides/_tg_stop-scaffolding-start-coding.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_tg_stop-scaffolding-start-coding.adoc b/adocs/documentation/src/main/asciidoc/guides/_tg_stop-scaffolding-start-coding.adoc
index 3656b2d..dd0cd14 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_tg_stop-scaffolding-start-coding.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_tg_stop-scaffolding-start-coding.adoc
@@ -668,7 +668,7 @@ Isis has great support for writing xref:ugtst.adoc#_ugtst_integ-test-support[int
 
 The REST API generated by Apache Isis conforms to the Restful Objects specification. Apache Isis 1.8.0 provides experimental support to allow the representations to be customized.
 
-* as per xref:ugvro.adoc#_ugvro_configuration-properties_simplified-object-representation[the documentation], configure the Restful Objects viewer to generate a simplified object representation: +
+* as per xref:ugvro.adoc#_ugvro_simplified-representations_configuration-properties[the documentation], configure the Restful Objects viewer to generate a simplified object representation: +
 +
 [source,ini]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/ff92fd0c/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs.adoc
index ca3b9fd..b35409e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs.adoc
@@ -8,6 +8,7 @@
 This chapter has FAQs (with solutions) for problems we've encountered ourselves or have been raised on the
 Apache Isis mailing lists.
 
+See also xref:ugvro.adoc#_ugvro_hints-and-tips[Restful Objects hints-n-tips].
 
 include::_ugfun_faqs_enabling-logging.adoc[leveloffset=+1]
 include::_ugfun_faqs_subtype-entity-not-fully-populated.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/ff92fd0c/adocs/documentation/src/main/asciidoc/guides/_ugvro_architecture.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugvro_architecture.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugvro_architecture.adoc
new file mode 100644
index 0000000..bf496d4
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugvro_architecture.adoc
@@ -0,0 +1,57 @@
+[[_ugvro_architecture]]
+= Architecture
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+The xref:ugvro.adoc#[RestfulObjects viewer] implements the http://restfulobjects.org[Restful Object spec], meaning
+that it defines a well-defined set of endpoint URLs as resources, and generates a well-defined set of (JSON)
+representations when these resources are accessed.
+
+By default, the Restful Objects viewer will automatically handle requests and return representations according to the
+RO spec.  However, its internal architecture provides several hooks for content negotiation, thereby allowing the
+generated representation to be influenced using the standard HTTP `Accept` header.  In response, the server uses
+the `Content-Type` header which the client can use to know how to process the returned representation.
+
+
+* `RepresentationService` +
++
+The xref:rgsvc.adoc#_rgsvc-spi_RepresentationService[`RepresentationService`] is an SPI domain service (plugin-point)
+that allows an arbitrary representation to be generated for any of the resources defined in the RO spec. +
++
+Normally this SPI service need not be replaced, because the default implementation
+(`RepresentationServiceContentNegotiator`) simply uses the HTTP `Accept` header and delegates onto another service, the
+(slightly misnamed) `ContentNegotiationService`, to actually generate the representation.  There can be multiple
+implementations of the `ContentNegotiationService` and the content negotiator will delegate to each in turn until one
+is able to handle the request (per the chain of responsibliity pattern).
+
+* `ContentNegotiationService` +
++
+As noted above, there can be multiple implementations of the
+xref:rgsvc.adoc#_rgsvc-spi_ContentNegotiationService[`ContentNegotiationService`], each one handling a particular
+HTTP `Accept` header.  If the implementation does not recognize the value of the header, if can simply return `null`. +
++
+The framework provides a number of implementations; an implementation that handles the
+xref:ugvro.adoc#_ugvro_simplified-representations[simplified representation] of the Apache Isis profile
+(`1.11.0-SNAPSHOT`); an implementation that provides support for the `x-ro-domain-type` parameter, and a
+default/fallback implementation that returns the representations defined by the RO spec.
+
+* `ContentMappingService` +
++
+The xref:rgsvc.adoc#_rgsvc-spi_ContentMappingService[`ContentMappingService`] is used by the implementation of
+`ContentNegotationService` that recognizes the `x-ro-domain-type`, its role being to transform a domain object
+(usually an entity) into some other form (usually a DTO), as specified by the `x-ro-domain-type` parameter.  There
+can be many such implementations, each handling a different target domain type.
+
+
+This diagram shows how these services collaborate:
+
+image::{_imagesdir}reference-services-spi/RepresentationService/service-collaborations.png[width="800px",link="{_imagesdir}reference-services-spi/RepresentationService/service-collaborations.png"]
+
+
+Taken together these domain services offer a lot of flexibility in terms of the representations that can be generated
+from the RestfulObjects viewer.
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/ff92fd0c/adocs/documentation/src/main/asciidoc/guides/_ugvro_configuration-properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugvro_configuration-properties.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugvro_configuration-properties.adoc
index 1f072ec..0fe9e9f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugvro_configuration-properties.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugvro_configuration-properties.adoc
@@ -5,15 +5,20 @@
 :_imagesdir: images/
 
 
-The Restful Objects viewer provides a number of configuration option that extend/simplify/alter the representations generated from the Restful Objects specification.
+The Restful Objects viewer provides a couple of configuration option that extend/simplify/alter the representations
+generated from the Restful Objects specification.
 
-These configuration properties are typically stored in `WEB-INF/viewer_restfulobjects.properties`.  However, you can place all configuration properties into `WEB-INF/isis.properties` if you wish (the configuration properties from all config files are merged together).
+These configuration properties are typically stored in `WEB-INF/viewer_restfulobjects.properties`.  However, you can
+place all configuration properties into `WEB-INF/isis.properties` if you wish (the configuration properties from all
+config files are merged together).
 
-[WARNING]
+[NOTE]
 ====
-These configuration settings should be considered beta, and may change in the future in response to emerging requirements.
+As of `1.11.0-SNAPSHOT` these configuration settings should be considered deprecated, because the
+xref:ugvro.adoc#_ugvro_simplified-representations[simplified representation] support provided by the Apache Isis profile is a more flexible solution.
 
-Also, be aware enabling these settings makes the representations with respect to the http://restfulobjects.org[Restful Object spec].  (Based on experience in Apache Isis, in the future the spec may be updated to allow such extensions).
+Also, be aware enabling these settings makes the representations non-standard with respect to
+http://restfulobjects.org[Restful Object spec].
 ====
 
 
@@ -28,45 +33,11 @@ Also, be aware enabling these settings makes the representations with respect to
 |`isis.viewer.restfulobjects.` +
 `honorUiHints`
 | `true`,`false` (`_false_`)
-| See xref:ugvro.adoc#_ugvro_configuration-properties_honor-ui-hints[discussion], below.
-
-|`isis.viewer.restfulobjects.` +
-`suppressDescribedByLinks`
-| `true`,`false` (`_false_`)
-.6+| See xref:ugvro.adoc#_ugvro_configuration-properties_suppressing-elements[discussion], below.
-
-|`isis.viewer.restfulobjects.` +
-`suppressUpdateLink`
-| `true`,`false` (`_false_`)
-
-|`isis.viewer.restfulobjects.` +
-`suppressMemberId`
-| `true`,`false` (`_false_`)
-
-|`isis.viewer.restfulobjects.` +
-`suppressMemberLinks`
-| `true`,`false` (`_false_`)
-
-|`isis.viewer.restfulobjects.` +
-`suppressMemberExtensions`
-| `true`,`false` (`_false_`)
-
-|`isis.viewer.restfulobjects.` +
-`suppressMemberDisabledReason`
-| `true`,`false` (`_false_`)
-
-|`isis.viewer.restfulobjects.` +
-`objectPropertyValuesOnly`
-| `true`,`false` (`_false_`)
-| See xref:ugvro.adoc#_ugvro_configuration-properties_simplified-object-representation[discussion], below.
+|A mechanism for reducing the number of round-trips by eagerly rendering collections; discussed xref:ugvro.adoc#_ugvro_ro-spec_extensions_minimizing-round-trips_honor-ui-hints[here].
 
 |===
 
 
-
-
-include::_ugvro_configuration-properties_honor-ui-hints.adoc[leveloffset=+1]
-include::_ugvro_configuration-properties_suppressing-elements.adoc[leveloffset=+1]
-include::_ugvro_configuration-properties_simplified-object-representation.adoc[leveloffset=+1]
-
-
+There are also a number of configuration properties that can be used to suppress or simplify the default RO-spec
+representations.  These pre-date the Apache Isis profile `1.11.0-SNAPSHOT` support, so are considered deprecated.
+Discussion of them can nevertheless be found xref:ugvro.adoc#_ugvro_simplified-representations_configuration-properties[here].
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/ff92fd0c/adocs/documentation/src/main/asciidoc/guides/_ugvro_configuration-properties_honor-ui-hints.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugvro_configuration-properties_honor-ui-hints.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugvro_configuration-properties_honor-ui-hints.adoc
deleted file mode 100644
index 1dbd618..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugvro_configuration-properties_honor-ui-hints.adoc
+++ /dev/null
@@ -1,27 +0,0 @@
-[[_ugvro_configuration-properties_honor-ui-hints]]
-= Honor UI hints
-: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/
-
-
-
-
-By default the representations generated by Restful Objects ignore any Apache Isis metamodel hints referring to the UI.
-In particular, if a collection is annotated then `Render(EAGERLY)` then the contents of the collection are _not_
-eagerly embedded in the object representation.
-
-However, this behaviour can be overridden globally using following property (typically added to `WEB-INF/viewer_restfulobjects.properties`):
-
-[source,ini]
-----
-isis.viewer.restfulobjects.honorUiHints=true
-----
-
-[NOTE]
-====
-In the future we might extend this per-request.  Raise/vote on a JIRA ticket if you require this feature.
-====
-
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/ff92fd0c/adocs/documentation/src/main/asciidoc/guides/_ugvro_configuration-properties_simplified-object-representation.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugvro_configuration-properties_simplified-object-representation.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugvro_configuration-properties_simplified-object-representation.adoc
deleted file mode 100644
index 83e7e29..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugvro_configuration-properties_simplified-object-representation.adoc
+++ /dev/null
@@ -1,68 +0,0 @@
-[[_ugvro_configuration-properties_simplified-object-representation]]
-= Simplified object representation
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The representations specified by the http://restfulobjects.org[Restful Object spec] are very rich in hypermedia
-controls and metadata, intended to support a wide variety of possible REST clients.
-
-As described xref:ugvro.adoc#_ugvro_configuration-properties_suppressing-elements[above], it is possible to suppress various elements of these representations. Even then, though, the representations may be too complex for some bespoke REST clients that require a very "flat" object representation.
-
-The Restful Objects viewer therefore supports generating a much simpler representation of objects using the following configuration property (typically added to `WEB-INF/viewer_restfulobjects.properties`):
-
-[source,ini]
-----
-isis.viewer.restfulobjects.objectPropertyValuesOnly=true
-----
-
-This generates a representation such as:
-
-[source,javascript]
-----
-{
-    "title" : "Buy milk due by 2014-10-27",
-    "domainType" : "TODO",
-    "instanceId" : "0",
-    "members" : {
-        "description" : "Buy milk",
-        "category" : "Domestic",
-        "subcategory" : "Shopping",
-        "complete" : false,
-        "versionSequence" : 1,
-        "relativePriority" : 2,
-        "dueBy" : "2014-10-27",
-        "cost" : "0.75",
-        "notes" : null,
-        "attachment" : null,
-        "doc" : null
-    },
-    "links" : [
-        {
-            "rel" : "self",
-            "href" : "http://localhost:8080/restful/objects/TODO/0",
-            "method" : "GET",
-            "type" : "application/json;profile=\"urn:org.restfulobjects:repr-types/object\"",
-            "title" : "Buy milk due by 2014-10-27"
-        },
-        {
-            "rel" : "describedby",
-            "href" : "http://localhost:8080/restful/domain-types/TODO",
-            "method" : "GET",
-            "type" : "application/json;profile=\"urn:org.restfulobjects:repr-types/domain-type\""
-        }
-    ],
-    "extensions" : {
-        "oid" : "TODO:0"
-    },
-}
-----
-
-[NOTE]
-====
-In the future we might extend this per-request.  Raise/vote on a JIRA ticket if you require this feature.
-====
-
-If the above isn't flexible and you need complete control over all representations see the section on xref:ugvro.adoc#_ugvro_extending[Extending the Restful Objects viewer].

http://git-wip-us.apache.org/repos/asf/isis/blob/ff92fd0c/adocs/documentation/src/main/asciidoc/guides/_ugvro_configuration-properties_suppressing-elements.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugvro_configuration-properties_suppressing-elements.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugvro_configuration-properties_suppressing-elements.adoc
deleted file mode 100644
index c8bf314..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugvro_configuration-properties_suppressing-elements.adoc
+++ /dev/null
@@ -1,39 +0,0 @@
-[[_ugvro_configuration-properties_suppressing-elements]]
-= Suppressing elements of the representation
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The representations specified by the http://restfulobjects.org[Restful Object spec] are very rich in hypermedia controls and metadata, intended to support a wide variety of possible REST clients. However, if an application is providing its REST API only for a small well-defined set of REST clients, then it is possible to suppress (remove) various elements of these representations.
-
-This is done by globally using the following properties (typically added to `WEB-INF/viewer_restfulobjects.properties`):
-
-[source,ini]
-----
-isis.viewer.restfulobjects.suppressDescribedByLinks=true      # <1>
-isis.viewer.restfulobjects.suppressUpdateLink=true            # <2>
-isis.viewer.restfulobjects.suppressMemberId=true              # <3>
-isis.viewer.restfulobjects.suppressMemberLinks=true           # <4>
-isis.viewer.restfulobjects.suppressMemberExtensions=true      # <5>
-isis.viewer.restfulobjects.suppressMemberDisabledReason=true  # <6>
-----
-<1> suppresses the "describedby" links (on all representations)
-<2> suppresses the  "update" link (on object representation)
-<3> suppresses the  "id" json-prop for object members (on object representation and member detail representations)
-<4> suppresses the  "links" json-prop for object members (on the object representation and member detail representations)
-<5> suppresses the  "extensions" json-prop for object members (on the object representation and member detail representations)
-<6> suppresses the  "disabledReason" json-prop for object members (on the object representation and member detail representations)
-
-The defaults for all of these is false, meaning that the hypermedia/metadata is NOT suppressed.
-
-[NOTE]
-====
-In the future we might extend this per-request.  Raise/vote on a JIRA ticket if you require this feature.
-====
-
-If an even simpler representations (of objects) are required, see xref:ugvro.adoc#_ugvro_configuration-properties_simplified-object-representation[simplified object representation], immediately below.  And if the above isn't flexible and you need complete control over all representations see the section on xref:ugvro.adoc#_ugvro_extending[Extending the Restful Objects viewer] in the xref:ugbtb.adoc#[Extending] chapter.
-
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/ff92fd0c/adocs/documentation/src/main/asciidoc/guides/_ugvro_extending.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugvro_extending.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugvro_extending.adoc
deleted file mode 100644
index d74f529..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugvro_extending.adoc
+++ /dev/null
@@ -1,51 +0,0 @@
-[[_ugvro_extending]]
-= Extending the Viewer
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-The xref:ugvro.adoc#[RestfulObjects viewer] implements the http://restfulobjects.org[Restful Object spec], meaning that it defines a well-defined set of endpoint URLs as resources, and generates a well-defined set of (JSON) representations when these resources are accessed.
-
-Sometimes though you may want to extend or change the representations generated.  This might be because you want to write a RESTful client that uses a particular library (say a Javascript library or web components) that can only handle representations in a certain form.
-
-Or, you might want to have Apache Isis generate representations according to some other "standard", of which there are many (see note).
-
-[NOTE]
-====
-Other "standards" for defining representations that we are aware of include: http://stateless.co/hal_specification.html[HAL] (Mike Kelly), http://amundsen.com/media-types/collection/[Collection+JSON] (Mike Amundsen), https://github.com/kevinswiber/siren[Siren] (Kevin Swiber), http://jsonapi.org/[JSON API] (Steve Klabnik), https://github.com/cainus/hyper-json-spec[Hyper+JSON] (Gregg Cainus), https://www.w3.org/TR/json-ld/[JSON-LD] (W3C) and http://www.markus-lanthaler.com/hydra/[Hydra] (Markus Lanthaler).
-
-A good discussion about the relative merits of several of these different hypermedia formats can be found https://groups.google.com/forum/#!msg/api-craft/NgjzQYVOE4s/EAB2jxtU_TMJ[here].
-====
-
-
-Whatever your reasons, Apache Isis provides several mechanisms by which you can change the generated representation.  This section lists these, from the simplest (most limited) to the most flexible (more work).
-
-* Configuration Properties +
-+
-If all that is required is a very simple representations (of objects), you can reconfigure the xref:ugvro.adoc#[RestfulObjects viewer] to provide a simplified output, as described xref:ugvro.adoc#_ugvro_configuration-properties_simplified-object-representation[here]. +
-+
-If you simply want to suppress certain elements, as described  xref:ugvro.adoc#_ugvro_configuration-properties_suppressing-elements[here].
-
-* `RepresentationService` +
-+
-The xref:rgsvc.adoc#_rgsvc-spi_RepresentationService[`RepresentationService`] is an SPI domain service (plugin-point) that allows an arbitrary representation to be generated for any of the resources defined in the RO spec. +
-+
-The default implementation does, of course, generate the representations as defined in the RO spec.
-
-* `ContentNegotiationService` +
-+
-The xref:rgsvc.adoc#_rgsvc-spi_ContentNegotiationService[`ContentNegotiationService`] is very similar to `RepresentationService`, in that it allows for a different representation to be generated.  It isn't responsible for generating the default RO representations, however; if can simply return `null` (and leave it to the `RepresentationService` to generate the correct representations. +
-+
-The default implementation provides support for the `x-ro-domain-type` parameter for HTTP `Accept` headers, providing the capability sketched out in section 34.1 of the RO spec v1.0.  As such, it delegates to `ContentMappingService`, described below.
-
-* `ContentMappingService` +
-+
-The xref:rgsvc.adoc#_rgsvc-spi_ContentMappingService[`ContentMappingService`] is used by the default implementation of `ContentNegotationService` to transform a domain object (usually an entity) into some other form (usually a DTO), as specified by the `x-ro-domain-type` parameter.
-
-This diagram shows how these services collaborate:
-
-image::{_imagesdir}reference-services-spi/RepresentationService/service-collaborations.png[width="700px",link="{_imagesdir}reference-services-spi/RepresentationService/service-collaborations.png"]
-
-
-Taken together these configuration properties and domain services offer a lot of flexibility in terms of the representations that can be generated from the xref:ugvro.adoc#[RestfulObjects viewer].  Please be aware though that these using these SPIs means that the representations generated by the viewer are no longer conformant with those of the RO spec.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/ff92fd0c/adocs/documentation/src/main/asciidoc/guides/_ugvro_features.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugvro_features.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugvro_features.adoc
deleted file mode 100644
index 4ba5352..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugvro_features.adoc
+++ /dev/null
@@ -1,13 +0,0 @@
-[[_ugvro_features]]
-= Features
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The REST API opens up an Apache Isis domain model to a huge variety of applications, from bespoke single-page apps, through integration scenarious, through providing an API for bulk-upload/migration from an existing system.
-
-NOTE: TODO - further discussion required
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/ff92fd0c/adocs/documentation/src/main/asciidoc/guides/_ugvro_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugvro_hints-and-tips.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugvro_hints-and-tips.adoc
index c499e65..14498bc 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugvro_hints-and-tips.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugvro_hints-and-tips.adoc
@@ -11,6 +11,8 @@ Since the Restful Objects viewer is designed for computer programs to interact w
 This section provides a few hints-and-tips to help you on your way.
 
 
+
+
 == Using Chrome Tools
 
 The screencast below shows how to explore the Restful API using Chrome plugins/extensions, and how we use them to write end-2-end (TCK) tests for the Restful Objects viewer.
@@ -92,3 +94,4 @@ The JSON representations generated by the Restful Objects viewer are in compact
 
 
 
+

http://git-wip-us.apache.org/repos/asf/isis/blob/ff92fd0c/adocs/documentation/src/main/asciidoc/guides/_ugvro_ro-spec.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugvro_ro-spec.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugvro_ro-spec.adoc
index 339340b..735604c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugvro_ro-spec.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugvro_ro-spec.adoc
@@ -5,8 +5,197 @@
 :_imagesdir: images/
 
 
-The Restful Objects spec can be downloaded link:http://restfulobjects.org[here].
+The Restful Objects v1.0 specification defines a comprehensive hypermedia API, consisting of HTTP resources and
+corresponding JSON representations, for accessing and manipulating a domain object model.
 
-NOTE: TODO - a brief summary here
+The Restful Objects spec can be downloaded from link:http://restfulobjects.org[here] as either a PDF or Word doc.
 
 
+
+[[_ugvro_ro-spec_goals]]
+== Goals of the Spec
+
+The goal of Restful Objects is to allow domain models to be accessed through HTTP resources, returning a set of JSON
+representations. These representations can then be consumed by any client (e.g. Javascript, Java, .NET, Ruby, Python).
+
+Both the resources and representations are generalized so that they can be applied to any domain model, and by default
+all representations have media types designed to allow a completely generic client to be written, capable of working,
+unmodified, with any domain model that has a Restful Objects interface.
+
+Alternatively, the developer may write a custom client that has some shared knowledge of the domain being exposed, and
+render the information in a more specific fashion.
+
+Restful Objects also defines that representations are served up with parameterized media types. This allows clients to
+use content negotiation to ensure that representations do not change in a breaking fashion, enabling server and client
+to evolve independently.
+
+The Restful Objects specification is at a higher-level of abstraction than, say, the JAX-RS specifications for Java
+platform, or the WCF specifications on .NET. Specifically, the domain classes that it exposes are represented in a very
+general form. They consist of:
+
+* properties (fields), each holding either a scalar value or reference to another object;
+* collections, each holding a vector reference to other entities;
+* actions (operations/methods), whereby the object can execute business logic.
+
+Beyond this, though, Restful Objects makes very few assumptions. In particular, Restful Objects does not prescribe the
+nature of the domain model.
+
+The Restful Objects spec may be downloaded directly from github as either a PDF or as a Word doc.
+
+
+== Resources and Representations
+
+The diagram below - taken from the Restful Objects spec - shows the various resources (URLs) and representations (JSON)
+that are defined:
+
+image::{_imagesdir}restfulobjects/ro-spec-resources-and-representations.png[width="800px",link="{_imagesdir}restfulobjects/ro-spec-resources-and-representations.png"]
+
+The resource URLs are always well-defined, but Apache Isis' implementation allows for different representations to
+be returned, using content negotiation.  This is discussed further below.
+
+[NOTE]
+====
+In fact, there's nothing in Apache Isis to prevent you from defining your own REST controllers to provide custom
+resource URLs.  One use case might be to support user registration/authentication, a topic out-of-scope of the RO spec
+itself.
+====
+
+
+[[_ugvro_ro-spec_apache-isis-implementation]]
+== Apache Isis' implementation
+
+The Restful Objects viewer is Apache Isis' implementation of the Restful Objects spec.  It implements all the mandatory
+features of the specification.  It also implements some of the optional capabilities (as defined in section 3 of the
+RO spec, and as represented in the version resource, section 8.1):
+
+[cols="1a,1a,1a", options="header"]
+|===
+
+| Capability
+| Support
+| Notes
+
+
+| blobsClobs
+| yes
+| 
+
+| deleteObjects
+| yes
+|
+
+| domainModel
+| formal
+| The 'simple' scheme is _not_ supported
+
+| validateOnly
+| yes
+|
+
+
+|protoPersistentObjects
+|yes
+|
+
+|===
+
+
+
+
+[[_ugvro_ro-spec_extensions]]
+== Extensions
+
+The Restful Objects viewer also implements some of the "future ideas" that are out of scope for the RO spec v1.0, but
+described in section 34, "ideas for future extensions".
+
+
+
+[[_ugvro_ro-spec_extensions_content-negotiation]]
+=== Content Negotiation (34.1)
+
+Apache Isis provides two levels of support for content negotiation.
+
+[[_ugvro_ro-spec_extensions_content-negotiation_x-ro-domain-type]]
+==== `x-ro-domain-type`
+
+The first level is very similar to the "Domain Model Agnostic" approach sketched out in the RO spec.  The client
+can send an `x-ro-domain-type` parameter for either domain object representations (section 14 of the spec) or
+action invocation results (section 19 of the spec).  This can be combined with either `application/json` or
+`application/xml`.
+
+For example, the client could use an `Accept` header such as:
+
+[source]
+----
+Accept: application/xml;x-ro-domain-type="com.mycompany.viewmodels.v2.CustomerViewModel"
+----
+
+The server will use the xref:rgsvc.adoc#_rgsvc-spi_ContentMappingService[`ContentMappingService`] to attempt to
+transform the domain object into the requested `x-ro-domain-type`.  The whole process is discussed in more detail in
+the xref:ugvro.adoc#_ugvro_architecture[architecture] chapter.
+
+
+[[_ugvro_ro-spec_extensions_content-negotiation_apache-isis-profile]]
+==== Apache Isis profile
+
+The representations defined by the RO spec are very rich and enable complex client-side applications to be built.
+However, their sophistication can be an impediment to their use if one wishes to write a simple app using third-party
+components that expect to consume much simpler representations.  Examples of such tools are
+link:http://angular-ui.github.io/bootstrap/[Angular Bootstrap],
+link:http://vitalets.github.io/angular-xeditable/[Angular XEditable],
+link:https://github.com/mgcrea/angular-strap[Angular Strap].
+
+This support is discussed further in the xref:ugvro.adoc#_ugvro_simplified-representations[simplified representations]
+chapter.
+
+
+[[_ugvro_ro-spec_extensions_minimizing-round-trips]]
+=== Minimizing Round-trips (34.4)
+
+The Restful Objects viewer supports the `x-ro-follow-links` query parameter in a way very similar to that suggested
+in the RO spec, the main point being to avoid the "N+1" problem of too many (slow) network calls.  For example, using
+this feature one can load a grid of data in a single call.  (That said, the xref:ugvro.adoc#_ugvro_simplified-representations[simplified representations]
+supported by Restful Objects viewer also support this use case, albeit in way that deviates from the RO spec).
+
+The video below demonstrates the Restful Object viewer's support for `x-ro-follow-links` parameter, using the
+(non-ASF) http://github.com/isisaddons/isis-app-kitchensink[Isis addons' kitchensink] app as the example,
+This app contains three entities, `Grandparent`, `Parent` and `Child` that define a hierarchy of 1:m relationships.
+
+video::hSKnqqBQ7Zo[youtube,width="840px",height="472px"]
+
+The queries that are shown in the video include:
+
+* show parent and its children (titles) +
++
+pass:[<pre>http://localhost:8080/restful/objects/PARENT/0?x-ro-follow-links=members[children\].value]
+
+* show parent and its children (full details) +
++
+pass:[<pre>http://localhost:8080/restful/objects/PARENT/0?x-ro-follow-links=members[children\].value.href]
+
+* child's parent (title) +
++
+pass:[<pre>http://localhost:8080/restful/objects/CHILD/0?x-ro-follow-links=members[parent\].value]
+
+* child's siblings (up to its parent, down to children) +
++
+pass:[<pre>http://localhost:8080/restful/objects/CHILD/0?x-ro-follow-links=members[parent\].value.members[children\].value]
+
+
+
+[[_ugvro_ro-spec_extensions_minimizing-round-trips_honor-ui-hints]]
+==== Honor UI hints
+
+By default the representations generated by Restful Objects ignore any Apache Isis metamodel hints referring to the UI.
+In particular, if a collection is annotated then `Render(EAGERLY)` then the contents of the collection are _not_
+eagerly embedded in the object representation.
+
+However, this behaviour can be overridden globally using following property (typically added to `WEB-INF/viewer_restfulobjects.properties`):
+
+[source,ini]
+----
+isis.viewer.restfulobjects.honorUiHints=true
+----
+
+This means that standard Apache Isis annotations can be used as a simple way to obtain follow-links (driven from the
+server model, though, rather than the requesting client).
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/ff92fd0c/adocs/documentation/src/main/asciidoc/guides/_ugvro_simplified-representations.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugvro_simplified-representations.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugvro_simplified-representations.adoc
new file mode 100644
index 0000000..51f68d7
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugvro_simplified-representations.adoc
@@ -0,0 +1,146 @@
+[[_ugvro_simplified-representations]]
+= Simplified Representations
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The representations defined by the RO spec are very rich and enable complex client-side applications to be built.
+However, their sophistication can be an impediment to their use if one wishes to write a simple app using third-party
+components that expect to consume much simpler representations.  Examples of such tools are
+link:http://angular-ui.github.io/bootstrap/[Angular Bootstrap],
+link:http://vitalets.github.io/angular-xeditable/[Angular XEditable],
+link:https://github.com/mgcrea/angular-strap[Angular Strap].
+
+
+As of `1.11.0-SNAPSHOT`, Apache Isis provides support for its own simplified representation for the most commonly-used
+representations.  This is implemented using the `ContentNegotiationService` described in the
+xref:ugvro.adoc#_ugvro_architecture[architecture] chapter.
+
+
+
+[[_ugvro_simplified-representations_apache-isis-profile]]
+== The Apache Isis "Profile"
+
+The RO spec uses the standard `Accept` header for content negotiation, and defines its own "profile" for the standard
+representations; these take the form:
+
+[source]
+----
+Accept: application/json;profile="urn:org.restfulobjects:repr-types/xxx"
+----
+
+where "xxx" varies by resource.  The detail can be found in section 2.4.1 of the RO spec.
+
+The Apache Isis viewer also defines its own "Isis" profile which enables the client to request simplified
+representations for the most frequently accessed resources.  This is done by specifying an `Accept` header of:
+
+[source]
+----
+Accept: application/json;profile="urn:org.apache.isis/v1"
+----
+
+Not every resource supports this header, but the most commonly accessed ones do.  In each case the server will set the
+`Content-Type` header so that the client knows how to process the representation.
+
+[cols="1a,4a", options="header"]
+|===
+
+| Resource
+| Description
+
+
+|Domain object +
+(section 14)
+|The representation of a domain object is simple key/value pairs for each property.  The contents of any collections are
+also eagerly returned, consisting of an array of elements of each referenced object.  Each such element contains
+key/value pairs of each property (in other words, a grid of data is returned), along with special `$$href` and
+`$$title` properties. +
+
+In addition, the representation defined by the RO spec is also included, under a special `$$ro` property. +
+
+[source]
+----
+Content-Type: application/json;
+              profile="urn:org.apache.isis/v1";repr-type="object"
+----
+
+|Object Collection +
+(section 17)
+|Collections are represented as an array of elements of key/value for each referenced object, and again each element
+the containing the key/value pairs of the properties of that object (a grid, again). +
+
+In addition, the representation defined by the RO spec is also included, as a special object with a single `$$ro`
+property. +
+
+[source]
+----
+Content-Type: application/json;
+              profile="urn:org.apache.isis/v1";repr-type="object-collection"
+----
+
+|Action invocation +
+(section 19)
+|If the action returned an object, then the domain object representation described above is returned. +
+
+[source]
+----
+Content-Type: application/json;
+              profile="urn:org.apache.isis/v1";repr-type="object"
+----
+
+If the action returned a list, then the same array representation as (parented) object collections is returned, though
+with a slightly different `Content-Type` to distinguish:
+
+[source]
+----
+Content-Type: application/json;
+              profile="urn:org.apache.isis/v1";repr-type="list"
+----
+
+Note that actions returning scalar values or void are not supported; for these the regular RO spec representation will
+be returned.
+
+|===
+
+
+
+
+[[_ugvro_simplified-representations_other-representations]]
+== Supporting other Representations
+
+Sometimes though you may want to extend or change the representations generated.  This might be because you want to
+write a RESTful client that uses a particular library (say a Javascript library or web components) that can only handle representations in a certain form.
+
+Or, you might want to have Apache Isis generate representations according to some other "standard", of which there are
+many:
+
+* Mike Kelly's http://stateless.co/hal_specification.html[HAL] specification
+* Mike Amundsen's http://amundsen.com/media-types/collection/[Collection+JSON] specification
+* Kevin Swiber's https://github.com/kevinswiber/siren[Siren] specification
+* Steve Klabnik's http://jsonapi.org/[JSON API] specification
+* Gregg Cainus' https://github.com/cainus/hyper-json-spec[Hyper+JSON] specification
+* the W3C's https://www.w3.org/TR/json-ld/[JSON-LD] specification
+* Markus Lanthaler's http://www.markus-lanthaler.com/hydra/[Hydra] specification.
+
+A good discussion about the relative merits of several of these different hypermedia formats can be found https://groups.google.com/forum/#!msg/api-craft/NgjzQYVOE4s/EAB2jxtU_TMJ[here].
+
+Or, of course, you may have your own internal specification that you wish to use.
+
+Supporting any of these alternative representations can be achieved by providing a suitable implementation of
+`ContentNegotiationService`.  The existing implementations (eg `ContentNegotiationServiceSimplified`) can be used as a
+starting point.
+
+[NOTE]
+====
+These will, admittedly, need to access the internal APIs for the Apache Isis metamodel, and you should be aware that
+these are not formal API; they may change over time.  That said, they are very stable and have not changed
+significantly over the last few years.
+====
+
+
+
+include::_ugvro_simplified-representations_configuration-properties.adoc[leveloffset=+1]
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/ff92fd0c/adocs/documentation/src/main/asciidoc/guides/_ugvro_simplified-representations_configuration-properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugvro_simplified-representations_configuration-properties.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugvro_simplified-representations_configuration-properties.adoc
new file mode 100644
index 0000000..dbcd036
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugvro_simplified-representations_configuration-properties.adoc
@@ -0,0 +1,135 @@
+[[_ugvro_simplified-representations_configuration-properties]]
+= Global Config Props (Deprecated)
+: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/
+
+
+If all that is required is a very simple representations (of objects), you can configure the Restful Objects viewer
+to provide a simplified output, then this can be done with a number of (global) configuration properties.
+
+These configuration properties pre-date the support, introduced in `1.11.0-SNAPSHOT`, for the Apache Isis profile, and
+are limited by the fact that they are global configuration settings, so cannot be influenced on a request-by-request
+basis (as is the case with the `Accept` header used for the Apache Isis profile). They have therefore been
+deprecated, and may be removed in the future.
+
+Nevertheless, those configuration properties are:
+
+.Deprecated Configuration Properties
+[cols="2a,1,3", options="header"]
+|===
+|Property
+|Value +
+(_default value_)
+|Description
+
+|`isis.viewer.restfulobjects.` +
+`suppressDescribedByLinks`
+| `true`,`false` (`_false_`)
+|Suppresses the "describedby" links (on all representations)
+
+|`isis.viewer.restfulobjects.` +
+`suppressUpdateLink`
+| `true`,`false` (`_false_`)
+|suppresses the  "update" link (on object representation)
+
+|`isis.viewer.restfulobjects.` +
+`suppressMemberId`
+| `true`,`false` (`_false_`)
+|suppresses the  "id" json-prop for object members (on object representation and member detail representations)
+
+|`isis.viewer.restfulobjects.` +
+`suppressMemberLinks`
+| `true`,`false` (`_false_`)
+|suppresses the  "links" json-prop for object members (on the object representation and member detail representations)
+
+|`isis.viewer.restfulobjects.` +
+`suppressMemberExtensions`
+| `true`,`false` (`_false_`)
+|suppresses the  "extensions" json-prop for object members (on the object representation and member detail representations)
+
+|`isis.viewer.restfulobjects.` +
+`suppressMemberDisabledReason`
+| `true`,`false` (`_false_`)
+|suppresses the  "disabledReason" json-prop for object members (on the object representation and member detail representations)
+
+|`isis.viewer.restfulobjects.` +
+`objectPropertyValuesOnly`
+| `true`,`false` (`_false_`)
+| See xref:ugvro.adoc#_ugvro_simplified-representations_configuration-properties_object-property-values-only[discussion] below.
+|
+
+|===
+
+
+For example, these configuration properties could all be added in the `WEB-INF/viewer_restfulobjects.properties`):
+
+[source,ini]
+----
+isis.viewer.restfulobjects.suppressDescribedByLinks=true
+isis.viewer.restfulobjects.suppressUpdateLink=true
+isis.viewer.restfulobjects.suppressMemberId=true
+isis.viewer.restfulobjects.suppressMemberLinks=true
+isis.viewer.restfulobjects.suppressMemberExtensions=true
+isis.viewer.restfulobjects.suppressMemberDisabledReason=true
+----
+
+
+[NOTE]
+====
+If these configuration settings are set in conjunction with using the
+xref:ugvro.adoc#_ugvro_simplified-representations_apache-isis-profile[Apache Isis profile], then the special `$$ro`
+property in the representations with reflect these settings.
+====
+
+
+
+If the `objectPropertyValuesOnly` configuration property is set:
+
+[source,ini]
+----
+isis.viewer.restfulobjects.objectPropertyValuesOnly=true
+----
+
+then this generates a representation such as:
+
+[source,javascript]
+----
+{
+    "title" : "Buy milk due by 2014-10-27",
+    "domainType" : "TODO",
+    "instanceId" : "0",
+    "members" : {
+        "description" : "Buy milk",
+        "category" : "Domestic",
+        "subcategory" : "Shopping",
+        "complete" : false,
+        "versionSequence" : 1,
+        "relativePriority" : 2,
+        "dueBy" : "2014-10-27",
+        "cost" : "0.75",
+        "notes" : null,
+        "attachment" : null,
+        "doc" : null
+    },
+    "links" : [
+        {
+            "rel" : "self",
+            "href" : "http://localhost:8080/restful/objects/TODO/0",
+            "method" : "GET",
+            "type" : "application/json;profile=\"urn:org.restfulobjects:repr-types/object\"",
+            "title" : "Buy milk due by 2014-10-27"
+        },
+        {
+            "rel" : "describedby",
+            "href" : "http://localhost:8080/restful/domain-types/TODO",
+            "method" : "GET",
+            "type" : "application/json;profile=\"urn:org.restfulobjects:repr-types/domain-type\""
+        }
+    ],
+    "extensions" : {
+        "oid" : "TODO:0"
+    },
+}
+----
+

http://git-wip-us.apache.org/repos/asf/isis/blob/ff92fd0c/adocs/documentation/src/main/asciidoc/guides/images/reference-services-spi/RepresentationService/service-collaborations.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/reference-services-spi/RepresentationService/service-collaborations.png b/adocs/documentation/src/main/asciidoc/guides/images/reference-services-spi/RepresentationService/service-collaborations.png
index 995b089..859e5dd 100644
Binary files a/adocs/documentation/src/main/asciidoc/guides/images/reference-services-spi/RepresentationService/service-collaborations.png and b/adocs/documentation/src/main/asciidoc/guides/images/reference-services-spi/RepresentationService/service-collaborations.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/ff92fd0c/adocs/documentation/src/main/asciidoc/guides/images/reference-services-spi/RepresentationService/service-collaborations.pptx
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/reference-services-spi/RepresentationService/service-collaborations.pptx b/adocs/documentation/src/main/asciidoc/guides/images/reference-services-spi/RepresentationService/service-collaborations.pptx
index bbdb734..7522518 100644
Binary files a/adocs/documentation/src/main/asciidoc/guides/images/reference-services-spi/RepresentationService/service-collaborations.pptx and b/adocs/documentation/src/main/asciidoc/guides/images/reference-services-spi/RepresentationService/service-collaborations.pptx differ

http://git-wip-us.apache.org/repos/asf/isis/blob/ff92fd0c/adocs/documentation/src/main/asciidoc/guides/images/restfulobjects/ro-spec-resources-and-representations.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/restfulobjects/ro-spec-resources-and-representations.png b/adocs/documentation/src/main/asciidoc/guides/images/restfulobjects/ro-spec-resources-and-representations.png
new file mode 100644
index 0000000..c7c8fa5
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/restfulobjects/ro-spec-resources-and-representations.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/ff92fd0c/adocs/documentation/src/main/asciidoc/guides/rgcms.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms.adoc
index 750cfa4..253c5fa 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms.adoc
@@ -7,7 +7,7 @@
 
 
 [[_rgcms]]
-= Classes, Methods and Schema
+== Classes, Methods and Schema
 
 This reference guide lists and describes various elements of the the Apache Isis Programming Model, specifically
 reserved and prefix xref:rgcms.adoc#_rgcms_methods[methods] (such as `title()` and `validate...()`) and various utility and

http://git-wip-us.apache.org/repos/asf/isis/blob/ff92fd0c/adocs/documentation/src/main/asciidoc/guides/ugvro.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvro.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvro.adoc
index 95ee4b7..a6529c9 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvro.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvro.adoc
@@ -11,10 +11,16 @@
 == Restful Objects Viewer
 
 Apache Isis' Restful Objects viewer is an implementation of the link:http://restfulobjects.org[Restful Objects spec],
-which defines a generic way to expose a domain model through a REST (or more precisely, hypermedia) API.
+which defines a generic way to expose a domain model through a REST (or more precisely, hypermedia) API.  Having a REST
+API opens up an Apache Isis domain model to a huge variety of applications, from bespoke single-page apps,
+through integration scenarious, through providing an API for bulk-upload/migration from an existing system.
+
+The Restful Objects viewer also provides a number of extensions specific to Apache Isis.  Most significant of these is
+enhanced content negotiation support, making it easier to use the returned representations within bespoke clients using
+standard third-party configurations.
+
+This user guide discuss features, configuration and also how to extend the Restful Objects viewer.
 
-It also provides a number of extensions specific to Apache Isis.  Most significant of these is
-This user guide discuss features, configuration and how to extend the Restful Objects viewer.
 
 === Other Guides
 
@@ -40,9 +46,10 @@ In addition, there is a xref:cg.adoc#_cg[Contributors' Guide] describing develop
 
 
 
-include::_ugvro_features.adoc[leveloffset=+1]
 include::_ugvro_ro-spec.adoc[leveloffset=+1]
+include::_ugvro_architecture.adoc[leveloffset=+1]
+include::_ugvro_simplified-representations.adoc[leveloffset=+1]
+
 include::_ugvro_configuration-properties.adoc[leveloffset=+1]
 include::_ugvro_hints-and-tips.adoc[leveloffset=+1]
 
-include::_ugvro_extending.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/ff92fd0c/core/viewer-restfulobjects-rendering/src/main/java/org/apache/isis/viewer/restfulobjects/rendering/service/RepresentationServiceContentNegotiator.java
----------------------------------------------------------------------
diff --git a/core/viewer-restfulobjects-rendering/src/main/java/org/apache/isis/viewer/restfulobjects/rendering/service/RepresentationServiceContentNegotiator.java b/core/viewer-restfulobjects-rendering/src/main/java/org/apache/isis/viewer/restfulobjects/rendering/service/RepresentationServiceContentNegotiator.java
new file mode 100644
index 0000000..abfdaf3
--- /dev/null
+++ b/core/viewer-restfulobjects-rendering/src/main/java/org/apache/isis/viewer/restfulobjects/rendering/service/RepresentationServiceContentNegotiator.java
@@ -0,0 +1,215 @@
+/**
+ *  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.
+ */
+package org.apache.isis.viewer.restfulobjects.rendering.service;
+
+import java.util.List;
+import java.util.Map;
+
+import javax.annotation.PostConstruct;
+import javax.inject.Inject;
+import javax.ws.rs.core.Response;
+import javax.ws.rs.core.Response.ResponseBuilder;
+
+import com.google.common.base.Function;
+
+import org.apache.isis.applib.annotation.DomainService;
+import org.apache.isis.applib.annotation.NatureOfService;
+import org.apache.isis.applib.annotation.Programmatic;
+import org.apache.isis.core.metamodel.adapter.ObjectAdapter;
+import org.apache.isis.viewer.restfulobjects.rendering.domainobjects.ActionResultReprRenderer.SelfLink;
+import org.apache.isis.viewer.restfulobjects.rendering.domainobjects.MemberReprMode;
+import org.apache.isis.viewer.restfulobjects.rendering.domainobjects.ObjectAndAction;
+import org.apache.isis.viewer.restfulobjects.rendering.domainobjects.ObjectAndActionInvocation;
+import org.apache.isis.viewer.restfulobjects.rendering.domainobjects.ObjectAndCollection;
+import org.apache.isis.viewer.restfulobjects.rendering.domainobjects.ObjectAndProperty;
+import org.apache.isis.viewer.restfulobjects.rendering.service.conneg.ContentNegotiationService;
+import org.apache.isis.viewer.restfulobjects.rendering.service.conneg.ContentNegotiationServiceForRestfulObjectsV1_0;
+
+@DomainService(
+        nature = NatureOfService.DOMAIN
+)
+public class RepresentationServiceContentNegotiator implements RepresentationService {
+
+
+    @PostConstruct
+    public void init(final Map<String, String> properties) {
+
+    }
+
+
+    @Override
+    @Programmatic
+    public Response objectRepresentation(
+            final Context rendererContext,
+            final ObjectAdapter objectAdapter) {
+
+        final Context2 renderContext2 = asContext2(rendererContext);
+        final ResponseBuilder responseBuilder = buildResponse(new Function<ContentNegotiationService, ResponseBuilder>() {
+            @Override
+            public ResponseBuilder apply(final ContentNegotiationService connegService) {
+                return connegService.buildResponse(renderContext2, objectAdapter);
+            }
+        });
+
+        assertContentNegotiationServiceHandled(responseBuilder);
+        return buildResponse(responseBuilder);
+    }
+
+    /**
+     * @deprecated - use {@link #objectRepresentation(Context, ObjectAdapter, Intent)}
+     */
+    @Deprecated
+    @Override
+    @Programmatic
+    public Response objectRepresentation(
+            final Context rendererContext,
+            final ObjectAdapter objectAdapter,
+            final Intent unused) {
+        return objectRepresentation(rendererContext, objectAdapter);
+    }
+
+
+    @Override
+    @Programmatic
+    public Response propertyDetails(
+            final Context rendererContext,
+            final ObjectAndProperty objectAndProperty,
+            final MemberReprMode memberReprMode) {
+
+        final Context2 renderContext2 = asContext2(rendererContext);
+        final ResponseBuilder responseBuilder = buildResponse(new Function<ContentNegotiationService, ResponseBuilder>() {
+            @Override
+            public ResponseBuilder apply(final ContentNegotiationService connegService) {
+                return connegService.buildResponse(renderContext2, objectAndProperty);
+            }
+        });
+
+        assertContentNegotiationServiceHandled(responseBuilder);
+        return buildResponse(responseBuilder);
+    }
+
+
+    @Override
+    @Programmatic
+    public Response collectionDetails(
+            final Context rendererContext,
+            final ObjectAndCollection objectAndCollection,
+            final MemberReprMode memberReprMode) {
+
+        final Context2 renderContext2 = asContext2(rendererContext);
+        final ResponseBuilder responseBuilder = buildResponse(new Function<ContentNegotiationService, ResponseBuilder>() {
+            @Override
+            public ResponseBuilder apply(final ContentNegotiationService connegService) {
+                return connegService.buildResponse(renderContext2, objectAndCollection);
+            }
+        });
+
+        assertContentNegotiationServiceHandled(responseBuilder);
+        return buildResponse(responseBuilder);
+    }
+
+
+
+
+    @Override
+    @Programmatic
+    public Response actionPrompt(
+            final Context rendererContext,
+            final ObjectAndAction objectAndAction) {
+
+        final Context2 renderContext2 = asContext2(rendererContext);
+        final ResponseBuilder responseBuilder = buildResponse(new Function<ContentNegotiationService, ResponseBuilder>() {
+            @Override
+            public ResponseBuilder apply(final ContentNegotiationService connegService) {
+                return connegService.buildResponse(renderContext2, objectAndAction);
+            }
+        });
+
+        assertContentNegotiationServiceHandled(responseBuilder);
+        return buildResponse(responseBuilder);
+    }
+
+
+    @Override
+    @Programmatic
+    public Response actionResult(
+            final Context rendererContext,
+            final ObjectAndActionInvocation objectAndActionInvocation,
+            final SelfLink selfLink) {
+
+        final Context2 renderContext2 = asContext2(rendererContext);
+        final ResponseBuilder responseBuilder = buildResponse(new Function<ContentNegotiationService, ResponseBuilder>() {
+            @Override
+            public ResponseBuilder apply(final ContentNegotiationService connegService) {
+                return connegService.buildResponse(renderContext2, objectAndActionInvocation);
+            }
+        });
+
+        assertContentNegotiationServiceHandled(responseBuilder);
+        return buildResponse(responseBuilder);
+    }
+
+    private Context2 asContext2(final Context rendererContext) {
+        if (rendererContext instanceof Context2) {
+            final Context2 context = (Context2) rendererContext;
+            return context;
+        }
+        throw new IllegalArgumentException(String.format(
+                "The %s requires that the context to implement %s",
+                RepresentationServiceContentNegotiator.class.getSimpleName(), Context2.class.getName()));
+    }
+
+    void assertContentNegotiationServiceHandled(final ResponseBuilder responseBuilder) {
+        if (responseBuilder == null) {
+            throw new IllegalStateException("Could not locate " + ContentNegotiationService.class.getSimpleName() + " to handle request");
+        }
+    }
+
+    /**
+     * Iterates over all {@link #contentNegotiationServices injected} {@link ContentNegotiationService}s to find one
+     * that returns a {@link ResponseBuilder} using the provided function.
+     *
+     * <p>
+     *     There will always be at least one such service, namely the
+     *     {@link ContentNegotiationServiceForRestfulObjectsV1_0}.
+     * </p>
+     *
+     * @param connegServiceBuildResponse - the function to ask of the {@link ContentNegotiationService}.
+     */
+    ResponseBuilder buildResponse(
+            final Function<ContentNegotiationService, ResponseBuilder> connegServiceBuildResponse) {
+        ResponseBuilder responseBuilder = null;
+        for (final ContentNegotiationService contentNegotiationService : contentNegotiationServices) {
+            responseBuilder = connegServiceBuildResponse.apply(contentNegotiationService);
+            if(responseBuilder != null) {
+                return responseBuilder;
+            }
+        }
+        return null;
+    }
+
+    /**
+     * Overriddable to allow further customization.
+     */
+    protected Response buildResponse(final ResponseBuilder responseBuilder) {
+        return responseBuilder.build();
+    }
+
+
+    @Inject
+    List<ContentNegotiationService> contentNegotiationServices;
+}

http://git-wip-us.apache.org/repos/asf/isis/blob/ff92fd0c/core/viewer-restfulobjects-rendering/src/main/java/org/apache/isis/viewer/restfulobjects/rendering/service/RepresentationServiceForRestfulObjects.java
----------------------------------------------------------------------
diff --git a/core/viewer-restfulobjects-rendering/src/main/java/org/apache/isis/viewer/restfulobjects/rendering/service/RepresentationServiceForRestfulObjects.java b/core/viewer-restfulobjects-rendering/src/main/java/org/apache/isis/viewer/restfulobjects/rendering/service/RepresentationServiceForRestfulObjects.java
index 51a6689..b9dbe7d 100644
--- a/core/viewer-restfulobjects-rendering/src/main/java/org/apache/isis/viewer/restfulobjects/rendering/service/RepresentationServiceForRestfulObjects.java
+++ b/core/viewer-restfulobjects-rendering/src/main/java/org/apache/isis/viewer/restfulobjects/rendering/service/RepresentationServiceForRestfulObjects.java
@@ -16,200 +16,9 @@
  */
 package org.apache.isis.viewer.restfulobjects.rendering.service;
 
-import java.util.List;
-import java.util.Map;
-
-import javax.annotation.PostConstruct;
-import javax.inject.Inject;
-import javax.ws.rs.core.Response;
-import javax.ws.rs.core.Response.ResponseBuilder;
-
-import com.google.common.base.Function;
-
-import org.apache.isis.applib.annotation.DomainService;
-import org.apache.isis.applib.annotation.NatureOfService;
-import org.apache.isis.applib.annotation.Programmatic;
-import org.apache.isis.core.metamodel.adapter.ObjectAdapter;
-import org.apache.isis.viewer.restfulobjects.rendering.domainobjects.ActionResultReprRenderer.SelfLink;
-import org.apache.isis.viewer.restfulobjects.rendering.domainobjects.MemberReprMode;
-import org.apache.isis.viewer.restfulobjects.rendering.domainobjects.ObjectAndAction;
-import org.apache.isis.viewer.restfulobjects.rendering.domainobjects.ObjectAndActionInvocation;
-import org.apache.isis.viewer.restfulobjects.rendering.domainobjects.ObjectAndCollection;
-import org.apache.isis.viewer.restfulobjects.rendering.domainobjects.ObjectAndProperty;
-import org.apache.isis.viewer.restfulobjects.rendering.service.conneg.ContentNegotiationService;
-import org.apache.isis.viewer.restfulobjects.rendering.service.conneg.ContentNegotiationServiceForRestfulObjectsV1_0;
-
-@DomainService(
-        nature = NatureOfService.DOMAIN
-)
-public class RepresentationServiceForRestfulObjects implements RepresentationService {
-
-
-    @PostConstruct
-    public void init(final Map<String, String> properties) {
-
-    }
-
-
-    @Override
-    @Programmatic
-    public Response objectRepresentation(
-            final Context rendererContext,
-            final ObjectAdapter objectAdapter) {
-
-        final Context2 renderContext2 = asContext2(rendererContext);
-        final ResponseBuilder responseBuilder = buildResponse(new Function<ContentNegotiationService, ResponseBuilder>() {
-            @Override
-            public ResponseBuilder apply(final ContentNegotiationService connegService) {
-                return connegService.buildResponse(renderContext2, objectAdapter);
-            }
-        });
-
-        assertContentNegotiationServiceHandled(responseBuilder);
-        return buildResponse(responseBuilder);
-    }
-
-    /**
-     * @deprecated - use {@link #objectRepresentation(Context, ObjectAdapter, Intent)}
-     */
-    @Deprecated
-    @Override
-    @Programmatic
-    public Response objectRepresentation(
-            final Context rendererContext,
-            final ObjectAdapter objectAdapter,
-            final Intent unused) {
-        return objectRepresentation(rendererContext, objectAdapter);
-    }
-
-
-    @Override
-    @Programmatic
-    public Response propertyDetails(
-            final Context rendererContext,
-            final ObjectAndProperty objectAndProperty,
-            final MemberReprMode memberReprMode) {
-
-        final Context2 renderContext2 = asContext2(rendererContext);
-        final ResponseBuilder responseBuilder = buildResponse(new Function<ContentNegotiationService, ResponseBuilder>() {
-            @Override
-            public ResponseBuilder apply(final ContentNegotiationService connegService) {
-                return connegService.buildResponse(renderContext2, objectAndProperty);
-            }
-        });
-
-        assertContentNegotiationServiceHandled(responseBuilder);
-        return buildResponse(responseBuilder);
-    }
-
-
-    @Override
-    @Programmatic
-    public Response collectionDetails(
-            final Context rendererContext,
-            final ObjectAndCollection objectAndCollection,
-            final MemberReprMode memberReprMode) {
-
-        final Context2 renderContext2 = asContext2(rendererContext);
-        final ResponseBuilder responseBuilder = buildResponse(new Function<ContentNegotiationService, ResponseBuilder>() {
-            @Override
-            public ResponseBuilder apply(final ContentNegotiationService connegService) {
-                return connegService.buildResponse(renderContext2, objectAndCollection);
-            }
-        });
-
-        assertContentNegotiationServiceHandled(responseBuilder);
-        return buildResponse(responseBuilder);
-    }
-
-
-
-
-    @Override
-    @Programmatic
-    public Response actionPrompt(
-            final Context rendererContext,
-            final ObjectAndAction objectAndAction) {
-
-        final Context2 renderContext2 = asContext2(rendererContext);
-        final ResponseBuilder responseBuilder = buildResponse(new Function<ContentNegotiationService, ResponseBuilder>() {
-            @Override
-            public ResponseBuilder apply(final ContentNegotiationService connegService) {
-                return connegService.buildResponse(renderContext2, objectAndAction);
-            }
-        });
-
-        assertContentNegotiationServiceHandled(responseBuilder);
-        return buildResponse(responseBuilder);
-    }
-
-
-    @Override
-    @Programmatic
-    public Response actionResult(
-            final Context rendererContext,
-            final ObjectAndActionInvocation objectAndActionInvocation,
-            final SelfLink selfLink) {
-
-        final Context2 renderContext2 = asContext2(rendererContext);
-        final ResponseBuilder responseBuilder = buildResponse(new Function<ContentNegotiationService, ResponseBuilder>() {
-            @Override
-            public ResponseBuilder apply(final ContentNegotiationService connegService) {
-                return connegService.buildResponse(renderContext2, objectAndActionInvocation);
-            }
-        });
-
-        assertContentNegotiationServiceHandled(responseBuilder);
-        return buildResponse(responseBuilder);
-    }
-
-    private Context2 asContext2(final Context rendererContext) {
-        if (rendererContext instanceof Context2) {
-            final Context2 context = (Context2) rendererContext;
-            return context;
-        }
-        throw new IllegalArgumentException(String.format(
-                "The %s requires that the context to implement %s",
-                RepresentationServiceForRestfulObjects.class.getSimpleName(), Context2.class.getName()));
-    }
-
-    void assertContentNegotiationServiceHandled(final ResponseBuilder responseBuilder) {
-        if (responseBuilder == null) {
-            throw new IllegalStateException("Could not locate " + ContentNegotiationService.class.getSimpleName() + " to handle request");
-        }
-    }
-
-    /**
-     * Iterates over all {@link #contentNegotiationServices injected} {@link ContentNegotiationService}s to find one
-     * that returns a {@link ResponseBuilder} using the provided function.
-     *
-     * <p>
-     *     There will always be at least one such service, namely the
-     *     {@link ContentNegotiationServiceForRestfulObjectsV1_0}.
-     * </p>
-     *
-     * @param connegServiceBuildResponse - the function to ask of the {@link ContentNegotiationService}.
-     */
-    ResponseBuilder buildResponse(
-            final Function<ContentNegotiationService, ResponseBuilder> connegServiceBuildResponse) {
-        ResponseBuilder responseBuilder = null;
-        for (final ContentNegotiationService contentNegotiationService : contentNegotiationServices) {
-            responseBuilder = connegServiceBuildResponse.apply(contentNegotiationService);
-            if(responseBuilder != null) {
-                return responseBuilder;
-            }
-        }
-        return null;
-    }
-
-    /**
-     * Overriddable to allow further customization.
-     */
-    protected Response buildResponse(final ResponseBuilder responseBuilder) {
-        return responseBuilder.build();
-    }
-
-
-    @Inject
-    List<ContentNegotiationService> contentNegotiationServices;
+/**
+ * @deprecated - renamed to {@link RepresentationServiceContentNegotiator}.
+ */
+@Deprecated
+public class RepresentationServiceForRestfulObjects extends RepresentationServiceContentNegotiator {
 }


[45/52] [abbrv] isis git commit: ISIS-1237: merge feature branch

Posted by mg...@apache.org.
ISIS-1237: merge feature branch


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/c64caa1a
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/c64caa1a
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/c64caa1a

Branch: refs/heads/ISIS-1224-select2-v4
Commit: c64caa1ae9f3dbf984855bfd5109f2fa19e4a759
Parents: 2d9b2ee 9ac72b5
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Fri Dec 11 10:24:04 2015 +0000
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Fri Dec 11 10:24:04 2015 +0000

----------------------------------------------------------------------
 adocs/documentation/Gemfile.lock                |   3 -
 .../_migration-notes_1.10.0-to-1.11.0.adoc      |  27 +
 .../isis/applib/annotation/NatureOfService.java |  22 +-
 .../services/i18n/TranslatableString.java       |   1 +
 .../applib/services/swagger/SwaggerService.java |  72 ++
 .../services/swagger/SwaggerServiceMenu.java    |  80 ++
 .../isis/applib/services/swagger/Util.java      |  46 ++
 core/metamodel/pom.xml                          |  11 +
 .../services/swagger/SwaggerServiceDefault.java |  81 ++
 .../services/swagger/internal/Caching.java      |  48 ++
 .../swagger/internal/SwaggerSpecGenerator.java  | 826 +++++++++++++++++++
 .../services/swagger/internal/Util.java         | 164 ++++
 .../swagger/internal/ValuePropertyFactory.java  | 174 ++++
 .../internal/SwaggerSpecGeneratorTest.java      |  69 ++
 .../i18n/po/TranslationServicePoMenu.java       |  37 +-
 .../ContentNegotiationServiceAbstract.java      |  19 +-
 core/viewer-restfulobjects-server/pom.xml       |  11 +
 .../server/RestfulObjectsApplication.java       |   3 +
 ...estfulObjectsApplicationExceptionMapper.java |  12 +-
 .../server/resources/SwaggerSpecResource.java   | 125 +++
 .../java/domainapp/dom/simple/SimpleObject.java |   1 +
 example/application/simpleapp/webapp/pom.xml    |   1 -
 .../webapp/src/main/webapp/WEB-INF/web.xml      |  17 +-
 .../webapp/src/main/webapp/about/index.html     |  18 +-
 .../src/main/webapp/swagger-ui/index.html       | 122 +++
 25 files changed, 1945 insertions(+), 45 deletions(-)
----------------------------------------------------------------------



[44/52] [abbrv] isis git commit: ISIS-1237: sorting out tagging.

Posted by mg...@apache.org.
ISIS-1237: sorting out tagging.


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/9ac72b58
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/9ac72b58
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/9ac72b58

Branch: refs/heads/ISIS-1224-select2-v4
Commit: 9ac72b58572343e8fac7110552687148248dde50
Parents: 4502dc1
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Fri Dec 11 10:09:37 2015 +0000
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Fri Dec 11 10:09:37 2015 +0000

----------------------------------------------------------------------
 .../_migration-notes_1.10.0-to-1.11.0.adoc      |   4 +-
 .../swagger/internal/SwaggerSpecGenerator.java  | 158 +++++++++++++------
 .../internal/SwaggerSpecGeneratorTest.java      |  69 ++++++++
 .../java/domainapp/dom/simple/SimpleObject.java |   8 -
 4 files changed, 185 insertions(+), 54 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/9ac72b58/adocs/documentation/src/main/asciidoc/_migration-notes_1.10.0-to-1.11.0.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/_migration-notes_1.10.0-to-1.11.0.adoc b/adocs/documentation/src/main/asciidoc/_migration-notes_1.10.0-to-1.11.0.adoc
index 6dbd3b3..44c1100 100644
--- a/adocs/documentation/src/main/asciidoc/_migration-notes_1.10.0-to-1.11.0.adoc
+++ b/adocs/documentation/src/main/asciidoc/_migration-notes_1.10.0-to-1.11.0.adoc
@@ -52,7 +52,7 @@ Update the `web.xml`:
 </servlet-mapping>
 ----
 
+There is also an page to load the Swagger UI; this resides in `src/main/webapp/swagger-ui/index.html`.  Copy the index page from the app generated by the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
 
-The text of the simple archetype's `about/index.html` has also changed; the `<li`> for the `/restful` URL has been
-replaced with a `/swagger-ui` URL.
+The text of the simple app's `about/index.html` has also changed (the `<li`> for the `/restful` URL has been replaced with a `/swagger-ui` URL).  If you use this file, then update it.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/9ac72b58/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGenerator.java
----------------------------------------------------------------------
diff --git a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGenerator.java b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGenerator.java
index c58ee23..b1eaf1d 100644
--- a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGenerator.java
+++ b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGenerator.java
@@ -18,22 +18,28 @@
  */
 package org.apache.isis.core.metamodel.services.swagger.internal;
 
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
 import java.util.Arrays;
 import java.util.Collection;
 import java.util.List;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
 
 import com.fasterxml.jackson.core.JsonProcessingException;
 import com.google.common.base.Strings;
+import com.google.common.collect.Lists;
 
 import org.apache.isis.applib.annotation.ActionSemantics;
 import org.apache.isis.applib.annotation.NatureOfService;
+import org.apache.isis.applib.fixturescripts.FixtureResult;
 import org.apache.isis.applib.services.swagger.SwaggerService;
+import org.apache.isis.core.commons.exceptions.IsisException;
 import org.apache.isis.core.commons.factory.InstanceUtil;
 import org.apache.isis.core.metamodel.facets.actcoll.typeof.TypeOfFacet;
 import org.apache.isis.core.metamodel.facets.object.domainservice.DomainServiceFacet;
 import org.apache.isis.core.metamodel.facets.object.mixin.MixinFacet;
 import org.apache.isis.core.metamodel.facets.object.objectspecid.ObjectSpecIdFacet;
-import org.apache.isis.core.metamodel.services.ServiceUtil;
 import org.apache.isis.core.metamodel.spec.ObjectSpecification;
 import org.apache.isis.core.metamodel.spec.SpecificationLoader;
 import org.apache.isis.core.metamodel.spec.feature.ObjectAction;
@@ -101,7 +107,8 @@ public class SwaggerSpecGenerator {
     }
 
     void appendServicePathsAndDefinitions(final Swagger swagger, final SwaggerService.Visibility visibility) {
-        final Collection<ObjectSpecification> allSpecs = specificationLoader.allSpecifications();
+        // take copy to avoid concurrent modification exception
+        final Collection<ObjectSpecification> allSpecs = Lists.newArrayList(specificationLoader.allSpecifications());
         for (final ObjectSpecification serviceSpec :  allSpecs) {
 
             final DomainServiceFacet domainServiceFacet = serviceSpec.getFacet(DomainServiceFacet.class);
@@ -130,7 +137,8 @@ public class SwaggerSpecGenerator {
     }
 
     void appendObjectPathsAndDefinitions(final Swagger swagger, final SwaggerService.Visibility visibility) {
-        final Collection<ObjectSpecification> allSpecs = specificationLoader.allSpecifications();
+        // take copy to avoid concurrent modification exception
+        final Collection<ObjectSpecification> allSpecs = Lists.newArrayList(specificationLoader.allSpecifications());
         for (final ObjectSpecification objectSpec : allSpecs) {
 
             final DomainServiceFacet domainServiceFacet = objectSpec.getFacet(DomainServiceFacet.class);
@@ -150,6 +158,10 @@ public class SwaggerSpecGenerator {
             if(objectSpec.isValue()) {
                 continue;
             }
+            // special cases
+            if(objectSpec.getCorrespondingClass() == FixtureResult.class) {
+                continue;
+            }
 
             final List<OneToOneAssociation> objectProperties = Util.propertiesOf(objectSpec, visibility);
             final List<OneToManyAssociation> objectCollections = Util.collectionsOf(objectSpec, visibility);
@@ -191,17 +203,17 @@ public class SwaggerSpecGenerator {
                 newModel(Util.roSpec("5.2")));
 
         swagger.path("/user",
-                    new Path()
-                            .get(new Operation()
-                                    .tag(tag)
-                                    .description(Util.roSpec("6.1"))
-                                    .produces("application/json")
-                                    .produces("application/json;profile=urn:org.restfulobjects:repr-types/user")
-                                    .response(200,
-                                            newResponse(Caching.USER_INFO)
-                                                    .description("OK")
-                                                    .schema(new RefProperty("#/definitions/RestfulObjectsSupportingUserModel"))
-                                    )));
+                new Path()
+                        .get(new Operation()
+                                .tag(tag)
+                                .description(Util.roSpec("6.1"))
+                                .produces("application/json")
+                                .produces("application/json;profile=urn:org.restfulobjects:repr-types/user")
+                                .response(200,
+                                        newResponse(Caching.USER_INFO)
+                                                .description("OK")
+                                                .schema(new RefProperty("#/definitions/RestfulObjectsSupportingUserModel"))
+                                )));
         swagger.addDefinition("RestfulObjectsSupportingUserModel",
                 newModel(Util.roSpec("6.2"))
                         .property("userName", stringProperty())
@@ -211,17 +223,17 @@ public class SwaggerSpecGenerator {
                         .required("roles"));
 
         swagger.path("/services",
-                        new Path()
-                                .get(new Operation()
-                                        .tag(tag)
-                                        .description(Util.roSpec("7.1"))
-                                        .produces("application/json")
-                                        .produces("application/json;profile=urn:org.restfulobjects:repr-types/services")
-                                        .response(200,
-                                                newResponse(Caching.USER_INFO)
-                                                        .description("OK")
-                                                        .schema(new RefProperty("#/definitions/RestfulObjectsSupportingServicesModel"))
-                                        )));
+                new Path()
+                        .get(new Operation()
+                                .tag(tag)
+                                .description(Util.roSpec("7.1"))
+                                .produces("application/json")
+                                .produces("application/json;profile=urn:org.restfulobjects:repr-types/services")
+                                .response(200,
+                                        newResponse(Caching.USER_INFO)
+                                                .description("OK")
+                                                .schema(new RefProperty("#/definitions/RestfulObjectsSupportingServicesModel"))
+                                )));
         swagger.addDefinition("RestfulObjectsSupportingServicesModel",
                 newModel(Util.roSpec("7.2"))
                         .property("value", arrayOfLinks())
@@ -229,17 +241,17 @@ public class SwaggerSpecGenerator {
                         .required("roles"));
 
         swagger.path("/version",
-                        new Path()
-                                .get(new Operation()
-                                        .tag(tag)
-                                        .description(Util.roSpec("8.1"))
-                                        .produces("application/json")
-                                        .produces("application/json;profile=urn:org.restfulobjects:repr-types/RestfulObjectsSupportingServicesModel")
-                                        .response(200,
-                                                newResponse(Caching.NON_EXPIRING)
-                                                        .description("OK")
-                                                        .schema(new ObjectProperty())
-                                        )));
+                new Path()
+                        .get(new Operation()
+                                .tag(tag)
+                                .description(Util.roSpec("8.1"))
+                                .produces("application/json")
+                                .produces("application/json;profile=urn:org.restfulobjects:repr-types/RestfulObjectsSupportingServicesModel")
+                                .response(200,
+                                        newResponse(Caching.NON_EXPIRING)
+                                                .description("OK")
+                                                .schema(new ObjectProperty())
+                                )));
         swagger.addDefinition("RestfulObjectsSupportingServicesModel",
                 newModel(Util.roSpec("8.2"))
                         .property("specVersion", stringProperty())
@@ -290,9 +302,11 @@ public class SwaggerSpecGenerator {
         swagger.path(String.format("/services/%s", serviceId), path);
 
         final String serviceModelDefinition = serviceId + "Model";
+
+        final String tag = tagFor(serviceId);
         path.get(
                 new Operation()
-                        .tag(serviceId)
+                        .tag(tag)
                         .description(Util.roSpec("15.1"))
                         .produces("application/json")
                         .produces("application/json;profile=urn:org.restfulobjects:repr-types/object")
@@ -318,10 +332,9 @@ public class SwaggerSpecGenerator {
         final Path path = new Path();
         swagger.path(String.format("/objects/%s/{objectId}", objectType), path);
 
-        final String tag = objectType.startsWith("org.apache.isis")? "> apache isis internals": objectType;
+        final String tag = tagFor(objectType);
         final Operation operation = new Operation();
-        path.get(
-                operation);
+        path.get(operation);
         operation
                 .tag(tag)
                 .description(Util.roSpec("14.1"))
@@ -399,9 +412,10 @@ public class SwaggerSpecGenerator {
         final Path path = new Path();
         swagger.path(String.format("/services/%s/actions/%s/invoke", serviceId, actionId), path);
 
+        final String tag = tagFor(serviceId);
         final Operation invokeOperation =
                 new Operation()
-                        .tag(serviceId)
+                        .tag(tag)
                         .description(Util.roSpec("19.1") + ": (invoke) resource of " + serviceId + "#" + actionId)
                         .produces("application/json;profile=urn:org.apache.isis/v1")
                         .produces("application/json;profile=urn:org.apache.isis/v1;suppress=true")
@@ -482,9 +496,10 @@ public class SwaggerSpecGenerator {
         final Path path = new Path();
         swagger.path(String.format("/objects/%s/{objectId}/collections/%s", objectType, collectionId), path);
 
+        final String tag = tagFor(objectType);
         final Operation collectionOperation =
                 new Operation()
-                        .tag(objectType)
+                        .tag(tag)
                         .description(Util.roSpec("17.1") + ": resource of " + objectType + "#" + collectionId)
                         .parameter(
                                 new PathParameter()
@@ -522,9 +537,10 @@ public class SwaggerSpecGenerator {
         final Path path = new Path();
         swagger.path(String.format("/objects/%s/{objectId}/actions/%s/invoke", objectType, actionId), path);
 
+        final String tag = tagFor(objectType);
         final Operation invokeOperation =
                 new Operation()
-                        .tag(objectType)
+                        .tag(tag)
                         .description(Util.roSpec("19.1") + ": (invoke) resource of " + objectType + "#" + actionId)
                         .parameter(
                                 new PathParameter()
@@ -712,7 +728,25 @@ public class SwaggerSpecGenerator {
     // TODO: this is horrid, there ought to be a facet we can call instead...
     static String serviceIdFor(final ObjectSpecification serviceSpec) {
         Object tempServiceInstance = InstanceUtil.createInstance(serviceSpec.getCorrespondingClass());
-        return ServiceUtil.id(tempServiceInstance);
+        return serviceId(tempServiceInstance);
+    }
+
+    static String serviceId(final Object object) {
+        final Class<?> cls = object.getClass();
+        try {
+            final Method m = cls.getMethod("getId", new Class[0]);
+            return (String) m.invoke(object, new Object[0]);
+        } catch (final SecurityException e) {
+            throw new IsisException(e);
+        } catch (final NoSuchMethodException e) {
+            return object.getClass().getName();
+        } catch (final IllegalArgumentException e) {
+            throw new IsisException(e);
+        } catch (final IllegalAccessException e) {
+            throw new IsisException(e);
+        } catch (final InvocationTargetException e) {
+            throw new IsisException(e);
+        }
     }
 
     static String objectTypeFor(final ObjectSpecification objectSpec) {
@@ -753,4 +787,40 @@ public class SwaggerSpecGenerator {
         return Util.withCachingHeaders(new Response(), caching);
     }
 
+    static Pattern tagPatternIsisAddons = Pattern.compile("^org\\.isisaddons\\.module\\.([^\\.]+)\\.(.+)$");
+    static Pattern tagPatternForFqcn = Pattern.compile("^.*\\.([^\\.]+)\\.([^\\.]+)$");
+    static Pattern tagPatternForSchemaTable = Pattern.compile("^([^\\.]+)\\.([^\\.]+)$");
+    static Pattern tagPatternForJaxbDto = Pattern.compile("^([^\\.]+)\\.(v[0-9][^\\.]*)([^\\.]+)$");
+    static String tagFor(final String str) {
+        if (str.startsWith("org.apache.isis")) {
+            return "> apache isis internals";
+        }
+
+        Matcher matcher;
+        matcher = tagPatternIsisAddons.matcher(str);
+        if (matcher.matches()) {
+            return "isisaddons " + matcher.group(1);
+        }
+        matcher = Pattern.compile("^.*\\.([^\\.]+)\\.(v[0-9][^\\.]*)\\.([^\\.]+)$").matcher(str);
+        if (matcher.matches()) {
+            return matcher.group(1);
+        }
+        matcher = tagPatternForFqcn.matcher(str);
+        if (matcher.matches()) {
+            return matcher.group(1);
+        }
+        matcher = tagPatternForSchemaTable.matcher(str);
+        if (matcher.matches()) {
+            // special cases for other Isis addons
+            if(str.startsWith("isis")) {
+                return "isisaddons " + str.substring(4, str.indexOf("."));
+            }
+            return matcher.group(1);
+        }
+
+
+        return str;
+    }
+
+
 }

http://git-wip-us.apache.org/repos/asf/isis/blob/9ac72b58/core/metamodel/src/test/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGeneratorTest.java
----------------------------------------------------------------------
diff --git a/core/metamodel/src/test/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGeneratorTest.java b/core/metamodel/src/test/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGeneratorTest.java
new file mode 100644
index 0000000..cbebd55
--- /dev/null
+++ b/core/metamodel/src/test/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGeneratorTest.java
@@ -0,0 +1,69 @@
+/*
+ *  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.
+ */
+package org.apache.isis.core.metamodel.services.swagger.internal;
+
+import org.junit.Test;
+
+import static org.hamcrest.CoreMatchers.equalTo;
+import static org.hamcrest.CoreMatchers.is;
+import static org.junit.Assert.assertThat;
+
+public class SwaggerSpecGeneratorTest {
+
+    public static class TagFor extends SwaggerSpecGeneratorTest {
+
+        @Test
+        public void fullyQualifiedClass() throws Exception {
+            String tag = SwaggerSpecGenerator.tagFor("foo.bar.Abc");
+            assertThat(tag, is(equalTo("bar")));
+        }
+
+        @Test
+        public void jaxb() throws Exception {
+            String tag = SwaggerSpecGenerator.tagFor("todoapp.app.viewmodels.todoitem.v1_0.ToDoItemDto");
+            assertThat(tag, is(equalTo("todoitem")));
+        }
+
+        @Test
+        public void schemaClass() throws Exception {
+            String tag = SwaggerSpecGenerator.tagFor("bar.Abc");
+            assertThat(tag, is(equalTo("bar")));
+        }
+
+        @Test
+        public void noPackage() throws Exception {
+            String tag = SwaggerSpecGenerator.tagFor("Abc");
+            assertThat(tag, is(equalTo("Abc")));
+        }
+
+        @Test
+        public void isisAddons() throws Exception {
+            String tag = SwaggerSpecGenerator.tagFor("org.isisaddons.module.security.app.feature.ApplicationClass");
+            assertThat(tag, is(equalTo("isisaddons security")));
+        }
+
+        @Test
+        public void applib() throws Exception {
+            String tag = SwaggerSpecGenerator.tagFor("org.apache.isis.applib.fixturescripts.FixtureResult");
+            assertThat(tag, is(equalTo("> apache isis internals")));
+        }
+
+    }
+
+}
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/9ac72b58/example/application/simpleapp/dom/src/main/java/domainapp/dom/simple/SimpleObject.java
----------------------------------------------------------------------
diff --git a/example/application/simpleapp/dom/src/main/java/domainapp/dom/simple/SimpleObject.java b/example/application/simpleapp/dom/src/main/java/domainapp/dom/simple/SimpleObject.java
index bee0af9..3057180 100644
--- a/example/application/simpleapp/dom/src/main/java/domainapp/dom/simple/SimpleObject.java
+++ b/example/application/simpleapp/dom/src/main/java/domainapp/dom/simple/SimpleObject.java
@@ -18,14 +18,10 @@
  */
 package domainapp.dom.simple;
 
-import java.util.List;
-
 import javax.jdo.JDOHelper;
 import javax.jdo.annotations.IdentityType;
 import javax.jdo.annotations.VersionStrategy;
 
-import com.google.common.collect.Lists;
-
 import org.apache.isis.applib.DomainObjectContainer;
 import org.apache.isis.applib.annotation.Action;
 import org.apache.isis.applib.annotation.BookmarkPolicy;
@@ -116,10 +112,6 @@ public class SimpleObject implements Comparable<SimpleObject> {
     }
 
 
-    public List<SimpleObject> getOthers() {
-        return Lists.newArrayList();
-    }
-
 
     /**
      * version (derived property)


[42/52] [abbrv] isis git commit: ISIS-1237: renamed api-docs/index.html to swagger-ui/index.htm; updated about/index.html; refactoring and extending the main service

Posted by mg...@apache.org.
ISIS-1237: renamed api-docs/index.html to swagger-ui/index.htm; updated about/index.html; refactoring and extending the main service


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/3d9f8fe0
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/3d9f8fe0
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/3d9f8fe0

Branch: refs/heads/ISIS-1224-select2-v4
Commit: 3d9f8fe035822d8cb0ad81bca1b5d7538fbdcb76
Parents: 53ead49
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Thu Dec 10 14:30:24 2015 +0000
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Dec 10 14:30:24 2015 +0000

----------------------------------------------------------------------
 .../isis/applib/annotation/NatureOfService.java |  22 +-
 .../services/i18n/TranslatableString.java       |   1 +
 .../services/swagger/SwaggerServiceDefault.java |  24 +-
 .../services/swagger/internal/Caching.java      |  48 ++
 .../swagger/internal/SwaggerSpecGenerator.java  | 472 ++++++++---------
 .../services/swagger/internal/Util.java         | 164 ++++++
 .../services/swagger/internal/example.json      | 515 -------------------
 .../webapp/src/main/webapp/about/index.html     |  13 +-
 .../webapp/src/main/webapp/api-docs/index.html  | 122 -----
 .../src/main/webapp/swagger-ui/index.html       | 122 +++++
 10 files changed, 592 insertions(+), 911 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/3d9f8fe0/core/applib/src/main/java/org/apache/isis/applib/annotation/NatureOfService.java
----------------------------------------------------------------------
diff --git a/core/applib/src/main/java/org/apache/isis/applib/annotation/NatureOfService.java b/core/applib/src/main/java/org/apache/isis/applib/annotation/NatureOfService.java
index b37c2bc..0502d80 100644
--- a/core/applib/src/main/java/org/apache/isis/applib/annotation/NatureOfService.java
+++ b/core/applib/src/main/java/org/apache/isis/applib/annotation/NatureOfService.java
@@ -56,6 +56,26 @@ public enum NatureOfService {
      * Equivalent to annotating all actions with both (the now deprecated) {@link org.apache.isis.applib.annotation.NotInServiceMenu} and {@link org.apache.isis.applib.annotation.NotContributed} annotations).
      * </p>
      */
-    DOMAIN
+    DOMAIN;
+
+    boolean isViewRestOnly() {
+        return this == VIEW_REST_ONLY;
+    }
+    boolean isView() {
+        return this == VIEW;
+    }
+    boolean isViewMenuOnly() {
+        return this == VIEW_MENU_ONLY;
+    }
+    boolean isViewContributionsOnly() {
+        return this == VIEW_CONTRIBUTIONS_ONLY;
+    }
+    boolean isDomain() {
+        return this == DOMAIN;
+    }
+
+    boolean isViewOrViewMenuOnly() {
+        return isView() || isViewMenuOnly();
+    }
 
 }

http://git-wip-us.apache.org/repos/asf/isis/blob/3d9f8fe0/core/applib/src/main/java/org/apache/isis/applib/services/i18n/TranslatableString.java
----------------------------------------------------------------------
diff --git a/core/applib/src/main/java/org/apache/isis/applib/services/i18n/TranslatableString.java b/core/applib/src/main/java/org/apache/isis/applib/services/i18n/TranslatableString.java
index 5509eb5..515a2b7 100644
--- a/core/applib/src/main/java/org/apache/isis/applib/services/i18n/TranslatableString.java
+++ b/core/applib/src/main/java/org/apache/isis/applib/services/i18n/TranslatableString.java
@@ -200,6 +200,7 @@ public final class TranslatableString {
      *     {@link Exception#getMessage() message} when only a translatable message has been provided.
      * </p>
      */
+    @Programmatic
     public String getPattern() {
         return !isPluralForm() || number == 1 ? getSingularText() : getPluralText();
     }

http://git-wip-us.apache.org/repos/asf/isis/blob/3d9f8fe0/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/SwaggerServiceDefault.java
----------------------------------------------------------------------
diff --git a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/SwaggerServiceDefault.java b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/SwaggerServiceDefault.java
index c447788..c6ac0e8 100644
--- a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/SwaggerServiceDefault.java
+++ b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/SwaggerServiceDefault.java
@@ -18,6 +18,10 @@
  */
 package org.apache.isis.core.metamodel.services.swagger;
 
+import java.util.Map;
+
+import javax.annotation.PostConstruct;
+
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
@@ -36,13 +40,31 @@ public class SwaggerServiceDefault implements SwaggerService, SpecificationLoade
     @SuppressWarnings("unused")
     private final static Logger LOG = LoggerFactory.getLogger(SwaggerServiceDefault.class);
 
+    public static final String KEY_RESTFUL_BASE_PATH = "isis.services.swagger.restfulBasePath";
+    public static final String KEY_RESTFUL_BASE_PATH_DEFAULT = "/restful";
+
+    private String basePath;
+
+    @PostConstruct
+    public void init(final Map<String,String> properties) {
+        this.basePath = getPropertyElse(properties, KEY_RESTFUL_BASE_PATH, KEY_RESTFUL_BASE_PATH_DEFAULT);
+    }
+
+    static String getPropertyElse(final Map<String, String> properties, final String key, final String dflt) {
+        String basePath = properties.get(key);
+        if(basePath == null) {
+            basePath = dflt;
+        }
+        return basePath;
+    }
+
     @Override
     public String generateSwaggerSpec(
             final Visibility visibility,
             final Format format) {
 
         final SwaggerSpecGenerator swaggerSpecGenerator = new SwaggerSpecGenerator(specificationLoader);
-        final String swaggerSpec = swaggerSpecGenerator.generate(visibility, format);
+        final String swaggerSpec = swaggerSpecGenerator.generate(basePath, visibility, format);
         return swaggerSpec;
     }
 

http://git-wip-us.apache.org/repos/asf/isis/blob/3d9f8fe0/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/Caching.java
----------------------------------------------------------------------
diff --git a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/Caching.java b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/Caching.java
new file mode 100644
index 0000000..55eb624
--- /dev/null
+++ b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/Caching.java
@@ -0,0 +1,48 @@
+package org.apache.isis.core.metamodel.services.swagger.internal;
+
+import io.swagger.models.Response;
+import io.swagger.models.properties.IntegerProperty;
+
+/*
+ *  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.
+ */
+enum Caching {
+    TRANSACTIONAL {
+        @Override public void withHeaders(final Response response) {
+
+        }
+    },
+    USER_INFO {
+        @Override public void withHeaders(final Response response) {
+            response
+                    .header("Cache-Control",
+                            new IntegerProperty()
+                                    ._default(3600));
+        }
+    },
+    NON_EXPIRING {
+        @Override public void withHeaders(final Response response) {
+            response
+                    .header("Cache-Control",
+                            new IntegerProperty()
+                                    ._default(86400).description(Util.roSpec("2.13")));
+        }
+    };
+
+    public abstract void withHeaders(final Response response);
+}

http://git-wip-us.apache.org/repos/asf/isis/blob/3d9f8fe0/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGenerator.java
----------------------------------------------------------------------
diff --git a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGenerator.java b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGenerator.java
index 896d4f0..f1ca3e5 100644
--- a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGenerator.java
+++ b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGenerator.java
@@ -27,19 +27,18 @@ import com.google.common.base.Strings;
 
 import org.apache.isis.applib.annotation.ActionSemantics;
 import org.apache.isis.applib.annotation.NatureOfService;
-import org.apache.isis.applib.filter.Filters;
 import org.apache.isis.applib.services.swagger.SwaggerService;
 import org.apache.isis.core.commons.factory.InstanceUtil;
-import org.apache.isis.core.metamodel.facets.actcoll.typeof.TypeOfFacet;
 import org.apache.isis.core.metamodel.facets.object.domainservice.DomainServiceFacet;
+import org.apache.isis.core.metamodel.facets.object.mixin.MixinFacet;
 import org.apache.isis.core.metamodel.facets.object.objectspecid.ObjectSpecIdFacet;
 import org.apache.isis.core.metamodel.services.ServiceUtil;
-import org.apache.isis.core.metamodel.spec.ActionType;
 import org.apache.isis.core.metamodel.spec.ObjectSpecification;
 import org.apache.isis.core.metamodel.spec.SpecificationLoader;
-import org.apache.isis.core.metamodel.spec.feature.Contributed;
 import org.apache.isis.core.metamodel.spec.feature.ObjectAction;
 import org.apache.isis.core.metamodel.spec.feature.ObjectActionParameter;
+import org.apache.isis.core.metamodel.spec.feature.OneToManyAssociation;
+import org.apache.isis.core.metamodel.spec.feature.OneToOneAssociation;
 
 import io.swagger.models.Info;
 import io.swagger.models.ModelImpl;
@@ -51,7 +50,6 @@ import io.swagger.models.parameters.BodyParameter;
 import io.swagger.models.parameters.PathParameter;
 import io.swagger.models.parameters.QueryParameter;
 import io.swagger.models.properties.ArrayProperty;
-import io.swagger.models.properties.IntegerProperty;
 import io.swagger.models.properties.MapProperty;
 import io.swagger.models.properties.ObjectProperty;
 import io.swagger.models.properties.Property;
@@ -68,16 +66,39 @@ public class SwaggerSpecGenerator {
         this.specificationLoader = specificationLoader;
     }
 
-    public String generate(final SwaggerService.Visibility visibility, final SwaggerService.Format format) {
+    public String generate(
+            final String basePath,
+            final SwaggerService.Visibility visibility,
+            final SwaggerService.Format format) {
+
         final Swagger swagger = new Swagger();
-        swagger.basePath("/restful");
+        swagger.basePath(basePath);
         swagger.info(new Info()
-                        .version("1.0.0")
-                        .title("Restful Objects"));
+                        //.version("1.0.0") // TODO: provide some way of passing the name, version etc (some sort of SPI service?)
+                        .title(visibility.name() + " API")
+        );
+
+        appendRestfulObjectsSupportingPathsAndDefinitions(swagger);
+        appendLinkModelDefinition(swagger);
 
-        appendBoilerplate(swagger);
-        appendLinkDefinitions(swagger);
+        appendServicePathsAndDefinitions(swagger, visibility);
+        appendObjectPathsAndDefinitions(swagger, visibility);
+
+        switch (format) {
+            case JSON:
+                return Json.pretty(swagger);
+            case YAML:
+                try {
+                    return Yaml.pretty().writeValueAsString(swagger);
+                } catch (JsonProcessingException e) {
+                    throw new RuntimeException(e);
+                }
+            default:
+                throw new IllegalArgumentException("Unrecognized format: " + format);
+        }
+    }
 
+    void appendServicePathsAndDefinitions(final Swagger swagger, final SwaggerService.Visibility visibility) {
         final Collection<ObjectSpecification> allSpecs = specificationLoader.allSpecifications();
         for (final ObjectSpecification serviceSpec :  allSpecs) {
 
@@ -94,146 +115,131 @@ public class SwaggerSpecGenerator {
                 continue;
             }
 
-            final List<ActionType> actionTypes = actionTypesFor(visibility);
-            final List<ObjectAction> serviceActions = serviceSpec.getObjectActions(
-                    actionTypes, Contributed.EXCLUDED, Filters.<ObjectAction>any());
-            if (serviceActions.isEmpty()) {
+            final List<ObjectAction> serviceActions = Util.actionsOf(serviceSpec, visibility);
+            if(serviceActions.isEmpty()) {
                 continue;
             }
-
-            final ObjectProperty serviceMembers = appendServicePath(swagger, serviceSpec);
+            appendServicePath(swagger, serviceSpec);
 
             for (final ObjectAction serviceAction : serviceActions) {
-                if (visibility.isPublic() && !isVisibleForPublic(serviceAction)) {
-                    continue;
-                }
-                appendActionTo(serviceMembers, serviceAction);
                 appendServiceActionInvokePath(swagger, serviceAction);
             }
         }
+    }
 
+    void appendObjectPathsAndDefinitions(final Swagger swagger, final SwaggerService.Visibility visibility) {
+        final Collection<ObjectSpecification> allSpecs = specificationLoader.allSpecifications();
         for (final ObjectSpecification objectSpec : allSpecs) {
 
             final DomainServiceFacet domainServiceFacet = objectSpec.getFacet(DomainServiceFacet.class);
             if (domainServiceFacet != null) {
                 continue;
             }
-
+            final MixinFacet mixinFacet = objectSpec.getFacet(MixinFacet.class);
+            if (mixinFacet != null) {
+                continue;
+            }
+            if(visibility.isPublic() && !Util.isVisibleForPublic(objectSpec)) {
+                continue;
+            }
             if(objectSpec.isAbstract()) {
                 continue;
             }
+            if(objectSpec.isValue()) {
+                continue;
+            }
+
+            final List<OneToOneAssociation> objectProperties = Util.propertiesOf(objectSpec, visibility);
+            final List<OneToManyAssociation> objectCollections = Util.collectionsOf(objectSpec, visibility);
+            final List<ObjectAction> objectActions = Util.actionsOf(objectSpec, visibility);
 
-            final List<ActionType> actionTypes = actionTypesFor(visibility);
-            final List<ObjectAction> objectActions = objectSpec.getObjectActions(
-                    actionTypes, Contributed.INCLUDED, Filters.<ObjectAction>any());
-            if (objectActions.isEmpty()) {
+            if(objectProperties.isEmpty() && objectCollections.isEmpty()) {
                 continue;
             }
+            final ModelImpl isisModel = appendObjectPathAndModelDefinitions(swagger, objectSpec);
+            appendObjectModel(isisModel, objectProperties, objectCollections);
 
-            final ObjectProperty objectMembers = appendObjectPath(swagger, objectSpec);
+            for (final OneToManyAssociation objectCollection : objectCollections) {
+                appendCollectionTo(swagger, objectCollection);
+            }
 
             for (final ObjectAction objectAction : objectActions) {
-                if (visibility.isPublic() && !isVisibleForPublic(objectAction)) {
-                    continue;
-                }
-                appendActionTo(objectMembers, objectAction);
                 appendObjectActionInvokePath(swagger, objectAction);
             }
         }
-
-        switch (format) {
-            case JSON:
-                return Json.pretty(swagger);
-            case YAML:
-                try {
-                    return Yaml.pretty().writeValueAsString(swagger);
-                } catch (JsonProcessingException e) {
-                    throw new RuntimeException(e);
-                }
-            default:
-                throw new IllegalArgumentException("Unrecognized format: " + format);
-        }
     }
 
-    void appendBoilerplate(final Swagger swagger) {
-        appendBoilerplatePaths(swagger);
-        appendBoilerplateDefinitions(swagger);
-    }
+    void appendRestfulObjectsSupportingPathsAndDefinitions(final Swagger swagger) {
+
+        final String tag = "> restful objects supporting resources";
 
-    void appendBoilerplatePaths(final Swagger swagger) {
         swagger.path("/",
                 new Path()
                         .get(new Operation()
-                                .tag("boilerplate")
-                                .description(roSpec("5.1"))
+                                .tag(tag)
+                                .description(Util.roSpec("5.1"))
                                 .produces("application/json")
                                 .produces("application/json;profile=urn:org.restfulobjects:repr-types/home-page")
                                 .response(200,
                                         newResponse(Caching.NON_EXPIRING)
                                                 .description("OK")
-                                                .schema(new RefProperty("#/definitions/home-page"))
-                                )))
-                .path("/user",
-                        new Path()
-                                .get(new Operation()
-                                        .tag("boilerplate")
-                                        .description(roSpec("6.1"))
-                                        .produces("application/json")
-                                        .produces("application/json;profile=urn:org.restfulobjects:repr-types/user")
-                                        .response(200,
-                                                newResponse(Caching.USER_INFO)
-                                                        .description("OK")
-                                                        .schema(new RefProperty("#/definitions/user"))
-                                        )))
-                .path("/services",
+                                                .schema(new RefProperty("#/definitions/RestfulObjectsSupportingHomePageModel"))
+                                )));
+        swagger.addDefinition("RestfulObjectsSupportingHomePageModel",
+                newModel(Util.roSpec("5.2")));
+
+        swagger.path("/user",
+                    new Path()
+                            .get(new Operation()
+                                    .tag(tag)
+                                    .description(Util.roSpec("6.1"))
+                                    .produces("application/json")
+                                    .produces("application/json;profile=urn:org.restfulobjects:repr-types/user")
+                                    .response(200,
+                                            newResponse(Caching.USER_INFO)
+                                                    .description("OK")
+                                                    .schema(new RefProperty("#/definitions/RestfulObjectsSupportingUserModel"))
+                                    )));
+        swagger.addDefinition("RestfulObjectsSupportingUserModel",
+                newModel(Util.roSpec("6.2"))
+                        .property("userName", stringProperty())
+                        .property("roles", arrayOfStrings())
+                        .property("links", arrayOfLinks())
+                        .required("userName")
+                        .required("roles"));
+
+        swagger.path("/services",
                         new Path()
                                 .get(new Operation()
-                                        .tag("boilerplate")
-                                        .description(roSpec("7.1"))
+                                        .tag(tag)
+                                        .description(Util.roSpec("7.1"))
                                         .produces("application/json")
                                         .produces("application/json;profile=urn:org.restfulobjects:repr-types/services")
                                         .response(200,
                                                 newResponse(Caching.USER_INFO)
                                                         .description("OK")
-                                                        .schema(new RefProperty("#/definitions/services"))
-                                        )))
+                                                        .schema(new RefProperty("#/definitions/RestfulObjectsSupportingServicesModel"))
+                                        )));
+        swagger.addDefinition("RestfulObjectsSupportingServicesModel",
+                newModel(Util.roSpec("7.2"))
+                        .property("value", arrayOfLinks())
+                        .required("userName")
+                        .required("roles"));
 
-                .path("/version",
+        swagger.path("/version",
                         new Path()
                                 .get(new Operation()
-                                        .tag("boilerplate")
-                                        .description(roSpec("8.1"))
+                                        .tag(tag)
+                                        .description(Util.roSpec("8.1"))
                                         .produces("application/json")
-                                        .produces("application/json;profile=urn:org.restfulobjects:repr-types/version")
+                                        .produces("application/json;profile=urn:org.restfulobjects:repr-types/RestfulObjectsSupportingServicesModel")
                                         .response(200,
                                                 newResponse(Caching.NON_EXPIRING)
                                                         .description("OK")
-                                                        .schema(new RefProperty("#/definitions/version"))
+                                                        .schema(new ObjectProperty())
                                         )));
-    }
-
-    void appendBoilerplateDefinitions(final Swagger swagger) {
-        swagger.addDefinition("home-page",
-                newModel(roSpec("5.2")));
-
-        swagger.addDefinition("user",
-                newModel(roSpec("6.2"))
-                        .property("userName", stringProperty())
-                        .property("roles", arrayOfStrings())
-                        .property("links", arrayOfLinksGetOnly())
-                        .required("userName")
-                        .required("roles")
-        );
-
-        swagger.addDefinition("services",
-                newModel(roSpec("7.2"))
-                        .property("value", arrayOfLinksGetOnly())
-                        .required("userName")
-                        .required("roles")
-        );
-
-        swagger.addDefinition("version",
-                newModel(roSpec("8.2"))
+        swagger.addDefinition("RestfulObjectsSupportingServicesModel",
+                newModel(Util.roSpec("8.2"))
                         .property("specVersion", stringProperty())
                         .property("implVersion", stringProperty())
                         .property("optionalCapabilities",
@@ -245,13 +251,11 @@ public class SwaggerSpecGenerator {
                                         .property("protoPersistentObjects", stringProperty())
                         )
                         .required("userName")
-                        .required("roles")
-        );
+                        .required("roles"));
     }
 
-    void appendLinkDefinitions(final Swagger swagger) {
-
-        swagger.addDefinition("link",
+    void appendLinkModelDefinition(final Swagger swagger) {
+        swagger.addDefinition("LinkModel",
                 new ModelImpl()
                     .type("object")
                     .property("rel", stringProperty())
@@ -265,105 +269,109 @@ public class SwaggerSpecGenerator {
                     .required("method")
         );
 
-        swagger.addDefinition("link-get-only",
-                new ModelImpl()
-                    .type("object")
-                    .property("rel", stringProperty())
-                    .property("href", stringProperty())
-                    .property("title", stringProperty())
-                    .property("method", stringPropertyEnum("GET"))
-                    .property("type", stringProperty())
-                    .required("rel")
-                    .required("href")
-                    .required("method")
-        );
     }
 
-    ObjectProperty appendServicePath(final Swagger swagger, final ObjectSpecification objectSpec) {
+    void appendServicePath(final Swagger swagger, final ObjectSpecification objectSpec) {
 
         final String serviceId = serviceIdFor(objectSpec);
 
         final Path path = new Path();
         swagger.path(String.format("/services/%s", serviceId), path);
 
+        final String serviceModelDefinition = serviceId + "Model";
         path.get(
                 new Operation()
                         .tag(serviceId)
-                        .description(roSpec("15.1"))
+                        .description(Util.roSpec("15.1"))
                         .produces("application/json")
                         .produces("application/json;profile=urn:org.restfulobjects:repr-types/object")
                         .response(200,
                                 newResponse(Caching.TRANSACTIONAL)
                                         .description("OK")
-                                        .schema(new RefProperty("#/definitions/service-" + serviceId)))
+                                        .schema(new RefProperty("#/definitions/" + serviceModelDefinition)))
         );
 
-        final ObjectProperty serviceMembers = new ObjectProperty();
-        final ModelImpl serviceRepr =
-                newModel(roSpec("15.1.2") + ": representation of " + serviceId)
+        final ModelImpl model =
+                newModel(Util.roSpec("15.1.2") + ": representation of " + serviceId)
                         .property("title", stringProperty())
                         .property("serviceId", stringProperty()._default(serviceId))
-                        .property("members", serviceMembers);
+                        .property("members", new ObjectProperty());
 
-        swagger.addDefinition("service-" + serviceId, serviceRepr);
-        return serviceMembers;
+        swagger.addDefinition(serviceModelDefinition, model);
     }
 
-    ObjectProperty appendObjectPath(final Swagger swagger, final ObjectSpecification objectSpec) {
+    ModelImpl appendObjectPathAndModelDefinitions(final Swagger swagger, final ObjectSpecification objectSpec) {
 
         final String objectType = objectTypeFor(objectSpec);
 
         final Path path = new Path();
         swagger.path(String.format("/objects/%s/{objectId}", objectType), path);
 
+        final String isisModelDefinition = objectType + "Model";
+        final String restfulObjectsModelDefinition = objectType + "RestfulObjectsModel";
+        final String tag = objectType.startsWith("org.apache.isis")? "> apache isis internals": objectType;
+        final Operation operation = new Operation();
         path.get(
-                new Operation()
-                        .tag(objectType)
-                        .description(roSpec("14.1"))
-                        .parameter(
-                                new PathParameter()
-                                        .name("objectId")
-                                        .type("string"))
-                        .produces("application/json")
-                        .produces("application/json;profile=urn:org.restfulobjects:repr-types/object")
-                        .produces("application/json;profile=urn:org.apache.isis/v1")
-                        .produces("application/json;profile=urn:org.apache.isis/v1;suppress=true")
-                        .response(200,
-                                newResponse(Caching.TRANSACTIONAL)
-                                        .description("OK")
-                                        .schema(new RefProperty("#/definitions/object-" + objectType)))
-        );
+                operation);
+        operation
+                .tag(tag)
+                .description(Util.roSpec("14.1"))
+                .parameter(
+                    new PathParameter()
+                        .name("objectId")
+                        .type("string"))
+                .produces("application/json;profile=urn:org.apache.isis/v1")
+                .produces("application/json;profile=urn:org.apache.isis/v1;suppress=true")
+                .produces("application/json;profile=urn:org.restfulobjects:repr-types/object");
+
+
+        // per https://github.com/swagger-api/swagger-spec/issues/146, swagger 2.0 doesn't support multiple
+        // modelled representations per path and response code;
+        // in particular cannot associate representation/model with Accept header ('produces(...) method)
+        if (false) {
+            operation.response(200,
+                    newResponse(Caching.TRANSACTIONAL)
+                            .description("if Accept: application/json;profile=urn:org.restfulobjects:repr-types/object")
+                            .schema(new RefProperty("#/definitions/" + restfulObjectsModelDefinition)));
+
+            final ModelImpl roSpecModel =
+                    newModel(Util.roSpec("14.4") + ": representation of " + objectType)
+                            .property("title", stringProperty())
+                            .property("domainType", stringProperty()._default(objectType))
+                            .property("instanceId", stringProperty())
+                            .property("members", new ObjectProperty());
+            swagger.addDefinition(restfulObjectsModelDefinition, roSpecModel);
+        }
 
-        final ObjectProperty serviceMembers = new ObjectProperty();
-        final ModelImpl serviceRepr =
-                newModel(roSpec("14.4") + ": representation of " + objectType)
-                        .property("title", stringProperty())
-                        .property("domainType", stringProperty()._default(objectType))
-                        .property("instanceId", stringProperty())
-                        .property("members", serviceMembers);
+        operation
+                .response(200,
+                        newResponse(Caching.TRANSACTIONAL)
+                                .description("if Accept: application/json;profile=urn:org.apache.isis/v1")
+                                .schema(new RefProperty("#/definitions/"
+                                        + isisModelDefinition)));
 
-        swagger.addDefinition("object-" + objectType, serviceRepr);
-        return serviceMembers;
-    }
 
-    private String objectTypeFor(final ObjectSpecification objectSpec) {
-        return objectSpec.getFacet(ObjectSpecIdFacet.class).value().asString();
+        final ModelImpl isisModel = new ModelImpl();
+        swagger.addDefinition(isisModelDefinition, isisModel);
+
+        // return so can be appended to
+        return isisModel;
     }
 
-    void appendActionTo(final ObjectProperty serviceMembers, final ObjectAction serviceAction) {
-        String serviceActionId = serviceAction.getId();
+    // UNUSED
+    void appendServiceActionPromptTo(final ObjectProperty serviceMembers, final ObjectAction action) {
+        String actionId = action.getId();
 
-        // within the services representation itself
-        serviceMembers.property(serviceActionId,
+        serviceMembers.property(actionId,
                 new ObjectProperty()
-                        .property("id", stringPropertyEnum(serviceActionId))
+                        .property("id", stringPropertyEnum(actionId))
                         .property("memberType", stringPropertyEnum("action"))
                         .property("links",
                                 new ObjectProperty()
                                         .property("rel", stringPropertyEnum( String.format(
-                                                "urn:org.restfulobjects:rels/details;action=%s", serviceActionId)))
+                                                "urn:org.restfulobjects:rels/details;action=%s", actionId)))
                                         .property("href", stringPropertyEnum(String.format(
-                                                "actions/%s", serviceActionId))))
+                                                "actions/%s", actionId))))
                         .property("method", stringPropertyEnum("GET"))
                         .property("type", stringPropertyEnum(
                                 "application/json;profile=urn:org.restfulobjects:repr-types/object-action"))
@@ -385,11 +393,11 @@ public class SwaggerSpecGenerator {
         final Operation invokeOperation =
                 new Operation()
                         .tag(serviceId)
-                        .description(roSpec("19.1") + ": (invoke) resource of " + serviceId + "#" + actionId)
-                        .produces("application/json")
-                        .produces("application/json;profile=urn:org.restfulobjects:repr-types/action-result")
+                        .description(Util.roSpec("19.1") + ": (invoke) resource of " + serviceId + "#" + actionId)
                         .produces("application/json;profile=urn:org.apache.isis/v1")
-                        .produces("application/json;profile=urn:org.apache.isis/v1;suppress=true");
+                        .produces("application/json;profile=urn:org.apache.isis/v1;suppress=true")
+                        .produces("application/json;profile=urn:org.restfulobjects:repr-types/action-result")
+                ;
 
         final ActionSemantics.Of semantics = serviceAction.getSemantics();
         if(semantics.isSafeInNature()) {
@@ -400,7 +408,7 @@ public class SwaggerSpecGenerator {
                         .parameter(
                                 new QueryParameter()
                                         .name(parameter.getId())
-                                        .description(roSpec("2.9.1") + (!Strings.isNullOrEmpty(parameter.getDescription())? (": " + parameter.getDescription()) : ""))
+                                        .description(Util.roSpec("2.9.1") + (!Strings.isNullOrEmpty(parameter.getDescription())? (": " + parameter.getDescription()) : ""))
                                         .required(false)
                                         .type("string")
                         );
@@ -408,7 +416,7 @@ public class SwaggerSpecGenerator {
             if(!parameters.isEmpty()) {
                 invokeOperation.parameter(new QueryParameter()
                         .name("x-isis-querystring")
-                        .description(roSpec("2.10") + ": all (formal) arguments as base64 encoded string")
+                        .description(Util.roSpec("2.10") + ": all (formal) arguments as base64 encoded string")
                         .required(false)
                         .type("string"));
             }
@@ -469,15 +477,14 @@ public class SwaggerSpecGenerator {
         final Operation invokeOperation =
                 new Operation()
                         .tag(objectType)
-                        .description(roSpec("19.1") + ": (invoke) resource of " + objectType + "#" + actionId)
+                        .description(Util.roSpec("19.1") + ": (invoke) resource of " + objectType + "#" + actionId)
                         .parameter(
                                 new PathParameter()
                                         .name("objectId")
                                         .type("string"))
-                        .produces("application/json")
-                        .produces("application/json;profile=urn:org.restfulobjects:repr-types/action-result")
                         .produces("application/json;profile=urn:org.apache.isis/v1")
-                        .produces("application/json;profile=urn:org.apache.isis/v1;suppress=true");
+                        .produces("application/json;profile=urn:org.apache.isis/v1;suppress=true")
+                        .produces("application/json;profile=urn:org.restfulobjects:repr-types/action-result");
 
         final ActionSemantics.Of semantics = objectAction.getSemantics();
         if(semantics.isSafeInNature()) {
@@ -488,7 +495,7 @@ public class SwaggerSpecGenerator {
                         .parameter(
                                 new QueryParameter()
                                         .name(parameter.getId())
-                                        .description(roSpec("2.9.1") + (!Strings.isNullOrEmpty(parameter.getDescription())? (": " + parameter.getDescription()) : ""))
+                                        .description(Util.roSpec("2.9.1") + (!Strings.isNullOrEmpty(parameter.getDescription())? (": " + parameter.getDescription()) : ""))
                                         .required(false)
                                         .type("string")
                         );
@@ -496,7 +503,7 @@ public class SwaggerSpecGenerator {
             if(!parameters.isEmpty()) {
                 invokeOperation.parameter(new QueryParameter()
                         .name("x-isis-querystring")
-                        .description(roSpec("2.10") + ": all (formal) arguments as base64 encoded string")
+                        .description(Util.roSpec("2.10") + ": all (formal) arguments as base64 encoded string")
                         .required(false)
                         .type("string"));
             }
@@ -542,8 +549,17 @@ public class SwaggerSpecGenerator {
                 );
     }
 
+    void appendCollectionTo(final Swagger members, final OneToManyAssociation serviceAction) {
 
-    private String roSpecForResponseOf(final ObjectAction action) {
+    }
+
+    void appendObjectModel(
+            final ModelImpl swagger,
+            final List<OneToOneAssociation> objectProperties, final List<OneToManyAssociation> objectCollections) {
+
+    }
+
+    static String roSpecForResponseOf(final ObjectAction action) {
         final ActionSemantics.Of semantics = action.getSemantics();
         switch (semantics) {
             case SAFE_AND_REQUEST_CACHEABLE:
@@ -557,62 +573,31 @@ public class SwaggerSpecGenerator {
         }
     }
 
-    private boolean isVisibleForPublic(final ObjectAction objectAction) {
-        final ObjectSpecification specification = objectAction.getReturnType();
-        boolean visible = isVisibleForPublic(specification);
-        if(!visible) {
-            return false;
-        }
-        List<ObjectSpecification> parameterTypes = objectAction.getParameterTypes();
-        for (ObjectSpecification parameterType : parameterTypes) {
-            boolean paramVisible = isVisibleForPublic(parameterType);
-            if(!paramVisible) {
-                return false;
-            }
-        }
-        return true;
-    }
-
-    private boolean isVisibleForPublic(final ObjectSpecification specification) {
-        if (specification == null) {
-            return true;
-        }
-        if(specification.isViewModel()) {
-            return true;
-        }
-        if(specification.isValue()) {
-            return true;
-        }
-        if(specification.isParentedOrFreeCollection()) {
-            TypeOfFacet typeOfFacet = specification.getFacet(TypeOfFacet.class);
-            ObjectSpecification elementSpec = typeOfFacet.valueSpec();
-            return isVisibleForPublic(elementSpec);
-        }
-        final Class<?> correspondingClass = specification.getCorrespondingClass();
-        return correspondingClass == void.class || correspondingClass == Void.class;
-    }
-
-    private ModelImpl newModel(final String description) {
+    static ModelImpl newModel(final String description) {
         return new ModelImpl()
                 .description(description)
                 .type("object")
-                .property("links", arrayOfLinksGetOnly())
+                .property("links", arrayOfLinks())
                 .property("extensions", new MapProperty())
                 .required("links")
                 .required("extensions");
     }
 
     // TODO: this is horrid, there ought to be a facet we can call instead...
-    String serviceIdFor(final ObjectSpecification serviceSpec) {
+    static String serviceIdFor(final ObjectSpecification serviceSpec) {
         Object tempServiceInstance = InstanceUtil.createInstance(serviceSpec.getCorrespondingClass());
         return ServiceUtil.id(tempServiceInstance);
     }
 
-    StringProperty stringProperty() {
+    static String objectTypeFor(final ObjectSpecification objectSpec) {
+        return objectSpec.getFacet(ObjectSpecIdFacet.class).value().asString();
+    }
+
+    static StringProperty stringProperty() {
         return new StringProperty();
     }
 
-    StringProperty stringPropertyEnum(String... enumValues) {
+    static StringProperty stringPropertyEnum(String... enumValues) {
         StringProperty stringProperty = stringProperty();
         stringProperty._enum(Arrays.asList(enumValues));
         if(enumValues.length >= 1) {
@@ -621,66 +606,17 @@ public class SwaggerSpecGenerator {
         return stringProperty;
     }
 
-    ArrayProperty arrayOfLinksGetOnly() {
+    static ArrayProperty arrayOfLinks() {
         return new ArrayProperty()
-                .items(new RefProperty("#/definitions/link-get-only"));
+                .items(new RefProperty("#/definitions/LinkModel"));
     }
 
-    ArrayProperty arrayOfStrings() {
+    static ArrayProperty arrayOfStrings() {
         return new ArrayProperty().items(stringProperty());
     }
 
-    private Response newResponse(final Caching caching) {
-        return withCachingHeaders(new Response(), caching);
+    static Response newResponse(final Caching caching) {
+        return Util.withCachingHeaders(new Response(), caching);
     }
 
-    enum Caching {
-        TRANSACTIONAL {
-            @Override public void withHeaders(final Response response) {
-
-            }
-        },
-        USER_INFO {
-            @Override public void withHeaders(final Response response) {
-                response
-                        .header("Cache-Control",
-                                new IntegerProperty()
-                                        ._default(3600));
-            }
-        },
-        NON_EXPIRING {
-            @Override public void withHeaders(final Response response) {
-                response
-                        .header("Cache-Control",
-                                new IntegerProperty()
-                                        ._default(86400).description(roSpec("2.13")));
-            }
-        };
-
-        public abstract void withHeaders(final Response response);
-    }
-
-    private static String roSpec(final String section) {
-        return "RO Spec v1.0, section " + section;
-    }
-
-    private Response withCachingHeaders(final Response response, final Caching caching) {
-        caching.withHeaders(response);
-
-        return response;
-    }
-
-    private List<ActionType> actionTypesFor(final SwaggerService.Visibility visibility) {
-        switch (visibility) {
-        case PUBLIC:
-            return Arrays.asList(ActionType.USER);
-        case PRIVATE:
-            return Arrays.asList(ActionType.USER);
-        case PRIVATE_WITH_PROTOTYPING:
-            return Arrays.asList(ActionType.USER, ActionType.EXPLORATION, ActionType.PROTOTYPE, ActionType.DEBUG);
-        }
-        throw new IllegalArgumentException("Unrecognized type '" + visibility + "'");
-    }
-
-
 }

http://git-wip-us.apache.org/repos/asf/isis/blob/3d9f8fe0/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/Util.java
----------------------------------------------------------------------
diff --git a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/Util.java b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/Util.java
new file mode 100644
index 0000000..4ab66e2
--- /dev/null
+++ b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/Util.java
@@ -0,0 +1,164 @@
+/*
+ *  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.
+ */
+package org.apache.isis.core.metamodel.services.swagger.internal;
+
+import java.util.Arrays;
+import java.util.Collection;
+import java.util.List;
+
+import org.apache.isis.applib.filter.Filter;
+import org.apache.isis.applib.filter.Filters;
+import org.apache.isis.applib.services.swagger.SwaggerService;
+import org.apache.isis.core.metamodel.facets.actcoll.typeof.TypeOfFacet;
+import org.apache.isis.core.metamodel.spec.ActionType;
+import org.apache.isis.core.metamodel.spec.ObjectSpecification;
+import org.apache.isis.core.metamodel.spec.feature.Contributed;
+import org.apache.isis.core.metamodel.spec.feature.ObjectAction;
+import org.apache.isis.core.metamodel.spec.feature.ObjectAssociation;
+import org.apache.isis.core.metamodel.spec.feature.OneToManyAssociation;
+import org.apache.isis.core.metamodel.spec.feature.OneToOneAssociation;
+
+import io.swagger.models.Response;
+
+public final class Util {
+
+    private Util(){}
+
+    static boolean isVisibleForPublic(final ObjectAction objectAction) {
+        final ObjectSpecification specification = objectAction.getReturnType();
+        boolean visible = isVisibleForPublic(specification);
+        if(!visible) {
+            return false;
+        }
+        List<ObjectSpecification> parameterTypes = objectAction.getParameterTypes();
+        for (ObjectSpecification parameterType : parameterTypes) {
+            boolean paramVisible = isVisibleForPublic(parameterType);
+            if(!paramVisible) {
+                return false;
+            }
+        }
+        return true;
+    }
+
+    static boolean isVisibleForPublic(final ObjectAssociation objectAssociation) {
+        final ObjectSpecification specification = objectAssociation.getSpecification();
+        return isVisibleForPublic(specification);
+    }
+
+    static boolean isVisibleForPublic(final ObjectSpecification specification) {
+        if (specification == null) {
+            return true;
+        }
+        if(specification.isViewModel()) {
+            return true;
+        }
+        if(specification.isValue()) {
+            return true;
+        }
+        if(specification.isParentedOrFreeCollection()) {
+            TypeOfFacet typeOfFacet = specification.getFacet(TypeOfFacet.class);
+            if(typeOfFacet != null) {
+                ObjectSpecification elementSpec = typeOfFacet.valueSpec();
+                return isVisibleForPublic(elementSpec);
+            }
+        }
+
+        final Class<?> correspondingClass = specification.getCorrespondingClass();
+        return  Collection.class.isAssignableFrom(correspondingClass) ||
+                correspondingClass.isArray() ||
+                correspondingClass == void.class ||
+                correspondingClass == Void.class;
+    }
+
+    static Filter<ObjectAssociation> associationsWith(final SwaggerService.Visibility visibility) {
+        return new Filter<ObjectAssociation>() {
+          @Override
+          public boolean accept(final ObjectAssociation objectAssociation) {
+              return !visibility.isPublic() || isVisibleForPublic(objectAssociation);
+          }
+      };
+    }
+
+    static List<OneToOneAssociation> propertiesOf(
+            final ObjectSpecification objectSpecification,
+            final SwaggerService.Visibility visibility) {
+        return associationsOf(objectSpecification, ObjectAssociation.Filters.PROPERTIES, visibility);
+    }
+
+    static List<OneToManyAssociation> collectionsOf(
+            final ObjectSpecification objectSpecification,
+            final SwaggerService.Visibility visibility) {
+        return associationsOf(objectSpecification, ObjectAssociation.Filters.COLLECTIONS, visibility);
+    }
+
+    static <T extends ObjectAssociation> List<T> associationsOf(
+            final ObjectSpecification objectSpecification,
+            final Filter<ObjectAssociation> associationFilter, final SwaggerService.Visibility visibility) {
+        @SuppressWarnings("rawtypes")
+        final List<ObjectAssociation> list =
+                objectSpecification.getAssociations(
+                        Contributed.INCLUDED,
+                        Filters.and(
+                                associationFilter,
+                                associationsWith(visibility)
+                        ));
+
+        return cast(list);
+    }
+
+    @SuppressWarnings("unchecked")
+    static <T> List<T> cast(final List list) {
+        return list;
+    }
+
+    static List<ObjectAction> actionsOf(
+            final ObjectSpecification objectSpec,
+            final SwaggerService.Visibility visibility) {
+        final List<ActionType> actionTypes = actionTypesFor(visibility);
+
+        return objectSpec.getObjectActions(actionTypes, Contributed.INCLUDED, new Filter<ObjectAction>() {
+            @Override
+            public boolean accept(final ObjectAction objectAction) {
+                return !visibility.isPublic() || isVisibleForPublic(objectAction);
+            }
+        });
+    }
+
+    static String roSpec(final String section) {
+        return "RO Spec v1.0, section " + section;
+    }
+
+    static Response withCachingHeaders(final Response response, final Caching caching) {
+        caching.withHeaders(response);
+
+        return response;
+    }
+
+    static List<ActionType> actionTypesFor(final SwaggerService.Visibility visibility) {
+        switch (visibility) {
+        case PUBLIC:
+            return Arrays.asList(ActionType.USER);
+        case PRIVATE:
+            return Arrays.asList(ActionType.USER);
+        case PRIVATE_WITH_PROTOTYPING:
+            return Arrays.asList(ActionType.USER, ActionType.EXPLORATION, ActionType.PROTOTYPE, ActionType.DEBUG);
+        }
+        throw new IllegalArgumentException("Unrecognized type '" + visibility + "'");
+    }
+}

http://git-wip-us.apache.org/repos/asf/isis/blob/3d9f8fe0/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/example.json
----------------------------------------------------------------------
diff --git a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/example.json b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/example.json
deleted file mode 100644
index 7036c06..0000000
--- a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/example.json
+++ /dev/null
@@ -1,515 +0,0 @@
-{
-  "swagger": "2.0",
-  "info": {
-    "version": "1.0.0",
-    "title": "Restful Objects"
-  },
-  "paths": {
-    "/": {
-      "get": {
-        "description": "Home page",
-        "produces": [
-          "application/json"
-        ],
-        "responses": {
-          "200": {
-            "description": "OK",
-            "schema": {
-              "type": "object",
-              "required": [
-                "links"
-              ],
-              "properties": {
-                "links": {
-                  "type": "array",
-                  "items": {
-                    "$ref": "#/definitions/LinkRepresentation"
-                  }
-                }
-              }
-            }
-          }
-        }
-      }
-    },
-    "/services": {
-      "get": {
-        "description": "Services",
-        "produces": [
-          "application/json"
-        ],
-        "responses": {
-          "200": {
-            "description": "OK",
-            "schema": {
-              "type": "object",
-              "required": [
-                "value",
-                "links"
-              ],
-              "properties": {
-                "value": {
-                  "type": "array",
-                  "items": {
-                    "$ref": "#/definitions/LinkRepresentation"
-                  }
-                },
-                "links": {
-                  "type": "array",
-                  "items": {
-                    "$ref": "#/definitions/LinkRepresentation"
-                  }
-                }
-              }
-            }
-          }
-        }
-      }
-    },
-    "/services/SimpleObjects": {
-      "get": {
-        "description": "SimpleObjects service",
-        "produces": [
-          "application/json"
-        ],
-        "responses": {
-          "200": {
-            "description": "OK",
-            "schema": {
-              "$ref": "#/definitions/ServiceRepresentation"
-            }
-          }
-        }
-      }
-    },
-    "/services/SimpleObjects/actions/findByName": {
-      "get": {
-        "description": "SimpleObjects findByName action",
-        "produces": [
-          "application/json"
-        ],
-        "responses": {
-          "200": {
-            "description": "OK",
-            "schema": {
-              "$ref": "#/definitions/ActionPromptRepresentation"
-            }
-          }
-        }
-      }
-    },
-    "/services/SimpleObjects/actions/findByName/invoke": {
-      "get": {
-        "description": "SimpleObjects findByName invocation result",
-        "consumes": [
-          "application/json"
-        ],
-        "produces": [
-          "application/json;profile=\"urn:org.restfulobjects/repr-types/action-result\"",
-          "application/json;profile=\"urn:org.apache.isis/v1\"",
-          "application/json;profile=\"urn:org.apache.isis/v1\";suppress=\"true\""
-        ],
-        "responses": {
-          "200": {
-            "description": "All objects matching name",
-            "schema": {
-              "$ref": "#/definitions/ActionInvocationRepresentationOfList"
-            }
-          }
-        }
-      }
-    },
-    "/objects/simple.SimpleObject/{id}": {
-      "get": {
-        "description": "representation of simple.SimpleObject",
-        "parameters": [
-          {
-            "in": "path",
-            "name": "id",
-            "required": true,
-            "type": "string"
-          }
-        ],
-        "produces": [
-          "application/json;profile=\"urn:org.restfulobjects/repr-types/object\"",
-          "application/json;profile=\"urn:org.apache.isis/v1\";repr-type=\"object\""
-        ],
-        "responses": {
-          "200": {
-            "description": "OK",
-            "schema": {
-              "$ref": "#/definitions/ObjectRepresentation"
-            }
-          }
-        }
-      }
-    }
-  },
-  "definitions": {
-    "ServiceRepresentation": {
-      "type": "object",
-      "required": [
-        "links",
-        "extensions",
-        "title",
-        "serviceId"
-      ],
-      "properties": {
-        "links": {
-          "type": "array",
-          "items": {
-            "$ref": "#/definitions/LinkRepresentation"
-          }
-        },
-        "extensions": {
-          "$ref": "#/definitions/ServiceOrObjectExtensionsRepresentation"
-        },
-        "title": {
-          "type": "string"
-        },
-        "serviceId": {
-          "type": "string"
-        },
-        "members": {
-          "type": "object",
-          "required": [
-            "listAll",
-            "findByName",
-            "create"
-          ],
-          "properties": {
-            "listAll": {
-              "$ref": "#/definitions/ActionRepresentation"
-            },
-            "findByName": {
-              "$ref": "#/definitions/ActionRepresentation"
-            },
-            "create": {
-              "$ref": "#/definitions/ActionRepresentation"
-            }
-          }
-        }
-      }
-    },
-    "ObjectRepresentation": {
-      "type": "object",
-      "required": [
-        "links",
-        "extensions",
-        "title",
-        "domainType",
-        "instanceId",
-        "members"
-      ],
-      "properties": {
-        "links": {
-          "type": "array",
-          "items": {
-            "$ref": "#/definitions/LinkRepresentation"
-          }
-        },
-        "extensions": {
-          "$ref": "#/definitions/ServiceOrObjectExtensionsRepresentation"
-        },
-        "title": {
-          "type": "string"
-        },
-        "domainType": {
-          "type": "string"
-        },
-        "instanceId": {
-          "type": "string"
-        },
-        "members": {
-          "type": "object",
-          "required": [
-            "name",
-            "versionSequence",
-            "downloadJdoMetadata",
-            "updateName"
-          ],
-          "properties": {
-            "name": {
-              "type": "object",
-              "required": [
-                "id",
-                "memberType",
-                "links",
-                "value",
-                "extensions"
-              ],
-              "properties": {
-                "id": {
-                  "type": "string"
-                },
-                "memberType": {
-                  "type": "string",
-                  "default": "property"
-                },
-                "links": {
-                  "type": "array",
-                  "items": {
-                    "$ref": "#/definitions/LinkRepresentation"
-                  }
-                },
-                "value": {
-                  "type": "string"
-                },
-                "disabledReason": {
-                  "type": "string"
-                },
-                "extensions": {
-                  "type": "object"
-                }
-              }
-            },
-            "versionSequence": {
-              "type": "object",
-              "required": [
-                "id",
-                "memberType",
-                "links",
-                "value",
-                "format",
-                "extensions"
-              ],
-              "properties": {
-                "id": {
-                  "type": "string"
-                },
-                "memberType": {
-                  "type": "string",
-                  "default": "property"
-                },
-                "links": {
-                  "type": "array",
-                  "items": {
-                    "$ref": "#/definitions/LinkRepresentation"
-                  }
-                },
-                "value": {
-                  "type": "integer"
-                },
-                "format": {
-                  "type": "string"
-                },
-                "disabledReason": {
-                  "type": "string"
-                },
-                "extensions": {
-                  "type": "object"
-                }
-              }
-            },
-            "downloadJdoMetadata": {
-              "$ref": "#/definitions/ActionRepresentation"
-            },
-            "updateName": {
-              "$ref": "#/definitions/ActionRepresentation"
-            }
-          }
-        }
-      }
-    },
-    "ActionPromptRepresentation": {
-      "type": "object",
-      "required": [
-        "id",
-        "memberType",
-        "links",
-        "extensions",
-        "parameters"
-      ],
-      "properties": {
-        "id": {
-          "type": "string"
-        },
-        "memberType": {
-          "type": "string"
-        },
-        "links": {
-          "type": "array",
-          "items": {
-            "$ref": "#/definitions/LinkRepresentation"
-          }
-        },
-        "extensions": {
-          "type": "object",
-          "required": [
-            "actionType",
-            "actionSemantics"
-          ],
-          "properties": {
-            "actionType": {
-              "type": "string"
-            },
-            "actionSemantics": {
-              "type": "string",
-              "enum": [
-                "safe",
-                "idempotent",
-                "non_idempotent"
-              ]
-            }
-          }
-        },
-        "parameters": {
-          "type": "object",
-          "required": [
-            "name"
-          ],
-          "properties": {
-            "name": {
-              "$ref": "#/definitions/ActionParameterRepresentation"
-            }
-          }
-        }
-      }
-    },
-    "ServiceOrObjectExtensionsRepresentation": {
-      "type": "object",
-      "required": [
-        "oid",
-        "isService",
-        "isPersistent"
-      ],
-      "properties": {
-        "oid": {
-          "type": "string"
-        },
-        "isService": {
-          "type": "boolean"
-        },
-        "isPersistent": {
-          "type": "boolean"
-        }
-      }
-    },
-    "ActionRepresentation": {
-      "type": "object",
-      "required": [
-        "id",
-        "memberType",
-        "links"
-      ],
-      "properties": {
-        "id": {
-          "type": "string"
-        },
-        "memberType": {
-          "type": "string",
-          "default": "action"
-        },
-        "links": {
-          "type": "array",
-          "items": {
-            "$ref": "#/definitions/LinkRepresentation"
-          }
-        }
-      }
-    },
-    "ActionParameterRepresentation": {
-      "type": "object",
-      "required": [
-        "num",
-        "id",
-        "name",
-        "description"
-      ],
-      "properties": {
-        "num": {
-          "type": "integer"
-        },
-        "id": {
-          "type": "string"
-        },
-        "name": {
-          "type": "string"
-        },
-        "description": {
-          "type": "string"
-        }
-      }
-    },
-    "ActionInvocationRepresentationOfList": {
-      "type": "object",
-      "required": [
-        "links",
-        "resulttype",
-        "result"
-      ],
-      "properties": {
-        "links": {
-          "type": "array",
-          "items": {
-            "$ref": "#/definitions/LinkRepresentation"
-          }
-        },
-        "resulttype": {
-          "type": "string",
-          "default": "list"
-        },
-        "result": {
-          "type": "object",
-          "required": [
-            "value",
-            "links",
-            "extensions"
-          ],
-          "properties": {
-            "value": {
-              "type": "array",
-              "items": {
-                "$ref": "#/definitions/LinkRepresentation"
-              }
-            },
-            "links": {
-              "type": "array",
-              "items": {
-                "$ref": "#/definitions/LinkRepresentation"
-              }
-            },
-            "extensions": {
-              "type": "object"
-            }
-          }
-        }
-      }
-    },
-    "LinkRepresentation": {
-      "type": "object",
-      "required": [
-        "rel",
-        "href",
-        "method"
-      ],
-      "properties": {
-        "rel": {
-          "type": "string",
-          "description": "relationship of this Link"
-        },
-        "href": {
-          "type": "string"
-        },
-        "title": {
-          "type": "string"
-        },
-        "method": {
-          "type": "string",
-          "enum": [
-            "GET",
-            "POST",
-            "PUT",
-            "DELETE"
-          ]
-        },
-        "type": {
-          "type": "string"
-        },
-        "arguments": {
-          "type": "object"
-        }
-      }
-    }
-  }
-}
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/3d9f8fe0/example/application/simpleapp/webapp/src/main/webapp/about/index.html
----------------------------------------------------------------------
diff --git a/example/application/simpleapp/webapp/src/main/webapp/about/index.html b/example/application/simpleapp/webapp/src/main/webapp/about/index.html
index 070651a..b14a4b3 100644
--- a/example/application/simpleapp/webapp/src/main/webapp/about/index.html
+++ b/example/application/simpleapp/webapp/src/main/webapp/about/index.html
@@ -81,13 +81,18 @@ th, td {
                 <li>
                     <p>
                         <b>
-                            <a href="restful/">restful/</a>
+                            <a href="swagger-ui/index.html">swagger-ui/</a>
                         </b>
                     </p>
                     <p>
-                        provides access to a RESTful API conformant with the
-                        <a href="http://restfulobjects.org">Restful Objects</a> spec</td>.  This is part of Apache Isis Core.  The
-                        implementation technology is JBoss RestEasy.
+                        provides the Swagger UI access to RESTful API, consuming dynamically generated Swagger
+                        specification files.  There are three versions of this API: <a href="restful/swagger/public">public</a> (third-party) use, for <a href="restful/swagger/private">private</a> (internal) use, and extended version of the private API
+                        that includes <a href="restful/swagger/prototyping">prototyping</a> actions.
+                    </p>
+                    <p>The RESTful API can return both simple representations (suitable for use within custom apps),
+                        and also a richer hypermedia API conformant with the
+                        <a href="http://restfulobjects.org">Restful Objects</a> spec.  The HTTP <code>Accept</code> header
+                        is used to select which representation is required.
                     </p>
                 </li>
             </ul>

http://git-wip-us.apache.org/repos/asf/isis/blob/3d9f8fe0/example/application/simpleapp/webapp/src/main/webapp/api-docs/index.html
----------------------------------------------------------------------
diff --git a/example/application/simpleapp/webapp/src/main/webapp/api-docs/index.html b/example/application/simpleapp/webapp/src/main/webapp/api-docs/index.html
deleted file mode 100644
index 7ecbcb1..0000000
--- a/example/application/simpleapp/webapp/src/main/webapp/api-docs/index.html
+++ /dev/null
@@ -1,122 +0,0 @@
-<!DOCTYPE html>
-<html>
-<head>
-    <meta charset="UTF-8">
-    <base href="../webjars/swagger-ui/2.1.3/"/>
-    <title>Swagger UI</title>
-    <link rel="icon" type="image/png" href="images/favicon-32x32.png" sizes="32x32" />
-    <link rel="icon" type="image/png" href="images/favicon-16x16.png" sizes="16x16" />
-    <link href='css/typography.css' media='screen' rel='stylesheet' type='text/css'/>
-    <link href='css/reset.css' media='screen' rel='stylesheet' type='text/css'/>
-    <link href='css/screen.css' media='screen' rel='stylesheet' type='text/css'/>
-    <link href='css/reset.css' media='print' rel='stylesheet' type='text/css'/>
-    <link href='css/print.css' media='print' rel='stylesheet' type='text/css'/>
-    <script src='lib/jquery-1.8.0.min.js' type='text/javascript'></script>
-    <script src='lib/jquery.slideto.min.js' type='text/javascript'></script>
-    <script src='lib/jquery.wiggle.min.js' type='text/javascript'></script>
-    <script src='lib/jquery.ba-bbq.min.js' type='text/javascript'></script>
-    <script src='lib/handlebars-2.0.0.js' type='text/javascript'></script>
-    <script src='lib/underscore-min.js' type='text/javascript'></script>
-    <script src='lib/backbone-min.js' type='text/javascript'></script>
-    <script src='swagger-ui.js' type='text/javascript'></script>
-    <script src='lib/highlight.7.3.pack.js' type='text/javascript'></script>
-    <script src='lib/marked.js' type='text/javascript'></script>
-    <script src='lib/swagger-oauth.js' type='text/javascript'></script>
-
-    <!-- Some basic translations -->
-    <!-- <script src='lang/translator.js' type='text/javascript'></script> -->
-    <!-- <script src='lang/ru.js' type='text/javascript'></script> -->
-    <!-- <script src='lang/en.js' type='text/javascript'></script> -->
-
-    <script type="text/javascript">
-    $(function () {
-      var url = document.getElementById("input_baseUrl").selectedOptions[0].value;
-
-      // Pre load translate...
-      if(window.SwaggerTranslator) {
-        window.SwaggerTranslator.translate();
-      }
-      window.swaggerUi = new SwaggerUi({
-        url: url,
-        dom_id: "swagger-ui-container",
-        supportedSubmitMethods: ['get', 'post', 'put', 'delete', 'patch'],
-        onComplete: function(swaggerApi, swaggerUi){
-          if(typeof initOAuth == "function") {
-            initOAuth({
-              clientId: "your-client-id",
-              clientSecret: "your-client-secret-if-required",
-              realm: "your-realms",
-              appName: "your-app-name",
-              scopeSeparator: ","
-            });
-          }
-
-          if(window.SwaggerTranslator) {
-            window.SwaggerTranslator.translate();
-          }
-
-          $('pre code').each(function(i, e) {
-            hljs.highlightBlock(e)
-          });
-
-          addApiKeyAuthorization();
-        },
-        onFailure: function(data) {
-          log("Unable to Load SwaggerUI");
-        },
-        docExpansion: "none",
-        apisSorter: "alpha",
-        defaultModelRendering: 'schema',
-        showRequestHeaders: false
-      });
-
-      function addApiKeyAuthorization(){
-        var key = encodeURIComponent($('#input_apiKey')[0].value);
-        if(key && key.trim() != "") {
-            var apiKeyAuth = new SwaggerClient.ApiKeyAuthorization("api_key", key, "query");
-            window.swaggerUi.api.clientAuthorizations.add("api_key", apiKeyAuth);
-            log("added key " + key);
-        }
-      }
-
-      $('#input_apiKey').change(addApiKeyAuthorization);
-
-      // if you have an apiKey you would like to pre-populate on the page for demonstration purposes...
-      /*
-        var apiKey = "myApiKeyXXXX123456789";
-        $('#input_apiKey').val(apiKey);
-      */
-
-      window.swaggerUi.load();
-
-      function log() {
-        if ('console' in window) {
-          console.log.apply(console, arguments);
-        }
-      }
-  });
-  </script>
-</head>
-
-<body class="swagger-section">
-<div id='header'>
-    <div class="swagger-ui-wrap">
-        <a id="logo" href="http://swagger.io">swagger</a>
-        <form id='api_selector'>
-            <div class='input'>
-                <select id="input_baseUrl" name="baseUrl">
-                    <option id="private" label="private" value="/restful/swagger/private"/>
-                    <option id="public" label="public" value="/restful/swagger/public"/>
-                    <option id="prototyping" label="prototyping" value="/restful/swagger/prototyping"/>
-                </select>
-            </div>
-            <div class='input' style="display:none;"><input placeholder="api_key" id="input_apiKey" name="apiKey" type="text"/></div>
-            <div class='input'><a id="explore" href="#" data-sw-translate>Explore</a></div>
-        </form>
-    </div>
-</div>
-
-<div id="message-bar" class="swagger-ui-wrap" data-sw-translate>&nbsp;</div>
-<div id="swagger-ui-container" class="swagger-ui-wrap"></div>
-</body>
-</html>
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/3d9f8fe0/example/application/simpleapp/webapp/src/main/webapp/swagger-ui/index.html
----------------------------------------------------------------------
diff --git a/example/application/simpleapp/webapp/src/main/webapp/swagger-ui/index.html b/example/application/simpleapp/webapp/src/main/webapp/swagger-ui/index.html
new file mode 100644
index 0000000..fc4d3a4
--- /dev/null
+++ b/example/application/simpleapp/webapp/src/main/webapp/swagger-ui/index.html
@@ -0,0 +1,122 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="UTF-8">
+    <base href="../webjars/swagger-ui/2.1.3/"/>
+    <title>Swagger UI</title>
+    <link rel="icon" type="image/png" href="images/favicon-32x32.png" sizes="32x32" />
+    <link rel="icon" type="image/png" href="images/favicon-16x16.png" sizes="16x16" />
+    <link href='css/typography.css' media='screen' rel='stylesheet' type='text/css'/>
+    <link href='css/reset.css' media='screen' rel='stylesheet' type='text/css'/>
+    <link href='css/screen.css' media='screen' rel='stylesheet' type='text/css'/>
+    <link href='css/reset.css' media='print' rel='stylesheet' type='text/css'/>
+    <link href='css/print.css' media='print' rel='stylesheet' type='text/css'/>
+    <script src='lib/jquery-1.8.0.min.js' type='text/javascript'></script>
+    <script src='lib/jquery.slideto.min.js' type='text/javascript'></script>
+    <script src='lib/jquery.wiggle.min.js' type='text/javascript'></script>
+    <script src='lib/jquery.ba-bbq.min.js' type='text/javascript'></script>
+    <script src='lib/handlebars-2.0.0.js' type='text/javascript'></script>
+    <script src='lib/underscore-min.js' type='text/javascript'></script>
+    <script src='lib/backbone-min.js' type='text/javascript'></script>
+    <script src='swagger-ui.js' type='text/javascript'></script>
+    <script src='lib/highlight.7.3.pack.js' type='text/javascript'></script>
+    <script src='lib/marked.js' type='text/javascript'></script>
+    <script src='lib/swagger-oauth.js' type='text/javascript'></script>
+
+    <!-- Some basic translations -->
+    <!-- <script src='lang/translator.js' type='text/javascript'></script> -->
+    <!-- <script src='lang/ru.js' type='text/javascript'></script> -->
+    <!-- <script src='lang/en.js' type='text/javascript'></script> -->
+
+    <script type="text/javascript">
+    $(function () {
+      var url = document.getElementById("input_baseUrl").selectedOptions[0].value;
+
+      // Pre load translate...
+      if(window.SwaggerTranslator) {
+        window.SwaggerTranslator.translate();
+      }
+      window.swaggerUi = new SwaggerUi({
+        url: url,
+        dom_id: "swagger-ui-container",
+        supportedSubmitMethods: ['get', 'post', 'put', 'delete', 'patch'],
+        onComplete: function(swaggerApi, swaggerUi){
+          if(typeof initOAuth == "function") {
+            initOAuth({
+              clientId: "your-client-id",
+              clientSecret: "your-client-secret-if-required",
+              realm: "your-realms",
+              appName: "your-app-name",
+              scopeSeparator: ","
+            });
+          }
+
+          if(window.SwaggerTranslator) {
+            window.SwaggerTranslator.translate();
+          }
+
+          $('pre code').each(function(i, e) {
+            hljs.highlightBlock(e)
+          });
+
+          addApiKeyAuthorization();
+        },
+        onFailure: function(data) {
+          log("Unable to Load SwaggerUI");
+        },
+        docExpansion: "none",
+        apisSorter: "alpha",
+        defaultModelRendering: 'schema',
+        showRequestHeaders: false
+      });
+
+      function addApiKeyAuthorization(){
+        var key = encodeURIComponent($('#input_apiKey')[0].value);
+        if(key && key.trim() != "") {
+            var apiKeyAuth = new SwaggerClient.ApiKeyAuthorization("api_key", key, "query");
+            window.swaggerUi.api.clientAuthorizations.add("api_key", apiKeyAuth);
+            log("added key " + key);
+        }
+      }
+
+      $('#input_apiKey').change(addApiKeyAuthorization);
+
+      // if you have an apiKey you would like to pre-populate on the page for demonstration purposes...
+      /*
+        var apiKey = "myApiKeyXXXX123456789";
+        $('#input_apiKey').val(apiKey);
+      */
+
+      window.swaggerUi.load();
+
+      function log() {
+        if ('console' in window) {
+          console.log.apply(console, arguments);
+        }
+      }
+  });
+  </script>
+</head>
+
+<body class="swagger-section">
+<div id='header'>
+    <div class="swagger-ui-wrap">
+        <a id="logo" href="http://swagger.io">swagger</a>
+        <form id='api_selector'>
+            <div class='input'>
+                <select id="input_baseUrl" name="baseUrl">
+                    <option id="private" label="private" value="/restful/swagger/private"/>
+                    <option id="public" label="public" value="/restful/swagger/public"/>
+                    <option id="prototyping" label="prototyping" value="/restful/swagger/prototyping"/>
+                </select>
+            </div>
+            <div class='input' style="display:none;"><input placeholder="api_key" id="input_apiKey" name="apiKey" type="text"/></div>
+            <div class='input'><a id="explore" href="#" data-sw-translate>Reload</a></div>
+        </form>
+    </div>
+</div>
+
+<div id="message-bar" class="swagger-ui-wrap" data-sw-translate>&nbsp;</div>
+<div id="swagger-ui-container" class="swagger-ui-wrap"></div>
+</body>
+</html>
\ No newline at end of file


[27/52] [abbrv] isis git commit: ISIS-1243: fixing links to fundamentals guide; updating asciidoc live templates; updating contributors guide that documents the asciidoc live templates

Posted by mg...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_ugtst_integ-test-support_bootstrapping.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugtst_integ-test-support_bootstrapping.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugtst_integ-test-support_bootstrapping.adoc
index ffa31ef..18d8b70 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugtst_integ-test-support_bootstrapping.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugtst_integ-test-support_bootstrapping.adoc
@@ -11,7 +11,7 @@ Nevertheless, we do need to bootstrap the runtime for the very first test.
 
 As of 1.9.0 the bootstrapping of integration tests and webapps has been simplified through the xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`] class.  Since this isn't mandatory, for now we present both techniques.
 
-The example code in this section is taken from the app generated by the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
+The example code in this section is taken from the app generated by the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_ugtst_integ-test-support_maven-configuration.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugtst_integ-test-support_maven-configuration.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugtst_integ-test-support_maven-configuration.adoc
index 587fe92..3f15828 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugtst_integ-test-support_maven-configuration.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugtst_integ-test-support_maven-configuration.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-Apache Isis' integration test support is automatically configured if you use the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].  To set it up manually, update the `pom.xml` of your domain object model module:
+Apache Isis' integration test support is automatically configured if you use the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].  To set it up manually, update the `pom.xml` of your domain object model module:
 
 [source,xml]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_ugtst_unit-test-support_contract-tests.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugtst_unit-test-support_contract-tests.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugtst_unit-test-support_contract-tests.adoc
index 6171c86..0073431 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugtst_unit-test-support_contract-tests.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugtst_unit-test-support_contract-tests.adoc
@@ -64,11 +64,11 @@ public class SortedSetsContractTestAll extends SortedSetsContractTestAbstract {
 
 == Bidirectional
 
-This contract test automatically checks that bidirectional 1:m or 1:1 associations are being maintained correctly (assuming that they follow the xref:ug.adoc#_ugfun_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships[mutual registration pattern]
+This contract test automatically checks that bidirectional 1:m or 1:1 associations are being maintained correctly (assuming that they follow the xref:ugfun.adoc#_ugfun_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships[mutual registration pattern]
 
 [TIP]
 ====
-(If using the JDO objectstore, then) there is generally no need to programmatically maintain 1:m relationships (indeed it may introduce subtle errors). For more details, see xref:ug.adoc#_ugfun_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships[here].  Also check out the xref:cg.adoc#_cg_ide-templates[IDE templates] for further guidance.
+(If using the JDO objectstore, then) there is generally no need to programmatically maintain 1:m relationships (indeed it may introduce subtle errors). For more details, see xref:ugfun.adoc#_ugfun_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships[here].  Also check out the xref:cg.adoc#_cg_ide-templates[IDE templates] for further guidance.
 ====
 
 For example, suppose that `ParentDomainObject` and `ChildDomainObject` have a 1:m relationship (`ParentDomainObject#children` / `ChildDomainObject#parent`), and also `PeerDomainObject` has a 1:1 relationship with itself (`PeerDomainObject#next` / `PeerDomainObject#previous`).

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_ugtst_unit-test-support_maven-configuration.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugtst_unit-test-support_maven-configuration.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugtst_unit-test-support_maven-configuration.adoc
index 9fa4881..36af192 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugtst_unit-test-support_maven-configuration.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugtst_unit-test-support_maven-configuration.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-Apache Isis' unit test support is automatically configured if you use the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].  To set it up manually, update the `pom.xml` of your domain object model module:
+Apache Isis' unit test support is automatically configured if you use the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].  To set it up manually, update the `pom.xml` of your domain object model module:
 
 [source,xml]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_ugvw_customisation_about-page.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugvw_customisation_about-page.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugvw_customisation_about-page.adoc
index 8a6426f..e1f394b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugvw_customisation_about-page.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugvw_customisation_about-page.adoc
@@ -31,7 +31,7 @@ If none of these are found, then no version is displayed.
 
 [TIP]
 ====
-This configuration is included within the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
+This configuration is included within the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
 ====
 
 === Adding attributes to the WAR's manifest

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_ugvw_customisation_tweaking-css-classes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugvw_customisation_tweaking-css-classes.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugvw_customisation_tweaking-css-classes.adoc
index 5e1d869..5bd0d8f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugvw_customisation_tweaking-css-classes.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugvw_customisation_tweaking-css-classes.adoc
@@ -92,7 +92,7 @@ div.x-myapp-highlight span.scalarName {
 }
 ----
 
-Note also that instead of using `@PropertyLayout(cssClass=...)` annotation, you can also specify the CSS style using a xref:ug.adoc#_ugfun_object-layout_dynamic[dynamic layout] JSON file:
+Note also that instead of using `@PropertyLayout(cssClass=...)` annotation, you can also specify the CSS style using a xref:ugfun.adoc#_ugfun_object-layout_dynamic[dynamic layout] JSON file:
 
 [source,javascript]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/_ugvw_layout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugvw_layout.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugvw_layout.adoc
index 322e045..bc2a1ea 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugvw_layout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugvw_layout.adoc
@@ -6,7 +6,7 @@
 
 
 
-The wicket viewer has full support for the various methods of specifying the xref:ug.adoc#_ugfun_object-layout[layout of objects], either statically or dynamically.
+The wicket viewer has full support for the various methods of specifying the xref:ugfun.adoc#_ugfun_object-layout[layout of objects], either statically or dynamically.
 
 Dynamic reloading is automatically supported when running in xref:rgcfg.adoc#_rgcfg_deployment-types[prototype (development) mode], the Wicket viewer automatically rebuilds the metamodel for each class as it is rendered.    Conversely, do note that the Wicket viewer will *not* pick up new metadata if running in production/server mode.
 
@@ -46,7 +46,7 @@ And finally, from the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Is
 image::{_imagesdir}wicket-viewer/layouts/todoapp-ToDoItem.png[width="800px",link="{_imagesdir}wicket-viewer/layouts/todoapp-ToDoItem.png"]
 
 
-To learn more about how to configure these types of layout, see the xref:ug.adoc#_ugfun_object-layout[object layout] chapter.
+To learn more about how to configure these types of layout, see the xref:ugfun.adoc#_ugfun_object-layout[object layout] chapter.
 
 
 
@@ -92,6 +92,6 @@ Therefore, make sure the following is added to the dom project's `pom.xml`:
 </resources>
 ----
 
-If using an Apache Isis xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype], then the POM is already correctly configured.
+If using an Apache Isis xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype], then the POM is already correctly configured.
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/cg.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/cg.adoc b/adocs/documentation/src/main/asciidoc/guides/cg.adoc
index 9da1818..b294bab 100644
--- a/adocs/documentation/src/main/asciidoc/guides/cg.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/cg.adoc
@@ -39,7 +39,7 @@ The reference guides are:
 * xref:rgant.adoc#[Annotations]
 * xref:rgsvc.adoc#[Domain Services]
 * xref:rgcfg.adoc#[Configuration Properties]
-* xref:rg.adoc#[Classes, Methods and Schema]
+* xref:rgcms.adoc#[Classes, Methods and Schema]
 
 In addition, there is (this) xref:cg.adoc#_cg[Contributors' Guide] describing development practices for contributors and committers alike.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/rg.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rg.adoc b/adocs/documentation/src/main/asciidoc/guides/rg.adoc
index 4711809..8197779 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rg.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rg.adoc
@@ -22,6 +22,6 @@ The reference guides are:
 * xref:rgant.adoc#[Annotations]
 * xref:rgsvc.adoc#[Domain Services]
 * xref:rgcfg.adoc#[Configuration Properties]
-* xref:rg.adoc#[Classes, Methods and Schema]
+* xref:rgcms.adoc#[Classes, Methods and Schema]
 
 In addition, there is a xref:cg.adoc#_cg[Contributors' Guide] describing development practices for contributors and committers alike.

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/rgant.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant.adoc
index 491e973..e0259b1 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant.adoc
@@ -3,6 +3,7 @@
 :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/
+:numbered:
 
 
 [[_rgant]]
@@ -30,7 +31,7 @@ The reference guides are:
 * xref:rgant.adoc#[Annotations]
 * xref:rgsvc.adoc#[Domain Services]
 * xref:rgcfg.adoc#[Configuration Properties]
-* xref:rg.adoc#[Classes, Methods and Schema]
+* xref:rgcms.adoc#[Classes, Methods and Schema]
 
 In addition, there is a xref:cg.adoc#_cg[Contributors' Guide] describing development practices for contributors and committers alike.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/rgcfg.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcfg.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcfg.adoc
index d064cce..09ab94e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcfg.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcfg.adoc
@@ -3,6 +3,7 @@
 :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/
+:numbered:
 
 
 [[_rgcfg]]
@@ -11,6 +12,17 @@
 Apache Isis' own configuration properties are simple key-value pairs, typically held in the `WEBINF/isis.properties`
 file and other related files. This guide describes how to configure an Apache Isis application.
 
+[NOTE]
+====
+Configuration properties for the viewers can be found in the xref:ugvw.adoc#[Wicket Viewer] guide
+and the xref:ugvro.adoc#[RestfulObjects viewer] guide.  Likewise[details of configuring security (Apache Shiro) can be
+found in the xref:ugsec.adoc#[Security] guide.
+
+Also, note that by default the configuration values are part of the built WAR file.  Details on how to override these
+configuration properties externally for different environments can be found in the
+xref:ugbtb.adoc#_ugbtb_deployment[Beyond the Basics] guide, (deployment chapter).
+====
+
 === Other Guides
 
 Apache Isis documentation is broken out into a number of user and reference guides.
@@ -28,20 +40,12 @@ The reference guides are:
 
 * xref:rgant.adoc#[Annotations]
 * xref:rgsvc.adoc#[Domain Services]
-* xref:rgcfg.adoc#[Configuration Properties]
-* xref:rg.adoc#[Classes, Methods and Schema]
+* xref:rgcfg.adoc#[Configuration Properties] (this guide)
+* xref:rgcms.adoc#[Classes, Methods and Schema]
 
 In addition, there is a xref:cg.adoc#_cg[Contributors' Guide] describing development practices for contributors and committers alike.
 
 
-[NOTE]
-====
-Configuration properties for the viewers can be found in the xref:ugvw.adoc#[Wicket Viewer] guide and the xref:ugvro.adoc#[RestfulObjects viewer] guide.  Likewise[details of configuring security (Apache Shiro) can be found in the xref:ugsec.adoc#[Security] guide.
-
-Also, note that by default the configuration values are part of the built WAR file.  Details on how to override these
-configuration properties externally for different environments can be found in the
-xref:ugbtb.adoc#_ugbtb_deployment[Beyond the Basics] guide, (deployment chapter).
-====
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/rgcms.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms.adoc
index b6dcc5e..750cfa4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms.adoc
@@ -1,4 +1,4 @@
-[[rg]]
+[[rgcms]]
 = Classes, Methods and Schema
 :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: ../
@@ -6,7 +6,7 @@
 :numbered:
 
 
-[[_rg]]
+[[_rgcms]]
 = Classes, Methods and Schema
 
 This reference guide lists and describes various elements of the the Apache Isis Programming Model, specifically
@@ -34,7 +34,7 @@ The reference guides are:
 * xref:rgant.adoc#[Annotations]
 * xref:rgsvc.adoc#[Domain Services]
 * xref:rgcfg.adoc#[Configuration Properties]
-* xref:rg.adoc#[Classes, Methods and Schema] (this guide)
+* xref:rgcms.adoc#[Classes, Methods and Schema] (this guide)
 
 In addition, there is a xref:cg.adoc#_cg[Contributors' Guide] describing development practices for contributors and committers alike.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/rgsvc.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc.adoc
index a141126..5feb1fd 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc.adoc
@@ -3,6 +3,7 @@
 :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/
+:numbered:
 
 
 [[_rgsvc]]
@@ -30,7 +31,7 @@ The reference guides are:
 * xref:rgant.adoc#[Annotations]
 * xref:rgsvc.adoc#[Domain Services] (this guide)
 * xref:rgcfg.adoc#[Configuration Properties]
-* xref:rg.adoc#[Classes, Methods and Schema]
+* xref:rgcms.adoc#[Classes, Methods and Schema]
 
 In addition, there is a xref:cg.adoc#_cg[Contributors' Guide] describing development practices for contributors and committers alike.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/tg.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/tg.adoc b/adocs/documentation/src/main/asciidoc/guides/tg.adoc
index 8856b4c..624a352 100644
--- a/adocs/documentation/src/main/asciidoc/guides/tg.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/tg.adoc
@@ -3,6 +3,7 @@
 :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/
+:numbered:
 
 
 [[_tg]]

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/ug.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ug.adoc b/adocs/documentation/src/main/asciidoc/guides/ug.adoc
index c34ef34..90ddfb3 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ug.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ug.adoc
@@ -22,6 +22,6 @@ The reference guides are:
 * xref:rgant.adoc#[Annotations]
 * xref:rgsvc.adoc#[Domain Services]
 * xref:rgcfg.adoc#[Configuration Properties]
-* xref:rg.adoc#[Classes, Methods and Schema]
+* xref:rgcms.adoc#[Classes, Methods and Schema]
 
 In addition, there is a xref:cg.adoc#_cg[Contributors' Guide] describing development practices for contributors and committers alike.

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/ugbtb.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb.adoc
index 7001a58..a7ba529 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb.adoc
@@ -32,7 +32,7 @@ The reference guides are:
 * xref:rgant.adoc#[Annotations]
 * xref:rgsvc.adoc#[Domain Services]
 * xref:rgcfg.adoc#[Configuration Properties]
-* xref:rg.adoc#[Classes, Methods and Schema]
+* xref:rgcms.adoc#[Classes, Methods and Schema]
 
 In addition, there is a xref:cg.adoc#_cg[Contributors' Guide] describing development practices for contributors and committers alike.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/ugfun.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun.adoc
index 00abbf2..ddda6ff 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun.adoc
@@ -9,12 +9,12 @@
 [[_ugfun]]
 == Fundamentals
 
-This guide introduces the xref:ug.adoc#_ugfun_core-concepts[core concepts] and ideas behind Apache Isis,
-and tells you how to xref:ug.adoc#_ugfun_getting-started[get started] with a Maven archetype.
+This guide introduces the xref:ugfun.adoc#_ugfun_core-concepts[core concepts] and ideas behind Apache Isis,
+and tells you how to xref:ugfun.adoc#_ugfun_getting-started[get started] with a Maven archetype.
 
-It also describes a number of xref:ug.adoc#_ugfun_how-tos[how-to]s, describes how to influence the
-xref:ug.adoc#_ugfun_object-layout[UI layout] of your domain objects (this is ultimately just a type of metadata), and it
- catalogues various xref:ug.adoc#_ugfun_faqs.adoc[FAQ]s.
+It also describes a number of xref:ugfun.adoc#_ugfun_how-tos[how-to]s, describes how to influence the
+xref:ugfun.adoc#_ugfun_object-layout[UI layout] of your domain objects (this is ultimately just a type of metadata), and it
+ catalogues various xref:ugfun.adoc#_ugfun_faqs.adoc[FAQ]s.
 
 === Other Guides
 
@@ -34,7 +34,7 @@ The reference guides are:
 * xref:rgant.adoc#[Annotations]
 * xref:rgsvc.adoc#[Domain Services]
 * xref:rgcfg.adoc#[Configuration Properties]
-* xref:rg.adoc#[Classes, Methods and Schema]
+* xref:rgcms.adoc#[Classes, Methods and Schema]
 
 In addition, there is a xref:cg.adoc#_cg[Contributors' Guide] describing development practices for contributors and committers alike.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/ugsec.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugsec.adoc b/adocs/documentation/src/main/asciidoc/guides/ugsec.adoc
index 34f9de3..2038eff 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugsec.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugsec.adoc
@@ -3,6 +3,7 @@
 :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/
+:numbered:
 
 
 [[_ugsec]]
@@ -29,7 +30,7 @@ The reference guides are:
 * xref:rgant.adoc#[Annotations]
 * xref:rgsvc.adoc#[Domain Services]
 * xref:rgcfg.adoc#[Configuration Properties]
-* xref:rg.adoc#[Classes, Methods and Schema]
+* xref:rgcms.adoc#[Classes, Methods and Schema]
 
 In addition, there is a xref:cg.adoc#_cg[Contributors' Guide] describing development practices for contributors and committers alike.
 
@@ -46,7 +47,7 @@ Isis has two levels of permissions.  _Read_ permission means that the user can v
 
 Isis provides an API for both authentication and authorization, and provides an implementation that integrates with link:http://shiro.apache.org[Apache Shiro].  Shiro in turn uses the concept of a _realm_ as a source for both authentication and optionally authorization.
 
-Shiro ships with a simple text-based realm -- the `IniRealm` -- which reads users (and password), user roles and role permissions from the `WEB-INF/shiro.ini` file.  The xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] is configured to use this realm.
+Shiro ships with a simple text-based realm -- the `IniRealm` -- which reads users (and password), user roles and role permissions from the `WEB-INF/shiro.ini` file.  The xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] is configured to use this realm.
 
 Shiro also ships with an implementation of an LDAP-based realm; LDAP is often used to manage user/passwords and corresponding user groups.  Apache Isis in turn extends this with its `IsisLdapRealm`, which provides more flexibility for both group/role and role/permissions management.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/ugtst.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugtst.adoc b/adocs/documentation/src/main/asciidoc/guides/ugtst.adoc
index 1997486..c558cc2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugtst.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugtst.adoc
@@ -3,6 +3,7 @@
 :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/
+:numbered:
 
 
 
@@ -34,7 +35,7 @@ The reference guides are:
 * xref:rgant.adoc#[Annotations]
 * xref:rgsvc.adoc#[Domain Services]
 * xref:rgcfg.adoc#[Configuration Properties]
-* xref:rg.adoc#[Classes, Methods and Schema]
+* xref:rgcms.adoc#[Classes, Methods and Schema]
 
 In addition, there is a xref:cg.adoc#_cg[Contributors' Guide] describing development practices for contributors and committers alike.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/ugvro.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvro.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvro.adoc
index 2dbdd6c..95ee4b7 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvro.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvro.adoc
@@ -3,6 +3,7 @@
 :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/
+:numbered:
 
 
 
@@ -12,6 +13,7 @@
 Apache Isis' Restful Objects viewer is an implementation of the link:http://restfulobjects.org[Restful Objects spec],
 which defines a generic way to expose a domain model through a REST (or more precisely, hypermedia) API.
 
+It also provides a number of extensions specific to Apache Isis.  Most significant of these is
 This user guide discuss features, configuration and how to extend the Restful Objects viewer.
 
 === Other Guides
@@ -32,7 +34,7 @@ The reference guides are:
 * xref:rgant.adoc#[Annotations]
 * xref:rgsvc.adoc#[Domain Services]
 * xref:rgcfg.adoc#[Configuration Properties]
-* xref:rg.adoc#[Classes, Methods and Schema]
+* xref:rgcms.adoc#[Classes, Methods and Schema]
 
 In addition, there is a xref:cg.adoc#_cg[Contributors' Guide] describing development practices for contributors and committers alike.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/guides/ugvw.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw.adoc
index bfe7b43..29add35 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw.adoc
@@ -36,7 +36,7 @@ The reference guides are:
 * xref:rgant.adoc#[Annotations]
 * xref:rgsvc.adoc#[Domain Services]
 * xref:rgcfg.adoc#[Configuration Properties]
-* xref:rg.adoc#[Classes, Methods and Schema]
+* xref:rgcms.adoc#[Classes, Methods and Schema]
 
 In addition, there is a xref:cg.adoc#_cg[Contributors' Guide] describing development practices for contributors and committers alike.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f6f60c70/adocs/documentation/src/main/asciidoc/resources/templates/isis-asciidoc-templates-idea.xml
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/resources/templates/isis-asciidoc-templates-idea.xml b/adocs/documentation/src/main/asciidoc/resources/templates/isis-asciidoc-templates-idea.xml
index 2c0e28b..5b65582 100644
--- a/adocs/documentation/src/main/asciidoc/resources/templates/isis-asciidoc-templates-idea.xml
+++ b/adocs/documentation/src/main/asciidoc/resources/templates/isis-asciidoc-templates-idea.xml
@@ -102,7 +102,7 @@
       <option name="AsciiDoc" value="true" />
     </context>
   </template>
-  <template name="adlinkaddonsapp" value="(non-ASF) http://github.com/isisaddons/isis-app-$APP$[Isis addons' $APP$]" description="Link to specific Isis Addons app" toReformat="false" toShortenFQNames="true" deactivated="true">
+  <template name="adlinkaddonsapp" value="(non-ASF) http://github.com/isisaddons/isis-app-$APP$[Isis addons' $APP$]" description="Link to specific Isis Addons app" toReformat="false" toShortenFQNames="true">
     <variable name="APP" expression="" defaultValue="" alwaysStopAt="true" />
     <context>
       <option name="AsciiDoc" value="true" />
@@ -167,50 +167,43 @@
       <option name="AsciiDoc" value="true" />
     </context>
   </template>
-  <template name="adrgmp" value="xref:rg.adoc#_rg_methods_prefixes_manpage-$methodName$[`$methodName$...()`]" description="x-ref to ref guide manpage for method prefix" toReformat="false" toShortenFQNames="true">
+  <template name="adrgmp" value="xref:rgcsm.adoc#_rgcsm_methods_prefixes_$methodName$[`$methodName$...()`]" description="x-ref to ref guide manpage for method prefix" toReformat="false" toShortenFQNames="true">
     <variable name="methodName" expression="" defaultValue="" alwaysStopAt="true" />
     <context>
       <option name="AsciiDoc" value="true" />
     </context>
   </template>
-  <template name="adug1" value="xref:ug.adoc#$chapter$[$DisplayText$]" description="x-ref to user guide level 1 (chapter)" toReformat="false" toShortenFQNames="true">
-    <variable name="chapter" expression="" defaultValue="_ug_" alwaysStopAt="true" />
-    <variable name="DisplayText" expression="" defaultValue="" alwaysStopAt="true" />
-    <context>
-      <option name="AsciiDoc" value="true" />
-    </context>
-  </template>
-  <template name="adrgsa" value="xref:rg.adoc#_rg_services-api_manpage-$ServiceType$[`$ServiceType$`]" description="x-ref to ref guide manpage for service api" toReformat="false" toShortenFQNames="true">
+  <template name="adrgsa" value="xref:rgsvc.adoc#_rgsvc_api_$ServiceType$[`$ServiceType$`]" description="x-ref to ref guide manpage for service api" toReformat="false" toShortenFQNames="true">
     <variable name="ServiceType" expression="" defaultValue="" alwaysStopAt="true" />
     <context>
       <option name="AsciiDoc" value="true" />
     </context>
   </template>
-  <template name="adrgmr" value="xref:rg.adoc#_rg_methods_reserved_manpage-$methodName$[`$methodName$()`]" description="x-ref to ref guide manpage for reserved method" toReformat="false" toShortenFQNames="true">
+  <template name="adrgmr" value="xref:rgcsm.adoc#_rgcsm_methods_reserved_$methodName$[`$methodName$()`]" description="x-ref to ref guide manpage for reserved method" toReformat="false" toShortenFQNames="true">
     <variable name="methodName" expression="" defaultValue="" alwaysStopAt="true" />
     <context>
       <option name="AsciiDoc" value="true" />
     </context>
   </template>
-  <template name="adrgss" value="xref:rg.adoc#_rg_services-spi_manpage-$ServiceType$[`$ServiceType$`]" description="x-ref to ref guide manpage for service spi" toReformat="false" toShortenFQNames="true">
+  <template name="adrgss" value="xref:rgsvc.adoc#_rgsvc-spi_$ServiceType$[`$ServiceType$`]" description="x-ref to ref guide manpage for service spi" toReformat="false" toShortenFQNames="true">
     <variable name="ServiceType" expression="" defaultValue="" alwaysStopAt="true" />
     <context>
       <option name="AsciiDoc" value="true" />
     </context>
   </template>
-  <template name="adrgcv" value="xref:rg.adoc#_rg_classes_value-types_manpage-$Type$[`$Type$`]" description="x-ref to ref guide manpage for class value type" toReformat="false" toShortenFQNames="true">
+  <template name="adrgcv" value="xref:rgcsm.adoc#_rgcsm_classes_value-types_$Type$[`$Type$`]" description="x-ref to ref guide manpage for class value type" toReformat="false" toShortenFQNames="true">
     <variable name="Type" expression="" defaultValue="" alwaysStopAt="true" />
     <context>
       <option name="AsciiDoc" value="true" />
     </context>
   </template>
-  <template name="adrgcs" value="xref:rg.adoc#_rg_classes_super_manpage-$Type$[`$Type$`]" description="x-ref to ref guide manpage for class superclass" toReformat="false" toShortenFQNames="true">
+  <template name="adrgcs" value="xref:rgcsm.adoc#_rgcsm_classes_super_$Type$[`$Type$`]" description="x-ref to ref guide manpage for class superclass" toReformat="false" toShortenFQNames="true">
     <variable name="Type" expression="" defaultValue="" alwaysStopAt="true" />
     <context>
       <option name="AsciiDoc" value="true" />
     </context>
   </template>
-  <template name="adrgcu" value="xref:rg.adoc#_rg_classes_utility_manpage-$Type$[`$Type$`]" description="x-ref to ref guide manpage for class utility" toReformat="false" toShortenFQNames="true">
+  <template name="adrgcu" value="xref:rgcsm.adoc#_rgcsm_classes_utility_$Type$[`$Type$`]" description="x-ref to ref guide manpage for class utility" toReformat="false" toShortenFQNames="true">
     <variable name="Type" expression="" defaultValue="" alwaysStopAt="true" />
     <context>
       <option name="AsciiDoc" value="true" />
@@ -222,29 +215,12 @@
       <option name="AsciiDoc" value="true" />
     </context>
   </template>
-  <template name="adrgna" value="xref:rg.adoc#_rg_annotations_manpage-$Type$[`@$Type$`]" description="x-ref to ref guide manpage for annotation" toReformat="false" toShortenFQNames="true">
+  <template name="adrgna" value="xref:rgant.adoc#_rgant_$Type$[`@$Type$`]" description="x-ref to ref guide manpage for annotation" toReformat="false" toShortenFQNames="true">
     <variable name="Type" expression="" defaultValue="" alwaysStopAt="true" />
     <context>
       <option name="AsciiDoc" value="true" />
     </context>
   </template>
-  <template name="adug2" value="xref:ug.adoc#$chapter$_$section$[$DisplayText$]" description="x-ref to user guide level 2 (chapter section)" toReformat="false" toShortenFQNames="true">
-    <variable name="chapter" expression="" defaultValue="_ug_" alwaysStopAt="true" />
-    <variable name="section" expression="" defaultValue="" alwaysStopAt="true" />
-    <variable name="DisplayText" expression="" defaultValue="" alwaysStopAt="true" />
-    <context>
-      <option name="AsciiDoc" value="true" />
-    </context>
-  </template>
-  <template name="adug3" value="xref:ug.adoc#$chapter$_$section$_$subsection$[$DisplayText$]" description="x-ref to user guide level 3 (chapter section subsection)" toReformat="false" toShortenFQNames="true">
-    <variable name="chapter" expression="" defaultValue="_ug_" alwaysStopAt="true" />
-    <variable name="section" expression="" defaultValue="" alwaysStopAt="true" />
-    <variable name="subsection" expression="" defaultValue="" alwaysStopAt="true" />
-    <variable name="DisplayText" expression="" defaultValue="" alwaysStopAt="true" />
-    <context>
-      <option name="AsciiDoc" value="true" />
-    </context>
-  </template>
   <template name="adxrefany" value="xref:$chapter$[$DisplayText$]" description="x-ref to any" toReformat="false" toShortenFQNames="true">
     <variable name="chapter" expression="" defaultValue="" alwaysStopAt="true" />
     <variable name="DisplayText" expression="" defaultValue="" alwaysStopAt="true" />
@@ -252,24 +228,21 @@
       <option name="AsciiDoc" value="true" />
     </context>
   </template>
-  <template name="adrgnt" value="xref:rg.adoc#_rg_annotations_manpage-$Type$_$attribute$[`@$Type$#$attribute$()`]" description="x-ref to ref guide manpage for annotation's attribute" toReformat="false" toShortenFQNames="true">
+  <template name="adrgnt" value="xref:rgant.adoc#_rgant_$Type$_$attribute$[`@$Type$#$attribute$()`]" description="x-ref to ref guide manpage for annotation's attribute" toReformat="false" toShortenFQNames="true">
     <variable name="Type" expression="" defaultValue="" alwaysStopAt="true" />
     <variable name="attribute" expression="" defaultValue="" alwaysStopAt="true" />
     <context>
       <option name="AsciiDoc" value="true" />
     </context>
   </template>
-  <template name="adugvw" value="xref:ug.adoc#_ug_wicket-viewer[Wicket viewer]" description="x-ref to user guide wicket viewer" toReformat="false" toShortenFQNames="true">
-    <context>
-      <option name="AsciiDoc" value="true" />
-    </context>
-  </template>
-  <template name="adugvro" value="xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer]" description="x-ref to user guide restfulobjects viewer" toReformat="false" toShortenFQNames="true">
+  <template name="adugvw" value="xref:ugvw.adoc#$bookmark$[$DisplayText$]" description="x-ref to user guide wicket viewer" toReformat="false" toShortenFQNames="true">
+    <variable name="bookmark" expression="" defaultValue="" alwaysStopAt="true" />
+    <variable name="DisplayText" expression="" defaultValue="Wicket viewer" alwaysStopAt="true" />
     <context>
       <option name="AsciiDoc" value="true" />
     </context>
   </template>
-  <template name="adrgntx" value="xref:rg.adoc#_rg_annotations_manpage-$Type$_$attribute$[$linkText$]" description="x-ref to ref guide manpage for annotation's attribute, overriding the link text" toReformat="false" toShortenFQNames="true">
+  <template name="adrgntx" value="xref:rgant.adoc#_rgant_$Type$_$attribute$[$linkText$]" description="x-ref to ref guide manpage for annotation's attribute, overriding the link text" toReformat="false" toShortenFQNames="true">
     <variable name="Type" expression="" defaultValue="" alwaysStopAt="true" />
     <variable name="attribute" expression="" defaultValue="" alwaysStopAt="true" />
     <variable name="linkText" expression="" defaultValue="" alwaysStopAt="true" />
@@ -291,73 +264,63 @@
       <option name="AsciiDoc" value="true" />
     </context>
   </template>
-  <template name="adrg1" value="xref:rg.adoc#$chapter$[$DisplayText$]" description="x-ref to ref guide level 1 (chapter)" toReformat="false" toShortenFQNames="true">
-    <variable name="chapter" expression="" defaultValue="_rg_" alwaysStopAt="true" />
-    <variable name="DisplayText" expression="" defaultValue="" alwaysStopAt="true" />
-    <context>
-      <option name="AsciiDoc" value="true" />
-    </context>
-  </template>
-  <template name="adrg2" value="xref:rg.adoc#$chapter$_$section$[$DisplayText$]" description="x-ref to ref guide level 2 (chapter section)" toReformat="false" toShortenFQNames="true">
-    <variable name="chapter" expression="" defaultValue="_rg_" alwaysStopAt="true" />
-    <variable name="section" expression="" defaultValue="" alwaysStopAt="true" />
-    <variable name="DisplayText" expression="" defaultValue="" alwaysStopAt="true" />
-    <context>
-      <option name="AsciiDoc" value="true" />
-    </context>
-  </template>
-  <template name="adrg3" value="xref:rg.adoc#$chapter$_$section$_$subsection$[$DisplayText$]" description="x-ref to ref guide level 3 (chapter section subsection)" toReformat="false" toShortenFQNames="true">
-    <variable name="chapter" expression="" defaultValue="_rg_" alwaysStopAt="true" />
-    <variable name="section" expression="" defaultValue="" alwaysStopAt="true" />
-    <variable name="subsection" expression="" defaultValue="" alwaysStopAt="true" />
-    <variable name="DisplayText" expression="" defaultValue="" alwaysStopAt="true" />
+  <template name="adrgcfg" value="xref:rgcfg.adoc#$bookmark$[$DisplayText$]" description="x-ref to ref guide configuration properties guide" toReformat="false" toShortenFQNames="true">
+    <variable name="bookmark" expression="" defaultValue="" alwaysStopAt="true" />
+    <variable name="DisplayText" expression="" defaultValue="Configuration Properties guide" alwaysStopAt="true" />
     <context>
       <option name="AsciiDoc" value="true" />
     </context>
   </template>
-  <template name="adrgcfg" value="xref:rg.adoc#_rg_runtime_configuring-core[configuration property]" description="x-ref to ref guide configuration properties section" toReformat="false" toShortenFQNames="true">
+  <template name="adrgsvc" value="xref:rgsvc.adoc#$bookmark$[$DisplayText$]" description="xref to domain services guide" toReformat="false" toShortenFQNames="true">
+    <variable name="bookmark" expression="" defaultValue="" alwaysStopAt="true" />
+    <variable name="DisplayText" expression="" defaultValue="Domain Services guide" alwaysStopAt="true" />
     <context>
       <option name="AsciiDoc" value="true" />
     </context>
   </template>
-  <template name="adcg" value="xref:cg.adoc#_cg[Contributors' Guide]" description="xref to contributors guide" toReformat="false" toShortenFQNames="true">
+  <template name="adugfun" value="xref:ugfun.adoc#$bookmark$[$DisplayText$]" description="xref to fundamentals guide" toReformat="false" toShortenFQNames="true">
+    <variable name="bookmark" expression="" defaultValue="" alwaysStopAt="true" />
+    <variable name="DisplayText" expression="" defaultValue="Fundamentals Guide" alwaysStopAt="true" />
     <context>
       <option name="AsciiDoc" value="true" />
     </context>
   </template>
-  <template name="adrg" value="xref:rg.adoc#_rg[Reference Guide]" description="xref to reference guide" toReformat="false" toShortenFQNames="true">
+  <template name="adai" value="Apache Isis " description="Apache Isis" toReformat="false" toShortenFQNames="true">
     <context>
       <option name="AsciiDoc" value="true" />
     </context>
   </template>
-  <template name="adug" value="xref:ug.adoc#_ug[Users' Guide]" description="xref to user' guide" toReformat="false" toShortenFQNames="true">
+  <template name="adcg" value="xref:cg.adoc#$bookmark$[$DisplayText$]" description="x-ref to contributors guide" toReformat="false" toShortenFQNames="true">
+    <variable name="bookmark" expression="" defaultValue="" alwaysStopAt="true" />
+    <variable name="DisplayText" expression="" defaultValue="Contributors guide" alwaysStopAt="true" />
     <context>
       <option name="AsciiDoc" value="true" />
     </context>
   </template>
-  <template name="adai" value="Apache Isis " description="Apache Isis" toReformat="false" toShortenFQNames="true">
+  <template name="adtg" value="xref:tg.adoc#$bookmark$[$DisplayText$]" description="x-ref to tutorials guide" toReformat="false" toShortenFQNames="true">
+    <variable name="bookmark" expression="" defaultValue="" alwaysStopAt="true" />
+    <variable name="DisplayText" expression="" defaultValue="Tutorials" alwaysStopAt="true" />
     <context>
       <option name="AsciiDoc" value="true" />
     </context>
   </template>
-  <template name="adcg1" value="xref:cg.adoc#_cg_$chapter$[$DisplayText$]" description="x-ref to contributors guide level 1 (chapter)" toReformat="false" toShortenFQNames="true">
-    <variable name="chapter" expression="" defaultValue="" alwaysStopAt="true" />
-    <variable name="DisplayText" expression="" defaultValue="" alwaysStopAt="true" />
+  <template name="adugtst" value="xref:ugtst.adoc#$bookmark$[$DisplayText$]" description="x-ref to user guide testing guide" toReformat="false" toShortenFQNames="true">
+    <variable name="bookmark" expression="" defaultValue="" alwaysStopAt="true" />
+    <variable name="DisplayText" expression="" defaultValue="Testing guide" alwaysStopAt="true" />
     <context>
       <option name="AsciiDoc" value="true" />
     </context>
   </template>
-  <template name="adcg2" value="xref:cg.adoc#_cg_$chapter$_$section$[$DisplayText$]" description="x-ref to contributors guide level 2 (chapter section)" toReformat="false" toShortenFQNames="true">
-    <variable name="chapter" expression="" defaultValue="" alwaysStopAt="true" />
-    <variable name="section" expression="" defaultValue="" alwaysStopAt="true" />
-    <variable name="DisplayText" expression="" defaultValue="" alwaysStopAt="true" />
+  <template name="adugbtb" value="xref:ugbtb.adoc#$bookmark$[$DisplayText$]" description="x-ref to user guide beyond the basics" toReformat="false" toShortenFQNames="true">
+    <variable name="bookmark" expression="" defaultValue="" alwaysStopAt="true" />
+    <variable name="DisplayText" expression="" defaultValue="Beyond the Basics guide" alwaysStopAt="true" />
     <context>
       <option name="AsciiDoc" value="true" />
     </context>
   </template>
-  <template name="adtg1" value="xref:tg.adoc#$chapter$[$DisplayText$]" description="x-ref to tutorials level 1 (chapter)" toReformat="false" toShortenFQNames="true">
-    <variable name="chapter" expression="" defaultValue="_tg_" alwaysStopAt="true" />
-    <variable name="DisplayText" expression="" defaultValue="" alwaysStopAt="true" />
+  <template name="adugsec" value="xref:ugsec.adoc#$bookmark$[$DisplayText$]" description="x-ref to user guide security guide" toReformat="false" toShortenFQNames="true">
+    <variable name="bookmark" expression="" defaultValue="" alwaysStopAt="true" />
+    <variable name="DisplayText" expression="" defaultValue="Security guide" alwaysStopAt="true" />
     <context>
       <option name="AsciiDoc" value="true" />
     </context>


[02/52] [abbrv] isis git commit: ISIS-1234: extracted configuration guide from rg.adoc.

Posted by mg...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout.adoc
index a351dea..0f5a3d3 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout.adoc
@@ -34,7 +34,7 @@ The table below summarizes the annotation's attributes.
 
 |xref:rgant.adoc#_rgant-DomainObjectLayout_cssclass[`cssClass()`]
 |Any string valid as a CSS class
-|the css class that a domain class (type) should have, to allow more targetted styling in xref:rg.adoc#_rg_runtime_application-specific_application-css[`application.css`]
+|the css class that a domain class (type) should have, to allow more targetted styling in xref:rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css`]
 
 
 |xref:rgant.adoc#_rgant-DomainObjectLayout_cssClassFa[`cssClassFa()`]

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClass.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClass.adoc
index 17b9a47..2dbefe6 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClass.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClass.adoc
@@ -6,7 +6,7 @@
 
 
 
-The `cssClass()` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the domain object.   xref:rg.adoc#_rg_runtime_application-specific_application-css[Application-specific CSS] can then be used to target and adjust the UI representation of that particular element.
+The `cssClass()` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the domain object.   xref:rgcfg.adoc#_rgcfg_application-specific_application-css[Application-specific CSS] can then be used to target and adjust the UI representation of that particular element.
 
 This attribute can also be applied to xref:rgant.adoc#_rgant-DomainObjectLayout_cssClass[domain objects], xref:rgant.adoc#_rgant-ViewModelLayout_cssClass[view models], xref:rgant.adoc#_rgant-ActionLayout_cssClass[actions] xref:rgant.adoc#_rgant-PropertyLayout_cssClass[properties],  xref:rgant.adoc#_rgant-CollectionLayout_cssClass[collections] and xref:rgant.adoc#_rgant-ParameterLayout_cssClass[parameters].
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_paged.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_paged.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_paged.adoc
index 67a0226..17921a8 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_paged.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_paged.adoc
@@ -28,6 +28,6 @@ public class Order {
 ----
 
 
-It is also possible to specify a global default for the page size of standalone collections, using the xref:rg.adoc#_rg_runtime_configuring-core[configuration property] `isis.viewer.paged.standalone`.
+It is also possible to specify a global default for the page size of standalone collections, using the xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.viewer.paged.standalone`.
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_auditing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_auditing.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_auditing.adoc
index e392c9a..1d07822 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_auditing.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_auditing.adoc
@@ -7,7 +7,7 @@
 
 The `auditing()` attribute indicates that if the object is modified, then each of its changed properties should be submitted to the xref:rgsvc.adoc#_rgsvc-spi_AuditingService[`AuditingService`], if one has been configured.
 
-The default value for the attribute is `AS_CONFIGURED`, meaning that the xref:rg.adoc#_rg_runtime_configuring-core[configuration property] `isis.services.audit.objects` is used to determine the whether the action is published:
+The default value for the attribute is `AS_CONFIGURED`, meaning that the xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.services.audit.objects` is used to determine the whether the action is published:
 
 * `all` +
 +

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_editing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_editing.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_editing.adoc
index 1f4ed3f..6a15cfa 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_editing.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_editing.adoc
@@ -8,7 +8,7 @@
 
 The `editing()` attribute determines whether a domain object's properties and collections are not editable (are read-only).
 
-The default is `AS_CONFIGURED`, meaning that the xref:rg.adoc#_rg_runtime_configuring-core[configuration property] `isis.objects.editing` is used to determine the whether the object is modifiable:
+The default is `AS_CONFIGURED`, meaning that the xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.objects.editing` is used to determine the whether the object is modifiable:
 
 * `true` +
 +

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_publishing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_publishing.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_publishing.adoc
index 665447c..55d08c3 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_publishing.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_publishing.adoc
@@ -10,7 +10,7 @@ The `publishing()` attribute determines whether and how a modified object instan
 
 A common use case is to notify external "downstream" systems of changes in the state of the Isis application.
 
-The default value for the attribute is `AS_CONFIGURED`, meaning that the xref:rg.adoc#_rg_runtime_configuring-core[configuration property] `isis.services.publish.objects` is used to determine the whether the action is published:
+The default value for the attribute is `AS_CONFIGURED`, meaning that the xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.services.publish.objects` is used to determine the whether the action is published:
 
 * `all` +
 +

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rgant-ParameterLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-ParameterLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-ParameterLayout.adoc
index 07efd3c..09fc3e7 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-ParameterLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-ParameterLayout.adoc
@@ -21,7 +21,7 @@ The table below summarizes the annotation's attributes.
 
 |xref:rgant.adoc#_rgant-ParameterLayout_cssClass[`cssClass()`]
 |Any string valid as a CSS class
-|the css class that a parameter should have, to allow more targetted styling in xref:rg.adoc#_rg_runtime_application-specific_application-css[`application.css`]
+|the css class that a parameter should have, to allow more targetted styling in xref:rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css`]
 
 
 |xref:rgant.adoc#_rgant-ParameterLayout_describedAs[`describedAs()`]

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rgant-ParameterLayout_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-ParameterLayout_cssClass.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-ParameterLayout_cssClass.adoc
index 03aba40..b5aa6f9 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-ParameterLayout_cssClass.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-ParameterLayout_cssClass.adoc
@@ -7,7 +7,7 @@
 
 
 
-The `cssClass()` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the action parameter.   xref:rg.adoc#_rg_runtime_application-specific_application-css[Application-specific CSS] can then be used to target and adjust the UI representation of that particular element.
+The `cssClass()` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the action parameter.   xref:rgcfg.adoc#_rgcfg_application-specific_application-css[Application-specific CSS] can then be used to target and adjust the UI representation of that particular element.
 
 This attribute can also be applied to xref:rgant.adoc#_rgant-DomainObjectLayout_cssClass[domain objects], xref:rgant.adoc#_rgant-ViewModelLayout_cssClass[view models], xref:rgant.adoc#_rgant-ActionLayout_cssClass[actions] xref:rgant.adoc#_rgant-PropertyLayout_cssClass[properties],  xref:rgant.adoc#_rgant-CollectionLayout_cssClass[collections] and xref:rgant.adoc#_rgant-ParameterLayout_cssClass[parameters].
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rgant-PostConstruct.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-PostConstruct.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-PostConstruct.adoc
index b2d429a..46e2fde 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-PostConstruct.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-PostConstruct.adoc
@@ -29,7 +29,7 @@ In the form shown above the method accepts no arguments.  Alternatively - for do
 @Programmatic
 public void init(Map<String,String> properties) { ... }
 ----
-Isis uses argument to pass in the configuration properties read from all xref:rg.adoc#_rg_runtime_configuration-files[configuration files]:
+Isis uses argument to pass in the configuration properties read from all xref:rgcfg.adoc#_rgcfg_configuration-files[configuration files]:
 
 [TIP]
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout.adoc
index 1a13e81..4ab9658 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout.adoc
@@ -21,7 +21,7 @@ The table below summarizes the annotation's attributes.
 
 |xref:rgant.adoc#_rgant-PropertyLayout_cssClass[`cssClass()`]
 |Any string valid as a CSS class
-|the css class that a property should have, to allow more targetted styling in xref:rg.adoc#_rg_runtime_application-specific_application-css[`application.css`]
+|the css class that a property should have, to allow more targetted styling in xref:rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css`]
 
 
 |xref:rgant.adoc#_rgant-PropertyLayout_describedAs[`describedAs()`]
@@ -42,7 +42,7 @@ The table below summarizes the annotation's attributes.
 
 Defaults is `LEFT`, unless xref:rgant.adoc#_rgant-PropertyLayout_multiLine[`multiLine`] in which case `TOP`.  The value `RIGHT` is only supported for boolean properties. +
 
-It is also possible to change the default through a xref:rg.adoc#_rg_runtime_configuring-core_isis-viewers-propertyLayout-labelPosition[configuration property]
+It is also possible to change the default through a xref:rgcfg.adoc#_rgcfg_configuring-core_isis-viewers-propertyLayout-labelPosition[configuration property]
 
 
 |xref:rgant.adoc#_rgant-PropertyLayout_multiLine[`multiLine()`]

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_cssClass.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_cssClass.adoc
index 7d98ad8..a522810 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_cssClass.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_cssClass.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-The `cssClass()` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the property.   xref:rg.adoc#_rg_runtime_application-specific_application-css[Application-specific CSS] can then be used to target and adjust the UI representation of that particular element.
+The `cssClass()` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the property.   xref:rgcfg.adoc#_rgcfg_application-specific_application-css[Application-specific CSS] can then be used to target and adjust the UI representation of that particular element.
 
 This attribute can also be applied to xref:rgant.adoc#_rgant-DomainObjectLayout_cssClass[domain objects], xref:rgant.adoc#_rgant-ViewModelLayout_cssClass[view models], xref:rgant.adoc#_rgant-ActionLayout_cssClass[actions] xref:rgant.adoc#_rgant-CollectionLayout_cssClass[collections] and xref:rgant.adoc#_rgant-ParameterLayout_cssClass[parameters].
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_labelPosition.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_labelPosition.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_labelPosition.adoc
index 4b5c45d..f711de9 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_labelPosition.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-PropertyLayout_labelPosition.adoc
@@ -77,7 +77,7 @@ can be used instead, eg:
 ====
 If you want a consistent look-n-feel throughout the app, eg all property labels to the top, then it'd be rather frustrating to have to annotate every property.
 
-Instead, a default can be specified using a xref:rg.adoc#_rg_runtime_configuring-core[configuration property] in `isis.properties`:
+Instead, a default can be specified using a xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] in `isis.properties`:
 
 [source,ini]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rgant-Property_editing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-Property_editing.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-Property_editing.adoc
index 3caa60a..d4b47ca 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-Property_editing.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-Property_editing.adoc
@@ -13,7 +13,7 @@ Whether a property is enabled or disabled depends upon these factors:
 
 * whether the domain object has been configured as immutable through the xref:rgant.adoc#_rgant-DomainObject_editing[`@DomainObject#editing()`] attribute
 
-* else (that is, if the domain object's editability is specified as being `AS_CONFIGURED`), then the value of the xref:rg.adoc#_rg_runtime_configuring-core[configuration property] `isis.objects.editing`.  If set to `false`, then the object's properties (and collections) are _not_ editable
+* else (that is, if the domain object's editability is specified as being `AS_CONFIGURED`), then the value of the xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.objects.editing`.  If set to `false`, then the object's properties (and collections) are _not_ editable
 
 * else, then the value of the `@Property(editing=...)` attribute itself
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rgant-ViewModelLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-ViewModelLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-ViewModelLayout.adoc
index 57debb3..ca7efaf 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-ViewModelLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-ViewModelLayout.adoc
@@ -22,7 +22,7 @@ The table below summarizes the annotation's attributes.
 
 |xref:rgant.adoc#_rgant-ViewModelLayout_cssclass[`cssClass()`]
 |Any string valid as a CSS class
-|the css class that a domain class (type) should have, to allow more targetted styling in xref:rg.adoc#_rg_runtime_application-specific_application-css[`application.css`]
+|the css class that a domain class (type) should have, to allow more targetted styling in xref:rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css`]
 
 
 |xref:rgant.adoc#_rgant-ViewModelLayout_cssClassFa[`cssClassFa()`]

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rgant-ViewModelLayout_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-ViewModelLayout_cssClass.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-ViewModelLayout_cssClass.adoc
index bd5cbea..4afc818 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-ViewModelLayout_cssClass.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-ViewModelLayout_cssClass.adoc
@@ -6,7 +6,7 @@
 
 
 
-The `cssClass()` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the view model.   xref:rg.adoc#_rg_runtime_application-specific_application-css[Application-specific CSS] can then be used to target and adjust the UI representation of that particular element.
+The `cssClass()` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the view model.   xref:rgcfg.adoc#_rgcfg_application-specific_application-css[Application-specific CSS] can then be used to target and adjust the UI representation of that particular element.
 
 This attribute can also be applied to xref:rgant.adoc#_rgant-DomainObjectLayout_cssClass[domain objects], xref:rgant.adoc#_rgant-ActionLayout_cssClass[actions] xref:rgant.adoc#_rgant-PropertyLayout_cssClass[properties],  xref:rgant.adoc#_rgant-CollectionLayout_cssClass[collections] and xref:rgant.adoc#_rgant-ParameterLayout_cssClass[parameters].
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rgant-ViewModelLayout_paged.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-ViewModelLayout_paged.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-ViewModelLayout_paged.adoc
index 46a7d89..f4cfb2c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-ViewModelLayout_paged.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-ViewModelLayout_paged.adoc
@@ -29,6 +29,6 @@ public class OrderAnalysis {
 ----
 
 
-It is also possible to specify a global default for the page size of standalone collections, using the xref:rg.adoc#_rg_runtime_configuring-core[configuration property] `isis.viewer.paged.standalone`.
+It is also possible to specify a global default for the page size of standalone collections, using the xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.viewer.paged.standalone`.
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuration-files.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuration-files.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuration-files.adoc
new file mode 100644
index 0000000..90bc9a2
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuration-files.adoc
@@ -0,0 +1,40 @@
+[[_rgcfg_configuration-files]]
+= Configuration Files
+: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/
+
+
+When running an Apache Isis webapp, configuration properties are read from configuration files held in the `WEB-INF` directory.
+
+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 xref:ugvw.adoc#[Wicket viewer] is in use
+
+* `viewer_restfulobjects.properties` - if the xref:ugvro.adoc#[RestfulObjects viewer] is in use
+
+* `viewer.properties` - for any other viewer configuration (but there are none currently)
+
+* `persistor_datanucleus.properties` - assuming the JDO/DataNucleus objectstore is in use
+
+* `persistor.properties` - for any other objectstore configuration.  +
++
+This typically is used to hold `JDBC` ``URL``s, which is arguably a slight violation of the file (because there's nothing in Apache Isis to say that persistors have to use `JDBC`.  However, it is generally convenient to put these `JDBC` settings into a single location.  If you want, they could reside inin any of `persistor_datanucleus.properties`, `persistor.properties` or (even) `isis.properties`
+
+* `authentication_shiro.properties`, `authorization_shiro.properties`
++
+assuming the Shiro Security is in use (but there are no security-related config properties currently; use shiro.ini for Shiro config)
+
+* `authentication.properties`, `authorization.properties` +
++
+for any other security-related config properties (but there are none currently).
+
+You can if you wish simply store all properties in the `isis.properties` file; but we think that breaking properties out into sections is preferable.
+
+
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-core.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-core.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-core.adoc
new file mode 100644
index 0000000..03fbc56
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-core.adoc
@@ -0,0 +1,455 @@
+[[_rgcfg_configuring-core]]
+= Configuring Core
+: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 section lists the core/runtime configuration properties recognized by Apache Isis.
+
+[NOTE]
+====
+Configuration properties for the JDO/DataNucleus objectstore can be found in the xref:rgcfg.adoc#_rgcfg_configuring-datanucleus[Configuring DataNucleus] section later in this chapter, while configuration properties for the viewers can be found in the their respective chapters, xref:ugvw.adoc#_ugvw_configuration-properties[here for Wicket viewer], and xref:ugvro.adoc#_ugvro_configuration-properties[here for the Restful Objects viewer].
+====
+
+
+
+.Core Configuration Properties
+[cols="2a,1,3a", options="header"]
+|===
+|Property
+|Value +
+(default value)
+|Description
+
+|`isis.object.` +
+`editing`
+|`true`,`false` +
+(`true`)
+|Whether objects' properties and collections can be edited directly (for objects annotated with xref:rgant.adoc#_rgant-DomainObject_editing[`@DomainObject#editing()`]); see xref:rgcfg.adoc#_rgcfg_configuring-core_isis-objects-editing[below] for further discussion.
+
+
+|`isis.persistor.` +
+`disableConcurrencyChecking`
+|`true`,`false` +
+(`false`)
+| Disables concurrency checking globally.  +
+
+Only intended for "emergency use" as a workaround while pending fix/patch to Apache Isis itself.  (Note that there is no "datanucleus" in the property).
+
+|`isis.reflector.facet.` +
+`actionAnnotation.` +
+`domainEvent.postForDefault`
+|`true`,`false` +
+(`true`)
+|Whether an event should be posted if xref:rgant.adoc#_rgant-Action_domainEvent[`@Action#domainEvent()`] is not specified (is set to `ActionDomainEvent.Default`).
+
+|`isis.reflector.facet.` +
+`collectionAnnotation.` +
+`domainEvent.postForDefault`
+|`true`,`false` +
+(`true`)
+|Whether an event should be posted if xref:rgant.adoc#_rgant-Collection_domainEvent[`@Collection#domainEvent()`] is not specified (is set to `CollectionDomainEvent.Default`).
+
+|`isis.reflector.facet.` +
+`cssClass.patterns`
+|regex:css1, regex2:css2,...
+|Comma separated list of key:value pairs, where the key is a regex matching action names (eg `delete.*`) and the value is a link:http://getbootstrap.com/css/[Bootstrap] CSS button class (eg `btn-warning) to be applied (as per `@CssClass()`) to all action members matching the regex. +
+
+See xref:ug.adoc#_ug_how-tos_ui-hints_action-icons-and-css[UI hints] for more details.
+
+|`isis.reflector.facet.` +
+`cssClassFa.patterns`
+|regex:fa-icon,regex2:fa-icon2,...
+|Comma separated list of key:value pairs, where the key is a regex matching action names (eg `create.*`) and the value is a link:http://fortawesome.github.io/Font-Awesome/icons/[font-awesome] icon name (eg `fa-plus`) to be applied (as per `@CssClassFa()`) to all action members matching the regex. +
+
+See xref:ug.adoc#_ug_how-tos_ui-hints_action-icons-and-css[UI hints] for more details.
+
+|`isis.reflector.facet.` +
+`domainObjectAnnotation.` +
+`createdLifecycleEvent.` +
+`postForDefault` +
+(`1.11.0-SNAPSHOT`)
+|`true`,`false` +
+(`true`)
+|Whether an event should be posted if xref:rgant.adoc#_rgant-DomainObject_createdLifecycleEvent[`@DomainObject#createdLifecycleEvent()`] is not specified (is set to `ObjectCreatedEvent.Default`).
+
+|`isis.reflector.facet.` +
+`domainObjectAnnotation.` +
+`loadedLifecycleEvent.` +
+`postForDefault` +
+(`1.11.0-SNAPSHOT`)
+|`true`,`false` +
+(`true`)
+|Whether an event should be posted if xref:rgant.adoc#_rgant-DomainObject_loadedLifecycleEvent[`@DomainObject#loadedLifecycleEvent()`] is not specified (is set to `ObjectLoadedEvent.Default`).
+
+|`isis.reflector.facet.` +
+`domainObjectAnnotation.` +
+`persistingLifecycleEvent.` +
+`postForDefault` +
+(`1.11.0-SNAPSHOT`)
+|`true`,`false` +
+(`true`)
+|Whether an event should be posted if xref:rgant.adoc#_rgant-DomainObject_persistingLifecycleEvent[`@DomainObject#persistingLifecycleEvent()`] is not specified (is set to `ObjectPersistingEvent.Default`).
+
+|`isis.reflector.facet.` +
+`domainObjectAnnotation.` +
+`persistedLifecycleEvent.` +
+`postForDefault` +
+(`1.11.0-SNAPSHOT`)
+|`true`,`false` +
+(`true`)
+|Whether an event should be posted if xref:rgant.adoc#_rgant-DomainObject_persistedLifecycleEvent[`@DomainObject#persistedLifecycleEvent()`] is not specified (is set to `ObjectPersistedEvent.Default`).
+
+|`isis.reflector.facet.` +
+`domainObjectAnnotation.` +
+`removingLifecycleEvent.` +
+`postForDefault` +
+(`1.11.0-SNAPSHOT`)
+|`true`,`false` +
+(`true`)
+|Whether an event should be posted if xref:rgant.adoc#_rgant-DomainObject_removingLifecycleEvent[`@DomainObject#removingLifecycleEvent()`] is not specified (is set to `ObjectRemovingEvent.Default`).
+
+|`isis.reflector.facet.` +
+`domainObjectAnnotation.` +
+`updatingLifecycleEvent.` +
+`postForDefault` +
+(`1.11.0-SNAPSHOT`)
+|`true`,`false` +
+(`true`)
+|Whether an event should be posted if xref:rgant.adoc#_rgant-DomainObject_updatingLifecycleEvent[`@DomainObject#updatingLifecycleEvent()`] is not specified (is set to `ObjectUpdatingEvent.Default`).
+
+|`isis.reflector.facet.` +
+`domainObjectAnnotation.` +
+`updatedLifecycleEvent.` +
+`postForDefault` +
+(`1.11.0-SNAPSHOT`)
+|`true`,`false` +
+(`true`)
+|Whether an event should be posted if xref:rgant.adoc#_rgant-DomainObject_updatedLifecycleEvent[`@DomainObject#updatedLifecycleEvent()`] is not specified (is set to `ObjectUpdatedEvent.Default`).
+
+|`isis.reflector.facet.` +
+`domainObjectLayoutAnnotation.` +
+`cssClassUiEvent.postForDefault` +
+(`1.11.0-SNAPSHOT`)
+|`true`,`false` +
+(`true`)
+|Whether an event should be posted if xref:rgant.adoc#_rgant-DomainObjectLayout_cssClassUiEvent[`@DomainObjectLayout#cssClassUiEvent()`] is not specified (is set to `CssClassUiEvent.Default`).
+
+|`isis.reflector.facet.` +
+`domainObjectLayoutAnnotation.` +
+`iconUiEvent.postForDefault` +
+(`1.11.0-SNAPSHOT`)
+|`true`,`false` +
+(`true`)
+|Whether an event should be posted if xref:rgant.adoc#_rgant-DomainObjectLayout_iconUiEvent[`@DomainObjectLayout#iconUiEvent()`] is not specified (is set to `IconUiEvent.Default`).
+
+|`isis.reflector.facet.` +
+`domainObjectLayoutAnnotation.` +
+`titleUiEvent.postForDefault` +
+(`1.11.0-SNAPSHOT`)
+|`true`,`false` +
+(`true`)
+|Whether an event should be posted if xref:rgant.adoc#_rgant-DomainObjectLayout_titleUiEvent[`@DomainObjectLayout#titleUiEvent()`] is not specified (is set to `TitleUiEvent.Default`).
+
+|`isis.reflector.facet.` +
+`filterVisibility`
+|`true`,`false` +
+(`true`)
+|Whether objects should be filtered for visibility. +
+
+See xref:rgcfg.adoc#_rgcfg_configuring-core_filterVisibility[section below] for further discussion.
+
+|`isis.reflector.facet.` +
+`propertyAnnotation.` +
+`domainEvent.postForDefault`
+|`true`,`false` +
+(`true`)
+|Whether an event should be posted if xref:rgant.adoc#_rgant-Property_domainEvent[`@Property#domainEvent()`] is not specified (is set to `PropertyDomainEvent.Default`).
+
+|`isis.reflector.facets`
+|`FQCN`
+|Fully qualified class names of a custom implementation of `ProgrammingModel` interface. +
+
+See xref:ugbtb.adoc#_ugbtb_programming-model_finetuning[finetuning the programming model] for more details.
+
+|`isis.reflector.facets.` +
+`exclude`
+|`FQCN`,`FQCN2`,...
+|Fully qualified class names of (existing, built-in) facet factory classes to be included to the programming model. +
+
+See xref:ugbtb.adoc#_ugbtb_programming-model_finetuning[finetuning the programming model] for more details.
+
+|`isis.reflector.facets.` +
+`include`
+|`FQCN`,`FQCN2`,...
+|Fully qualified class names of (new, custom) facet factory classes to be included to the programming model. +
+See xref:ugbtb.adoc#_ugbtb_programming-model_finetuning[finetuning the programming model] for more details.
+
+
+|`isis.reflector.` +
+`layoutMetadataReaders`
+|`FQCN`,`FQCN2`,...
+|Fully qualified class names of classes to be instantiated to read layout metadata, as used in for xref:ug.adoc#_ug_object-layout_dynamic[dynamic layout]s. +
+
+See xref:ugbtb.adoc#_ugbtb_programming-model_layout-metadata-reader[Layout Metadata Reader] for more information.
+
+
+
+|`isis.reflector.validator`
+|`FQCN`
+|Custom implementation of `MetaModelValidator` (in the `org.apache.isis.core.metamodel.specloader.validator` package) +
+
+See xref:ugbtb.adoc#_ugbtb_programming-model_custom-validator[Custom Validator] to learn more.
+
+|`isis.reflector.validator.` +
+`allowDeprecated`
+|`true`,`false` +
+(`true`)
+| Whether deprecated annotations or naming conventions are tolerated or not.  If not, then a metamodel validation error will be triggered, meaning the app won't boot (fail-fast).
+
+
+|`isis.services`
+|`FQCN`,`FQCN2`,...
+|Fully qualified class names of classes to be instantiated as domain services.  +
+
+Each entry can be optionally prefixed by "n:" specifying the relative order on the menu (corresponds to xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`]).
+
+This property is IGNORED if the xref:rgcfg.adoc#_rgcfg_configuring-components[`isis.appManifest`] configuration property is specified, or if an xref:rg.adoc#_rg_classes_super_manpage-AppManifest[`AppManifest`] is provided programmatically.
+
+
+|`isis.services.` +
+`audit.objects`
+| `all`, `none` +
+(`all`)
+|Whether the changed properties of objects should be automatically audited (for objects annotated with xref:rgant.adoc#_rgant-DomainObject_auditing[`@DomainObject(auditing=Auditing.AS_CONFIGURED)`].
+
+|`isis.services.` +
+`command.actions`
+| `all`, `ignoreSafe`, `none` (`all`)
+|Whether actions should be automatically reified into commands (for actions annotated with xref:rgant.adoc#_rgant-Action_command[`@Action(command=CommandReification.AS_CONFIGURED)`].  +
+
+`ignoreQueryOnly` is an alias for `ignoreSafe`.
+
+
+|`isis.services.` +
+`container.disableAutoFlush`
+|`true`,`false` +
+(`false`)
+|Whether the `DomainObjectContainer` should automatically flush pending changes prior to querying (via `allMatches()`, `firstMatch()` and so on).
+
+|`isis.services.` +
+`container.disableAutoFlush`
+|`true`,`false` +
+(`false`)
+|Whether the `DomainObjectContainer` should automatically flush pending changes prior to querying (via `allMatches()`, `firstMatch()` and so on).
+
+
+
+|`isis.services.` +
+`ContentNegotiation-` +
+`ServiceXRoDomainType` +
+.prettyPrint
+| `true`,`false` +
+(depends)
+|If a domain object has been mapped to the specified JAXB `x-ro-domain-type`, then determines whether the result is pretty-printed or not. +
++
+If no configuration property is available, then the defaults is determined by the xref:rgcfg.adoc#_rgcfg_deployment-types[deployment type]: production mode disables pretty printing, while prototype mode enables it.
+
+
+
+| `isis.service.` +
+`email.tls.enabled`
+|`true`,`false` +
+(`true`)
+|Whether to enable TLS for the email SMTP connection (used by xref:rgsvc.adoc#_rgsvc-api_EmailService[`EmailService`]).  +
+
+NB: note that the key is mis-spelt, (`isis.service.email` rather than `isis.services.email`)
+
+| `isis.service.` +
+`email.sender.hostname` +
+| host (`_smtp.gmail.com_`)
+|The hostname of the external SMTP provider (used by xref:rgsvc.adoc#_rgsvc-api_EmailService[`EmailService`]).  +
+
+NB: note that the key is mis-spelt, (`isis.service.email` rather than `isis.services.email`)
+
+| `isis.service.` +
+`email.port` +
+| port number (`_587_`)
+|The port number for the SMTP service on the the external SMTP host (used by xref:rgsvc.adoc#_rgsvc-api_EmailService[`EmailService`]).  +
+
+NB: note that the key is mis-spelt, (`isis.service.email` rather than `isis.services.email`)
+
+
+| `isis.service.` +
+`email.sender.address` +
+| email address
+|The email address to use for sending out email (used by xref:rgsvc.adoc#_rgsvc-api_EmailService[`EmailService`]).  *Mandatory*.  +
+
+NB: note that the key is mis-spelt, (`isis.service.email` rather than `isis.services.email`)
+
+| `isis.service.` +
+`email.sender.password` +
+| email password
+|The corresponding password for the email address to use for sending out email (used by xref:rgsvc.adoc#_rgsvc-api_EmailService[`EmailService`]).  *Mandatory*.  +
+
+NB: note that the key is mis-spelt, (`isis.service.email` rather than `isis.services.email`)
+
+
+| `isis.services.` +
+`eventbus.implementation` +
+| `guava`, `axon`, +
+FQCN (`_guava_`)
+|which implementation to use by the xref:rgsvc.adoc#_rgsvc-api_EventBusService[`EventBusService`] as the underlying event bus.
+
+| `isis.services.` +
+`eventbus.allowLateRegistration` +
+|`true`,`false` +
+(`false`)
+|whether a domain service can register with the xref:rgsvc.adoc#_rgsvc-api_EventBusService[`EventBusService`] after any events have posted. +
+
+Since this almost certainly constitutes a bug in application code, by default this is disallowed.
+
+
+| `isis.services.` +
+`exceprecog.logRecognizedExceptions` +
+|`true`,`false` +
+(`false`)
+|whether recognized exceptions should also be logged. +
+
+Generally a recognized exception is one that is expected (for example a uniqueness constraint violated in the database) and which does not represent an error condition.  This property logs the exception anyway, useful for debugging.
+
+
+| `isis.services.` +
+`ExceptionRecognizerComposite-` +
+`ForJdoObjectStore.disable` +
+|`true`,`false` +
+(`false`)
+|whether to disable the default recognizers registered by `ExceptionRecognizerCompositeForJdoObjectStore`. +
+
+This implementation provides a default set of recognizers to convert RDBMS constraints into user-friendly messages.  In the (probably remote) chance that this functionality isn't required, they can be disabled through this flag.
+
+
+|`isis.services.` +
+`publish.objects`
+| `all`, `none` +
+(`all`)
+|Whether changed objects should be automatically published (for objects annotated with xref:rgant.adoc#_rgant-DomainObject_publishing[`@DomainObject(publishing=Publishing.AS_CONFIGURED)`].
+
+|`isis.services.` +
+`publish.actions`
+| `all`, `ignoreSafe`, `none` (`all`)
+|Whether actions should be automatically published (for actions annotated with xref:rgant.adoc#_rgant-Action_publishing[`@Action(publishing=Publishing.AS_CONFIGURED)`]. +
+
+
+|`isis.services.` +
+`ServicesInstallerFromAnnotation.` +
+`packagePrefix`
+|fully qualified package names (CSV)
+|to search for domain services (including all subpackages).
+
+This property is IGNORED if the xref:rgcfg.adoc#_rgcfg_configuring-components[`isis.appManifest`] configuration property is specified, or if an xref:rg.adoc#_rg_classes_super_manpage-AppManifest[`AppManifest`] is provided programmatically.
+
+
+|`isis.services.` +
+`translation.po.mode`
+| `read`,`write`
+|Whether to force the `TranslationService` into either read or write mode. +
+
+See xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[i18n support] to learn more about the translation service.
+
+|`isis.viewers.` +
+`paged.parented`
+|positive integer (12)
+|Default page size for parented collections (as owned by an object, eg `Customer#getOrders()`)
+
+|`isis.viewers.` +
+`paged.standalone`
+|positive integer (25)
+|Default page size for standalone collections (as returned from an action invocation)
+
+
+|`isis.viewers.` +
+`propertyLayout.labelPosition`
+|`TOP`, `LEFT` +
+(`LEFT`)
+|Default for label position for all properties if not explicitly specified using xref:rgant.adoc#_rgant-PropertyLayout_labelPosition[`@PropertyLayout#labelPosition()`]
+
+|===
+
+
+
+[[_rgcfg_configuring-core_filterVisibility]]
+== Filtering visibility
+
+The framework provides the `isis.reflector.facet.filterVisibility` configuration property that influences whether a returned object is visible to the end-user:
+
+* Action invocations: +
+
+If an action returns a collection that includes the object, then the object will be excluded from the list when rendered. If it returns a single object and the user does not have access to that object, then the action will seemingly return `null`
+
+* Collections: +
+
+If a parent object has a collection references another object to which the user does not have access, then (as for actions) the object will not be rendered in the list
+
+* Properties: +
+
+If an parent object has a (scalar) reference some other object to which the user does not have access, then the reference will be rendered as empty.
+
+* Choices and autoComplete lists: +
+
+If an object is returned in a list of choices or within an auto-complete list, and the user does not have access, then it is excluded from the rendered list.
+
+The original motivation for this feature was to transparently support such features as multi-tenancy (as per the (non-ASF) http://github.com/isisaddons/isis-module-security[Isis addons' security] module).  That is, if an entity is logically "owned" by a user, then the multi-tenancy support can be arranged to prevent some other user from viewing that object.
+
+By default this configuration property is enabled.  To disable the visibility filtering, set the appropriate configuration property to `false`:
+
+[source,ini]
+----
+isis.reflector.facet.filterVisibility=false
+----
+
+Filtering is supported by the Wicket viewer, and by the xref:rgsvc.adoc#_rgsvc-api_WrapperFactory[`WrapperFactory`] domain service (provided the wrapper's execution mode is _not_ "skip rules").  However the Restful Objects viewer does _not_ currently support filtering.
+
+[NOTE]
+====
+In order for the framework to perform this filtering of collections, be aware that the framework takes a _copy_ of the original collection, filters on the collection, and returns that filtered collection rather than the original.
+
+There are no major side-effects from this algorithm, other than the fact that the referenced objects will (most likely) need to be resolved in order to determine if they are visible.  This could conceivably have a performance impact in some cases.
+====
+
+
+[[_rgcfg_configuring-core_isis-objects-editing]]
+== `objects.editing`
+
+This configuration property in effect allows editing to be disabled globally for an application:
+
+[source,ini]
+----
+isis.objects.editing=false
+----
+
+We recommend enabling this feature; it will help drive out the underlying business operations (processes and procedures) that require objects to change; these can then be captured as business actions.
+
+
+
+[[_rgcfg_configuring-core_isis-viewers-propertyLayout-labelPosition]]
+== `propertyLayout.labelPosition`
+
+If you want a consistent look-n-feel throughout the app, eg all property labels to the top, then it'd be rather
+frustrating to have to annotate every property.
+
+Instead, a default can be specified in `isis.properties`:
+
+[source,ini]
+----
+isis.viewers.propertyLayout.labelPosition=TOP
+----
+
+or
+
+[source,ini]
+----
+isis.viewers.propertyLayout.labelPosition=LEFT
+----
+
+If these are not present then Apache Isis will render according to internal defaults. At the time of writing, this means labels are to the left for all datatypes except multiline strings.

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus.adoc
new file mode 100644
index 0000000..f5f1b77
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus.adoc
@@ -0,0 +1,18 @@
+[[_rgcfg_configuring-datanucleus]]
+= Configuring DataNucleus
+: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 programmatically configures DataNucleus; any Apache 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 for itself also and read the `META-INF/persistence.xml`; at a minimum this defines the name of the "persistence unit".  n theory it could also hold mappings, though in Apache Isis we tend to use annotations instead.
+
+Furthermore, DataNucleus will search for various other XML mapping files, eg `mappings.jdo`.  A full list can be found http://www.datanucleus.org/products/datanucleus/jdo/metadata.html[here].  The metadata in these XML can be used to override the annotations of annotated entities; see xref:ugbtb.adoc#_ugbtb_more-advanced_overriding-jdo-annotations[Overriding JDO Annotatons] for further discussion.
+
+
+include::_rgcfg_configuring-datanucleus_properties.adoc[leveloffset=+1]
+include::_rgcfg_configuring-datanucleus_persistence-xml.adoc[leveloffset=+1]
+include::_rgcfg_configuring-datanucleus_eagerly-registering-entities.adoc[leveloffset=+1]
+include::_rgcfg_configuring-datanucleus_disabling-persistence-by-reachability.adoc[leveloffset=+1]
+include::_rgcfg_configuring-datanucleus_using-jndi-data-source.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_disabling-persistence-by-reachability.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_disabling-persistence-by-reachability.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_disabling-persistence-by-reachability.adoc
new file mode 100644
index 0000000..4bd6b69
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_disabling-persistence-by-reachability.adoc
@@ -0,0 +1,88 @@
+[[_rgcfg_configuring-datanucleus_disabling-persistence-by-reachability]]
+= Persistence by Reachability
+: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/
+
+By default, JDO/DataNucleus supports the concept of http://www.datanucleus.org/products/datanucleus/jdo/orm/cascading.html[persistence-by-reachability]. That is, if
+a non-persistent entity is associated with an already-persistent entity, then DataNucleus will detect this and will automatically persist the associated object. Put another way: there is no need to call Apache Isis' `DomainObjectContainer#persist(.)` or `DomainObjectContainer#persistIfNotAlready(.)` methods.
+
+However, convenient though this feature is, you may find that it causes performance issues.
+
+[WARNING]
+====
+DataNucleus' persistence-by-reachability may cause performance issues.  We strongly recommend that you disable it.
+====
+
+One scenario in particular where this performance issues can arise is if your entities implement the `java.lang.Comparable` interface, and you have used Apache Isis' xref:rg.adoc#_rg_classes_utility_manpage-ObjectContracts[`ObjectContracts`] utility class. The issue here is that `ObjectContracts` implementation can cause DataNucleus to recursively rehydrate a larger number of associated entities. (More detail below).
+
+We therefore recommend that you disable persistence-by-reachability by adding the following to `persistor_datanucleus.properties`:
+
+[source,ini]
+----
+isis.persistor.datanucleus.impl.datanucleus.persistenceByReachabilityAtCommit=false
+----
+
+This change has been made to the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype]
+
+If you do disable this feature, then you will (of course) need to ensure that you explicitly persist all entities using the `DomainObjectContainer#persist(.)` or `DomainObjectContainer#persistIfNotAlready(.)` methods.
+
+
+
+
+
+== The issue in more detail
+
+Consider these entities (http://yuml.me/edit/b8681268[yuml.me/b8681268]):
+
+image::{_imagesdir}runtime/configuring-datanucleus/disabling-persistence-by-reachability/party-agreementrole-agreement.png[width="750px"]
+
+
+
+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.
+
+All these entities implement `Comparable` using `ObjectContracts`, and the implementation of ``AgreementRole``'s (simplified) is:
+
+[source,java]
+----
+public class AgreementRole {
+    ...
+    public int compareTo(AgreementRole other) {
+        return ObjectContracts.compareTo(this, other, "agreement","startDate","party");
+    }
+}
+----
+
+while ``Agreement``'s is implemented as:
+
+[source,java]
+----
+public class Agreement {
+    ...
+    public int compareTo(Agreement other) {
+        return ObjectContracts.compareTo(this, other, "reference");
+    }
+}
+----
+
+and ``Party``'s is similarly implemented as:
+
+[source,java]
+----
+public class Party {
+    ...
+    public int compareTo(Party other) {
+        return ObjectContracts.compareTo(this, other, "reference");
+    }
+}
+----
+
+DataNucleus's persistence-by-reachability algorithm adds the `AgreementRole` instances into a `SortedSet`, which causes `AgreementRole#compareTo()` to fire:
+
+* the evaluation of the "agreement" property delegates back to the `Agreement`, whose own `Agreement#compareTo()` uses the scalar `reference` property. As the `Agreement` is already in-memory, this does not trigger any further database queries
+
+* the evaluation of the "startDate" property is just a scalar property of the `AgreementRole`, so will already in-memory
+
+* the evaluation of the "party" property delegates back to the `Party`, whose own `Party#compareTo()` requires the uses the scalar `reference` property. However, since the `Party` is not yet in-memory, using the `reference` property triggers a database query to "rehydrate" the `Party` instance.
+
+In other words, in figuring out whether `AgreementRole` requires the persistence-by-reachability algorithm to run, it causes the adjacent associated entity `Party` to also be retrieved.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_eagerly-registering-entities.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_eagerly-registering-entities.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_eagerly-registering-entities.adoc
new file mode 100644
index 0000000..cbe0c44
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_eagerly-registering-entities.adoc
@@ -0,0 +1,23 @@
+[[_rgcfg_configuring-datanucleus_eagerly-registering-entities]]
+= Eagerly Registering Entities
+: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/
+
+
+
+Both Apache Isis and DataNucleus have their own metamodels of the domain entities. Apache Isis builds its metamodel by walking the graph of types of the domain services.  The JDO/DataNucleus objectstore then takes these types and registers them with DataNucleus.
+
+In some cases, though, not every entity type is discoverable from the API of the service actions. This is especially the case if you have lots of subtypes (where the action method specifies only the supertype). In such cases the Isis and JDO metamodels is built lazily, when an instance of that (sub)type is first encountered.
+
+Apache Isis is quite happy for the metamodel to be lazily created, and - to be fair - DataNucleus also works well in most cases. In some cases, though, we have found that the JDBC driver (eg HSQLDB) will deadlock if DataNucleus tries to submit some DDL (for a lazily discovered type) intermingled with DML (for updating).  In any case, it's probably not good practice to have DataNucleus work this way.
+
+The framework thus provide mechanisms to search for all `@PersistenceCapable` entities under specified package(s), and registers them all eagerly.  In fact there are two:
+
+* as of 1.9.0 the recommended (and simpler) approach is to specify an xref:rg.adoc#_rg_classes_super_manpage-AppManifest[`AppManifest`], either as a xref:rgcfg.adoc#_rgcfg_configuring-components[`isis.appManifest`] configuration property or programmatically.
+
+* for earlier versions the `isis.persistor.datanucleus.RegisterEntities.packagePrefix` configuration property can be specified.  To bootstrap as a webapp this is usually specified in `persistor_datanucleus.properties`.  (This is also supported in 1.9.0 if no `AppManifest` is specified.  For integration testing this can be specified programatically.
+
+Further discussion on specifying the package(s) in integration testing (for either approach) can be found in the xref:ugtst.adoc#_ugtst_integ-test-support_bootstrapping[user guide].
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_persistence-xml.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_persistence-xml.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_persistence-xml.adoc
new file mode 100644
index 0000000..96c71f9
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_persistence-xml.adoc
@@ -0,0 +1,10 @@
+[[_rgcfg_configuring-datanucleus_persistence-xml]]
+= `persistence.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/
+
+
+NOTE: TODO
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_properties.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_properties.adoc
new file mode 100644
index 0000000..d784d71
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_properties.adoc
@@ -0,0 +1,66 @@
+[[_rgcfg_configuring-datanucleus_properties]]
+= 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/
+
+
+These configuration properties are typically stored in `WEB-INF/persistor_datanucleus.properties`.  However, you can place all configuration properties into `WEB-INF/isis.properties` if you wish (the configuration properties from all config files are merged together).
+
+== Configuration Properties for Apache Isis itself
+
+
+.JDO/DataNucleus Objectstore Configuration Properties
+[cols="2a,1,3a", options="header"]
+|===
+|Property
+|Value +
+(_default value_)
+|Description
+
+|`isis.persistor.` +
+`datanucleus.` +
+`classMetadataLoadedListener`
+|`FQCN`
+|The default (`o.a.i.os.jdo.dn.CreateSchemaObjectFromClassMetadata`) creates a DB schema object
+
+
+|`isis.persistor.datanucleus.` +
+`RegisterEntities.packagePrefix`
+|fully qualified package names (CSV)
+|that specifies the entities early rather than allow DataNucleus to find the entities lazily.  Further xref:rgcfg.adoc#_rgcfg_configuring-datanucleus_eagerly-registering-entities[discussion below].
+
+This property is IGNORED if the xref:rgcfg.adoc#_rgcfg_configuring-components[`isis.appManifest`] configuration property is specified, or if an xref:rg.adoc#_rg_classes_super_manpage-AppManifest[`AppManifest`] is provided programmatically.
+
+
+|`isis.persistor.datanucleus.` +
+`PublishingService.serializedForm`
+| zipped
+|
+
+|===
+
+
+
+== Configuration Properties passed through directly to DataNucleus.
+
+.JDO/DataNucleus Objectstore Configuration Properties
+[cols="2a,1,3a", options="header"]
+|===
+|Property
+|Value +
+(_default value_)
+|Description
+
+|`isis.persistor.datanucleus.impl.*`
+|
+| Passed through directly to Datanucleus (with `isis.persistor.datanucleus.impl` prefix stripped)
+
+|`isis.persistor.datanucleus.impl.` +
+`datanucleus.persistenceByReachabilityAtCommit`
+|`false`
+|We recommend this setting is disabled.  +
+Further xref:rgcfg.adoc#_rgcfg_configuring-datanucleus_disabling-persistence-by-reachability[discussion below].
+
+|===
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_using-jndi-data-source.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_using-jndi-data-source.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_using-jndi-data-source.adoc
new file mode 100644
index 0000000..3523b7b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_using-jndi-data-source.adoc
@@ -0,0 +1,75 @@
+[[_rgcfg_configuring-datanucleus_using-jndi-data-source]]
+= Using JNDI DataSource
+: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/
+
+Isis' JDO objectstore can be configured either to connect to the database using its own connection pool, or by using a container-managed datasource.
+
+
+
+== Application managed
+
+Using a connection pool managed directly by the application (that is, by Apache Isis' JDO objectstore and ultimately by DataNucleus) requires a single set of configuration properties to be specified.
+
+In the `WEB-INF\persistor_datanucleus.properties` file, specify the connection driver, url, username and password.
+
+For example:
+
+[source,ini]
+----
+isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionDriverName=net.sf.log4jdbc.DriverSpy
+isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionURL=jdbc:log4jdbc:hsqldb:mem:test
+isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionUserName=sa
+isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionPassword=
+----
+
+Those configuration properties that start with the prefix `isis.persistor.datanucleus.impl.` are passed through directly to DataNucleus (with the prefix removed).
+
+
+
+
+
+== Container managed (JNDI)
+
+Using a datasource managed by the servlet container requires three separate bits of configuration.
+
+Firstly, specify the name of the datasource in the `WEB-INF\persistor_datanucleus.properties` file. For example:
+
+If connection pool settings are also present in this file, they will simply be ignored. Any other configuration properties that start with the prefix `isis.persistor.datanucleus.impl.` are passed through directly to DataNucleus (with the prefix removed).
+
+Secondly, in the `WEB-INF/web.xml`, declare the resource reference:
+
+[source,xml]
+----
+<resource-ref>
+    <description>db</description>
+    <res-ref-name>jdbc/simpleapp</res-ref-name>
+    <res-type>javax.sql.DataSource</res-type>
+    <res-auth>Container</res-auth>
+</resource-ref>
+----
+
+Finally, declare the datasource as required by the servlet container. For example, if using Tomcat 7, the datasource can be specified by adding the following to `$TOMCAT_HOME/conf/context.xml`:
+
+[source,xml]
+----
+<Resource name="jdbc/simpleapp"
+  auth="Container"
+  type="javax.sql.DataSource"
+  maxActive="100"
+  maxIdle="30"
+  maxWait="10000"
+  username="sa"
+  password="p4ssword"
+  driverClassName="com.microsoft.sqlserver.jdbc.SQLServerDriver"
+  url="jdbc:sqlserver://127.0.0.1:1433;instance=.;databaseName=simpleapp"/>
+----
+
+You will also need to make sure that the JDBC driver is on the servlet container's classpath. For Tomcat, this means copying the driver to `$TOMCAT_HOME/lib`.
+
+[NOTE]
+====
+According to Tomcat's documentation, it is supposedly possible to copy the `conf/context.xml` to the name of the webapp, eg `conf/mywebapp.xml`, and scope the connection to that webapp only.  I was unable to get this working, however.
+====
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rgcfg_deployment-types.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_deployment-types.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_deployment-types.adoc
new file mode 100644
index 0000000..35d5d56
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_deployment-types.adoc
@@ -0,0 +1,111 @@
+[[_rgcfg_deployment-types]]
+= Deployment Types
+: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 distinguishes between the application being run in development mode vs running in production mode.  The framework calls this the "deployment type" (corresponding internally to the `DeploymentType` class).
+
+(For mostly historical reasons) development mode is actually called `SERVER_PROTOTYPE`, while production mode is called just `SERVER`.  (There is also a deprecated mode called `SERVER_EXPLORATION`; for all intents and purposes this can considered as an alias of `SERVER_PROTOTYPE`).
+
+When running in development/prototyping mode, certain capabilities are enabled; most notably any actions restricted to prototyping mode (using xref:rgant.adoc#_rgant-Action_restrictTo[`@Action#restrictTo()`]) will be available.
+
+
+
+== Using the Wicket Viewer
+
+Most of the you're likely to run Apache Isis using the xref:ugvw.adoc#[Wicket viewer].  In this case Apache Isis' "deployment type" concept maps to Wicket's "configuration" concept:
+
+.Apache Isis' deployment type corresponds to Apache Wicket's configuration
+[cols="1,1,2", options="header"]
+|===
+| Apache Isis +
+(Deployment Type)
+| Apache Wicket +
+(Configuration)
+| Notes
+
+| `SERVER_PROTOTYPE`
+| `development`
+| running in development/prototyping mode
+
+| `SERVER`
+| `deployment`
+| running in production mode
+
+|===
+
+
+Wicket's mechanism for specifying the "configuration" is to use a context parameter in `web.xml`; Apache Isis automatically infers its own deployment type from this.  In other words:
+
+* to specify SERVER (production) mode, use: +
++
+[source,xml]
+.`web.xml`
+----
+<context-param>
+    <param-name>configuration</param-name>
+    <param-value>deployment</param-value>
+</context-param>
+----
+
+* to specify `SERVER_PROTOTYPING` (development) mode, use: +
++
+[source,xml]
+.`web.xml`
+----
+<context-param>
+    <param-name>configuration</param-name>
+    <param-value>deployment</param-value>
+</context-param>
+----
+
+
+== Restful Objects viewer only
+
+Most Apache Isis applications will consist of at least the xref:ugvw.adoc#[Wicket viewer] and optionally the xref:ugvro.adoc#[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:ugbtb.adoc#_ugbtb_web-xml_servlet-context-listeners[ `IsisWebAppBootstrapper`].
+
+In this case the deployment type is specified through an Apache Isis-specific context parameter, called `isis.deploymentType`:
+
+* to specify `SERVER` (production) mode, use: +
++
+[source,xml]
+.`web.xml`
+----
+<context-param>
+    <param-name>isis.deploymentType</param-name>
+    <param-value>server</param-value>
+</context-param>
+----
+
+* to specify `SERVER_PROTOTYPE` (development) mode, use: +
++
+[source,xml]
+.`web.xml`
+----
+<context-param>
+    <param-name>isis.deploymentType</param-name>
+    <param-value>server-prototype</param-value>
+</context-param>
+----
+
+
+
+== Overriding the deployment type
+
+If bootstrapping the application using Apache Isis' xref:ugbtb.adoc#_ugbtb_deployment_cmd-line[`org.apache.isis.WebServer`] then it is possible to override the deployment type using the `-t` (or `--type`) flag.
+
+For example:
+
+[source,bash]
+----
+java -jar ... org.apache.isis.WebServer -t SERVER
+----
+
+where "..." is the (usually rather long) list of JAR files and class directories that will make up your application.
+
+This works for both the xref:ugvw.adoc#[Wicket viewer] and the xref:ugvro.adoc#[RestfulObjects viewer].
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rgcfg_specifying-components.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_specifying-components.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_specifying-components.adoc
new file mode 100644
index 0000000..f51b24f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_specifying-components.adoc
@@ -0,0 +1,110 @@
+[[_rgcfg_configuring-components]]
+= Specifying components
+: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/
+
+
+
+Bootstrapping an Apache Isis application involves identifying both:
+
+* the major components (authentication, persistence mechanisms, viewers) of Apache Isis, and also
+* specifying the domain services and persistent entities that make up the application itself.
+
+As of 1.9.0 there are two different ways to perform this bootstrapping.  The recommended (newer) approach is to use an xref:rg.adoc#_rg_classes_super_manpage-AppManifest[`AppManifest`], specified either programmatically or through the configuration properties.  This allows the components, services and entities to be specified from a single class.  The alternative (and older, pre 1.9.0) approach is to specify this information individually, through configuration properties.
+
+To specify the `AppManifest` as a configuration property, use:
+
+.Core Configuration Properties (ignored if `isis.appManifest` is present)
+[cols="2a,1,3a", options="header"]
+|===
+|Property
+|Value +
+(_default value_)
+|Implements
+
+|`isis.appManifest`
+|`FQCN`
+|`o.a.i.applib.AppManifest` +
+
+By convention this implementation resides in an `myapp-app` Maven module (as opposed to `myapp-dom` or `myapp-fixture`).  See the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype] for details.
+
+|===
+
+From this the framework can determine the domain services, persistent entities and security (authentication and authorization) mechanisms to use.  Other configuration (including fixtures) can also be specified this way.
+
+
+If the `AppManifest` approach is _not_ being used, then the following configuration properties are used to specify the major components of Apache Isis to use:
+
+.Core Configuration Properties (ignored if `isis.appManifest` is present)
+[cols="2a,1,3a", options="header"]
+|===
+|Property
+|Value +
+(_default value_)
+|Implements
+
+|`isis.authentication`
+|`shiro`, `bypass`, `FQCN` +
+(`_shiro_`)
+|`o.a.i.core.runtime.authentication.` `AuthenticationManagerInstaller` +
+
+This property is IGNORED if the `isis.appManifest` configuration property is specified, or if an xref:rg.adoc#_rg_classes_super_manpage-AppManifest[`AppManifest`] is provided programmatically.
+
+
+|`isis.authorization`
+|`shiro`, `bypass`, `FQCN` +
+(`_shiro_`)
+|`o.a.i.core.runtime.authorization.` `AuthorizationManagerInstaller` +
+
+This property is IGNORED if the `isis.appManifest` configuration property is specified, or if an xref:rg.adoc#_rg_classes_super_manpage-AppManifest[`AppManifest`] is provided programmatically.
+
+|`isis.persistor`
+|`datanucleus`
+(`_datanucleus_`)
+|`o.a.i.core.runtime.installerregistry.installerapi.` `PersistenceMechanismInstaller`
+
+This property is IGNORED completely in 1.9.0+; the `datanucleus` implementation is always used.
+
+
+|`isis.services-installer`
+|`configuration`, `configuration-and-annotation`, `FQCN` +
+(`_configuration_`)
+|`org.apache.isis.core.runtime.services.` `ServicesInstaller` +
+
+The mechanism to discover and load domain services:
+
+* `configuration-and-annotation` will search for `@DomainService`-annotated classes and also read from `isis.services` configuration property
+
+* `configuration` will only read from the `isis.services` configuration property. +
+
+* Otherwise an alternative implementation of the `o.a.i.core.runtime.services.ServicesInstaller` internal API can be provided. +
+
+This property is IGNORED if the `isis.appManifest` configuration property is specified, or if an xref:rg.adoc#_rg_classes_super_manpage-AppManifest[`AppManifest`] is provided programmatically.
+
+
+|===
+
+[TIP]
+====
+The values `"shiro"`, `"bypass"` etc are actually aliases for concrete implementations listed in Apache Isis' `installer-registry.properties` file (in `isis-core-runtime.jar`).  It is -- at least in theory -- possible to specify a fully qualified class name to replace either of the two security components.
+====
+
+If the `AppManifest` is _not_ being used then there are number of other configuration properties that also must be specified: `isis.services`, `isis.services.ServicesInstallerFromAnnotation.packagePrefix` and `isis.persistor.datanucleus.RegisterEntities.packagePrefix` and `isis.fixtures`; these are listed in the sections below.
+
+
+
+== Viewer Configuration
+
+Viewers are specified by way of the filters and servlets in the xref:ugbtb.adoc#_ugbtb_web-xml[`web.xml`] file; these are not bootstrapped by the framework, rather it is the other way around.  However, we can also hint to the framework as to which viewers are in use by way of a context parameter:
+
+[source,xml]
+----
+<context-param>
+    <param-name>isis.viewers</param-name>
+    <param-value>wicket,restfulobjects</param-value>
+</context-param>
+----
+
+The net effect of this configuration is simply to ensure that the `viewer_wicket.properties` and/or the `viewer_restfulobjects.properties` files are read.
+

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_ClockService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_ClockService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_ClockService.adoc
index dbac30a..e1073f5 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_ClockService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_ClockService.adoc
@@ -49,8 +49,8 @@ The default `ClockService` implementation in fact simply delegates to another cl
 
 * there are two subclasses implementations `Clock`, namely `SystemClock` and `FixtureClock`.
 * the first implementation that is instantiated registers itself as the singleton.
-* if running in xref:rg.adoc#_rg_runtime_deployment-types[production] (server) mode, then (unless another implementation has beaten it to the punch) the framework will instantiate the ``SystemClock`.  Once instantiated this cannot be replaced.
-* if running in xref:rg.adoc#_rg_runtime_deployment-types[prototype] mode, then the framework will instead instantiate `FixtureClock`.  This _can_ be replaced if required.
+* if running in xref:rgcfg.adoc#_rgcfg_deployment-types[production] (server) mode, then (unless another implementation has beaten it to the punch) the framework will instantiate the ``SystemClock`.  Once instantiated this cannot be replaced.
+* if running in xref:rgcfg.adoc#_rgcfg_deployment-types[prototype] mode, then the framework will instead instantiate `FixtureClock`.  This _can_ be replaced if required.
 
 The `FixtureClock` will behave as the system clock, unless its is explicitly set using `FixtureClock#setDate(...)` or `FixtureClock#setTime(...)` and so forth.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_CommandContext.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_CommandContext.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_CommandContext.adoc
index c6ff7e2..d11056a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_CommandContext.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_CommandContext.adoc
@@ -122,7 +122,7 @@ public class ToDoItem ... {
 ====
 As an alternative to annotating every action with `@Action#command()`, alternatively this can be configured as the default using `isis.services.command.actions` configuration property.
 
-See xref:rgant.adoc#_rgant-Action_command[`@Action#command()`] and xref:rg.adoc#_rg_runtime_configuring-core[runtime configuration] for further details.
+See xref:rgant.adoc#_rgant-Action_command[`@Action#command()`] and xref:rgcfg.adoc#_rgcfg_configuring-core[runtime configuration] for further details.
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_object-persistence-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_object-persistence-api.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_object-persistence-api.adoc
index 4be25fa..81acfcd 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_object-persistence-api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_object-persistence-api.adoc
@@ -56,7 +56,7 @@ container.persistIfNotAlready(cust);
 
 You should be aware that by default Apache Isis queues up calls to `#persist()` and `#remove()`.  These are then executed either when the request completes (and the transaction commits), or if the queue is flushed.  This can be done either implicitly by the framework, or as the result of a direct call to `#flush()`.
 
-By default the framework itself will cause `#flush()` to be called whenever a query is executed by way of `#allMatches(Query)`, as documented xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_generic-repository-api[above].  However, this behaviour can be disabled using the  xref:rg.adoc#_rg_runtime_configuring-core[configuration property] `isis.services.container.disableAutoFlush`.
+By default the framework itself will cause `#flush()` to be called whenever a query is executed by way of `#allMatches(Query)`, as documented xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_generic-repository-api[above].  However, this behaviour can be disabled using the  xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.services.container.disableAutoFlush`.
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_properties-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_properties-api.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_properties-api.adoc
index 9c9eff3..45edf3d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_properties-api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_properties-api.adoc
@@ -9,7 +9,7 @@
 
 = Properties API
 
-The properties API allows domain objects to read the configuration properties aggregated from the various xref:rg.adoc#_rg_runtime_configuration-files[configuration files].
+The properties API allows domain objects to read the configuration properties aggregated from the various xref:rgcfg.adoc#_rgcfg_configuration-files[configuration files].
 
 [source,java]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_EmailService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_EmailService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_EmailService.adoc
index 314dfcd..df18a4f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_EmailService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_EmailService.adoc
@@ -45,7 +45,7 @@ To use this service the following properties must be configured:
 * `isis.service.email.sender.address`
 * `isis.service.email.sender.password`
 
-and these properties may optionally be configured (each has a default to use gmail, documented xref:rg.adoc#_rg_runtime_configuring-core[here]):
+and these properties may optionally be configured (each has a default to use gmail, documented xref:rgcfg.adoc#_rgcfg_configuring-core[here]):
 
 * `isis.service.email.sender.hostname`
 * `isis.service.email.port`

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_EventBusService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_EventBusService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_EventBusService.adoc
index 4d5bd58..1145626 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_EventBusService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_EventBusService.adoc
@@ -348,7 +348,7 @@ If you do provide your own implementation of this SPI, be aware that your subscr
 
 The implementation of `EventBusService` provided by Apache Isis will by default use link:https://code.google.com/p/guava-libraries/[Guava]'s https://code.google.com/p/guava-libraries/wiki/EventBusExplained[`EventBus`] as the underlying in-memory event bus.  Alternatively the link:http://www.axonframework.org/[AxonFramework]'s link:http://www.axonframework.org/docs/2.4/single.html#d5e1489[SimpleEventBus] can be used.
 
-To specify which, add the xref:rg.adoc#_rg_runtime_configuring-core[configuration property] `isis.services.eventbus.implementation`:
+To specify which, add the xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.services.eventbus.implementation`:
 
 [source,ini]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_FixtureScriptsDefault.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_FixtureScriptsDefault.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_FixtureScriptsDefault.adoc
index 1176a8c..9c3d5dc 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_FixtureScriptsDefault.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_FixtureScriptsDefault.adoc
@@ -40,7 +40,7 @@ public class FixtureScriptsDefault ... {
 
 As noted in the introduction, this service is only instantiated if there is no other implementation of `FixtureScripts` available on the classpath.
 
-If an instance of `FixtureScriptsSpecificationProvider` is available on the classpath, then the service will be visible in the UI (assuming xref:rg.adoc#_rg_runtime_deployment-types[prototype mode]).  Otherwise the service will be available only to be injected and invoked programmatically.
+If an instance of `FixtureScriptsSpecificationProvider` is available on the classpath, then the service will be visible in the UI (assuming xref:rgcfg.adoc#_rgcfg_deployment-types[prototype mode]).  Otherwise the service will be available only to be injected and invoked programmatically.
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ContentNegotiationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ContentNegotiationService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ContentNegotiationService.adoc
index 29d3ceb..e6098d9 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ContentNegotiationService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ContentNegotiationService.adoc
@@ -171,14 +171,14 @@ image::{_imagesdir}reference-services-spi/ContentNegotiationService/accept-json.
 [_rgsvc-spi_ContentNegotiationService_Configuration]]
 == Configuration
 
-The default `ContentNegotiationServiceXRoDomainType` implementation provides a xref:rg.adoc#_rg_runtime_configuring-core[configuration property] which controls whether a mapped domain object is pretty-printed (formatted, indented) or not:
+The default `ContentNegotiationServiceXRoDomainType` implementation provides a xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] which controls whether a mapped domain object is pretty-printed (formatted, indented) or not:
 
 [source,ini]
 ----
 isis.services.ContentNegotiationServiceXRoDomainType.prettyPrint=true
 ----
 
-If the property is not set, then the default depends on the xref:rg.adoc#_rg_runtime_deployment-types[deployment type]; production mode will disable pretty printing, while prototyping mode will enable it.
+If the property is not set, then the default depends on the xref:rgcfg.adoc#_rgcfg_deployment-types[deployment type]; production mode will disable pretty printing, while prototyping mode will enable it.
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/1409af28/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ExceptionRecognizer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ExceptionRecognizer.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ExceptionRecognizer.adoc
index 8b130b2..a120ccd 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ExceptionRecognizer.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ExceptionRecognizer.adoc
@@ -115,5 +115,5 @@ isis.services=...,\
 Prior to 1.9.0, the `ExceptionRecognizerCompositeForJdoObjectStore` also required manual registration.
 ====
 
-If the JDO exception recognizers are not required (rather unlikely), then they can be disabled en-masse using the xref:rg.adoc#_rg_runtime_configuring-core[configuration property] `isis.services.ExceptionRecognizerCompositeForJdoObjectStore.disable`.
+If the JDO exception recognizers are not required (rather unlikely), then they can be disabled en-masse using the xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.services.ExceptionRecognizerCompositeForJdoObjectStore.disable`.
 


[12/52] [abbrv] isis git commit: ISIS-1243: removing manpage from .adoc file names.

Posted by mg...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_validation-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_validation-api.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_validation-api.adoc
index 30dbc15..fe1b732 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_validation-api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_validation-api.adoc
@@ -6,7 +6,7 @@
 
 
 
-The validation API allows a domain object to programmatically validate itself or any other domain object.  Specifically, this means the validating the current state of all properties, as well as any object-level validation defined by xref:rgcms.adoc#_rgcms_methods_reserved_manpage-validate[`validate()`].
+The validation API allows a domain object to programmatically validate itself or any other domain object.  Specifically, this means the validating the current state of all properties, as well as any object-level validation defined by xref:rgcms.adoc#_rgcms_methods_reserved_validate[`validate()`].
 
 The API provided is:
 
@@ -23,4 +23,4 @@ public interface DomainObjectContainer {
 
 If an object is changed by editing its properties, then (using the xref:ugvw.adoc#[Wicket viewer] at least) Apache Isis will check that the state of the object is valid.  There is currently however no equivalent guarantee for actions.
 
-The intent of this API was (originally at least) to provide a fallback whereby actions could at least be able to perform this validation programmatically (eg in their own xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-validate[`validate...()`] or xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-disable[`disable...()`] methods.  However, this feature should be considered experimental; your mileage may vary.
\ No newline at end of file
+The intent of this API was (originally at least) to provide a fallback whereby actions could at least be able to perform this validation programmatically (eg in their own xref:rgcms.adoc#_rgcms_methods_prefixes_validate[`validate...()`] or xref:rgcms.adoc#_rgcms_methods_prefixes_disable[`disable...()`] methods.  However, this feature should be considered experimental; your mileage may vary.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_EventBusService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_EventBusService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_EventBusService.adoc
index b2d620a..7fdde83 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_EventBusService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_EventBusService.adoc
@@ -89,7 +89,7 @@ This works for both singleton (application-scoped) and also xref:rgant.adoc#_rga
 
 [TIP]
 ====
-The xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractSubscriber[`AbstractSubscriber`] class automatically performs this
+The xref:rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[`AbstractSubscriber`] class automatically performs this
 registration.  As a convenience, (as of `1.11.0-SNAPSHOT`) it is also annotated with the
 xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] attribute.
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_FixtureScriptsDefault.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_FixtureScriptsDefault.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_FixtureScriptsDefault.adoc
index ac22f43..83e2fbb 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_FixtureScriptsDefault.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_FixtureScriptsDefault.adoc
@@ -8,13 +8,13 @@
 
 The `FixtureScriptsDefault` service provides the ability to execute xref:ugtst.adoc#_ugtst_fixture-scripts_api-and-usage[fixture scripts] .
 
-The service extends from the xref:rgcms.adoc#_rgcms_classes_super_manpage-FixtureScripts[`FixtureScripts`], and is only instantiated by the framework if there no custom implementation of `FixtureScripts` has been otherwise provided; in other words it is a fallback.
+The service extends from the xref:rgcms.adoc#_rgcms_classes_super_FixtureScripts[`FixtureScripts`], and is only instantiated by the framework if there no custom implementation of `FixtureScripts` has been otherwise provided; in other words it is a fallback.
 
 If this service is instantiated (as a fallback) then it uses the xref:rgsvc.adoc#_rgsvc-spi_FixtureScriptsSpecificationProvider[`FixtureScriptsSpecificationProvider`] to obtain a `FixtureScriptsSpecification`.  This configures this service, telling it which package to search for `FixtureScript` classes, how to execute those classes, and hints that influence the UI.
 
 [TIP]
 ====
-We recommend using xref:rgsvc.adoc#_rgsvc-spi_FixtureScriptsSpecificationProvider[`FixtureScriptsSpecificationProvider`] rather than subclassing xref:rgcms.adoc#_rgcms_classes_super_manpage-FixtureScripts[`FixtureScripts`].
+We recommend using xref:rgsvc.adoc#_rgsvc-spi_FixtureScriptsSpecificationProvider[`FixtureScriptsSpecificationProvider`] rather than subclassing xref:rgcms.adoc#_rgcms_classes_super_FixtureScripts[`FixtureScripts`].
 ====
 
 
@@ -33,7 +33,7 @@ public class FixtureScriptsDefault ... {
 }
 ----
 
-... in other words the same as xref:rgcms.adoc#_rgcms_classes_super_manpage-FixtureScripts[`FixtureScripts`] superclass that it inherits from.
+... in other words the same as xref:rgcms.adoc#_rgcms_classes_super_FixtureScripts[`FixtureScripts`] superclass that it inherits from.
 
 
 == Configuration

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_JaxbService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_JaxbService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_JaxbService.adoc
index 5008e43..198534d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_JaxbService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_JaxbService.adoc
@@ -50,7 +50,7 @@ Isis provides a default implementation of the service, `o.a.i.schema.services.ja
 This service is provided as a convenience for applications, but is also used internally by the framework to
 xref:rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`]-annotated
 xref:ugbtb.adoc#_ugbtb_more-advanced_view-models[view models].  The functionality to download XML and XSD schemas is also
-exposed in the UI through mixins to xref:rgcms.adoc#_rgcms_classes_roles_manpage-Dto[`Dto`] interface.
+exposed in the UI through mixins to xref:rgcms.adoc#_rgcms_classes_roles_Dto[`Dto`] interface.
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_MementoService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_MementoService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_MementoService.adoc
index 3014184..7196374 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_MementoService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_MementoService.adoc
@@ -71,7 +71,7 @@ If using another implementation, the `canSet(...)` method can be used to check i
 
 == Usage
 
-As noted in the introduction, a common use case for this service is in the implementation of the xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractViewModel[`ViewModel`] interface.
+As noted in the introduction, a common use case for this service is in the implementation of the xref:rgcms.adoc#_rgcms_classes_super_AbstractViewModel[`ViewModel`] interface.
 
 [TIP]
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_WrapperFactory.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_WrapperFactory.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_WrapperFactory.adoc
index 2fc4fa4..d83af8a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_WrapperFactory.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_WrapperFactory.adoc
@@ -74,8 +74,8 @@ Calling any of the above methods may result in a (subclass of) `InteractionExcep
 
 In addition, the following methods may also be called:
 
-* the xref:rgcms.adoc#_rgcms_methods_reserved_manpage-title[`title()`] and `toString()` methods
-* any xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-default[`default...()`], xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-choices[`choices...()`] or xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-autoComplete[`autoComplete...()`] methods
+* the xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`] and `toString()` methods
+* any xref:rgcms.adoc#_rgcms_methods_prefixes_default[`default...()`], xref:rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`] or xref:rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`] methods
 
 An exception will be thrown if any other methods are thrown.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi.adoc
index 1d3f6cb..026909d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi.adoc
@@ -60,7 +60,7 @@ The table below lists the SPIs that are defined in the Isis applib (`o.a.i.core:
 `ClassDiscoveryService`]
 |Mechanism to locate (from the classpath) classes with a specific annotation (eg xref:rgant.adoc#_rgant-DomainService[`@DomainService`])
 
-Subtypes of a given type (eg xref:rgcms.adoc#_rgcms_classes_super_manpage-FixtureScript[`FixtureScript`]).
+Subtypes of a given type (eg xref:rgcms.adoc#_rgcms_classes_super_FixtureScript[`FixtureScript`]).
 |`ClassDiscoveryService-` +
 `UsingReflections` +
 ``o.a.i.core`` +

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_AuditingService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_AuditingService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_AuditingService.adoc
index a07c4fb..c8d8a62 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_AuditingService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_AuditingService.adoc
@@ -46,7 +46,7 @@ The module also provides:
 
 * `AuditingServiceRepository` service to to search for persisted `AuditEntry``s.  None of its actions are visible in the user interface (they are all `@Programmatic`).
 
-* `AuditingServiceContributions` which contrbutes collections to the xref:rgcms.adoc#_rgcms_classes_mixins_manpage-HasTransactionId[ `HasTransactionId`] interface. This will therefore display all audit entries that occurred in a given transaction, in other words whenever a command, a published event or another audit entry is displayed.
+* `AuditingServiceContributions` which contrbutes collections to the xref:rgcms.adoc#_rgcms_classes_mixins_HasTransactionId[ `HasTransactionId`] interface. This will therefore display all audit entries that occurred in a given transaction, in other words whenever a command, a published event or another audit entry is displayed.
 
 
 
@@ -81,5 +81,5 @@ The auditing service works very well with the xref:rgsvc.adoc#_rgsvc-spi_Command
 
 You may also want to configure the xref:rgsvc.adoc#_rgsvc-spi_PublishingService[`PublishingService`].
 
-All three of these services collaborate implicitly by way of the xref:rgcms.adoc#_rgcms_classes_mixins_manpage-HasTransactionId[`HasTransactionId`] interface.
+All three of these services collaborate implicitly by way of the xref:rgcms.adoc#_rgcms_classes_mixins_HasTransactionId[`HasTransactionId`] interface.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ClassDiscoveryService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ClassDiscoveryService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ClassDiscoveryService.adoc
index 583acef..8203208 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ClassDiscoveryService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ClassDiscoveryService.adoc
@@ -8,7 +8,7 @@
 
 The `ClassDiscovery` service is used to automatically discover subclasses of any given type on the classpath.  The primary use case is to support "convention-over-configuration" designs that work with a minimum of configuration.
 
-This service is used by the xref:rgcms.adoc#_rgcms_classes_super_manpage-FixtureScripts[`FixtureScripts`] service to automatically locate any xref:rgcms.adoc#_rgcms_classes_super_manpage-FixtureScript[`FixtureScript`] implementations.
+This service is used by the xref:rgcms.adoc#_rgcms_classes_super_FixtureScripts[`FixtureScripts`] service to automatically locate any xref:rgcms.adoc#_rgcms_classes_super_FixtureScript[`FixtureScript`] implementations.
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_CommandService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_CommandService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_CommandService.adoc
index 0382e91..b62629b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_CommandService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_CommandService.adoc
@@ -12,8 +12,8 @@ Persistent `Command`s support several use cases:
 
 * they enable profiling of the running application (which actions are invoked then most often, what is their response time)
 * they act as a parent to any background commands that might be invoked through the xref:rgsvc.adoc#_rgsvc-api_BackgroundService[`BackgroundService`]
-* if xref:rgsvc.adoc#_rgsvc-spi_AuditingService[auditing] is configured, they provide better audit information, since the `Command` (the 'cause' of an action) can be correlated to the audit records (the "effect" of the action) by way of the xref:rgcms.adoc#_rgcms_classes_mixins_manpage-HasTransactionId[`transactionId`]
-* if xref:rgsvc.adoc#_rgsvc-spi_PublishingService[publishing] is configured, they provide better traceability as the `Command` is also correlated with any published events, again through the unique  xref:rgcms.adoc#_rgcms_classes_mixins_manpage-HasTransactionId[`transactionId`]
+* if xref:rgsvc.adoc#_rgsvc-spi_AuditingService[auditing] is configured, they provide better audit information, since the `Command` (the 'cause' of an action) can be correlated to the audit records (the "effect" of the action) by way of the xref:rgcms.adoc#_rgcms_classes_mixins_HasTransactionId[`transactionId`]
+* if xref:rgsvc.adoc#_rgsvc-spi_PublishingService[publishing] is configured, they provide better traceability as the `Command` is also correlated with any published events, again through the unique  xref:rgcms.adoc#_rgcms_classes_mixins_HasTransactionId[`transactionId`]
 * the associated xref:rgant.adoc#_rgant-Action_command[`@Action#command()`] annotation attribute also allows action invocations to be performed in the background. In this case the act of invoking the action on an object instead returns the `Command` to the user.
 
 
@@ -96,5 +96,5 @@ The services provided by this module combines very well with the xref:rgsvc.adoc
 
 You may also want to configure the xref:rgsvc.adoc#_rgsvc-spi_PublishingService[`PublishingService`].
 
-All three of these services collaborate implicitly by way of the xref:rgcms.adoc#_rgcms_classes_mixins_manpage-HasTransactionId[`HasTransactionId`] interface.
+All three of these services collaborate implicitly by way of the xref:rgcms.adoc#_rgcms_classes_mixins_HasTransactionId[`HasTransactionId`] interface.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_EventSerializer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_EventSerializer.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_EventSerializer.adoc
index 9aed9ab..7ffe90f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_EventSerializer.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_EventSerializer.adoc
@@ -25,7 +25,7 @@ public interface EventSerializer {
 }
 ----
 <1> returns an object for maximum flexibility, which is then handed off to the `PublishingService`.
-<2> standard metadata about the event, such as the user, the xref:rgcms.adoc#_rgcms_classes_mixins_manpage-HasTransactionId[`transactionId`], date/time etc
+<2> standard metadata about the event, such as the user, the xref:rgcms.adoc#_rgcms_classes_mixins_HasTransactionId[`transactionId`], date/time etc
 <3> for published actions, will generally be an `EventPayloadForActionInvocation` (or subclass thereof); for published objects, will generally be an `EventPayloadForObjectChanged` (or subclass thereof)
 
 It's important to make sure that the publishing service implementation is able to handle the serialized form.  Strings are a good lowest common denominator, but in some cases a type-safe equivalent, such as a w3c DOM `Document` or JSON node might be passed instead.

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_FixtureScriptsSpecificationProvider.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_FixtureScriptsSpecificationProvider.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_FixtureScriptsSpecificationProvider.adoc
index 4fffe73..5c9dea3 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_FixtureScriptsSpecificationProvider.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_FixtureScriptsSpecificationProvider.adoc
@@ -11,7 +11,7 @@ xref:rgsvc.adoc#_rgsvc-api_FixtureScriptsDefault[`FixtureScriptsDefault`] domain
 location to search for fixture scripts and other settings.
 
 The service is only used if the `FixtureScriptsDefault` service is instantiated as a fallback by the framework.  If
-the application provides its own subclass of xref:rgcms.adoc#_rgcms_classes_super_manpage-FixtureScripts[`FixtureScripts`]
+the application provides its own subclass of xref:rgcms.adoc#_rgcms_classes_super_FixtureScripts[`FixtureScripts`]
 superclass, then this provider service is not used.
 
 [TIP]

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_PublishingService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_PublishingService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_PublishingService.adoc
index 62634ff..97d1dc3 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_PublishingService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_PublishingService.adoc
@@ -25,7 +25,7 @@ public interface PublishingService {
     void setEventSerializer(EventSerializer eventSerializer);   // <3>
 }
 ----
-<1> standard metadata about the event, such as the user, the xref:rgcms.adoc#_rgcms_classes_mixins_manpage-HasTransactionId[`transactionId`], date/time etc
+<1> standard metadata about the event, such as the user, the xref:rgcms.adoc#_rgcms_classes_mixins_HasTransactionId[`transactionId`], date/time etc
 <2> for published actions, an `EventPayloadForActionInvocation` (or subclass thereof); for published objects, an `EventPayloadForObjectChanged` (or subclass thereof)
 <3> injects in the xref:rgsvc.adoc#_rgsvc-spi_EventSerializer[`EventSerializer`] service.  This is deprecated because not every implementation is required to use an `EventSerializer` so its inclusion within the SPI of `PublishingService` was in retrospect a mistake.
 
@@ -178,7 +178,7 @@ The `PublishingService` is intended for coarse-grained publish/subscribe for sys
 
 The xref:rgsvc.adoc#_rgsvc-api_EventBusService[`EventBusService`] meanwhile is intended for fine-grained publish/subscribe for object-to-object interactions within an Apache Isis domain object model. The event propagation is strictly in-memory, and there are no restrictions on the object acting as the event (it need not be serializable, for example).
 
-All three of these services collaborate implicitly by way of the xref:rgcms.adoc#_rgcms_classes_mixins_manpage-HasTransactionId[`HasTransactionId`] interface.
+All three of these services collaborate implicitly by way of the xref:rgcms.adoc#_rgcms_classes_mixins_HasTransactionId[`HasTransactionId`] interface.
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_tg_stop-scaffolding-start-coding.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_tg_stop-scaffolding-start-coding.adoc b/adocs/documentation/src/main/asciidoc/guides/_tg_stop-scaffolding-start-coding.adoc
index 0b88f42..f4d40a3 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_tg_stop-scaffolding-start-coding.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_tg_stop-scaffolding-start-coding.adoc
@@ -307,7 +307,7 @@ Domain entities have state: either values (primitives, strings) or references to
 * for all non-optional properties will either need to prompt for a value, or calculate some suitable default
 * change the implementation of title, if need be
 * revisit the title, consider whether to use the xref:rgant.adoc#_rgant-Title[`@Title`] annotation
-** rather than the xref:rgcms.adoc#_rgcms_methods_reserved_manpage-title[`title()`] `title()` method
+** rather than the xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`] `title()` method
 * order the properties using the xref:rgant.adoc#_rgant-MemberOrder[`@MemberOrder`], also `@MemberGroupLayout`
 ** see also the docs on xref:ug.adoc#_ug_object-layout_static[static layouts]
 * use the xref:rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`] annotation to position property/action parameter labels either to the LEFT, TOP or NONE
@@ -324,10 +324,10 @@ Domain entities can also reference other domain entities. These references may b
 * update the corresponding domain service (for creation actoin)
 * use different techniques to obtain references (shown in drop-down list box)
 ** use the xref:rgant.adoc#_rgant-DomainObject_bounded[`@DomainObjectLayout(bounded=...)`] annotation on the referenced type if there are only a small number (bounded) of instances
-** use a xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-choices[`choices...()`] supporting method
+** use a xref:rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`] supporting method
 *** on a property
 *** on an action parameter
-** use a xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-autoComplete[`autoComplete...()`] supporting method
+** use a xref:rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`] supporting method
 *** on a property
 *** on an action parameter
 
@@ -348,7 +348,7 @@ Quick detour: often we want to set up defaults to go with choices. Sensible defa
 Returning back to references, Isis also supports vector (multi-valued) references to another object instances� in other words collections. We sometimes called these "parented" collections (to distinguish from a "standalone" collection as returned from an action)
 
 * Ensure that all domain classes implement `java.lang.Comparable`
-** use the xref:rgcms.adoc#_rgcms_classes_utility_manpage-ObjectContracts[`ObjectContracts`] utility class to help implement `Comparable`
+** use the xref:rgcms.adoc#_rgcms_classes_utility_ObjectContracts[`ObjectContracts`] utility class to help implement `Comparable`
 *** you can also `equals()`, `hashCode()`, `toString()`
 * Add a xref:ug.adoc#_ug_how-tos_class-structure_collections[collection] to one of the entities
 ** Use `SortedSet` as the class
@@ -413,7 +413,7 @@ Or, more pithily: "see it, use it, do it"
 * Use the xref:rgant.adoc#_rgant-Property_hidden[`Property(hidden=...)`] annotation to make properties invisible
 ** likewise xref:rgant.adoc#_rgant-Collection_hidden[`@Collection(hidden=...)`] for collections
 ** the xref:rgant.adoc#_rgant-Programmatic[`@Programmatic`]  annotation can also be used and in many cases is to be preferred; the difference is that the latter means the member is not part of the Apache Isis metamodel.
-* Use the xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-hide[`hide...()`] supporting method on properties, collections and actions to make a property/collection/action invisible according to some imperative rule
+* Use the xref:rgcms.adoc#_rgcms_methods_prefixes_hide[`hide...()`] supporting method on properties, collections and actions to make a property/collection/action invisible according to some imperative rule
 
 
 === Use it!
@@ -421,14 +421,14 @@ Or, more pithily: "see it, use it, do it"
 * Use the xref:rgant.adoc#_rgant-Property_editing[`Property(editing=...)`] annotation to make property read-only
 ** likewise xref:rgant.adoc#_rgant-Collection_editing[`@Collection(editing=...)`] for collections
 ** alternatively, use xref:rgant.adoc#_rgant-DomainObject_editing[`@DomainObject(editing=...)`] to disable editing for all properties/collections
-* Use the xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-disable[`disable...()`] supporting method on properties and actions to make a property/action disabled according to some imperative rule
+* Use the xref:rgcms.adoc#_rgcms_methods_prefixes_disable[`disable...()`] supporting method on properties and actions to make a property/action disabled according to some imperative rule
 
 
 === Do it!
 
 * use the xref:rgant.adoc#_rgant-Property_regexPattern[`@Property(regexPattern=...)`] annotation to specify a regex pattern for properties, and use xref:rgant.adoc#_rgant-Parameter_regexPattern[`@Parameter(regexPattern=...)`] for parameters
 * use the xref:rgant.adoc#_rgant-Property_maxLength[`@Property(maxLength=...)`] annotation to indicate a maxmum number of characters, and xref:rgant.adoc#_rgant-Parameter_maxLength[`@Parameter(maxLength=...)`] for parameters
-* Use the xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-validate[`validate...()`] supporting method on properties or action parameter
+* Use the xref:rgcms.adoc#_rgcms_methods_prefixes_validate[`validate...()`] supporting method on properties or action parameter
 * optional: for any data type:
 ** use the xref:rgant.adoc#_rgant-Property_mustSatisfy[`Property(mustSatisfy=...)`] and xref:rgant.adoc#_rgant-Parameter_mustSatisfy[`Parameter(mustSatisfy=...)`] annotations to specify arbitrary constraints on properties and parameters
 
@@ -602,7 +602,7 @@ In most cases users can accomplish the business operations they need by invoking
 
 Also, if using Apache Isis' REST API then the REST client may be a native application (on a smartphone or tablet, say) that is deployed by a third party. In these cases exposing the entities directly would be inadvisable because a refactoring of the domain entity would change the REST API and probably break that REST client.
 
-To support these use cases, Apache Isis therefore allows you to write a view model, either by annotating the class with xref:rgant.adoc#_rgant-ViewModel[`@ViewModel`] or (for more control) by implementing the xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractViewModel[`ViewModel`] interface.
+To support these use cases, Apache Isis therefore allows you to write a view model, either by annotating the class with xref:rgant.adoc#_rgant-ViewModel[`@ViewModel`] or (for more control) by implementing the xref:rgcms.adoc#_rgcms_classes_super_AbstractViewModel[`ViewModel`] interface.
 
 * build a view model summarizing the state of the app (a "dashboard")
 * write a new `@HomePage` domain service action returning this dashboard viewmodel (and remove the `@HomePage` annotation from any other domain service if present)

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_cqrs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_cqrs.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_cqrs.adoc
index 5f5b82f..0a59241 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_cqrs.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_cqrs.adoc
@@ -17,7 +17,7 @@ Comparing CQRS to Apache Isis, the most obvious difference is that Apache Isis d
 
 There are other reasons though why a separate read model might make sense, such as to precompute particular queries, or against denormalized data.  In these cases Apache Isis can often provide a reasonable alternative, namely to map domain entities against RDBMS views, either materialized views or dynamic.  In such cases there is still only a single physical datastore, and so transactional integrity is retained.
 
-Or, the CQRS architecture can be more fully implemented with Apache Isis by introducing a separate read model, synchronized using the xref:rgsvc.adoc#_rgsvc-api_PublishingService[`PublishingService`], or using xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractSubscriber[subscribers]  on the xref:rgsvc.adoc#_rgsvc-api_EventBusService[`EventBusService`].  One can then use xref:ugbtb.adoc#_ugbtb_more-advanced_view-models[view models] to surface the data in the external read datastore.
+Or, the CQRS architecture can be more fully implemented with Apache Isis by introducing a separate read model, synchronized using the xref:rgsvc.adoc#_rgsvc-api_PublishingService[`PublishingService`], or using xref:rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscribers]  on the xref:rgsvc.adoc#_rgsvc-api_EventBusService[`EventBusService`].  One can then use xref:ugbtb.adoc#_ugbtb_more-advanced_view-models[view models] to surface the data in the external read datastore.
 
 With respect to commands, Apache Isis does of course support the xref:rgsvc.adoc#_rgsvc-spi_CommandService[`CommandService`] which allows each business action to be reified into a `Command`.  However, names are misleading here: Apache Isis' commands are relatively passive, merely recording the intent of the user to invoke some operation.  In a CQRS architecture, though, commands take a more active role, locating and acting upon the domain objects.  More significantly, in CQRS each command has its own class, such as `PlaceOrderCommand`, instantiated by the client and then executed.  With Apache Isis, though, the end-user merely invokes the `placeOrder(...)` action upon the domain object; the framework itself creates the `Command` as a side-effect of this.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_event-sourcing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_event-sourcing.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_event-sourcing.adoc
index f9653d8..3e756ee 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_event-sourcing.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_event-sourcing.adoc
@@ -14,6 +14,6 @@ Although it might seem counter-intuitive to be able store persistent state in th
 
 When combined with CQRS we see a command that triggers a business operation, and an event that results from it.  So, a `PlaceOrderCommand` command can result in an `OrderPlacedEvent` event.  A subscriber to this event might then generate a further command to act upon some other system (eg to dispatch the system).  Note that the event might be dispatched and consumed in-process or alternatively this might occur out-of-process.  If the latter, then the subscriber will operate within a separate transaction, meaning the usual eventual consistency concerns and also compensating actions if a rollback is required.  CQRS/event sourcing advocates point out - correctly  that this is just how things are in the "real world" too.
 
-In Apache Isis every business action (and indeed, property and collection) emits domain events through the xref:rgsvc.adoc#_rgsvc-api_EventBusService[`EventBusService`] , and can optionally also be published through the xref:rgsvc.adoc#_rgsvc-spi_PublishingService[`PublishingService`].  The former are dispatched and consumed in-process and within the same transaction, and for this reason the xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractSubscriber[subscribers] can also veto the events.  The latter are intended for out-of-process consumption; the (non-ASF) http://github.com/isisaddons/isis-module-publishing[Isis addons' publishing] and http://github.com/isisaddons/isis-module-publishmq[Isis addons' publishmq] modules provide implementations for dispatching either through a RDBMS database table, or directly through to an link:http://camel.apache.org[ActiveMQ] message queue (eg wired up to link:http://camel.apache.org[Apache Camel] event bus).
+In Apache Isis every business action (and indeed, property and collection) emits domain events through the xref:rgsvc.adoc#_rgsvc-api_EventBusService[`EventBusService`] , and can optionally also be published through the xref:rgsvc.adoc#_rgsvc-spi_PublishingService[`PublishingService`].  The former are dispatched and consumed in-process and within the same transaction, and for this reason the xref:rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscribers] can also veto the events.  The latter are intended for out-of-process consumption; the (non-ASF) http://github.com/isisaddons/isis-module-publishing[Isis addons' publishing] and http://github.com/isisaddons/isis-module-publishmq[Isis addons' publishmq] modules provide implementations for dispatching either through a RDBMS database table, or directly through to an link:http://camel.apache.org[ActiveMQ] message queue (eg wired up to link:http://camel.apache.org[Apache Camel] event bus).
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_ug_faqs_restful-image-property.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_faqs_restful-image-property.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_faqs_restful-image-property.adoc
index 12ddcf2..d025e8a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_faqs_restful-image-property.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_faqs_restful-image-property.adoc
@@ -15,6 +15,6 @@ This is in the form:
 
     (filename):(mime type):(binary data in base64)
 
-This is basically the xref:rgcms.adoc#_rgcms_classes_value-types_manpage-Blob[`Blob`] value type, in string form.
+This is basically the xref:rgcms.adoc#_rgcms_classes_value-types_Blob[`Blob`] value type, in string form.
 
 To use, split the parts then format the mime type and base64 data correctly before using as source in an `<img>` tag.

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_business-rules.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_business-rules.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_business-rules.adoc
index aeea83e..71794c6 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_business-rules.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_business-rules.adoc
@@ -10,7 +10,7 @@ NOTE: TODO
 
 == Visibility ("see it")
 
-NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-hide[`hide...()`]
+NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_hide[`hide...()`]
 
 ### Hide a Property
 
@@ -27,7 +27,7 @@ NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-hide[`hide...()`]
 
 == Usability ("use it")
 
-NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-disable[`disable...()`]
+NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_disable[`disable...()`]
 
 ### Disable a Property
 
@@ -53,7 +53,7 @@ In the Wicket viewer this means disabling the edit button.
 
 == Validity ("do it")
 
-NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-validate[`validate...()`], xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-validateAddTo[`validateAddTo...()`], xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-validateRemoveFrom[`validateRemoveFrom...()`] and xref:rgcms.adoc#_rgcms_methods_reserved_manpage-validate[`validate()`]
+NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_validate[`validate...()`], xref:rgcms.adoc#_rgcms_methods_prefixes_validateAddTo[`validateAddTo...()`], xref:rgcms.adoc#_rgcms_methods_prefixes_validateRemoveFrom[`validateRemoveFrom...()`] and xref:rgcms.adoc#_rgcms_methods_reserved_validate[`validate()`]
 
 
 ### Validate (change to) a Property

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_derived-members.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_derived-members.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_derived-members.adoc
index abe2ae8..dea0b06 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_derived-members.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_derived-members.adoc
@@ -39,10 +39,10 @@ public class Customer {
 
 == Trigger on property change
 
-NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-modify[`modify...()`], xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-clear[`clear...()`]
+NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_modify[`modify...()`], xref:rgcms.adoc#_rgcms_methods_prefixes_clear[`clear...()`]
 
 
 
 == Trigger on collection change
 
-NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-addTo[`addTo...()`], xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-removeFrom[`removeFrom...()`]
+NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_addTo[`addTo...()`], xref:rgcms.adoc#_rgcms_methods_prefixes_removeFrom[`removeFrom...()`]

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_domain-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_domain-services.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_domain-services.adoc
index 16c131a..eea9859 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_domain-services.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_domain-services.adoc
@@ -309,5 +309,5 @@ Shutdown is similar; the framework will call any method annotated with xref:rgan
 
 == The getId() method
 
-Optionally, a service may provide a xref:rgcms.adoc#_rgcms_methods_reserved_manpage-getId[`getId()`] method.  This method returns a logical identifier for a service, independent of its implementation.
+Optionally, a service may provide a xref:rgcms.adoc#_rgcms_methods_reserved_getId[`getId()`] method.  This method returns a logical identifier for a service, independent of its implementation.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_drop-downs-and-defaults.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_drop-downs-and-defaults.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_drop-downs-and-defaults.adoc
index c6bc242..94891a7 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_drop-downs-and-defaults.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_drop-downs-and-defaults.adoc
@@ -13,15 +13,15 @@ NOTE: TODO
 
 ### Choices for Property
 
-NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-choices[`choices...()`]
+NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`]
 
 ### Auto-complete for property
 
-NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-autoComplete[`autoComplete...()`]
+NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`]
 
 ### Default for property
 
-NOTE: TODO -  xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-default[`default...()`]
+NOTE: TODO -  xref:rgcms.adoc#_rgcms_methods_prefixes_default[`default...()`]
 
 
 
@@ -32,19 +32,19 @@ NOTE: TODO
 
 ### Choices for action parameter
 
-NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-choices[`choices...()`]
+NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`]
 
 ### Dependent choices for action params
 
-NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-choices[`choices...()`]
+NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`]
 
 ### Auto-complete for action param
 
-NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-autoComplete[`autoComplete...()`]
+NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`]
 
 ### Default for action param
 
-NOTE: TODO -  xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-default[`default...()`]
+NOTE: TODO -  xref:rgcms.adoc#_rgcms_methods_prefixes_default[`default...()`]
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships.adoc
index f7ec25f..0b1d64a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships.adoc
@@ -8,7 +8,7 @@
 
 When an object is added to a 1:m bidirectional relationship, the child object must refer to the parent and the child must be added to the parent's children collection.
 
-If there were no database involved then we would have recommended that you use the link:http://www.two-sdg.demon.co.uk/curbralan/papers/MutualRegistration.pdf[mutual registration] pattern to ensure that both the parent and child are updated correctly.  (The  xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-modify[`modify...()`] and xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-clear[`clear...()`] supporting methods were introduced in the framework primarily to help support implement the mutual registration pattern.
+If there were no database involved then we would have recommended that you use the link:http://www.two-sdg.demon.co.uk/curbralan/papers/MutualRegistration.pdf[mutual registration] pattern to ensure that both the parent and child are updated correctly.  (The  xref:rgcms.adoc#_rgcms_methods_prefixes_modify[`modify...()`] and xref:rgcms.adoc#_rgcms_methods_prefixes_clear[`clear...()`] supporting methods were introduced in the framework primarily to help support implement the mutual registration pattern.
 
 However, in a relational database, these two operations in the domain object model correspond simply to updating the foreign key of the child table to reference the parent's primary key.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_object-titles-and-icons.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_object-titles-and-icons.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_object-titles-and-icons.adoc
index 2e4274d..1ec22ed 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_object-titles-and-icons.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_object-titles-and-icons.adoc
@@ -75,7 +75,7 @@ Titles can sometimes get be long and therefore rather cumbersome in "parented" t
 
 === Imperative style
 
-NOTE: TODO - see xref:rgcms.adoc#_rgcms_methods_reserved_manpage-title[`title()`]
+NOTE: TODO - see xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`]
 
 
 
@@ -84,7 +84,7 @@ NOTE: TODO - see xref:rgcms.adoc#_rgcms_methods_reserved_manpage-title[`title()`
 
 The icon is often the same for all instances of a particular class, but it's also possible for an individual instance to return a custom icon.  This could represent the state of that object (eg a shipped order, say, or overdue library book).
 
-NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_reserved_manpage-iconName[`iconName()`], xref:rgant.adoc#_rgant-DomainObjectLayout_cssClassFa[`@DomainObjectLayout#cssClassFa()`]
+NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`], xref:rgant.adoc#_rgant-DomainObjectLayout_cssClassFa[`@DomainObjectLayout#cssClassFa()`]
 
 
 
@@ -92,6 +92,6 @@ NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_reserved_manpage-iconName[`iconName(
 == Object CSS Styling
 
 
-It is also possible for an object to return a xref:rgcms.adoc#_rgcms_methods_reserved_manpage-cssClass[CSS class].  In conjunction with xref:ugvw.adoc#_ugvw_customisation_tweaking-css-classes[customized CSS] this can be used to apply arbitrary styling; for example each object could be rendered in a page with a different background colour.
+It is also possible for an object to return a xref:rgcms.adoc#_rgcms_methods_reserved_cssClass[CSS class].  In conjunction with xref:ugvw.adoc#_ugvw_customisation_tweaking-css-classes[customized CSS] this can be used to apply arbitrary styling; for example each object could be rendered in a page with a different background colour.
 
-NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_reserved_manpage-cssClass[`cssClass()`], xref:rgant.adoc#_rgant-DomainObjectLayout_cssClass[`@DomainObjectLayout#cssClass()`] xref:rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`], xref:rgant.adoc#_rgant-PropertyLayout_cssClass[`@PropertyLayout#cssClass()`], xref:rgant.adoc#_rgant-CollectionLayout_cssClass[`@CollectionLayout#cssClass()`]
+NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_reserved_cssClass[`cssClass()`], xref:rgant.adoc#_rgant-DomainObjectLayout_cssClass[`@DomainObjectLayout#cssClass()`] xref:rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`], xref:rgant.adoc#_rgant-PropertyLayout_cssClass[`@PropertyLayout#cssClass()`], xref:rgant.adoc#_rgant-CollectionLayout_cssClass[`@CollectionLayout#cssClass()`]

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui_are-you-sure.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui_are-you-sure.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui_are-you-sure.adoc
index 93d9fe8..2ce9903 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui_are-you-sure.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui_are-you-sure.adoc
@@ -73,4 +73,4 @@ public String validateDelete(boolean areYouSure) {
 <1> invalid to return `this` (cannot render a deleted object)
 
 Note that the action itself does not use the boolean parameter, it is only
-used by the supporting xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-validate[`validate...()`] method.
\ No newline at end of file
+used by the supporting xref:rgcms.adoc#_rgcms_methods_prefixes_validate[`validate...()`] method.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_ugbtb_deployment_cmd-line.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_deployment_cmd-line.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_deployment_cmd-line.adoc
index 7bc9c9c..2a26746 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_deployment_cmd-line.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_deployment_cmd-line.adoc
@@ -29,7 +29,7 @@ The class also supports a number of command line arguments:
 |`-m`
 |`--manifest`
 |FQCN
-|Fully qualified class name of the xref:rgcms.adoc#_rgcms_classes_super_manpage-AppManifest[`AppManifest`] to use to bootstrap the system. +
+|Fully qualified class name of the xref:rgcms.adoc#_rgcms_classes_super_AppManifest[`AppManifest`] to use to bootstrap the system. +
 
 This flag sets/overrides the `isis.appManifest` configuration property to the specified class name.
 
@@ -37,7 +37,7 @@ This flag sets/overrides the `isis.appManifest` configuration property to the sp
 |`-f`
 |`--fixture`
 |FQCN
-|Fully qualified class name of the fixture (extending xref:rgcms.adoc#_rgcms_classes_super_manpage-FixtureScript[`FixtureScript`]) to be run to setup data. +
+|Fully qualified class name of the fixture (extending xref:rgcms.adoc#_rgcms_classes_super_FixtureScript[`FixtureScript`]) to be run to setup data. +
 
 This flag sets/overrides the `isis.fixtures` configuration property to the specified class name, and also sets the `isis.persistor.datanucleus.install-fixtures` configuration property to `true` to instruct the JDO/DataNucleus objectstore to actually load in the fixtures. +
 

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_decoupling_mixins.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_decoupling_mixins.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_decoupling_mixins.adoc
index ea72d13..32b734f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_decoupling_mixins.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_decoupling_mixins.adoc
@@ -144,7 +144,7 @@ DocumentHolder_documents mixin = container.mixin(DocumentHolder_documents.class,
 ----
 
 The xref:ugtst.adoc#_ugtst_integ-test-support_bootstrapping_IntegrationTestAbstract[`IntegrationTestAbstract`] and
-xref:rgcms.adoc#_rgcms_classes_super_manpage-FixtureScript[`FixtureScript`] classes both provide a `mixin(...)` convenience
+xref:rgcms.adoc#_rgcms_classes_super_FixtureScript[`FixtureScript`] classes both provide a `mixin(...)` convenience
 method.
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_decoupling_pushing-changes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_decoupling_pushing-changes.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_decoupling_pushing-changes.adoc
index b357ec9..7cd2f5d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_decoupling_pushing-changes.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_decoupling_pushing-changes.adoc
@@ -134,7 +134,7 @@ public class Department {
 --
 <1> maintain a count of the number of male ...
 <2> ... and female employees (getters and setters omitted)
-<3> the xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-addTo[`addTo...()`] method increments the derived properties
-<4> the xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-removeFrom[`removeFrom...()`] method similarly decrements the derived properties
+<3> the xref:rgcms.adoc#_rgcms_methods_prefixes_addTo[`addTo...()`] method increments the derived properties
+<4> the xref:rgcms.adoc#_rgcms_methods_prefixes_removeFrom[`removeFrom...()`] method similarly decrements the derived properties
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_i18n.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_i18n.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_i18n.adoc
index fe40119..e119bac 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_i18n.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_i18n.adoc
@@ -7,7 +7,7 @@
 
 Apache Isis' support for i18n allows every element of the domain model (the class names, property names, action names, parameter names and so forth) to be translated.
 
-It also supports translations of messages raised imperatively, by which we mean as the result of a call to `title()` to obtain an object's title, or messages resulting from any business rule violations (eg xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-disable[`disable...()`] or xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-validate[`validate...()`], and so on.
+It also supports translations of messages raised imperatively, by which we mean as the result of a call to `title()` to obtain an object's title, or messages resulting from any business rule violations (eg xref:rgcms.adoc#_rgcms_methods_prefixes_disable[`disable...()`] or xref:rgcms.adoc#_rgcms_methods_prefixes_validate[`validate...()`], and so on.
 
 Isis does not translate the values of your domain objects, though.  So, if you have a domain concept such as `Country` whose name is intended to be localized according to the current user, you will need to model
 

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_view-models_programming-model.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_view-models_programming-model.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_view-models_programming-model.adoc
index 9f8bd86..e7305b4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_view-models_programming-model.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_view-models_programming-model.adoc
@@ -66,7 +66,7 @@ public class ExcelUploadManager implements ViewModel {
   public String viewModelMemento() { ... }
   public void viewModelInit(String memento) { ... }
 }
-|Implement xref:rgcms.adoc#_rgcms_classes_super_manpage-ViewModel[`ViewModel`] interface.  The memento is as defined by the
+|Implement xref:rgcms.adoc#_rgcms_classes_super_ViewModel[`ViewModel`] interface.  The memento is as defined by the
 interface's methods: the programmer has full control (but also full responsibility) for the string memento.
 
 |DTO (`1.11.0-SNAPSHOT`)

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_ugtst_aaa.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugtst_aaa.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugtst_aaa.adoc
index 2e89107..e75a29b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugtst_aaa.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugtst_aaa.adoc
@@ -125,7 +125,7 @@ In the previous section we discussed using given/when/then as a form of organizi
 
 For integration tests though it can be difficult to keep the "given" short; there could be a lot of prerequisite data that needs to exist before you can actually exercise your system.  Moreover, however we do set up that data, but we also want to do so in a way that is resilient to the system changing over time.
 
-The solution that Apache Isis provides is a domain service called xref:rgcms.adoc#_rgcms_classes_super_manpage-FixtureScripts[Fixture Scripts], that defines a pattern and supporting classes to help ensure that the "data setup" for your tests are reusable and maintainable over time.
+The solution that Apache Isis provides is a domain service called xref:rgcms.adoc#_rgcms_classes_super_FixtureScripts[Fixture Scripts], that defines a pattern and supporting classes to help ensure that the "data setup" for your tests are reusable and maintainable over time.
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_ugtst_integ-test-support_typical-usage.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugtst_integ-test-support_typical-usage.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugtst_integ-test-support_typical-usage.adoc
index d75f70c..310a002 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugtst_integ-test-support_typical-usage.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugtst_integ-test-support_typical-usage.adoc
@@ -58,7 +58,7 @@ public class ToDoItemIntegTest extends AbstractToDoIntegTest {
     ...
 }
 ----
-<1> the xref:rgcms.adoc#_rgcms_classes_super_manpage-FixtureScripts[`FixtureScripts`] domain service is injected, providing us with the ability to run fixture scripts
+<1> the xref:rgcms.adoc#_rgcms_classes_super_FixtureScripts[`FixtureScripts`] domain service is injected, providing us with the ability to run fixture scripts
 <2> likewise, an instance of the `ToDoItems` domain service is injected.  We'll use this to lookup...
 <3> the object under test, held as a field
 <4> the fixture script for this test; it deletes all existing todo items (for the current user only) and then recreates them

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_ugtst_unit-test-support_contract-tests.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugtst_unit-test-support_contract-tests.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugtst_unit-test-support_contract-tests.adoc
index 30c4f90..24f7e1e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugtst_unit-test-support_contract-tests.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugtst_unit-test-support_contract-tests.adoc
@@ -41,7 +41,7 @@ If using DataNucleus against an RDBMS (as you probably are) then we strongly rec
 
 * second, `SortedSet` is preferable to `Set` because then the order is well-defined and predictable (to an end user, to the programmer). +
 +
-The xref:rgcms.adoc#_rgcms_classes_utility_manpage-ObjectContracts[`ObjectContracts`]  utility class substantially simplifies the task of implementing `Comparable` in your domain classes.
+The xref:rgcms.adoc#_rgcms_classes_utility_ObjectContracts[`ObjectContracts`]  utility class substantially simplifies the task of implementing `Comparable` in your domain classes.
 
 * third, if the relationship is bidirectional then JDO/Objectstore will automatically maintain the relationship.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_ugvw_features_blob-attachments.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugvw_features_blob-attachments.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugvw_features_blob-attachments.adoc
index f150240..ffd425f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugvw_features_blob-attachments.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugvw_features_blob-attachments.adoc
@@ -6,7 +6,7 @@
 
 
 
-The Isis application library provides the xref:rgcms.adoc#_rgcms_classes_value-types_manpage-Blob[Blob] value type (binary large objects) and also the xref:rgcms.adoc#_rgcms_classes_value-types_manpage-Clob[Clob]
+The Isis application library provides the xref:rgcms.adoc#_rgcms_classes_value-types_Blob[Blob] value type (binary large objects) and also the xref:rgcms.adoc#_rgcms_classes_value-types_Clob[Clob]
 value type (character large object), each of which also includes metadata about the data (specifically the filename and mime type).
 
 A class can define a property using either of these types, for example:

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/rg.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rg.adoc b/adocs/documentation/src/main/asciidoc/guides/rg.adoc
deleted file mode 100644
index 0951d3b..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/rg.adoc
+++ /dev/null
@@ -1,27 +0,0 @@
-[[rg]]
-= Classes, Methods and Schema
-: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/
-:numbered:
-
-
-[[_rg]]
-= Classes, Methods and Schema
-
-This reference guide lists and describes various elements of the the Apache Isis Programming Model, specifically
-reserved and prefix xref:rgcms.adoc#_rgcms_methods[methods] (such as `title()` and `validate...()`) and various utility and
-supporting xref:rgcms.adoc#_rgcms_classes[classes].
-
-It also describes the xref:rgcms.adoc#_rgcms_schema[XSD schema] defined by Apache Isis.  One use case is for the
-JAXB serialization of view models (`1.11.0-SNAPSHOT`).
-
-
-This reference guide does _not_ describe how to actually build an Apache Isis application; for that see the *xref:ug.adoc#_ug[Users' Guide]*.  The reference guide also doesn't explain how to setup your development environment; for that see the *xref:cg.adoc#_cg[Contributors' Guide]*.
-
-
-
-
-include::_rgcms_methods.adoc[leveloffset=+1]
-include::_rgcms_classes.adoc[leveloffset=+1]
-include::_rgcms_schema.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/rgcms.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms.adoc
new file mode 100644
index 0000000..0951d3b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms.adoc
@@ -0,0 +1,27 @@
+[[rg]]
+= Classes, Methods and Schema
+: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/
+:numbered:
+
+
+[[_rg]]
+= Classes, Methods and Schema
+
+This reference guide lists and describes various elements of the the Apache Isis Programming Model, specifically
+reserved and prefix xref:rgcms.adoc#_rgcms_methods[methods] (such as `title()` and `validate...()`) and various utility and
+supporting xref:rgcms.adoc#_rgcms_classes[classes].
+
+It also describes the xref:rgcms.adoc#_rgcms_schema[XSD schema] defined by Apache Isis.  One use case is for the
+JAXB serialization of view models (`1.11.0-SNAPSHOT`).
+
+
+This reference guide does _not_ describe how to actually build an Apache Isis application; for that see the *xref:ug.adoc#_ug[Users' Guide]*.  The reference guide also doesn't explain how to setup your development environment; for that see the *xref:cg.adoc#_cg[Contributors' Guide]*.
+
+
+
+
+include::_rgcms_methods.adoc[leveloffset=+1]
+include::_rgcms_classes.adoc[leveloffset=+1]
+include::_rgcms_schema.adoc[leveloffset=+1]


[51/52] [abbrv] isis git commit: Merge branch 'ISIS-1223-upgrade-to-wicket-7' into ISIS-1224-select2-v4

Posted by mg...@apache.org.
Merge branch 'ISIS-1223-upgrade-to-wicket-7' into ISIS-1224-select2-v4


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/17d7159f
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/17d7159f
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/17d7159f

Branch: refs/heads/ISIS-1224-select2-v4
Commit: 17d7159fa58871c64bc70be3b467a139d7464a90
Parents: bd2a54b 803fbc1
Author: Martin Tzvetanov Grigorov <mg...@apache.org>
Authored: Sun Dec 13 14:01:35 2015 +0100
Committer: Martin Tzvetanov Grigorov <mg...@apache.org>
Committed: Sun Dec 13 14:01:35 2015 +0100

----------------------------------------------------------------------
 README.adoc                                     |   8 +-
 adocs/documentation/Gemfile                     |   3 +
 adocs/documentation/Gemfile.lock                |   5 +-
 adocs/documentation/monitor.rb                  |  70 +-
 adocs/documentation/publish.sh                  |   8 +-
 .../_migration-notes_1.10.0-to-1.11.0.adoc      |  58 ++
 ...o-1.9.0_bootstrapping-using-AppManifest.adoc |   4 +-
 ...tes_1.8.0-to-1.9.0_exception-recognizer.adoc |   6 +-
 ..._fixture-scripts-specification-provider.adoc |   4 +-
 ...1.8.0-to-1.9.0_specify-all-dom-packages.adoc |   6 +-
 ...n-notes_1.8.0-to-1.9.0_upgrading-to-dn4.adoc |   2 +-
 ...tion-notes_1.8.0-to-1.9.0_war-packaging.adoc |   4 +-
 .../_migration-notes_1.9.0-to-1.10.0.adoc       |   6 +-
 .../asciidoc/_powered-by_gesconsultor-grc.adoc  |   6 +-
 .../src/main/asciidoc/_release-notes_1.9.0.adoc |   2 +-
 .../src/main/asciidoc/common-use-cases.adoc     |   4 +-
 .../documentation/src/main/asciidoc/demos.adoc  |  18 -
 .../src/main/asciidoc/documentation.adoc        |  57 +-
 .../asciidoc/guides/_cg_asciidoc-templates.adoc | 257 ++----
 .../_cg_committers_post-release-successful.adoc |  18 +-
 .../main/asciidoc/guides/_cg_ide-templates.adoc |  62 +-
 .../src/main/asciidoc/guides/_cg_ide.adoc       |   1 +
 .../main/asciidoc/guides/_cg_ide_agilej.adoc    |  55 ++
 .../main/asciidoc/guides/_cg_ide_eclipse.adoc   |   7 +-
 .../main/asciidoc/guides/_cg_ide_intellij.adoc  |  10 +-
 .../asciidoc/guides/_cg_ide_project-lombok.adoc |   4 +-
 .../asciidoc/guides/_cg_isis-maven-plugin.adoc  | 231 +----
 .../guides/_cg_isis-maven-plugin_validate.adoc  | 241 ++++++
 .../guides/_cg_isis-maven-plugin_xsd.adoc       | 329 ++++++++
 .../main/asciidoc/guides/_rg_annotations.adoc   |  63 --
 .../asciidoc/guides/_rg_annotations_aaa.adoc    |  17 -
 .../guides/_rg_annotations_aaa_deprecated.adoc  | 342 --------
 .../guides/_rg_annotations_aaa_jdo.adoc         | 113 ---
 .../guides/_rg_annotations_aaa_jee.adoc         |  59 --
 .../guides/_rg_annotations_aaa_main.adoc        | 103 ---
 .../guides/_rg_annotations_aaa_other.adoc       |  57 --
 .../guides/_rg_annotations_aaa_partial.adoc     |  92 --
 .../guides/_rg_annotations_manpage-Action.adoc  | 131 ---
 .../_rg_annotations_manpage-ActionLayout.adoc   | 133 ---
 ...ations_manpage-ActionLayout_bookmarking.adoc |  64 --
 ...ions_manpage-ActionLayout_contributedAs.adoc |  54 --
 ...notations_manpage-ActionLayout_cssClass.adoc |  41 -
 ...tations_manpage-ActionLayout_cssClassFa.adoc |  59 --
 ...ations_manpage-ActionLayout_describedAs.adoc |  37 -
 ...annotations_manpage-ActionLayout_hidden.adoc |  57 --
 ..._annotations_manpage-ActionLayout_named.adoc |  45 -
 ...notations_manpage-ActionLayout_position.adoc |  80 --
 .../_rg_annotations_manpage-Action_command.adoc | 134 ---
 ..._annotations_manpage-Action_domainEvent.adoc | 145 ----
 .../_rg_annotations_manpage-Action_hidden.adoc  |  49 --
 ..._rg_annotations_manpage-Action_invokeOn.adoc |  64 --
 ...g_annotations_manpage-Action_publishing.adoc |  53 --
 ...g_annotations_manpage-Action_restrictTo.adoc |  30 -
 ...rg_annotations_manpage-Action_semantics.adoc |  91 --
 .../_rg_annotations_manpage-Action_typeOf.adoc  |  31 -
 .../_rg_annotations_manpage-Collection.adoc     | 105 ---
 ...rg_annotations_manpage-CollectionLayout.adoc | 137 ---
 ...tions_manpage-CollectionLayout_cssClass.adoc |  36 -
 ...ns_manpage-CollectionLayout_defaultView.adoc |  43 -
 ...ns_manpage-CollectionLayout_describedAs.adoc |  38 -
 ...tations_manpage-CollectionLayout_hidden.adoc |  58 --
 ...otations_manpage-CollectionLayout_named.adoc |  53 --
 ...otations_manpage-CollectionLayout_paged.adoc |  45 -
 ...tations_manpage-CollectionLayout_render.adoc |  42 -
 ...tions_manpage-CollectionLayout_sortedBy.adoc |  59 --
 ...otations_manpage-Collection_domainEvent.adoc | 154 ----
 ..._annotations_manpage-Collection_editing.adoc |  48 --
 ...g_annotations_manpage-Collection_hidden.adoc |  54 --
 ...tations_manpage-Collection_notPersisted.adoc |  57 --
 ...g_annotations_manpage-Collection_typeOf.adoc |  26 -
 .../guides/_rg_annotations_manpage-Column.adoc  | 154 ----
 .../guides/_rg_annotations_manpage-Digits.adoc  |  35 -
 .../_rg_annotations_manpage-Discriminator.adoc  |  59 --
 .../_rg_annotations_manpage-DomainObject.adoc   | 105 ---
 ..._annotations_manpage-DomainObjectLayout.adoc | 115 ---
 ..._manpage-DomainObjectLayout_bookmarking.adoc |  66 --
 ...ons_manpage-DomainObjectLayout_cssClass.adoc |  34 -
 ...s_manpage-DomainObjectLayout_cssClassFa.adoc |  40 -
 ..._manpage-DomainObjectLayout_describedAs.adoc |  22 -
 ...ations_manpage-DomainObjectLayout_named.adoc |  37 -
 ...ations_manpage-DomainObjectLayout_paged.adoc |  33 -
 ...tions_manpage-DomainObjectLayout_plural.adoc |  28 -
 ...notations_manpage-DomainObject_auditing.adoc |  38 -
 ...age-DomainObject_autoCompleteRepository.adoc |  81 --
 ...nnotations_manpage-DomainObject_bounded.adoc |  36 -
 ...nnotations_manpage-DomainObject_editing.adoc |  61 --
 ...annotations_manpage-DomainObject_nature.adoc |  66 --
 ...tations_manpage-DomainObject_objectType.adoc |  46 -
 ...tations_manpage-DomainObject_publishing.adoc |  49 --
 .../_rg_annotations_manpage-DomainService.adoc  |  64 --
 ...annotations_manpage-DomainServiceLayout.adoc |  78 --
 ...ons_manpage-DomainServiceLayout_menuBar.adoc |  43 -
 ...s_manpage-DomainServiceLayout_menuOrder.adoc |  74 --
 ...tions_manpage-DomainServiceLayout_named.adoc |  29 -
 ...nnotations_manpage-DomainService_nature.adoc |  89 --
 ...ons_manpage-DomainService_repositoryFor.adoc |  26 -
 .../guides/_rg_annotations_manpage-Facets.adoc  |  15 -
 .../_rg_annotations_manpage-HomePage.adoc       |  52 --
 .../guides/_rg_annotations_manpage-Inject.adoc  | 154 ----
 ...g_annotations_manpage-MemberGroupLayout.adoc |  20 -
 .../_rg_annotations_manpage-MemberOrder.adoc    |  35 -
 .../_rg_annotations_manpage-MinLength.adoc      |  32 -
 .../guides/_rg_annotations_manpage-Mixin.adoc   |  40 -
 .../_rg_annotations_manpage-NotPersistent.adoc  |  18 -
 .../_rg_annotations_manpage-Parameter.adoc      |  96 ---
 ..._rg_annotations_manpage-ParameterLayout.adoc | 112 ---
 ...ations_manpage-ParameterLayout_cssClass.adoc |  29 -
 ...ons_manpage-ParameterLayout_describedAs.adoc |  38 -
 ...s_manpage-ParameterLayout_labelPosition.adoc |  41 -
 ...tions_manpage-ParameterLayout_multiLine.adoc |  32 -
 ...notations_manpage-ParameterLayout_named.adoc |  44 -
 ...age-ParameterLayout_renderedAsDayBefore.adoc |  35 -
 ...s_manpage-ParameterLayout_typicalLength.adoc |  36 -
 ...annotations_manpage-Parameter_maxLength.adoc |  35 -
 ...notations_manpage-Parameter_mustSatisfy.adoc |  65 --
 ...notations_manpage-Parameter_optionality.adoc |  36 -
 ...otations_manpage-Parameter_regexPattern.adoc |  31 -
 ..._annotations_manpage-PersistenceCapable.adoc |  90 --
 .../_rg_annotations_manpage-PostConstruct.adoc  |  71 --
 .../_rg_annotations_manpage-PreDestroy.adoc     |  53 --
 .../_rg_annotations_manpage-PrimaryKey.adoc     |  19 -
 .../_rg_annotations_manpage-Programmatic.adoc   |  27 -
 .../_rg_annotations_manpage-Property.adoc       | 134 ---
 .../_rg_annotations_manpage-PropertyLayout.adoc | 142 ----
 ...tations_manpage-PropertyLayout_cssClass.adoc |  36 -
 ...ions_manpage-PropertyLayout_describedAs.adoc |  33 -
 ...notations_manpage-PropertyLayout_hidden.adoc |  78 --
 ...ns_manpage-PropertyLayout_labelPosition.adoc |  96 ---
 ...ations_manpage-PropertyLayout_multiLine.adoc |  44 -
 ...nnotations_manpage-PropertyLayout_named.adoc |  51 --
 ...page-PropertyLayout_renderedAsDayBefore.adoc |  45 -
 ...ns_manpage-PropertyLayout_typicalLength.adoc |  25 -
 ...nnotations_manpage-Property_domainEvent.adoc | 140 ----
 ...rg_annotations_manpage-Property_editing.adoc |  43 -
 ..._rg_annotations_manpage-Property_hidden.adoc |  66 --
 ..._annotations_manpage-Property_maxLength.adoc |  49 --
 ...nnotations_manpage-Property_mustSatisfy.adoc |  57 --
 ...notations_manpage-Property_notPersisted.adoc |  61 --
 ...nnotations_manpage-Property_optionality.adoc | 129 ---
 ...notations_manpage-Property_regexPattern.adoc |  28 -
 .../_rg_annotations_manpage-RequestScoped.adoc  |  50 --
 .../guides/_rg_annotations_manpage-Title.adoc   |  38 -
 .../_rg_annotations_manpage-ViewModel.adoc      |  44 -
 ..._rg_annotations_manpage-ViewModelLayout.adoc | 102 ---
 ...ations_manpage-ViewModelLayout_cssClass.adoc |  30 -
 ...ions_manpage-ViewModelLayout_cssClassFa.adoc |  41 -
 ...ons_manpage-ViewModelLayout_describedAs.adoc |  23 -
 ...notations_manpage-ViewModelLayout_named.adoc |  35 -
 ...notations_manpage-ViewModelLayout_paged.adoc |  34 -
 ...otations_manpage-ViewModelLayout_plural.adoc |  24 -
 .../src/main/asciidoc/guides/_rg_classes.adoc   |  22 -
 .../_rg_classes_AppManifest-bootstrapping.adoc  | 282 -------
 .../guides/_rg_classes_contributee.adoc         |  13 -
 ...es_contributee_manpage-HasTransactionId.adoc |  31 -
 ...classes_contributee_manpage-HasUserName.adoc |  27 -
 .../guides/_rg_classes_domainevent.adoc         |  76 --
 ...domainevent_manpage-AbstractDomainEvent.adoc |  20 -
 ...s_domainevent_manpage-ActionDomainEvent.adoc |  20 -
 ...mainevent_manpage-CollectionDomainEvent.adoc |  21 -
 ...domainevent_manpage-PropertyDomainEvent.adoc |  17 -
 .../main/asciidoc/guides/_rg_classes_i18n.adoc  |  11 -
 ...classes_i18n_manpage-TranslatableString.adoc |  13 -
 .../guides/_rg_classes_lifecycleevent.adoc      | 130 ---
 ...cleevent_manpage-AbstractLifecycleEvent.adoc |  27 -
 ...fecycleevent_manpage-ObjectCreatedEvent.adoc |  20 -
 ...ifecycleevent_manpage-ObjectLoadedEvent.adoc |  17 -
 ...cycleevent_manpage-ObjectPersistedEvent.adoc |  19 -
 ...ycleevent_manpage-ObjectPersistingEvent.adoc |  21 -
 ...ecycleevent_manpage-ObjectRemovingEvent.adoc |  20 -
 ...fecycleevent_manpage-ObjectUpdatedEvent.adoc |  21 -
 ...ecycleevent_manpage-ObjectUpdatingEvent.adoc |  22 -
 .../main/asciidoc/guides/_rg_classes_roles.adoc |  15 -
 ...rg_classes_roles_manpage-HoldsUpdatedAt.adoc |  45 -
 ...rg_classes_roles_manpage-HoldsUpdatedBy.adoc |  19 -
 ..._rg_classes_roles_manpage-Timestampable.adoc |  23 -
 .../main/asciidoc/guides/_rg_classes_spec.adoc  | 108 ---
 .../main/asciidoc/guides/_rg_classes_super.adoc | 105 ---
 ...s_super_manpage-AbstractContainedObject.adoc |  32 -
 ...sses_super_manpage-AbstractDomainObject.adoc |  14 -
 ...er_manpage-AbstractFactoryAndRepository.adoc |  15 -
 ...g_classes_super_manpage-AbstractService.adoc |  10 -
 ...lasses_super_manpage-AbstractSubscriber.adoc |   8 -
 ...classes_super_manpage-AbstractViewModel.adoc |  15 -
 ..._rg_classes_super_manpage-FixtureScript.adoc |  21 -
 ...rg_classes_super_manpage-FixtureScripts.adoc |  12 -
 .../asciidoc/guides/_rg_classes_utility.adoc    |  16 -
 .../_rg_classes_utility_manpage-Enums.adoc      |   8 -
 ...classes_utility_manpage-ObjectContracts.adoc | 107 ---
 .../_rg_classes_utility_manpage-Reasons.adoc    |  31 -
 ..._rg_classes_utility_manpage-TitleBuffer.adoc |  13 -
 .../guides/_rg_classes_value-types.adoc         | 119 ---
 .../_rg_classes_value-types_manpage-Blob.adoc   |   8 -
 .../_rg_classes_value-types_manpage-Clob.adoc   |   8 -
 .../_rg_classes_value-types_manpage-Color.adoc  |   9 -
 .../_rg_classes_value-types_manpage-Money.adoc  |   8 -
 ...rg_classes_value-types_manpage-Password.adoc |   8 -
 .../src/main/asciidoc/guides/_rg_methods.adoc   |  17 -
 .../asciidoc/guides/_rg_methods_lifecycle.adoc  | 102 ---
 .../guides/_rg_methods_lifecycle_jdo-api.adoc   |  53 --
 .../_rg_methods_lifecycle_manpage-created.adoc  |  17 -
 .../_rg_methods_lifecycle_manpage-loaded.adoc   |  15 -
 ..._rg_methods_lifecycle_manpage-persisted.adoc |  16 -
 ...rg_methods_lifecycle_manpage-persisting.adoc |  16 -
 .../_rg_methods_lifecycle_manpage-removed.adoc  |  16 -
 .../_rg_methods_lifecycle_manpage-removing.adoc |  16 -
 .../_rg_methods_lifecycle_manpage-updated.adoc  |  18 -
 .../_rg_methods_lifecycle_manpage-updating.adoc |  15 -
 .../asciidoc/guides/_rg_methods_prefixes.adoc   | 219 -----
 .../_rg_methods_prefixes_manpage-addTo.adoc     |  37 -
 ...g_methods_prefixes_manpage-autoComplete.adoc |  96 ---
 .../_rg_methods_prefixes_manpage-choices.adoc   | 143 ----
 .../_rg_methods_prefixes_manpage-clear.adoc     |  32 -
 .../_rg_methods_prefixes_manpage-default.adoc   | 129 ---
 .../_rg_methods_prefixes_manpage-disable.adoc   |  93 ---
 .../_rg_methods_prefixes_manpage-get.adoc       |  19 -
 .../_rg_methods_prefixes_manpage-hide.adoc      |  82 --
 .../_rg_methods_prefixes_manpage-modify.adoc    |  37 -
 ..._rg_methods_prefixes_manpage-removeFrom.adoc |  37 -
 .../_rg_methods_prefixes_manpage-set.adoc       |  13 -
 .../_rg_methods_prefixes_manpage-validate.adoc  | 113 ---
 ..._methods_prefixes_manpage-validateAddTo.adoc |  45 -
 ...ods_prefixes_manpage-validateRemoveFrom.adoc |  45 -
 .../asciidoc/guides/_rg_methods_reserved.adoc   |  58 --
 .../_rg_methods_reserved_manpage-cssClass.adoc  |  46 -
 .../_rg_methods_reserved_manpage-disable.adoc   | 102 ---
 .../_rg_methods_reserved_manpage-getId.adoc     |  19 -
 .../_rg_methods_reserved_manpage-hide.adoc      |  39 -
 .../_rg_methods_reserved_manpage-iconName.adoc  |  36 -
 .../_rg_methods_reserved_manpage-title.adoc     |  65 --
 .../_rg_methods_reserved_manpage-validate.adoc  |  27 -
 .../main/asciidoc/guides/_rg_object-layout.adoc |  18 -
 .../_rg_object-layout_application-menu.adoc     | 171 ----
 .../guides/_rg_object-layout_dynamic.adoc       | 113 ---
 .../_rg_object-layout_static-vs-dynamic.adoc    |  26 -
 .../guides/_rg_object-layout_static.adoc        | 159 ----
 .../src/main/asciidoc/guides/_rg_runtime.adoc   |  28 -
 .../_rg_runtime_application-specific.adoc       |  13 -
 ...me_application-specific_application-css.adoc |   8 -
 ...ime_application-specific_application-js.adoc |   9 -
 .../guides/_rg_runtime_configuration-files.adoc |  40 -
 .../guides/_rg_runtime_configuring-core.adoc    | 332 --------
 .../_rg_runtime_configuring-datanucleus.adoc    |  18 -
 ...s_disabling-persistence-by-reachability.adoc |  88 --
 ...atanucleus_eagerly-registering-entities.adoc |  23 -
 ...configuring-datanucleus_persistence-xml.adoc |  10 -
 ...time_configuring-datanucleus_properties.adoc |  66 --
 ...ring-datanucleus_using-jndi-data-source.adoc |  75 --
 .../guides/_rg_runtime_deployment-types.adoc    | 111 ---
 .../_rg_runtime_specifying-components.adoc      | 110 ---
 .../main/asciidoc/guides/_rg_services-api.adoc  | 295 -------
 ...ces-api_manpage-ActionInvocationContext.adoc |  99 ---
 ..._services-api_manpage-BackgroundService.adoc | 124 ---
 ...roundService_BackgroundCommandExecution.adoc |  25 -
 ...es-api_manpage-BackgroundService_Quartz.adoc | 162 ----
 ...rg_services-api_manpage-BookmarkService.adoc | 118 ---
 ...ices-api_manpage-BulkInteractionContext.adoc |   9 -
 .../_rg_services-api_manpage-ClockService.adoc  | 105 ---
 ..._rg_services-api_manpage-CommandContext.adoc | 218 -----
 ...rg_services-api_manpage-DeepLinkService.adoc |  58 --
 ...vices-api_manpage-DomainObjectContainer.adoc |  44 -
 ...nObjectContainer_generic-repository-api.adoc |  89 --
 ...page-DomainObjectContainer_messages-api.adoc |  50 --
 ...mainObjectContainer_object-creation-api.adoc |  49 --
 ...nObjectContainer_object-persistence-api.adoc |  62 --
 ...-DomainObjectContainer_presentation-api.adoc |  46 -
 ...ge-DomainObjectContainer_properties-api.adoc |  54 --
 ...page-DomainObjectContainer_security-api.adoc |  48 --
 ...page-DomainObjectContainer_services-api.adoc |  37 -
 ...ge-DomainObjectContainer_validation-api.adoc |  26 -
 .../_rg_services-api_manpage-EmailService.adoc  |  99 ---
 ...rg_services-api_manpage-EventBusService.adoc | 391 ---------
 ...vices-api_manpage-FixtureScriptsDefault.adoc |  50 --
 ..._services-api_manpage-GuiceBeanProvider.adoc |  91 --
 ..._rg_services-api_manpage-IsisJdoSupport.adoc | 277 ------
 ..._rg_services-api_manpage-MementoService.adoc | 132 ---
 ...g_services-api_manpage-MetamodelService.adoc |  43 -
 ..._services-api_manpage-QueryResultsCache.adoc | 128 ---
 .../_rg_services-api_manpage-Scratchpad.adoc    | 130 ---
 .../_rg_services-api_manpage-SudoService.adoc   |  69 --
 ..._rg_services-api_manpage-WrapperFactory.adoc | 163 ----
 ...services-api_manpage-XmlSnapshotService.adoc | 215 -----
 .../main/asciidoc/guides/_rg_services-spi.adoc  | 287 -------
 ...rg_services-spi_manpage-AuditingService.adoc |  85 --
 ...es-spi_manpage-BackgroundCommandService.adoc | 130 ---
 ...vices-spi_manpage-ClassDiscoveryService.adoc |  84 --
 ..._rg_services-spi_manpage-CommandService.adoc | 100 ---
 ...vices-spi_manpage-ContentMappingService.adoc | 106 ---
 ...s-spi_manpage-ContentNegotiationService.adoc | 206 -----
 ...es-spi_manpage-EmailNotificationService.adoc |  81 --
 ...vices-spi_manpage-ErrorReportingService.adoc | 105 ---
 ...rg_services-spi_manpage-EventSerializer.adoc |  73 --
 ...ervices-spi_manpage-ExceptionRecognizer.adoc | 126 ---
 ...age-FixtureScriptsSpecificationProvider.adoc |  70 --
 ..._rg_services-spi_manpage-LocaleProvider.adoc |  72 --
 ..._services-spi_manpage-PublishingService.adoc | 164 ----
 ...vices-spi_manpage-RepresentationService.adoc | 107 ---
 ...services-spi_manpage-TranslationService.adoc |  80 --
 ...rvices-spi_manpage-TranslationsResolver.adoc |  68 --
 ...services-spi_manpage-UserProfileService.adoc |  44 -
 ...ces-spi_manpage-UserRegistrationService.adoc |  82 --
 .../src/main/asciidoc/guides/_rg_web-xml.adoc   | 458 ----------
 .../src/main/asciidoc/guides/_rgant-Action.adoc | 133 +++
 .../asciidoc/guides/_rgant-ActionLayout.adoc    | 133 +++
 .../guides/_rgant-ActionLayout_bookmarking.adoc |  64 ++
 .../_rgant-ActionLayout_contributedAs.adoc      |  54 ++
 .../guides/_rgant-ActionLayout_cssClass.adoc    |  41 +
 .../guides/_rgant-ActionLayout_cssClassFa.adoc  |  59 ++
 .../guides/_rgant-ActionLayout_describedAs.adoc |  37 +
 .../guides/_rgant-ActionLayout_hidden.adoc      |  57 ++
 .../guides/_rgant-ActionLayout_named.adoc       |  45 +
 .../guides/_rgant-ActionLayout_position.adoc    |  80 ++
 .../asciidoc/guides/_rgant-Action_command.adoc  | 134 +++
 .../guides/_rgant-Action_domainEvent.adoc       | 164 ++++
 .../asciidoc/guides/_rgant-Action_hidden.adoc   |  49 ++
 .../asciidoc/guides/_rgant-Action_invokeOn.adoc |  64 ++
 .../guides/_rgant-Action_publishing.adoc        |  53 ++
 .../guides/_rgant-Action_restrictTo.adoc        |  30 +
 .../guides/_rgant-Action_semantics.adoc         |  91 ++
 .../asciidoc/guides/_rgant-Action_typeOf.adoc   |  31 +
 .../main/asciidoc/guides/_rgant-Collection.adoc | 105 +++
 .../guides/_rgant-CollectionLayout.adoc         | 137 +++
 .../_rgant-CollectionLayout_cssClass.adoc       |  36 +
 .../_rgant-CollectionLayout_defaultView.adoc    |  43 +
 .../_rgant-CollectionLayout_describedAs.adoc    |  38 +
 .../guides/_rgant-CollectionLayout_hidden.adoc  |  58 ++
 .../guides/_rgant-CollectionLayout_named.adoc   |  53 ++
 .../guides/_rgant-CollectionLayout_paged.adoc   |  45 +
 .../guides/_rgant-CollectionLayout_render.adoc  |  42 +
 .../_rgant-CollectionLayout_sortedBy.adoc       |  59 ++
 .../guides/_rgant-Collection_domainEvent.adoc   | 174 ++++
 .../guides/_rgant-Collection_editing.adoc       |  48 ++
 .../guides/_rgant-Collection_hidden.adoc        |  54 ++
 .../guides/_rgant-Collection_notPersisted.adoc  |  57 ++
 .../guides/_rgant-Collection_typeOf.adoc        |  26 +
 .../src/main/asciidoc/guides/_rgant-Column.adoc | 154 ++++
 .../src/main/asciidoc/guides/_rgant-Digits.adoc |  35 +
 .../asciidoc/guides/_rgant-Discriminator.adoc   |  59 ++
 .../asciidoc/guides/_rgant-DomainObject.adoc    | 154 ++++
 .../guides/_rgant-DomainObjectLayout.adoc       | 132 +++
 .../_rgant-DomainObjectLayout_bookmarking.adoc  |  66 ++
 .../_rgant-DomainObjectLayout_cssClass.adoc     |  34 +
 .../_rgant-DomainObjectLayout_cssClassFa.adoc   |  40 +
 ...gant-DomainObjectLayout_cssClassUiEvent.adoc | 126 +++
 .../_rgant-DomainObjectLayout_describedAs.adoc  |  22 +
 .../_rgant-DomainObjectLayout_iconUiEvent.adoc  | 122 +++
 .../guides/_rgant-DomainObjectLayout_named.adoc |  37 +
 .../guides/_rgant-DomainObjectLayout_paged.adoc |  33 +
 .../_rgant-DomainObjectLayout_plural.adoc       |  28 +
 .../_rgant-DomainObjectLayout_titleUiEvent.adoc | 120 +++
 .../guides/_rgant-DomainObject_auditing.adoc    |  38 +
 ...ant-DomainObject_autoCompleteRepository.adoc |  81 ++
 .../guides/_rgant-DomainObject_bounded.adoc     |  36 +
 ...gant-DomainObject_createdLifecycleEvent.adoc | 108 +++
 .../guides/_rgant-DomainObject_editing.adoc     |  61 ++
 ...rgant-DomainObject_loadedLifecycleEvent.adoc | 105 +++
 .../guides/_rgant-DomainObject_nature.adoc      |  66 ++
 .../guides/_rgant-DomainObject_objectType.adoc  |  46 +
 ...nt-DomainObject_persistedLifecycleEvent.adoc | 111 +++
 ...t-DomainObject_persistingLifecycleEvent.adoc | 114 +++
 .../guides/_rgant-DomainObject_publishing.adoc  |  49 ++
 ...ant-DomainObject_removingLifecycleEvent.adoc | 114 +++
 ...gant-DomainObject_updatedLifecycleEvent.adoc | 110 +++
 ...ant-DomainObject_updatingLifecycleEvent.adoc | 114 +++
 .../asciidoc/guides/_rgant-DomainService.adoc   |  64 ++
 .../guides/_rgant-DomainServiceLayout.adoc      |  78 ++
 .../_rgant-DomainServiceLayout_menuBar.adoc     |  43 +
 .../_rgant-DomainServiceLayout_menuOrder.adoc   |  74 ++
 .../_rgant-DomainServiceLayout_named.adoc       |  29 +
 .../guides/_rgant-DomainService_nature.adoc     |  89 ++
 .../_rgant-DomainService_repositoryFor.adoc     |  26 +
 .../src/main/asciidoc/guides/_rgant-Facets.adoc |  15 +
 .../main/asciidoc/guides/_rgant-HomePage.adoc   |  52 ++
 .../src/main/asciidoc/guides/_rgant-Inject.adoc | 154 ++++
 .../guides/_rgant-MemberGroupLayout.adoc        |  20 +
 .../asciidoc/guides/_rgant-MemberOrder.adoc     |  35 +
 .../main/asciidoc/guides/_rgant-MinLength.adoc  |  32 +
 .../src/main/asciidoc/guides/_rgant-Mixin.adoc  |  40 +
 .../asciidoc/guides/_rgant-NotPersistent.adoc   |  18 +
 .../main/asciidoc/guides/_rgant-Parameter.adoc  |  96 +++
 .../asciidoc/guides/_rgant-ParameterLayout.adoc | 112 +++
 .../guides/_rgant-ParameterLayout_cssClass.adoc |  29 +
 .../_rgant-ParameterLayout_describedAs.adoc     |  38 +
 .../_rgant-ParameterLayout_labelPosition.adoc   |  41 +
 .../_rgant-ParameterLayout_multiLine.adoc       |  32 +
 .../guides/_rgant-ParameterLayout_named.adoc    |  44 +
 ...ant-ParameterLayout_renderedAsDayBefore.adoc |  35 +
 .../_rgant-ParameterLayout_typicalLength.adoc   |  36 +
 .../guides/_rgant-Parameter_maxLength.adoc      |  35 +
 .../guides/_rgant-Parameter_mustSatisfy.adoc    |  65 ++
 .../guides/_rgant-Parameter_optionality.adoc    |  36 +
 .../guides/_rgant-Parameter_regexPattern.adoc   |  37 +
 .../guides/_rgant-PersistenceCapable.adoc       |  90 ++
 .../asciidoc/guides/_rgant-PostConstruct.adoc   |  71 ++
 .../main/asciidoc/guides/_rgant-PreDestroy.adoc |  53 ++
 .../main/asciidoc/guides/_rgant-PrimaryKey.adoc |  19 +
 .../asciidoc/guides/_rgant-Programmatic.adoc    |  27 +
 .../main/asciidoc/guides/_rgant-Property.adoc   | 134 +++
 .../asciidoc/guides/_rgant-PropertyLayout.adoc  | 142 ++++
 .../guides/_rgant-PropertyLayout_cssClass.adoc  |  36 +
 .../_rgant-PropertyLayout_describedAs.adoc      |  33 +
 .../guides/_rgant-PropertyLayout_hidden.adoc    |  78 ++
 .../_rgant-PropertyLayout_labelPosition.adoc    |  96 +++
 .../guides/_rgant-PropertyLayout_multiLine.adoc |  44 +
 .../guides/_rgant-PropertyLayout_named.adoc     |  51 ++
 ...gant-PropertyLayout_renderedAsDayBefore.adoc |  45 +
 .../_rgant-PropertyLayout_typicalLength.adoc    |  25 +
 .../guides/_rgant-Property_domainEvent.adoc     | 154 ++++
 .../guides/_rgant-Property_editing.adoc         |  43 +
 .../asciidoc/guides/_rgant-Property_hidden.adoc |  66 ++
 .../guides/_rgant-Property_maxLength.adoc       |  49 ++
 .../guides/_rgant-Property_mustSatisfy.adoc     |  57 ++
 .../guides/_rgant-Property_notPersisted.adoc    |  61 ++
 .../guides/_rgant-Property_optionality.adoc     | 129 +++
 .../guides/_rgant-Property_regexPattern.adoc    |  35 +
 .../asciidoc/guides/_rgant-RequestScoped.adoc   |  50 ++
 .../src/main/asciidoc/guides/_rgant-Title.adoc  |  62 ++
 .../main/asciidoc/guides/_rgant-ViewModel.adoc  |  44 +
 .../asciidoc/guides/_rgant-ViewModelLayout.adoc | 102 +++
 .../guides/_rgant-ViewModelLayout_cssClass.adoc |  30 +
 .../_rgant-ViewModelLayout_cssClassFa.adoc      |  41 +
 .../_rgant-ViewModelLayout_describedAs.adoc     |  23 +
 .../guides/_rgant-ViewModelLayout_named.adoc    |  35 +
 .../guides/_rgant-ViewModelLayout_paged.adoc    |  34 +
 .../guides/_rgant-ViewModelLayout_plural.adoc   |  24 +
 .../guides/_rgant-XmlJavaTypeAdapter.adoc       |  27 +
 .../asciidoc/guides/_rgant-XmlRootElement.adoc  |  83 ++
 .../src/main/asciidoc/guides/_rgant_aaa.adoc    |  17 +
 .../asciidoc/guides/_rgant_aaa_deprecated.adoc  | 342 ++++++++
 .../main/asciidoc/guides/_rgant_aaa_jdo.adoc    | 113 +++
 .../main/asciidoc/guides/_rgant_aaa_jee.adoc    |  73 ++
 .../main/asciidoc/guides/_rgant_aaa_main.adoc   | 103 +++
 .../main/asciidoc/guides/_rgant_aaa_other.adoc  |  57 ++
 .../asciidoc/guides/_rgant_aaa_partial.adoc     |  92 ++
 .../guides/_rgcfg_configuration-files.adoc      |  40 +
 .../guides/_rgcfg_configuring-core.adoc         | 455 ++++++++++
 .../guides/_rgcfg_configuring-datanucleus.adoc  |  18 +
 ...s_disabling-persistence-by-reachability.adoc |  88 ++
 ...atanucleus_eagerly-registering-entities.adoc |  23 +
 ...configuring-datanucleus_persistence-xml.adoc |  10 +
 ...gcfg_configuring-datanucleus_properties.adoc |  66 ++
 ...ring-datanucleus_using-jndi-data-source.adoc |  75 ++
 .../guides/_rgcfg_deployment-types.adoc         | 111 +++
 .../guides/_rgcfg_specifying-components.adoc    | 110 +++
 .../main/asciidoc/guides/_rgcms_classes.adoc    |  23 +
 ...rgcms_classes_AppManifest-bootstrapping.adoc | 282 +++++++
 .../guides/_rgcms_classes_contributee.adoc      |  13 +
 ...ms_classes_contributee_HasTransactionId.adoc |  31 +
 .../_rgcms_classes_contributee_HasUserName.adoc |  27 +
 .../guides/_rgcms_classes_domainevent.adoc      |  76 ++
 ...classes_domainevent_AbstractDomainEvent.adoc |  20 +
 ...s_classes_domainevent_ActionDomainEvent.adoc |  20 +
 ...asses_domainevent_CollectionDomainEvent.adoc |  21 +
 ...classes_domainevent_PropertyDomainEvent.adoc |  17 +
 .../asciidoc/guides/_rgcms_classes_i18n.adoc    |  11 +
 .../_rgcms_classes_i18n_TranslatableString.adoc |  13 +
 .../guides/_rgcms_classes_lifecycleevent.adoc   | 130 +++
 ...s_lifecycleevent_AbstractLifecycleEvent.adoc |  27 +
 ...asses_lifecycleevent_ObjectCreatedEvent.adoc |  20 +
 ...lasses_lifecycleevent_ObjectLoadedEvent.adoc |  17 +
 ...ses_lifecycleevent_ObjectPersistedEvent.adoc |  19 +
 ...es_lifecycleevent_ObjectPersistingEvent.adoc |  21 +
 ...sses_lifecycleevent_ObjectRemovingEvent.adoc |  20 +
 ...asses_lifecycleevent_ObjectUpdatedEvent.adoc |  21 +
 ...sses_lifecycleevent_ObjectUpdatingEvent.adoc |  22 +
 .../asciidoc/guides/_rgcms_classes_roles.adoc   |  18 +
 .../guides/_rgcms_classes_roles_Dto.adoc        |  61 ++
 .../_rgcms_classes_roles_HoldsUpdatedAt.adoc    |  44 +
 .../_rgcms_classes_roles_HoldsUpdatedBy.adoc    |  19 +
 .../_rgcms_classes_roles_Persistable.adoc       |  34 +
 .../_rgcms_classes_roles_Timestampable.adoc     |  23 +
 .../asciidoc/guides/_rgcms_classes_spec.adoc    | 108 +++
 .../asciidoc/guides/_rgcms_classes_super.adoc   | 105 +++
 ...s_classes_super_AbstractContainedObject.adoc |  32 +
 ...gcms_classes_super_AbstractDomainObject.adoc |  14 +
 ...sses_super_AbstractFactoryAndRepository.adoc |  15 +
 .../_rgcms_classes_super_AbstractService.adoc   |  10 +
 ..._rgcms_classes_super_AbstractSubscriber.adoc |  18 +
 .../_rgcms_classes_super_AbstractViewModel.adoc |  15 +
 .../_rgcms_classes_super_FixtureScript.adoc     |  21 +
 .../_rgcms_classes_super_FixtureScripts.adoc    |  12 +
 .../asciidoc/guides/_rgcms_classes_uievent.adoc |  62 ++
 .../_rgcms_classes_uievent_CssClassUiEvent.adoc |  22 +
 .../_rgcms_classes_uievent_IconUiEvent.adoc     |  23 +
 .../_rgcms_classes_uievent_TitleUiEvent.adoc    |  22 +
 .../asciidoc/guides/_rgcms_classes_utility.adoc |  16 +
 .../guides/_rgcms_classes_utility_Enums.adoc    |   8 +
 .../_rgcms_classes_utility_ObjectContracts.adoc | 107 +++
 .../guides/_rgcms_classes_utility_Reasons.adoc  |  31 +
 .../_rgcms_classes_utility_TitleBuffer.adoc     |  13 +
 .../guides/_rgcms_classes_value-types.adoc      | 119 +++
 .../guides/_rgcms_classes_value-types_Blob.adoc |   8 +
 .../guides/_rgcms_classes_value-types_Clob.adoc |   8 +
 .../_rgcms_classes_value-types_Color.adoc       |   8 +
 .../_rgcms_classes_value-types_Money.adoc       |   8 +
 .../_rgcms_classes_value-types_Password.adoc    |   8 +
 .../main/asciidoc/guides/_rgcms_methods.adoc    |  17 +
 .../guides/_rgcms_methods_lifecycle.adoc        | 102 +++
 .../_rgcms_methods_lifecycle_created.adoc       |  17 +
 .../_rgcms_methods_lifecycle_jdo-api.adoc       |  53 ++
 .../guides/_rgcms_methods_lifecycle_loaded.adoc |  15 +
 .../_rgcms_methods_lifecycle_persisted.adoc     |  16 +
 .../_rgcms_methods_lifecycle_persisting.adoc    |  16 +
 .../_rgcms_methods_lifecycle_removed.adoc       |  16 +
 .../_rgcms_methods_lifecycle_removing.adoc      |  16 +
 .../_rgcms_methods_lifecycle_updated.adoc       |  18 +
 .../_rgcms_methods_lifecycle_updating.adoc      |  15 +
 .../guides/_rgcms_methods_prefixes.adoc         | 219 +++++
 .../guides/_rgcms_methods_prefixes_addTo.adoc   |  37 +
 .../_rgcms_methods_prefixes_autoComplete.adoc   |  96 +++
 .../guides/_rgcms_methods_prefixes_choices.adoc | 143 ++++
 .../guides/_rgcms_methods_prefixes_clear.adoc   |  32 +
 .../guides/_rgcms_methods_prefixes_default.adoc | 129 +++
 .../guides/_rgcms_methods_prefixes_disable.adoc |  93 +++
 .../guides/_rgcms_methods_prefixes_get.adoc     |  19 +
 .../guides/_rgcms_methods_prefixes_hide.adoc    |  82 ++
 .../guides/_rgcms_methods_prefixes_modify.adoc  |  37 +
 .../_rgcms_methods_prefixes_removeFrom.adoc     |  37 +
 .../guides/_rgcms_methods_prefixes_set.adoc     |  13 +
 .../_rgcms_methods_prefixes_validate.adoc       | 113 +++
 .../_rgcms_methods_prefixes_validateAddTo.adoc  |  45 +
 ...cms_methods_prefixes_validateRemoveFrom.adoc |  45 +
 .../guides/_rgcms_methods_reserved.adoc         |  58 ++
 .../_rgcms_methods_reserved_cssClass.adoc       |  46 +
 .../guides/_rgcms_methods_reserved_disable.adoc | 102 +++
 .../guides/_rgcms_methods_reserved_getId.adoc   |  19 +
 .../guides/_rgcms_methods_reserved_hide.adoc    |  39 +
 .../_rgcms_methods_reserved_iconName.adoc       |  36 +
 .../guides/_rgcms_methods_reserved_title.adoc   |  65 ++
 .../_rgcms_methods_reserved_validate.adoc       |  27 +
 .../main/asciidoc/guides/_rgcms_schema-aim.adoc |  97 +++
 .../asciidoc/guides/_rgcms_schema-common.adoc   | 103 +++
 .../src/main/asciidoc/guides/_rgcms_schema.adoc |  24 +
 .../src/main/asciidoc/guides/_rgsvc-api.adoc    | 306 +++++++
 .../_rgsvc-api_ActionInvocationContext.adoc     |  98 +++
 .../guides/_rgsvc-api_BackgroundService.adoc    | 123 +++
 ...roundService_BackgroundCommandExecution.adoc |  25 +
 .../_rgsvc-api_BackgroundService_Quartz.adoc    | 162 ++++
 .../guides/_rgsvc-api_BookmarkService.adoc      | 116 +++
 .../_rgsvc-api_BulkInteractionContext.adoc      |   9 +
 .../guides/_rgsvc-api_ClockService.adoc         | 101 +++
 .../guides/_rgsvc-api_CommandContext.adoc       | 216 +++++
 .../guides/_rgsvc-api_DeepLinkService.adoc      |  56 ++
 .../_rgsvc-api_DomainObjectContainer.adoc       |  40 +
 ...nObjectContainer_generic-repository-api.adoc |  89 ++
 ...-api_DomainObjectContainer_messages-api.adoc |  50 ++
 ...mainObjectContainer_object-creation-api.adoc |  49 ++
 ...nObjectContainer_object-persistence-api.adoc |  62 ++
 ..._DomainObjectContainer_presentation-api.adoc |  46 +
 ...pi_DomainObjectContainer_properties-api.adoc |  54 ++
 ...-api_DomainObjectContainer_security-api.adoc |  48 ++
 ...-api_DomainObjectContainer_services-api.adoc |  37 +
 ...pi_DomainObjectContainer_validation-api.adoc |  26 +
 .../guides/_rgsvc-api_EmailService.adoc         |  95 +++
 .../guides/_rgsvc-api_EventBusService.adoc      | 405 +++++++++
 .../_rgsvc-api_FixtureScriptsDefault.adoc       |  50 ++
 .../guides/_rgsvc-api_GuiceBeanProvider.adoc    |  91 ++
 .../guides/_rgsvc-api_IsisJdoSupport.adoc       | 276 ++++++
 .../asciidoc/guides/_rgsvc-api_JaxbService.adoc |  67 ++
 .../guides/_rgsvc-api_MementoService.adoc       | 131 +++
 .../guides/_rgsvc-api_MetamodelService.adoc     |  42 +
 .../guides/_rgsvc-api_QueryResultsCache.adoc    | 126 +++
 .../asciidoc/guides/_rgsvc-api_Scratchpad.adoc  | 128 +++
 .../asciidoc/guides/_rgsvc-api_SudoService.adoc |  69 ++
 .../guides/_rgsvc-api_WrapperFactory.adoc       | 162 ++++
 .../guides/_rgsvc-api_XmlSnapshotService.adoc   | 220 +++++
 .../src/main/asciidoc/guides/_rgsvc-spi.adoc    | 299 +++++++
 .../guides/_rgsvc-spi_AuditingService.adoc      |  85 ++
 .../_rgsvc-spi_BackgroundCommandService.adoc    | 131 +++
 .../_rgsvc-spi_ClassDiscoveryService.adoc       |  82 ++
 .../guides/_rgsvc-spi_CommandService.adoc       | 100 +++
 .../_rgsvc-spi_ContentMappingService.adoc       | 107 +++
 .../_rgsvc-spi_ContentNegotiationService.adoc   | 204 +++++
 .../_rgsvc-spi_EmailNotificationService.adoc    |  81 ++
 .../_rgsvc-spi_ErrorReportingService.adoc       | 106 +++
 .../guides/_rgsvc-spi_EventSerializer.adoc      |  74 ++
 .../guides/_rgsvc-spi_ExceptionRecognizer.adoc  | 119 +++
 ...spi_FixtureScriptsSpecificationProvider.adoc |  76 ++
 .../guides/_rgsvc-spi_LocaleProvider.adoc       |  70 ++
 .../guides/_rgsvc-spi_PublishingService.adoc    | 192 +++++
 .../_rgsvc-spi_RepresentationService.adoc       | 103 +++
 .../guides/_rgsvc-spi_TranslationService.adoc   |  80 ++
 .../guides/_rgsvc-spi_TranslationsResolver.adoc |  67 ++
 .../guides/_rgsvc-spi_UrlEncodingService.adoc   |  59 ++
 .../guides/_rgsvc-spi_UserProfileService.adoc   |  47 ++
 .../_rgsvc-spi_UserRegistrationService.adoc     |  98 +++
 .../main/asciidoc/guides/_tg_pet-clinic.adoc    |   2 +-
 .../_tg_stop-scaffolding-start-coding.adoc      | 134 +--
 .../main/asciidoc/guides/_ug_core-concepts.adoc |  22 -
 .../guides/_ug_core-concepts_add-ons.adoc       |  35 -
 .../_ug_core-concepts_building-blocks.adoc      | 267 ------
 ...re-concepts_framework-provided-services.adoc |  54 --
 ..._core-concepts_other-deployment-options.adoc |  81 --
 .../guides/_ug_core-concepts_philosophy.adoc    |  21 -
 .../_ug_core-concepts_philosophy_aop.adoc       |  36 -
 .../_ug_core-concepts_philosophy_dci.adoc       |   9 -
 ...oncepts_philosophy_domain-driven-design.adoc |  78 --
 ...cepts_philosophy_hexagonal-architecture.adoc |  29 -
 ..._core-concepts_philosophy_how-eases-ddd.adoc |  74 --
 ...ncepts_philosophy_naked-objects-pattern.adoc |  60 --
 ...bjects-pattern_object-interface-mapping.adoc |  18 -
 .../guides/_ug_core-concepts_principles.adoc    |  16 -
 ...core-concepts_principles_apache-isis-vs.adoc |  16 -
 ...concepts_principles_apache-isis-vs_cqrs.adoc |  28 -
 ...rinciples_apache-isis-vs_event-sourcing.adoc |  19 -
 ...ts_principles_apache-isis-vs_metawidget.adoc |  16 -
 ...ache-isis-vs_mvc-server-side-frameworks.adoc |  19 -
 ...ug_core-concepts_principles_isis-itself.adoc |  47 --
 .../_ug_core-concepts_principles_your-apps.adoc |  39 -
 .../main/asciidoc/guides/_ug_deployment.adoc    |  19 -
 .../guides/_ug_deployment_cmd-line.adoc         | 113 ---
 ...g_deployment_externalized-configuration.adoc | 245 ------
 .../asciidoc/guides/_ug_deployment_gae.adoc     |  50 --
 .../guides/_ug_deployment_jvm-flags.adoc        |  52 --
 .../asciidoc/guides/_ug_deployment_neo4j.adoc   |  59 --
 .../asciidoc/guides/_ug_deployment_tomcat.adoc  |  28 -
 .../src/main/asciidoc/guides/_ug_extending.adoc |  14 -
 .../guides/_ug_extending_programming-model.adoc |  13 -
 ...ding_programming-model_custom-validator.adoc | 107 ---
 ..._extending_programming-model_finetuning.adoc |  80 --
 ...rogramming-model_layout-metadata-reader.adoc |  82 --
 .../_ug_extending_restfulobjects-viewer.adoc    |  51 --
 .../guides/_ug_extending_wicket-viewer.adoc     |  25 -
 ...ng_wicket-viewer_custom-bootstrap-theme.adoc |  34 -
 ...ug_extending_wicket-viewer_custom-pages.adoc |  92 --
 ...ng_wicket-viewer_isis-addons-extensions.adoc |  17 -
 ...viewer_login-via-query-args-prototyping.adoc |  49 --
 ...g_wicket-viewer_replacing-page-elements.adoc | 167 ----
 .../asciidoc/guides/_ug_getting-started.adoc    |  37 -
 ...ug_getting-started_datanucleus-enhancer.adoc | 107 ---
 ..._ug_getting-started_simpleapp-archetype.adoc | 304 -------
 .../asciidoc/guides/_ug_headless-access.adoc    |  27 -
 ...less-access_AbstractIsisSessionTemplate.adoc |  40 -
 ...dless-access_BackgroundCommandExecution.adoc |  45 -
 .../src/main/asciidoc/guides/_ug_how-tos.adoc   |  21 -
 .../guides/_ug_how-tos_business-rules.adoc      |  72 --
 .../guides/_ug_how-tos_class-structure.adoc     |  38 -
 ...w-tos_class-structure_action-parameters.adoc |  26 -
 .../_ug_how-tos_class-structure_actions.adoc    |  19 -
 ...ow-tos_class-structure_class-definition.adoc |  24 -
 ..._ug_how-tos_class-structure_collections.adoc |  26 -
 ...ow-tos_class-structure_ignoring-methods.adoc |  16 -
 ...how-tos_class-structure_inject-services.adoc |  83 --
 ...lass-structure_properties-vs-parameters.adoc |  45 -
 .../_ug_how-tos_class-structure_properties.adoc | 299 -------
 .../guides/_ug_how-tos_contributed-members.adoc |  69 --
 .../main/asciidoc/guides/_ug_how-tos_crud.adoc  |  29 -
 .../guides/_ug_how-tos_derived-members.adoc     |  48 --
 .../guides/_ug_how-tos_domain-services.adoc     | 313 -------
 .../_ug_how-tos_drop-downs-and-defaults.adoc    |  65 --
 .../_ug_how-tos_entity-relationships.adoc       |  15 -
 ...aged-1-to-m-bidirectional-relationships.adoc |  58 --
 .../guides/_ug_how-tos_persisted-title.adoc     |  56 --
 ...placing-default-service-implementations.adoc |  64 --
 .../asciidoc/guides/_ug_how-tos_ui-hints.adoc   |  15 -
 ...g_how-tos_ui-hints_action-icons-and-css.adoc |  58 --
 .../_ug_how-tos_ui-hints_eager-rendering.adoc   |  58 --
 .../guides/_ug_how-tos_ui-hints_layout.adoc     |   9 -
 ...how-tos_ui-hints_names-and-descriptions.adoc |  47 --
 ...ow-tos_ui-hints_object-titles-and-icons.adoc |  97 ---
 .../main/asciidoc/guides/_ug_more-advanced.adoc |  26 -
 .../guides/_ug_more-advanced_bulk-actions.adoc  |   8 -
 .../guides/_ug_more-advanced_decoupling.adoc    |  28 -
 ..._more-advanced_decoupling_contributions.adoc |  23 -
 ..._ug_more-advanced_decoupling_db-schemas.adoc | 141 ----
 .../_ug_more-advanced_decoupling_event-bus.adoc |  11 -
 .../_ug_more-advanced_decoupling_mixins.adoc    | 191 -----
 ...ore-advanced_decoupling_pushing-changes.adoc | 140 ----
 ...-advanced_decoupling_vetoing-visibility.adoc |  15 -
 .../asciidoc/guides/_ug_more-advanced_i18n.adoc | 378 ---------
 .../_ug_more-advanced_mapping-rdbms-views.adoc  |   9 -
 .../guides/_ug_more-advanced_multi-tenancy.adoc |   8 -
 ...ore-advanced_overriding-jdo-annotations.adoc |  55 --
 ..._ug_more-advanced_persistence-lifecycle.adoc |   8 -
 .../guides/_ug_more-advanced_tips-n-tricks.adoc |  15 -
 ...ore-advanced_tips-n-tricks_are-you-sure.adoc |  76 --
 ...ore-advanced_tips-n-tricks_enhance-only.adoc |  17 -
 ...-advanced_tips-n-tricks_per-user-themes.adoc |  85 --
 ...-tricks_render-all-properties-in-tables.adoc |  49 --
 ...tricks_simulating-collections-of-values.adoc |  23 -
 ...g_more-advanced_transactions-and-errors.adoc |  33 -
 .../guides/_ug_more-advanced_view-models.adoc   |  22 -
 .../guides/_ug_restfulobjects-viewer.adoc       |  25 -
 ...objects-viewer_configuration-properties.adoc |  72 --
 ...configuration-properties_honor-ui-hints.adoc |  27 -
 ...erties_simplified-object-representation.adoc |  68 --
 ...uration-properties_suppressing-elements.adoc |  39 -
 .../_ug_restfulobjects-viewer_features.adoc     |  23 -
 ...ug_restfulobjects-viewer_hints-and-tips.adoc |  85 --
 .../src/main/asciidoc/guides/_ug_security.adoc  |  53 --
 .../_ug_security_api-for-applications.adoc      |  63 --
 ...security_configuring-isis-to-use-bypass.adoc |  23 -
 ..._security_configuring-isis-to-use-shiro.adoc |  76 --
 .../guides/_ug_security_shiro-caching.adoc      |  41 -
 .../guides/_ug_security_shiro-ini-realm.adoc    | 133 ---
 ...shiro-isis-enhanced-wildcard-permission.adoc |  61 --
 .../_ug_security_shiro-isis-ldap-realm.adoc     | 146 ----
 ..._shiro-isisaddons-security-module-realm.adoc |  36 -
 .../guides/_ug_security_shiro-jdbc-realm.adoc   | 113 ---
 .../_ug_security_usage-by-isis-viewers.adoc     | 208 -----
 .../src/main/asciidoc/guides/_ug_testing.adoc   |  17 -
 .../main/asciidoc/guides/_ug_testing_aaa.adoc   | 166 ----
 .../guides/_ug_testing_bdd-spec-support.adoc    |  22 -
 ...ug_testing_bdd-spec-support_bdd-tooling.adoc |  14 -
 ...g_testing_bdd-spec-support_how-it-works.adoc |  20 -
 ...ug_testing_bdd-spec-support_key-classes.adoc |  59 --
 ...ng_bdd-spec-support_maven-configuration.adoc |  73 --
 ...ing_bdd-spec-support_writing-a-bdd-spec.adoc | 141 ----
 .../guides/_ug_testing_fixture-scripts.adoc     |  44 -
 ...g_testing_fixture-scripts_api-and-usage.adoc | 352 --------
 ...ug_testing_fixture-scripts_sudo-service.adoc |  59 --
 .../guides/_ug_testing_integ-test-support.adoc  |  24 -
 ...esting_integ-test-support_bootstrapping.adoc | 260 ------
 ..._integ-test-support_maven-configuration.adoc |  46 -
 ...esting_integ-test-support_typical-usage.adoc | 124 ---
 ...ting_integ-test-support_wrapper-factory.adoc | 162 ----
 .../guides/_ug_testing_unit-test-support.adoc   |  14 -
 ...esting_unit-test-support_contract-tests.adoc | 171 ----
 ...ting_unit-test-support_jmock-extensions.adoc |  59 --
 ...g_unit-test-support_maven-configuration.adoc |  46 -
 ...est-support_soap-fake-server-junit-rule.adoc | 113 ---
 .../asciidoc/guides/_ug_troubleshooting.adoc    |  14 -
 .../_ug_troubleshooting_enabling-logging.adoc   |  39 -
 .../main/asciidoc/guides/_ug_wicket-viewer.adoc |  30 -
 ..._wicket-viewer_configuration-properties.adoc | 112 ---
 ...guration-properties_abbreviating-titles.adoc |  33 -
 ...ration-properties_showing-theme-chooser.adoc |  43 -
 ...uration-properties_stripped-wicket-tags.adoc |  26 -
 ...n-properties_suppressing-password-reset.adoc |  47 --
 ...tion-properties_suppressing-remember-me.adoc |  35 -
 ...guration-properties_suppressing-sign-up.adoc |  49 --
 .../guides/_ug_wicket-viewer_customisation.adoc |  18 -
 ..._wicket-viewer_customisation_about-page.adoc | 121 ---
 ...icket-viewer_customisation_auto-refresh.adoc |  35 -
 ..._wicket-viewer_customisation_brand-logo.adoc |  71 --
 ...er_customisation_cheap-n-cheerful-theme.adoc |  29 -
 ...-viewer_customisation_custom-javascript.adoc |  42 -
 ...cket-viewer_customisation_default-theme.adoc |  29 -
 ...ewer_customisation_tweaking-css-classes.adoc | 107 ---
 ..._customisation_using-different-css-file.adoc |  36 -
 ...icket-viewer_customisation_welcome-page.adoc |  42 -
 .../guides/_ug_wicket-viewer_features.adoc      |  26 -
 ...wicket-viewer_features_blob-attachments.adoc | 121 ---
 ...wicket-viewer_features_bookmarked-pages.adoc | 108 ---
 ...cket-viewer_features_hints-and-copy-url.adoc |  79 --
 ..._ug_wicket-viewer_features_recent-pages.adoc |  53 --
 ...wicket-viewer_features_titles-in-tables.adoc |  76 --
 ...icket-viewer_features_user-registration.adoc |  81 --
 .../guides/_ug_wicket-viewer_isis-addons.adoc   |  33 -
 .../guides/_ug_wicket-viewer_layout.adoc        |  97 ---
 .../_ug_wicket-viewer_request-parameters.adoc   |  53 --
 .../main/asciidoc/guides/_ugbtb_deployment.adoc |  19 +
 .../guides/_ugbtb_deployment_cmd-line.adoc      | 113 +++
 ...b_deployment_externalized-configuration.adoc | 245 ++++++
 .../asciidoc/guides/_ugbtb_deployment_gae.adoc  |  50 ++
 .../guides/_ugbtb_deployment_jvm-flags.adoc     |  52 ++
 .../guides/_ugbtb_deployment_neo4j.adoc         |  59 ++
 .../guides/_ugbtb_deployment_tomcat.adoc        |  28 +
 .../asciidoc/guides/_ugbtb_more-advanced.adoc   |  26 +
 .../guides/_ugbtb_more-advanced_decoupling.adoc |  28 +
 ..._more-advanced_decoupling_contributions.adoc |  23 +
 ...btb_more-advanced_decoupling_db-schemas.adoc | 141 ++++
 ...gbtb_more-advanced_decoupling_event-bus.adoc |  11 +
 .../_ugbtb_more-advanced_decoupling_mixins.adoc | 191 +++++
 ...ore-advanced_decoupling_pushing-changes.adoc | 140 ++++
 ...-advanced_decoupling_vetoing-visibility.adoc |  15 +
 .../_ugbtb_more-advanced_headless-access.adoc   |  27 +
 ...less-access_AbstractIsisSessionTemplate.adoc |  40 +
 ...dless-access_BackgroundCommandExecution.adoc |  45 +
 .../guides/_ugbtb_more-advanced_i18n.adoc       | 378 +++++++++
 ...ugbtb_more-advanced_mapping-rdbms-views.adoc |   9 +
 .../_ugbtb_more-advanced_multi-tenancy.adoc     |   8 +
 ...ore-advanced_overriding-jdo-annotations.adoc |  64 ++
 .../_ugbtb_more-advanced_persisted-title.adoc   |  82 ++
 ...placing-default-service-implementations.adoc |  64 ++
 ...b_more-advanced_transactions-and-errors.adoc |  33 +
 .../_ugbtb_more-advanced_view-models.adoc       |  19 +
 .../_ugbtb_more-advanced_view-models_jaxb.adoc  | 240 ++++++
 ...-advanced_view-models_programming-model.adoc |  87 ++
 ...btb_more-advanced_view-models_use-cases.adoc | 142 ++++
 .../guides/_ugbtb_programming-model.adoc        |  14 +
 ...gbtb_programming-model_custom-validator.adoc | 107 +++
 .../_ugbtb_programming-model_finetuning.adoc    |  80 ++
 ...rogramming-model_layout-metadata-reader.adoc |  82 ++
 .../main/asciidoc/guides/_ugbtb_web-xml.adoc    | 473 +++++++++++
 .../asciidoc/guides/_ugfun_core-concepts.adoc   |  22 +
 .../guides/_ugfun_core-concepts_add-ons.adoc    |  35 +
 .../_ugfun_core-concepts_building-blocks.adoc   | 335 ++++++++
 ...re-concepts_framework-provided-services.adoc |  54 ++
 ..._core-concepts_other-deployment-options.adoc |  81 ++
 .../guides/_ugfun_core-concepts_philosophy.adoc |  21 +
 .../_ugfun_core-concepts_philosophy_aop.adoc    |  36 +
 .../_ugfun_core-concepts_philosophy_dci.adoc    |   9 +
 ...oncepts_philosophy_domain-driven-design.adoc |  79 ++
 ...cepts_philosophy_hexagonal-architecture.adoc |  29 +
 ..._core-concepts_philosophy_how-eases-ddd.adoc |  74 ++
 ...ncepts_philosophy_naked-objects-pattern.adoc |  60 ++
 ...bjects-pattern_object-interface-mapping.adoc |  18 +
 .../guides/_ugfun_core-concepts_principles.adoc |  16 +
 ...core-concepts_principles_apache-isis-vs.adoc |  16 +
 ...concepts_principles_apache-isis-vs_cqrs.adoc |  28 +
 ...rinciples_apache-isis-vs_event-sourcing.adoc |  19 +
 ...ts_principles_apache-isis-vs_metawidget.adoc |  16 +
 ...ache-isis-vs_mvc-server-side-frameworks.adoc |  19 +
 ...un_core-concepts_principles_isis-itself.adoc |  47 ++
 ...gfun_core-concepts_principles_your-apps.adoc |  39 +
 .../src/main/asciidoc/guides/_ugfun_faqs.adoc   |  18 +
 .../guides/_ugfun_faqs_enabling-logging.adoc    |  39 +
 .../guides/_ugfun_faqs_enhance-only.adoc        |  17 +
 ..._ugfun_faqs_i18n-label-in-wicket-viewer.adoc |  16 +
 .../guides/_ugfun_faqs_per-user-themes.adoc     |  85 ++
 .../_ugfun_faqs_restful-image-property.adoc     |  20 +
 ...faqs_subtype-entity-not-fully-populated.adoc |  67 ++
 .../asciidoc/guides/_ugfun_getting-started.adoc |  37 +
 ...un_getting-started_datanucleus-enhancer.adoc | 107 +++
 ...fun_getting-started_simpleapp-archetype.adoc | 304 +++++++
 .../main/asciidoc/guides/_ugfun_how-tos.adoc    |  22 +
 .../guides/_ugfun_how-tos_bulk-actions.adoc     |   8 +
 .../guides/_ugfun_how-tos_business-rules.adoc   |  72 ++
 .../guides/_ugfun_how-tos_class-structure.adoc  |  38 +
 ...w-tos_class-structure_action-parameters.adoc |  26 +
 .../_ugfun_how-tos_class-structure_actions.adoc |  19 +
 ...ow-tos_class-structure_class-definition.adoc |  24 +
 ...fun_how-tos_class-structure_collections.adoc |  26 +
 ...ow-tos_class-structure_ignoring-methods.adoc |  16 +
 ...how-tos_class-structure_inject-services.adoc |  83 ++
 ...lass-structure_properties-vs-parameters.adoc |  45 +
 ...gfun_how-tos_class-structure_properties.adoc | 299 +++++++
 .../_ugfun_how-tos_contributed-members.adoc     |  69 ++
 .../asciidoc/guides/_ugfun_how-tos_crud.adoc    |  29 +
 .../guides/_ugfun_how-tos_derived-members.adoc  |  48 ++
 .../guides/_ugfun_how-tos_domain-services.adoc  | 313 +++++++
 .../_ugfun_how-tos_drop-downs-and-defaults.adoc |  65 ++
 .../_ugfun_how-tos_entity-relationships.adoc    |  15 +
 ...aged-1-to-m-bidirectional-relationships.adoc |  59 ++
 ...how-tos_render-all-properties-in-tables.adoc |  49 ++
 ...ow-tos_simulating-collections-of-values.adoc |  23 +
 .../guides/_ugfun_how-tos_ui-hints.adoc         |  15 +
 ...n_how-tos_ui-hints_action-icons-and-css.adoc |  58 ++
 ..._ugfun_how-tos_ui-hints_eager-rendering.adoc |  58 ++
 .../guides/_ugfun_how-tos_ui-hints_layout.adoc  |   9 +
 ...how-tos_ui-hints_names-and-descriptions.adoc |  47 ++
 ...ow-tos_ui-hints_object-titles-and-icons.adoc |  97 +++
 .../guides/_ugfun_how-tos_ui_are-you-sure.adoc  |  76 ++
 .../asciidoc/guides/_ugfun_object-layout.adoc   |  18 +
 .../_ugfun_object-layout_application-menu.adoc  | 171 ++++
 .../guides/_ugfun_object-layout_dynamic.adoc    | 113 +++
 .../_ugfun_object-layout_static-vs-dynamic.adoc |  26 +
 .../guides/_ugfun_object-layout_static.adoc     | 159 ++++
 .../guides/_ugsec_api-for-applications.adoc     |  63 ++
 .../_ugsec_configuring-isis-to-use-bypass.adoc  |  23 +
 .../_ugsec_configuring-isis-to-use-shiro.adoc   |  76 ++
 .../asciidoc/guides/_ugsec_shiro-caching.adoc   |  41 +
 .../asciidoc/guides/_ugsec_shiro-ini-realm.adoc | 133 +++
 ...shiro-isis-enhanced-wildcard-permission.adoc |  61 ++
 .../guides/_ugsec_shiro-isis-ldap-realm.adoc    | 146 ++++
 ..._shiro-isisaddons-security-module-realm.adoc |  36 +
 .../guides/_ugsec_shiro-jdbc-realm.adoc         | 113 +++
 .../guides/_ugsec_usage-by-isis-viewers.adoc    | 208 +++++
 .../src/main/asciidoc/guides/_ugtst_aaa.adoc    | 166 ++++
 .../guides/_ugtst_bdd-spec-support.adoc         |  22 +
 .../_ugtst_bdd-spec-support_bdd-tooling.adoc    |  14 +
 .../_ugtst_bdd-spec-support_how-it-works.adoc   |  20 +
 .../_ugtst_bdd-spec-support_key-classes.adoc    |  59 ++
 ...st_bdd-spec-support_maven-configuration.adoc |  73 ++
 ...tst_bdd-spec-support_writing-a-bdd-spec.adoc | 141 ++++
 .../asciidoc/guides/_ugtst_fixture-scripts.adoc |  44 +
 .../_ugtst_fixture-scripts_api-and-usage.adoc   | 352 ++++++++
 .../_ugtst_fixture-scripts_sudo-service.adoc    |  59 ++
 .../guides/_ugtst_integ-test-support.adoc       |  24 +
 ..._ugtst_integ-test-support_bootstrapping.adoc | 260 ++++++
 ..._integ-test-support_maven-configuration.adoc |  46 +
 ..._ugtst_integ-test-support_typical-usage.adoc | 124 +++
 ...gtst_integ-test-support_wrapper-factory.adoc | 162 ++++
 .../guides/_ugtst_unit-test-support.adoc        |  14 +
 ..._ugtst_unit-test-support_contract-tests.adoc | 171 ++++
 ...gtst_unit-test-support_jmock-extensions.adoc |  59 ++
 ...t_unit-test-support_maven-configuration.adoc |  46 +
 ...est-support_soap-fake-server-junit-rule.adoc | 113 +++
 .../asciidoc/guides/_ugvro_architecture.adoc    |  57 ++
 .../guides/_ugvro_configuration-properties.adoc |  54 ++
 .../asciidoc/guides/_ugvro_hints-and-tips.adoc  |  97 +++
 .../main/asciidoc/guides/_ugvro_ro-spec.adoc    | 201 +++++
 .../_ugvro_simplified-representations.adoc      | 368 ++++++++
 ...epresentations_configuration-properties.adoc | 135 +++
 .../guides/_ugvw_configuration-properties.adoc  | 112 +++
 ...guration-properties_abbreviating-titles.adoc |  33 +
 ...ration-properties_showing-theme-chooser.adoc |  43 +
 ...uration-properties_stripped-wicket-tags.adoc |  26 +
 ...n-properties_suppressing-password-reset.adoc |  47 ++
 ...tion-properties_suppressing-remember-me.adoc |  35 +
 ...guration-properties_suppressing-sign-up.adoc |  49 ++
 .../asciidoc/guides/_ugvw_customisation.adoc    |  18 +
 .../guides/_ugvw_customisation_about-page.adoc  | 121 +++
 .../_ugvw_customisation_auto-refresh.adoc       |  35 +
 .../guides/_ugvw_customisation_brand-logo.adoc  |  71 ++
 ...vw_customisation_cheap-n-cheerful-theme.adoc |  29 +
 .../_ugvw_customisation_custom-javascript.adoc  |  42 +
 .../_ugvw_customisation_default-theme.adoc      |  29 +
 ...ugvw_customisation_tweaking-css-classes.adoc | 107 +++
 ..._customisation_using-different-css-file.adoc |  36 +
 .../_ugvw_customisation_welcome-page.adoc       |  42 +
 .../main/asciidoc/guides/_ugvw_extending.adoc   |  25 +
 .../_ugvw_extending_custom-bootstrap-theme.adoc |  34 +
 .../guides/_ugvw_extending_custom-pages.adoc    |  92 ++
 .../_ugvw_extending_isis-addons-extensions.adoc |  17 +
 ...ending_login-via-query-args-prototyping.adoc |  49 ++
 ..._ugvw_extending_replacing-page-elements.adoc | 167 ++++
 .../main/asciidoc/guides/_ugvw_features.adoc    |  26 +
 .../guides/_ugvw_features_blob-attachments.adoc | 121 +++
 .../guides/_ugvw_features_bookmarked-pages.adoc | 108 +++
 .../_ugvw_features_hints-and-copy-url.adoc      |  79 ++
 .../guides/_ugvw_features_recent-pages.adoc     |  53 ++
 .../guides/_ugvw_features_titles-in-tables.adoc |  76 ++
 .../_ugvw_features_user-registration.adoc       |  81 ++
 .../main/asciidoc/guides/_ugvw_isis-addons.adoc |  33 +
 .../src/main/asciidoc/guides/_ugvw_layout.adoc  |  97 +++
 .../guides/_ugvw_request-parameters.adoc        |  53 ++
 .../src/main/asciidoc/guides/cg.adoc            |  30 +-
 .../guides/images/maven-plugin/xsd-goal.png     | Bin 0 -> 46790 bytes
 .../guides/images/maven-plugin/xsd-goal.pptx    | Bin 0 -> 64740 bytes
 .../service-collaborations.png                  | Bin 10368 -> 28874 bytes
 .../service-collaborations.pptx                 | Bin 52460 -> 51472 bytes
 .../ro-spec-resources-and-representations.png   | Bin 0 -> 139796 bytes
 .../src/main/asciidoc/guides/rg.adoc            |  33 +-
 .../src/main/asciidoc/guides/rgant.adoc         |  96 +++
 .../src/main/asciidoc/guides/rgcfg.adoc         |  62 ++
 .../src/main/asciidoc/guides/rgcms.adoc         |  46 +
 .../src/main/asciidoc/guides/rgsvc.adoc         |  40 +
 .../asciidoc/guides/simpleapp-archetype.adoc    |   2 +-
 .../src/main/asciidoc/guides/tg.adoc            |   1 +
 .../src/main/asciidoc/guides/ug.adoc            |  42 +-
 .../src/main/asciidoc/guides/ugbtb.adoc         |  44 +
 .../src/main/asciidoc/guides/ugfun.adoc         |  50 ++
 .../src/main/asciidoc/guides/ugsec.adoc         |  85 ++
 .../src/main/asciidoc/guides/ugtst.adoc         |  50 ++
 .../src/main/asciidoc/guides/ugvro.adoc         |  55 ++
 .../src/main/asciidoc/guides/ugvw.adoc          |  55 ++
 .../src/main/asciidoc/how-isis-works.adoc       |   2 +-
 .../documentation/src/main/asciidoc/index.html  |   2 +-
 .../src/main/asciidoc/isis-in-pictures.adoc     |  44 +-
 .../src/main/asciidoc/migration-notes.adoc      |   1 +
 .../asciidoc/resources/templates/.gitignore     |   1 +
 .../templates/asciidoc-templates-idea.xml       | 365 --------
 ...-settings-file-templates-for-apache-isis.jar | Bin 0 -> 9104 bytes
 .../templates/isis-asciidoc-templates-idea.xml  | 328 ++++++++
 .../resources/templates/isis-template-idea.xml  | 522 ++++++++++++
 .../resources/templates/isis-templates-idea.xml | 804 ------------------
 .../resources/templates/isis-templates2.xml     | 479 -----------
 adocs/template/document.html.erb                |  31 +
 .../apache/isis/applib/AbstractSubscriber.java  |  14 +-
 .../org/apache/isis/applib/AppManifest.java     |   1 +
 .../isis/applib/DomainObjectContainer.java      |  11 +
 .../isis/applib/annotation/DomainObject.java    |  91 ++
 .../applib/annotation/DomainObjectLayout.java   |  38 +-
 .../apache/isis/applib/annotation/Nature.java   |  30 +-
 .../isis/applib/annotation/NatureOfService.java |  22 +-
 .../isis/applib/annotation/Parameter.java       |   2 +-
 .../apache/isis/applib/annotation/Property.java |   4 +
 .../apache/isis/applib/annotation/Title.java    |   2 +-
 .../isis/applib/annotation/ViewModel.java       |  22 +
 .../apache/isis/applib/services/dto/Dto.java    |  21 +
 .../applib/services/dto/Dto_downloadXml.java    |  67 ++
 .../applib/services/dto/Dto_downloadXsd.java    | 125 +++
 .../apache/isis/applib/services/dto/Util.java   |  33 +
 .../services/eventbus/AbstractUiEvent.java      |  97 +++
 .../services/eventbus/ActionDomainEvent.java    |  32 +-
 .../eventbus/ActionInteractionEvent.java        |   8 +
 .../eventbus/CollectionDomainEvent.java         |  31 +-
 .../eventbus/CollectionInteractionEvent.java    |   7 +
 .../services/eventbus/CssClassUiEvent.java      | 102 +++
 .../applib/services/eventbus/IconUiEvent.java   | 101 +++
 .../services/eventbus/ObjectCreatedEvent.java   |  30 +
 .../services/eventbus/ObjectLoadedEvent.java    |  32 +
 .../services/eventbus/ObjectPersistedEvent.java |  30 +
 .../eventbus/ObjectPersistingEvent.java         |  30 +
 .../services/eventbus/ObjectRemovingEvent.java  |  30 +
 .../services/eventbus/ObjectUpdatedEvent.java   |  30 +
 .../services/eventbus/ObjectUpdatingEvent.java  |  30 +
 .../services/eventbus/PropertyDomainEvent.java  |  30 +-
 .../eventbus/PropertyInteractionEvent.java      |   5 +
 .../applib/services/eventbus/TitleUiEvent.java  | 129 +++
 .../services/i18n/TranslatableString.java       |   1 +
 .../isis/applib/services/jaxb/JaxbService.java  |  64 ++
 .../applib/services/swagger/SwaggerService.java |  72 ++
 .../services/swagger/SwaggerServiceMenu.java    |  80 ++
 .../isis/applib/services/swagger/Util.java      |  46 +
 .../urlencoding/UrlEncodingService.java         |  29 +
 .../UrlEncodingServiceUsingBaseEncoding.java    |  57 ++
 .../isis/tool/mavenplugin/IsisMojoAbstract.java |  24 +-
 .../isis/tool/mavenplugin/IsisMojoValidate.java |  15 +-
 .../isis/tool/mavenplugin/IsisMojoXsd.java      | 155 ++++
 .../tool/mavenplugin/MetaModelProcessor.java    |   2 +-
 core/metamodel/pom.xml                          |  11 +
 .../isis/core/commons/lang/ClassExtensions.java |   7 +-
 .../core/commons/lang/StringExtensions.java     |  12 +-
 .../isis/core/metamodel/facets/Annotations.java | 115 +++
 .../facets/ContributeeMemberFacetFactory.java   |   3 +-
 .../action/ActionAnnotationFacetFactory.java    |  10 +-
 .../ActionDomainEventFacetAbstract.java         |   3 -
 .../CollectionAnnotationFacetFactory.java       |  15 +-
 .../callbacks/CreatedCallbackFacetAbstract.java |  35 +
 .../callbacks/CreatedCallbackFacetFactory.java  |  62 ++
 .../CreatedCallbackFacetViaMethod.java          |  65 ++
 .../callbacks/CreatedLifecycleEventFacet.java   |  30 +
 ...ycleEventFacetForDomainObjectAnnotation.java |  49 ++
 .../object/callbacks/LifecycleEventFacet.java   |  28 +
 .../callbacks/LoadCallbackFacetFactory.java     |  68 ++
 .../callbacks/LoadedCallbackFacetAbstract.java  |  37 +
 .../callbacks/LoadedCallbackFacetViaMethod.java |  65 ++
 .../callbacks/LoadedLifecycleEventFacet.java    |  30 +
 ...ycleEventFacetForDomainObjectAnnotation.java |  49 ++
 .../callbacks/LoadingCallbackFacetAbstract.java |  41 +
 .../LoadingCallbackFacetViaMethod.java          |  69 ++
 .../callbacks/PersistCallbackFacetFactory.java  |  78 ++
 ...ersistCallbackViaSaveMethodFacetFactory.java |  78 ++
 .../PersistedCallbackFacetAbstract.java         |  37 +
 .../PersistedCallbackFacetViaMethod.java        |  65 ++
 .../callbacks/PersistedLifecycleEventFacet.java |  30 +
 ...ycleEventFacetForDomainObjectAnnotation.java |  49 ++
 .../PersistingCallbackFacetAbstract.java        |  37 +
 .../PersistingCallbackFacetViaMethod.java       |  65 ++
 .../PersistingLifecycleEventFacet.java          |  30 +
 ...ycleEventFacetForDomainObjectAnnotation.java |  50 ++
 .../callbacks/RemoveCallbackFacetFactory.java   |  78 ++
 ...moveCallbackViaDeleteMethodFacetFactory.java |  78 ++
 .../object/callbacks/RemovedCallbackFacet.java  |   2 +
 .../callbacks/RemovedCallbackFacetAbstract.java |  39 +
 .../RemovedCallbackFacetViaMethod.java          |  69 ++
 .../RemovingCallbackFacetAbstract.java          |  37 +
 .../RemovingCallbackFacetViaMethod.java         |  65 ++
 .../callbacks/RemovingLifecycleEventFacet.java  |  30 +
 ...ycleEventFacetForDomainObjectAnnotation.java |  51 ++
 .../callbacks/UpdateCallbackFacetFactory.java   |  68 ++
 .../callbacks/UpdatedCallbackFacetAbstract.java |  37 +
 .../UpdatedCallbackFacetViaMethod.java          |  65 ++
 .../callbacks/UpdatedLifecycleEventFacet.java   |  30 +
 ...ycleEventFacetForDomainObjectAnnotation.java |  51 ++
 .../UpdatingCallbackFacetAbstract.java          |  37 +
 .../UpdatingCallbackFacetViaMethod.java         |  69 ++
 .../callbacks/UpdatingLifecycleEventFacet.java  |  30 +
 ...ycleEventFacetForDomainObjectAnnotation.java |  51 ++
 .../create/CreatedCallbackFacetAbstract.java    |  37 -
 .../create/CreatedCallbackFacetFactory.java     |  62 --
 .../create/CreatedCallbackFacetViaMethod.java   |  65 --
 .../load/LoadCallbackFacetFactory.java          |  68 --
 .../load/LoadedCallbackFacetAbstract.java       |  37 -
 .../load/LoadedCallbackFacetViaMethod.java      |  65 --
 .../load/LoadingCallbackFacetAbstract.java      |  41 -
 .../load/LoadingCallbackFacetViaMethod.java     |  69 --
 .../persist/PersistCallbackFacetFactory.java    |  80 --
 ...ersistCallbackViaSaveMethodFacetFactory.java |  80 --
 .../persist/PersistedCallbackFacetAbstract.java |  37 -
 .../PersistedCallbackFacetViaMethod.java        |  65 --
 .../PersistingCallbackFacetAbstract.java        |  37 -
 .../PersistingCallbackFacetViaMethod.java       |  65 --
 .../remove/RemoveCallbackFacetFactory.java      |  80 --
 ...moveCallbackViaDeleteMethodFacetFactory.java |  80 --
 .../remove/RemovedCallbackFacetAbstract.java    |  37 -
 .../remove/RemovedCallbackFacetViaMethod.java   |  65 --
 .../remove/RemovingCallbackFacetAbstract.java   |  37 -
 .../remove/RemovingCallbackFacetViaMethod.java  |  65 --
 .../update/UpdateCallbackFacetFactory.java      |  68 --
 .../update/UpdatedCallbackFacetAbstract.java    |  37 -
 .../update/UpdatedCallbackFacetViaMethod.java   |  65 --
 .../update/UpdatingCallbackFacetAbstract.java   |  37 -
 .../update/UpdatingCallbackFacetViaMethod.java  |  69 --
 .../DomainObjectAnnotationFacetFactory.java     | 156 ++++
 ...bleObjectFacetForDomainObjectAnnotation.java |   7 +-
 ...ectLayoutAnnotationUsingCssClassUiEvent.java | 106 +++
 .../DomainObjectLayoutFacetFactory.java         |  31 +-
 ...nObjectLayoutAnnotationUsingIconUiEvent.java | 103 +++
 ...ObjectLayoutAnnotationUsingTitleUiEvent.java | 119 +++
 .../RemoveSubscriberMethodsFacetFactory.java    |  70 ++
 .../facets/object/parseable/ParseableFacet.java |   2 +-
 .../RecreatableObjectFacetAbstract.java         |  48 +-
 ...creatableObjectFacetDeclarativeAbstract.java | 166 ----
 ...ectFacetDeclarativeInitializingAbstract.java | 165 ++++
 .../RecreatableObjectFacetFactory.java          |  18 +-
 ...acetForRecreatableDomainObjectInterface.java |   6 +-
 ...jectFacetForRecreatableObjectAnnotation.java |   5 +-
 ...bjectFacetForRecreatableObjectInterface.java |   6 +-
 ...atableObjectFacetForViewModelAnnotation.java |  41 +
 ...eObjectFacetForXmlRootElementAnnotation.java |  65 ++
 .../annotation/RegExFacetOnTypeAnnotation.java  |   4 +-
 .../RegExFacetOnTypeAnnotationFactory.java      |   3 +-
 .../annotation/TitleAnnotationFacetFactory.java |  32 +-
 .../TitleFacetViaTitleAnnotation.java           |  29 +-
 .../facets/object/viewmodel/ViewModelFacet.java |  49 ++
 .../objectvalue/multiline/MultiLineFacet.java   |   4 +-
 .../facets/objectvalue/regex/RegExFacet.java    |   1 +
 .../objectvalue/regex/RegExFacetAbstract.java   |  12 +-
 .../regex/RegExFacetForParameterAnnotation.java |   7 +-
 ...egExFacetFromRegExAnnotationOnParameter.java |   7 +-
 .../PropertyAnnotationFacetFactory.java         |  14 +-
 .../regex/RegExFacetForPropertyAnnotation.java  |   8 +-
 .../RegExFacetForRegExAnnotationOnProperty.java |   7 +-
 .../json/LayoutMetadataReaderFromJson.java      |   8 +-
 .../metamodel/progmodel/ProgrammingModel.java   |   6 +-
 .../container/DomainObjectContainerDefault.java |  11 +
 .../Persistable_downloadJdoMetadata.java        |  80 ++
 .../metamodel/services/jdosupport/Util.java     |  33 +
 .../services/swagger/SwaggerServiceDefault.java |  81 ++
 .../services/swagger/internal/Caching.java      |  48 ++
 .../swagger/internal/ClassExcluder.java         |  52 ++
 .../services/swagger/internal/Generation.java   | 832 +++++++++++++++++++
 .../swagger/internal/SwaggerSpecGenerator.java  |  64 ++
 .../services/swagger/internal/Tagger.java       |  61 ++
 .../services/swagger/internal/Util.java         | 166 ++++
 .../swagger/internal/ValuePropertyFactory.java  | 176 ++++
 .../specloader/specimpl/ContributeeMember.java  |   2 +-
 .../specimpl/ObjectActionMixedIn.java           |   3 +-
 .../specimpl/ObjectMemberAbstract.java          |   2 +-
 .../isis/core/metamodel/util/EventUtil.java     |  45 +
 .../dflt/ProgrammingModelFacetsJava5.java       |  26 +-
 .../CreatedCallbackFacetFactoryTest.java        |   4 +-
 .../DeleteCallbackFacetFactoryTest.java         |   6 +-
 .../callback/LoadCallbackFacetFactoryTest.java  |   6 +-
 .../PersistAndSaveCallbackFacetFactoryTest.java |   8 +-
 .../PersistCallbackFacetFactoryTest.java        |   6 +-
 ...RemoveAndDeleteCallbackFacetFactoryTest.java |   8 +-
 .../RemoveCallbackFacetFactoryTest.java         |   6 +-
 .../callback/SaveCallbackFacetFactoryTest.java  |   6 +-
 .../UpdateCallbackFacetFactoryTest.java         |   6 +-
 .../TitleAnnotationFacetFactoryTest.java        |  13 +-
 .../TitleFacetViaTitleAnnotationTest.java       |  27 +-
 .../regex/RegExFacetAnnotationTest.java         |  14 +-
 .../swagger/internal/GenerationTest.java        |  48 ++
 .../services/swagger/internal/TaggerTest.java   |  69 ++
 core/runtime/pom.xml                            |   5 +
 .../i18n/po/TranslationServicePoMenu.java       |  37 +-
 .../services/memento/MementoServiceDefault.java |  38 +-
 .../system/persistence/PersistenceSession.java  |  96 ++-
 .../persistence/spi/JdoObjectIdSerializer.java  |   2 +-
 .../jaxb/CatalogingSchemaOutputResolver.java    |  85 ++
 .../services/jaxb/JaxbServiceDefault.java       | 142 ++++
 .../services/jaxb/StreamResultWithWriter.java   |  45 +
 .../utils/ActionInvocationMementoDtoUtils.java  |  12 +-
 ...odaLocalTimeXMLGregorianCalendarAdapter.java |   4 -
 .../jaxbadapters/PersistentEntityAdapter.java   |  67 ++
 ...atorOrAuthorizorTest_isVisibleInAnyRole.java |   3 -
 .../ActionResultRepresentation.java             |   3 +-
 .../rendering/RendererContext.java              |  18 +-
 .../rendering/RendererContext2.java             |   2 +-
 .../rendering/RendererContext4.java             |   3 +-
 .../rendering/RendererContext5.java             |   4 +-
 .../rendering/RendererContext6.java             |  33 +
 .../rendering/ReprRendererAbstract.java         |   6 +-
 .../restfulobjects/rendering/Responses.java     |  57 +-
 .../AbstractObjectMemberReprRenderer.java       |   5 +-
 .../domainobjects/ActionResultReprRenderer.java | 107 ++-
 .../domainobjects/DomainObjectReprRenderer.java |  26 +-
 .../domainobjects/ListReprRenderer.java         |   8 +-
 .../domainobjects/ObjectActionReprRenderer.java |   9 +-
 .../ObjectAndActionInvocation.java              |  43 +-
 .../domainobjects/ObjectAndCollection2.java     |  39 +
 .../domainobjects/ObjectAndProperty2.java       |  36 +
 .../ObjectCollectionReprRenderer.java           |  19 +-
 .../ObjectPropertyReprRenderer.java             |  12 +-
 .../domainobjects/ScalarValueReprRenderer.java  |   5 +-
 .../AbstractTypeFeatureReprRenderer.java        |   4 +-
 .../domaintypes/DomainTypeReprRenderer.java     |   6 +-
 .../service/RepresentationService.java          |  46 +-
 .../RepresentationServiceContentNegotiator.java | 214 +++++
 .../RepresentationServiceForRestfulObjects.java | 265 +-----
 .../conneg/ContentNegotiationService.java       |   2 -
 .../ContentNegotiationServiceAbstract.java      |  33 +
 ...NegotiationServiceForRestfulObjectsV1_0.java | 266 ++++++
 ...ontentNegotiationServiceOrgApacheIsisV1.java | 404 +++++++++
 core/viewer-restfulobjects-server/pom.xml       |  11 +
 .../restfulobjects/server/ResourceContext.java  |  45 +-
 .../server/RestfulObjectsApplication.java       |   6 +
 ...estfulObjectsApplicationExceptionMapper.java |  12 +-
 .../conneg/RestfulObjectsJaxbWriterForXml.java  |  67 ++
 .../restfulobjects/server/conneg/Util.java      |  33 +
 .../DomainObjectResourceServerside.java         |  73 +-
 .../server/resources/DomainResourceHelper.java  |  54 +-
 .../DomainServiceResourceServerside.java        |  41 +-
 .../resources/DomainTypeResourceServerside.java |  19 +-
 .../resources/HomePageResourceServerside.java   |   3 +-
 .../server/resources/ResourceAbstract.java      |  20 +-
 .../server/resources/SwaggerSpecResource.java   | 125 +++
 .../resources/UserResourceServerside.java       |   5 +-
 .../resources/VersionResourceServerside.java    |   3 +-
 ...ontextTest_ensureCompatibleAcceptHeader.java |   2 +-
 .../server/ResourceContextTest_getArg.java      |   4 +-
 .../viewer/wicket/model/models/ActionModel.java |   2 -
 .../model/models/EntityCollectionModel.java     |  17 +-
 .../ActionResultResponseHandlingStrategy.java   |  13 +-
 .../entityactions/EntityActionLinkFactory.java  |   4 +-
 .../entityactions/EntityActionUtil.java         |   2 +-
 .../actionmenu/serviceactions/CssMenuItem.java  |   4 +-
 .../ServiceActionLinkFactory.java               |   5 +-
 .../ui/components/actions/ActionPanel.java      |  72 +-
 .../collection/bulk/BulkActionsLinkFactory.java |   5 +-
 .../components/scalars/ScalarPanelAbstract.java |   4 +-
 .../ScalarPanelTextFieldParseableAbstract.java  |   2 +-
 .../StandaloneCollectionPanel.java              |   2 +-
 .../widgets/linkandlabel/ActionLinkFactory.java |   5 +-
 .../linkandlabel/ActionLinkFactoryAbstract.java |   3 +
 .../wicket/ui/pages/entity/EntityPage.java      |  21 -
 ...ppAppManifestWithFixturesBypassSecurity.java |  35 +
 .../java/domainapp/dom/simple/SimpleObject.java |  10 +-
 .../application/simpleapp/integtests/pom.xml    | 130 +--
 example/application/simpleapp/webapp/pom.xml    |   1 -
 .../src/main/webapp/WEB-INF/isis.properties     |  20 +
 .../webapp/src/main/webapp/WEB-INF/web.xml      |  17 +-
 .../webapp/src/main/webapp/about/index.html     |  18 +-
 .../src/main/webapp/swagger-ui/index.html       | 122 +++
 1208 files changed, 44359 insertions(+), 34158 deletions(-)
----------------------------------------------------------------------



[24/52] [abbrv] isis git commit: ISIS-1243: renamed ug.adoc to ugfun.adoc. Added standard section to each of the guides so can navigate between each easily.

Posted by mg...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_domain-driven-design.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_domain-driven-design.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_domain-driven-design.adoc
deleted file mode 100644
index f3994c5..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_domain-driven-design.adoc
+++ /dev/null
@@ -1,79 +0,0 @@
-[[_ug_core-concepts_philosophy_domain-driven-design]]
-= Domain-Driven Design
-: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/
-
-There's no doubt that we developers love the challenge of understanding and deploying complex technologies. But understanding the nuances and subtleties of the business domain itself is just as great a challenge, perhaps more so. If we devoted our efforts to understanding and addressing those subtleties, we could build better, cleaner, and more maintainable software that did a better job for our stakeholders. And there's no doubt that our stakeholders would thank us for it.
-
-A couple of years back Eric Evans wrote his book link:http://www.amazon.co.uk/Domain-driven-Design-Tackling-Complexity-Software/dp/0321125215[Domain-Driven Design], which is well on its way to becoming a seminal work. In fact, most if not all of the ideas in Evans' book have been expressed before, but what he did was pull those ideas together to show how predominantly object-oriented techniques can be used to develop rich, deep, insightful, and ultimately useful business applications.
-
-There are two central ideas at the heart of domain-driven design.
-
-* the *_ubiquitous language_* is about getting the whole team (both domain experts and developers) to communicate more transparently using a domain model.
-
-* Meanwhile, *_model-driven design_* is about capturing that model in a very straightforward manner in code.
-
-Let's look at each in turn.
-
-[[_ug_core-concepts_philosophy_domain-driven-design_ubiquitous-language]]
-== Ubiquitous Language
-
-It's no secret that the IT industry is plagued by project failures. Too often systems take longer than intended to implement, and when finally implemented, they don't address the real requirements anyway.
-
-Over the years we in IT have tried various approaches to address this failing. Using waterfall methodologies, we've asked for requirements to be fully and precisely written down before starting on anything else. Or, using agile methodologies, we've realized that requirements are likely to change anyway and have sought to deliver systems incrementally using feedback loops to refine the implementation.
-
-But let's not get distracted talking about methodologies. At the end of the day what really matters is communication between the domain experts (that is, the business) who need the system and the techies actually implementing it. If the two don't have and cannot evolve a shared understanding of what is required, then the chance of delivering a useful system will be next to nothing.
-
-Bridging this gap is traditionally what business analysts are for; they act as interpreters between the domain experts and the developers. However, this still means there are two (or more) languages in use, making it difficult to verify that the system being built is correct. If the analyst mistranslates a requirement, then neither the domain expert nor the application developer will discover this until (at best) the application is first demonstrated or (much worse) an end user sounds the alarm once the application has been deployed into production.
-
-Rather than trying to translate between a business language and a technical language, with  _DDD_ we aim to have the business and developers using the same terms for the same concepts in order to create a single *_domain model_*. This domain model identifies the relevant concepts of the domain, how they relate, and ultimately where the responsibilities are. This single domain model provides the vocabulary for the  ubiquitous language for our system.
-
-
-.Ubiquitous Language
-****
-Build a common language between the domain experts and developers by using the concepts of the domain model as the primary means of communication. Use the terms in speech, in diagrams, in writing, and when presenting.
-
-If an idea cannot be expressed using this set of concepts, then go back and extend the model. Look for and remove ambiguities and inconsistencies.
-****
-
-
-Creating a  ubiquitous language calls upon everyone involved in the system's development to express what they are doing through the vocabulary provided by the model. If this can't be done, then our model is incomplete. Finding the missing words deepens our understanding of the domain being modeled.
-
-This might sound like nothing more than me insisting that the developers shouldn't use jargon when talking to the business. Well, that's true enough, but it's not a one-way street. A  *ubiquitous language* demands that the developers work hard to understand the problem domain, but it also demands that the business works hard in being  *precise* in its naming and descriptions of those concepts. After all, ultimately the developers will have to express those concepts in a computer programming language.
-
-Also, although here I'm talking about the "domain experts" as being a homogeneous group of people, often they may come from different branches of the business. Even if we weren't building a computer system, there's a lot of value in helping the domain experts standardize their own terminology. Is the marketing department's "prospect" the same as sales' "customer," and is that the same as an after-sales "contract"?
-
-The need for precision within the  ubiquitous language also helps us scope the system. Most business processes evolve piecemeal and are often quite ill-defined. If the domain experts have a very good idea of what the business process should be, then that's a good candidate for automation, that is, including it in the scope of the system. But if the domain experts find it hard to agree, then it's probably best to leave it out. After all, human beings are rather more capable of dealing with fuzzy situations than computers.
-
-So, if the development team (business and developers together) continually searches to build their  ubiquitous language, then the domain model naturally becomes richer as the nuances of the domain are uncovered. At the same time, the knowledge of the business domain experts also deepens as edge conditions and contradictions that have previously been overlooked are explored.
-
-We use the  ubiquitous language to build up a domain model. But what do we do  *with* that model? The answer to that is the second of our central ideas.
-
-
-== Model-Driven Design
-
-Of the various methodologies that the IT industry has tried, many advocate the production of separate analysis models and implementation models. One example (from the mid 2000s) was that of the  _OMG_'s Model-Driven Architecture ( _MDA_) initiative, with its platform-independent model (the  _PIM_) and a platform-specific model (the  _PSM_).
-
-Bah and humbug! If we use our  ubiquitous language just to build up a high-level analysis model, then we will re-create the communication divide. The domain experts and business analysts will look only to the analysis model, and the developers will look only to the implementation model. Unless the mapping between the two is completely mechanical, inevitably the two will diverge.
-
-What do we mean by  *model* anyway? For some, the term will bring to mind  UML class or sequence diagrams and the like. But this isn't a model; it's a visual  *representation* of some aspect of a model. No, a domain model is a group of related concepts, identifying them, naming them, and defining how they relate. What is in the model depends on what our objective is. We're not looking to simply model everything that's out there in the real world. Instead, we want to take a relevant abstraction or simplification of it and then make it do something useful for us.  A model is neither right nor wrong, just more or less useful.
-
-For our  ubiquitous language to have value, the domain model that encodes it must have a straightforward, literal representation to the design of the software, specifically to the implementation. Our software's design should be driven by this model; we should have a model-driven design.
-
-
-.Model-Driven Design
-****
-There must be a straightforward and very literal way to represent the domain model in terms of software. The model should balance these two requirements: form the  ubiquitous language of the development team and be representable in code.
-
-Changing the code means changing the model; refining the model requires a change to the code.
-****
-
-
-Here also the word  *design* might mislead; some might be thinking of design documents and design diagrams, or perhaps of user interface (UX) design. But by  *design* we mean a way of organizing the domain concepts, which in turn leads to the way in which we organize their representation in code.
-
-Luckily, using *_object-oriented_* (_OO_) languages such as Java, this is relatively easy to do;  _OO_ is based on a modeling paradigm anyway. We can express domain concepts using classes and interfaces, and we can express the relationships between those concepts using associations.
-
-So far so good. Or maybe, so far so much motherhood and apple pie. Understanding the  _DDD_ concepts isn't the same as being able to apply them, and some of the  _DDD_ ideas can be difficult to put into practice. Time to discuss the naked objects pattern and how it eases that path by applying these central ideas of _DDD_ in a very concrete way.
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_hexagonal-architecture.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_hexagonal-architecture.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_hexagonal-architecture.adoc
deleted file mode 100644
index a6e0f45..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_hexagonal-architecture.adoc
+++ /dev/null
@@ -1,29 +0,0 @@
-[[_ug_core-concepts_philosophy_hexagonal-architecture]]
-= Hexagonal Architecture
-: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/
-
-One of the patterns that Evans discusses in his book is that of a *layered architecture*.  In it he describes why the domain model lives in its own layer within the architecture. The other layers of the application (usually presentation, application, and persistence) have their own responsibilities, and are completely separate.  Each layer is cohesive and depending only on the layers below.  In particular, we have a layer dedicated to the domain model. The code in this layer is unencumbered with the (mostly technical) responsibilities of the other layers and so can evolve to tackle complex domains as well as simple ones.
-
-This is a well-established pattern, almost a de-facto; there's very little debate that these responsibilities should be kept separate from each other.  With Apache Isis the responsibility for presentation is a framework concern, the responsibility for the domain logic is implemented by the (your) application code.
-
-A few years ago Alistair Cockburn reworked the traditional layered architecture diagram and came up with the *_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.
-====
-
-.The hexagonal architecture emphasizes multiple implementations of the different layers.
-image::{_imagesdir}core-concepts/philosophy/hexagonal-architecture.png[width="700px"]
-
-What Cockburn is emphasizing is that there's usually more than one way *into* an application (what he called the *_user-side' ports_*) and more than one way  *out of* an application too (the *_data-side ports_*). This is very similar to the concept of primary and secondary actors in use cases: a primary actor (often a human user but not always) is active and initiates an interaction, while a secondary actor (almost always an external system) is passive and waits to be interacted with.
-
-Associated with each port can be an *_adapter_* (in fact, Cockburn's alternative name for this architecture is *_ports and adapters_*). An adapter is a device (piece of software) that talks in the protocol (or  _API_) of the port. Each port could have several adapters.
-
-Apache Isis maps very nicely onto the  *hexagonal architecture*.  Apache Isis' viewers act as user-side adapters and use the Apache Isis metamodel API as a port into the domain objects.   For the data side, we are mostly concerned with persisting domain objects to some sort of object store.  Here Apache Isis delegates most of the heavy lifting to ORM implementing the JDO API.  Most of the time this will be DataNucleus configured to persist to an RDBMS, but DataNucleus can also support other object stores, for example Neo4J.  Alternatively Apache Isis can be configured to persist using some other JDO implementation, for example Google App Engine.
-
-
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_how-eases-ddd.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_how-eases-ddd.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_how-eases-ddd.adoc
deleted file mode 100644
index d2bba65..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_how-eases-ddd.adoc
+++ /dev/null
@@ -1,74 +0,0 @@
-[[_ug_core-concepts_philosophy_how-eases-ddd]]
-= How Apache Isis eases DDD
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The case for  _DDD_ might be compelling, but that doesn't necessarily make it easy to do. Let's take a look at some of the
-challenges that  _DDD_ throws up and see how Apache Isis (and its implementation of the naked objects pattern) helps address them.
-
-== DDD takes a conscious effort
-
-Here's what Eric Evans says about ubiquitous language:
-
-pass:[<div class="extended-quote-first"><p>]With a conscious effort by the [development] team the domain model can provide the backbone for [the] common [ubiquitous] language...connecting team communication to the software implementation."
-pass:[</p></div>]
-
-pass:[<div class="extended-quote-attribution"><p>]-- Eric Evans
-pass:[</p></div>]
-
-The word to pick up on here is *conscious*.  It takes a conscious effort by the entire team to develop the ubiquitous language. Everyone in the team must challenge the use of new or unfamiliar terms, must clarify concepts when used in a new context, and in general must be on the lookout for sloppy thinking. This takes willingness on the part of all involved, not to mention some practice.
-
-With Apache Isis, though, the  ubiquitous language evolves with scarcely any effort at all. For the business experts, the Apache Isis viewers show the domain concepts they identify and the relationships between those concepts in a straightforward fashion. Meanwhile, the developers can devote themselves to encoding those domain concepts directly as domain classes. There's no technology to get distracted by; there is literally nothing else for the developers to work on.
-
-
-== DDD must be grounded
-
-Employing a  model-driven design isn't necessarily straightforward, and the development processes used by some organizations positively hinder it. It's not sufficient for the business analysts or architects to come up with some idealized representation of the business domain and then chuck it over the wall for the programmers to do their best with.
-
-Instead, the concepts in the model must have a very literal representation in code. If we fail to do this, then we open up the communication divide, and our  ubiquitous language is lost. There is literally no point having a domain model that cannot be represented in code. We cannot invent our ubiquitous language in a vacuum, and the developers must ensure that the model remains grounded in the doable.
-
-In Apache Isis, we have a very pure one-to-one correspondence between the domain concepts and its implementation. Domain concepts are represented as classes and interfaces, easily demonstrated back to the business. If the model is clumsy, then the application will be clumsy too, and so the team can work together to find a better implementable model.
-
-
-
-== Model must be understandable
-
-If we are using code as the primary means of expressing the model, then we need to find a way to make this model understandable to the business.
-
-We could generate UML diagrams and the like from code. That will work for some members of the business community, but not for everyone. Or we could generate a PDF document from Javadoc comments, but comments aren't code and so the document may be inaccurate.  Anyway, even if we do create such a document, not everyone will read it.
-
-A better way to represent the model is to show it in action as a working prototype. As we show in the xref:ug.adoc#_ug_getting-started[Getting Started] section, Apache Isis enables this with ease. Such prototypes bring the domain model to life, engaging the audience in a way that a piece of paper never can.
-
-Moreover, with Apache Isis prototypes, the domain model will come shining through. If there are mistakes or misunderstandings in the domain model (inevitable when building any complex system), they will be obvious to all.
-
-
-
-
-== Architecture must be robust
-
-_DDD_ rightly requires that the domain model lives in its own layer within the architecture. The other layers of the application (usually presentation, application, and persistence) have their own responsibilities, and are completely separate.
-
-However, there are two immediate issues. The first is rather obvious: custom coding each of those other layers is an expensive proposition. Picking up on the previous point, this in itself can put the kibosh on using prototyping to represent the model, even if we wanted to do so.
-
-The second issue is more subtle. It takes real skill to ensure the correct separation of concerns between these layers, if indeed you can get an agreement as to what those concerns actually are. Even with the best intentions, it's all too easy for custom-written layers to blur the boundaries and put (for example) validation in the user interface layer when it should belong to the domain layer. At the other extreme, it's quite possible for custom layers to distort or completely subvert the underlying domain model.
-
-Because of Apache Isis' generic  __OOUI__s, there's no need to write the other layers of the architecture.  Of course, this reduces the development cost. But more than that, there will be no leakage of concerns outside the domain model. All the validation logic *must* be in the domain model because there is nowhere else to put it.
-
-Moreover, although Apache Isis does provide a complete runtime framework, there is no direct coupling of your domain model to the framework. That means it is very possible to take your domain model prototyped in Naked Objects and then deploy it on some other  _J(2)EE_ architecture, with a custom _UI_ if you want.  Apache Isis guarantees that your domain model is complete.
-
-
-
-
-== Extending the reach of DDD
-
-Domain-driven design is often positioned as  being applicable only to complex domains; indeed, the subtitle of Evans book is  "Tackling Complexity in the Heart of Software". The corollary is that DDD is overkill for simpler domains. The trouble is that we immediately have to make a choice: is the domain complex enough to warrant a domain-driven approach?
-
-This goes back to the previous point, building and maintaining a layered architecture. It doesn't seem cost effective to go to all the effort of a DDD approach if the underlying domain is simple.
-
-However, with Apache Isis, we don't write these other layers, so we don't have to make a call on how complex our domain is. We can start working solely on our domain, even if we suspect it will be simple. If it is indeed a simple domain, then there's no hardship, but if unexpected subtleties arise, then we're in a good position to handle them.
-
-If you're just starting out writing domain-driven applications, then Apache Isis should significantly ease your journey into applying _DDD_. On the other hand, if you've used _DDD_ for a while, then you should find Isis a very useful new tool in your arsenal.
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_naked-objects-pattern.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_naked-objects-pattern.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_naked-objects-pattern.adoc
deleted file mode 100644
index 70d6690..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_naked-objects-pattern.adoc
+++ /dev/null
@@ -1,60 +0,0 @@
-[[_ug_core-concepts_philosophy_naked-objects-pattern]]
-= Naked Objects Pattern
-: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 implements the naked objects pattern, originally formulated by Richard Pawson.  So who better than Richard to explain the origination of the idea?
-
-pass:[<div class="extended-quote-first"><p>]The Naked Objects pattern arose, at least in part, from my own frustration at the lack of success of the domain-driven approach. Good examples were hard to find--as they are still.
-pass:[</p></div>]
-
-pass:[<div class="extended-quote"><p>]A common complaint from _DDD_ practitioners was that it was hard to gain enough commitment from business stakeholders, or even to engage them at all. My own experience suggested that it was nearly impossible to engage business managers with UML diagrams.  It was much easier to engage them in rapid prototyping -- where they could see and interact with the results -- but most forms of rapid prototyping concentrate on the presentation layer, often at the expense of the underlying model and certainly at the expense of abstract thinking.
-pass:[</p></div>]
-
-pass:[<div class="extended-quote"><p>]Even if you could engage the business sponsors sufficiently to design a domain model, by the time you'd finished developing the system on top of the domain model, most of its benefits had disappeared. It's all very well creating an agile domain object model, but if any change to that model also dictates the modification of one or more layers underneath it (dealing with persistence) and multiple layers on top (dealing with presentation), then that agility is practically worthless.
-pass:[</p></div>]
-
-pass:[<div class="extended-quote"><p>]The other concern that gave rise to the birth of Naked Objects was how to make user interfaces of mainstream business systems more "expressive" -- how to make them feel more like using a drawing program or _CAD_ system. Most business systems are not at all expressive; they treat the user merely as a dumb *process-follower*, rather than as an empowered *problem-solver*.  Even the so-called usability experts had little to say on the subject: try finding the word "empowerment" or any synonym thereof in the index of any book on usability. Research had demonstrated that the best way to achieve expressiveness was to create an object-oriented user interface (_OOUI_). In practice, though, __OOUI__s were notoriously hard to develop.
-pass:[</p></div>]
-
-pass:[<div class="extended-quote"><p>]Sometime in the late 1990s, it dawned on me that if the domain model really did represent the "ubiquitous language" of the business and those domain objects were behaviorally rich (that is, business logic is encapsulated as methods on the domain objects rather than in procedural scripts on top of them), then the _UI_ could be nothing more than a reflection of the user interface. This would solve both of my concerns. It would make it easier to do domain-driven design, because one could instantly translate evolving domain modeling ideas into a working prototype. And it would deliver an expressive, object-oriented user interface for free. Thus was born the idea of Naked Objects.
-pass:[</p></div>]
-
-pass:[<div class="extended-quote-attribution"><p>]-- Richard Pawson
-pass:[</p></div>]
-
-You can learn much more about the pattern in the book, link:http://www.amazon.com/exec/obidos/ISBN=0470844205/[Naked Objects], also freely available to link:http://www.nakedobjects.org/book/[read online].  Richard co-wrote the book with one of Apache Isis' committers, Robert Matthews, who was in turn the author of the Naked Objects Framework for Java (the original codebase of of Apache Isis).
-
-You might also want to read Richard's link:resources/core-concepts/Pawson-Naked-Objects-thesis.pdf[PhD on the subject].
-
-
-[TIP]
-====
-One of the external examiners for Richard's PhD was link:http://en.wikipedia.org/wiki/Trygve_Reenskaug[Trygve Reenskaug], who originally formulated the MVC pattern at Xeroc PARC.  In his paper, link:http://heim.ifi.uio.no/~trygver/2007/2007.02.13-babyUML.pdf[Baby UML], Reenskaug describes that when implemented the first MVC, "the conventional wisdom in the group was that objects should be visible and tangible, thus bridging the gap between the human brain and the abstract data within the computer."  Sound familiar?  It's interesting to speculate what might have been if this idea had been implemented back then in the late 70s.
-
-Reenskaug then goes on to say that "this simple and powerful idea failed because ... users were used to seeing [objects] from different perspectives. The visible and tangible object would get very complex if it should be able to show itself and be manipulated in many different ways."
-
-In Apache Isis the responsibility of rendering an object is not the object itself, it is the framework.  Rather, the object inspects the object and uses that to decide how to render the object.  This is also extensible.  In the link:http://www.isisaddons.org[Isis Addons] (non-ASF) the http://github.com/isisaddons/isis-wicket-gmap3[Isis addons' gmap3] wicket extension renders any object with latitude/longitude on a map, while http://github.com/isisaddons/isis-wicket-fullcalendar2[Isis addons' fullcalendar2 wicket extension] renders any object with date(s) on a calendar.
-====
-
-
-
-include::_ug_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping.adoc[leveloffset=+1]
-
-
-
-
-== What this means in practice
-
-The screencast below shows what all of this means in practice, showing the relationship between a running app and the actual code underneath.
-
-.How Apache Isis builds a webapp from the underlying domain object model…
-video::ludOLyi6VyY[youtube,width="640px",height="472px"]
-
-[NOTE]
-====
-This screencast shows Apache Isis v1.0.0, Jan 2013.  The UI has been substantially refined since that release.
-====
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping.adoc
deleted file mode 100644
index 96b6fac..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping.adoc
+++ /dev/null
@@ -1,18 +0,0 @@
-[[_ug_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping]]
-= Object Interface Mapping
-: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/
-
-
-Another -- more technical -- way to think about the naked objects pattern is as an _object interface mapper_, or `OIM`.  We sometimes use this idea to explain naked objects to a bunch of developers.
-
-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 the naked objects pattern as representing the concept of mapping domain objects to a user interface.
-
-This is the way that the link:http://metawidget.org/[MetaWidget] team, in particular Richard Kennard, the primary contributor, likes to describe their tool.  MetaWidget has a number of ideas in common with Apache Isis, specifically the runtime generation of a UI for domain objects.  You can hear more from Kennard and others on this http://devchat.tv/js-jabber/150-jsj-oims[Javascript Jabber podcast].
-
-[NOTE]
-====
-We compare Apache Isis' with MetaWidget xref:ug.adoc#_ug_core-concepts_principles_apache-isis-vs_metawidget[here].
-====
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles.adoc
deleted file mode 100644
index da52685..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles.adoc
+++ /dev/null
@@ -1,16 +0,0 @@
-[[_ug_core-concepts_principles]]
-= Principles and Values
-: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 section describes some of the core principles and values that the framework aims to honour and support.
-
-The first of these relate to how we believe your domain application should be written: it should be decoupled, testable and so on).  Others relate to the implementation of the framework itself.
-
-The section concludes by contrasting the framework with some other open source frameworks commonly used.
-
-include::_ug_core-concepts_principles_your-apps.adoc[leveloffset=+1]
-include::_ug_core-concepts_principles_isis-itself.adoc[leveloffset=+1]
-include::_ug_core-concepts_principles_apache-isis-vs.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs.adoc
deleted file mode 100644
index bd8c2c0..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs.adoc
+++ /dev/null
@@ -1,16 +0,0 @@
-[[_ug_core-concepts_principles_apache-isis-vs]]
-= 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/
-
-Many other frameworks promise rapid application development and provide automatically generated user interfaces, so how
-do they compare to Apache Isis?
-
-
-include::_ug_core-concepts_principles_apache-isis-vs_mvc-server-side-frameworks.adoc[leveloffset=+1]
-include::_ug_core-concepts_principles_apache-isis-vs_cqrs.adoc[leveloffset=+1]
-include::_ug_core-concepts_principles_apache-isis-vs_event-sourcing.adoc[leveloffset=+1]
-include::_ug_core-concepts_principles_apache-isis-vs_metawidget.adoc[leveloffset=+1]
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_cqrs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_cqrs.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_cqrs.adoc
deleted file mode 100644
index 0a59241..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_cqrs.adoc
+++ /dev/null
@@ -1,28 +0,0 @@
-[[_ug_core-concepts_principles_apache-isis-vs_cqrs]]
-= vs CQRS
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-The CQRS architectural pattern (it stands for "Command Query Responsbility Separation") is the idea that the domain objects that mutate the state of the system - to which commands are sent and which then execute - should be separated from the mechanism by which the state of the system is queried (rendered).  The former are sometimes called the "write (domain) model", the latter the "read model".
-
-In the canonical version of this pattern there are separate datastores.  The commands act upon a command/write datastore.  The data in this datastore is then replicated in some way to the query/read datastore, usually denormalized or otherwise such that it is easy to query.  CQRS advocates recommend using very simple (almost naive) technology for the query/read model; it should be a simple projection of the query datastore.  Complexity instead lives elsewhere: business logic in the command/write model, and in the transformation logic betweeen the command/write and read/query datastores.  In particular, there is no requirement for the two datastores to use the same technology: one might be an RDBMS while the other a NoSQL datastore or even datawarehouse.
-
-In most implementations the command and query datastores are _not_ updated in the same transaction; instead there is some sort of replication mechanism.  This also means that the query datastore is eventually consistent rather than always consistent; there could be a lag of a few seconds before it is updated.  This means in turn that CQRS implementations require mechanisms to cater for offline query datastores; usually some sort of event bus.
-
-The CQRS architecture's extreme separation of responsibilities can result in a lot of boilerplate.  Any given domain concept, eg `Customer`, must be represented both in the command/write model and also in the query/read model.  Each business operation upon the command model is reified as a command object, for example `PlaceOrderCommand`.
-
-Comparing CQRS to Apache Isis, the most obvious difference is that Apache Isis does not separate out a command/write model from a query/read model, and there is usually just a single datastore.  But then again, having a separate read model just so that the querying is very straightforward is pointless with Apache Isis because, of course, Isis provides the UI "for free".
-
-There are other reasons though why a separate read model might make sense, such as to precompute particular queries, or against denormalized data.  In these cases Apache Isis can often provide a reasonable alternative, namely to map domain entities against RDBMS views, either materialized views or dynamic.  In such cases there is still only a single physical datastore, and so transactional integrity is retained.
-
-Or, the CQRS architecture can be more fully implemented with Apache Isis by introducing a separate read model, synchronized using the xref:rgsvc.adoc#_rgsvc-api_PublishingService[`PublishingService`], or using xref:rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscribers]  on the xref:rgsvc.adoc#_rgsvc-api_EventBusService[`EventBusService`].  One can then use xref:ugbtb.adoc#_ugbtb_more-advanced_view-models[view models] to surface the data in the external read datastore.
-
-With respect to commands, Apache Isis does of course support the xref:rgsvc.adoc#_rgsvc-spi_CommandService[`CommandService`] which allows each business action to be reified into a `Command`.  However, names are misleading here: Apache Isis' commands are relatively passive, merely recording the intent of the user to invoke some operation.  In a CQRS architecture, though, commands take a more active role, locating and acting upon the domain objects.  More significantly, in CQRS each command has its own class, such as `PlaceOrderCommand`, instantiated by the client and then executed.  With Apache Isis, though, the end-user merely invokes the `placeOrder(...)` action upon the domain object; the framework itself creates the `Command` as a side-effect of this.
-
-In CQRS the commands correspond to the business logic that mutates the system.  Whether this logic is part of the command class (`PlaceOrderCommand`) or whether that command delegates to methods on the domain object is an implementation detail; but it certainly is common for the business logic to be wholly within the command object and for the domain object to be merely a data holder of the data within the command/write datastore.
-
-In Apache Isis this same separation of business logic from the underlying data can be accomplished most straightforwardly using xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling_mixins[mixins] or xref:ug.adoc#_ug_how-tos_contributed-members[contributions].  In the UI (surfaced by the xref:ugvw.adoc#[Wicket viewer]) or in the REST API (surfaced by the xref:ugvro.adoc#[RestfulObjects viewer]) the behaviour appears to reside on the domain object; however the behaviour actually resides on separate classes and is mixed in (like a trait) only at runtime.
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_event-sourcing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_event-sourcing.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_event-sourcing.adoc
deleted file mode 100644
index 3e756ee..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_event-sourcing.adoc
+++ /dev/null
@@ -1,19 +0,0 @@
-[[_ug_core-concepts_principles_apache-isis-vs_event-sourcing]]
-= vs Event Sourcing
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The link:_ug_core-concepts_principles_apache-isis-vs_cqrs[CQRS architecture], discussed above, is often combined with _Event Sourcing_ pattern, though they are separate ideas.
-
-With event sourcing, each business operation emits a domain event (or possibly events) that allow other objects in the system to act accordingly.  For example, if a customer places an order then this might emit the `OrderPlacedEvent`.  Most significantly, the subscribers to these events can include the datastore itself; the state of the system is in effect a transaction log of every event that has occurred since "the beginning of time": it is sometimes called an event store.   With CQRS, this event datastore corresponds to the command/write datastore (the query/read datastore is of course derived from the command datastore).
-
-Although it might seem counter-intuitive to be able store persistent state in this way (as a souped up "transaction log"), the reality is that with modern compute capabilities make it quite feasible to replay many 10s/100s of thousands of events in a second.  And the architecture supports some interesting use cases; for example it becomes quite trivial to rewind the system back to some previous point in time.
-
-When combined with CQRS we see a command that triggers a business operation, and an event that results from it.  So, a `PlaceOrderCommand` command can result in an `OrderPlacedEvent` event.  A subscriber to this event might then generate a further command to act upon some other system (eg to dispatch the system).  Note that the event might be dispatched and consumed in-process or alternatively this might occur out-of-process.  If the latter, then the subscriber will operate within a separate transaction, meaning the usual eventual consistency concerns and also compensating actions if a rollback is required.  CQRS/event sourcing advocates point out - correctly  that this is just how things are in the "real world" too.
-
-In Apache Isis every business action (and indeed, property and collection) emits domain events through the xref:rgsvc.adoc#_rgsvc-api_EventBusService[`EventBusService`] , and can optionally also be published through the xref:rgsvc.adoc#_rgsvc-spi_PublishingService[`PublishingService`].  The former are dispatched and consumed in-process and within the same transaction, and for this reason the xref:rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscribers] can also veto the events.  The latter are intended for out-of-process consumption; the (non-ASF) http://github.com/isisaddons/isis-module-publishing[Isis addons' publishing] and http://github.com/isisaddons/isis-module-publishmq[Isis addons' publishmq] modules provide implementations for dispatching either through a RDBMS database table, or directly through to an link:http://camel.apache.org[ActiveMQ] message queue (eg wired up to link:http://camel.apache.org[Apache Camel] event bus).
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_metawidget.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_metawidget.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_metawidget.adoc
deleted file mode 100644
index 31c069f..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_metawidget.adoc
+++ /dev/null
@@ -1,16 +0,0 @@
-[[_ug_core-concepts_principles_apache-isis-vs_metawidget]]
-= vs MetaWidget
-: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/
-
-
-MetaWidget (mentioned xref:ug.adoc#_ug_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping[earlier] has a number of ideas in common with Apache Isis, specifically the runtime generation of a UI for domain objects.  And like Apache Isis, MetaWidget builds its own metamodel of the domain objects and uses this to render the object.
-
-However, there is a difference in philosophy in that MW is not a full-stack framework and does not (in their words) try to "own the UI".  Rather they support a huge variety of UI technologies and allow the domain object to be rendered in any of them.
-
-In contrast, Apache Isis is full-stack and does generate a complete UI; we then allow you to customize or extend this UI (as per the various link:http://www.isisaddons.org[Isis Addons] (non-ASF), and we also provide a full REST API through the xref:ugvro.adoc#[Restful Objects viewer]
-
-Also, it's worth noting that MetaWidget does have an elegant pipeline architecture, with APIs to allow even its metamodel to be replaced.  It would be feasible and probably quite straightforward to use Apache Isis' own metamodel as an implementation of the MetaWidget API.  This would allow MetaWidget to be able to render an Apache Isis domain application.
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_mvc-server-side-frameworks.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_mvc-server-side-frameworks.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_mvc-server-side-frameworks.adoc
deleted file mode 100644
index 7fb3512..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_mvc-server-side-frameworks.adoc
+++ /dev/null
@@ -1,19 +0,0 @@
-[[_ug_core-concepts_principles_apache-isis-vs_mvc-server-side-frameworks]]
-= vs MVC server-side frameworks
-: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/
-
-
-
-Some of most commonly used frameworks today are link:http://www.spring.io/[Spring MVC], link:http://rubyonrails.org/[Ruby on Rails] and link:http://www.grails.org[Grails], all of which implement one flavour or another of the server-side MVC pattern.  The MVC 1.0 specification (scheduled for JavaEE 8) is also similar.
-
-These frameworks all use the classic  *model-view-controller* ( _MVC_) pattern for web applications, with scaffolding, code-generation, and/or metaprogramming tools for the controllers and views, as well as convention over configuration to define how these components interact.  The views provided out of the box by these frameworks tend to be simple  _CRUD_-style interfaces. More sophisticated behavior is accomplished by customizing the generated controllers.
-
-The most obvious difference when developing an Apache Isis application is its deliberate lack of an explicit controller layer; non- _CRUD_ behavior is automatically made available in its generic object-oriented  _UI_s.  More sophisticated UIs can be built either by xref:ugvw.adoc#_ugvw_extending[extending Apache Isis' Wicket viewer] or by writing a bespoke UI leveraging the REST (hypermedia) API automatically exposed by xref:ugvro.adoc#[Isis' Restful Objects viewer].  Other frameworks can also be used to implement REST APIs, of course, but generally they require a significant amount of development to get anywhere near the level of sophistication provided automatically by Apache Isis' REST API.
-
-Although these frameworks all provide their own ecosystems of extensions, Apache Isis' equivalent link:http://www.isisaddons.org[Isis Addons] (non-ASF) tend to work at a higher-level of abstraction.  For example, each of these frameworks will integrate with various security mechanism, but the http://github.com/isisaddons/isis-module-security[Isis addons' security module] provides a full subdomain of users, roles, features and permissions that can be plugged into any Isis application.  Similarly, the http://github.com/isisaddons/isis-module-command[Isis addons' command] and http://github.com/isisaddons/isis-module-audit[Isis addons' audit] modules in combination provide a support for auditing and traceability that can also be used for out of the box profiling.  Again, these addons can be plugged into any Isis app.
-
-In terms of testing support, each of these other frameworks provide mechanisms to allow the webapp to be tested from within a JUnit test harness. Apache Isis' support is similar.  Where Apache Isis differs though is that it enables end-to-end testing without the need for slow and fragile Selenium tests. Instead, Apache Isis provides a "xref:ugtst.adoc#_ugtst_integ-test-support_wrapper-factory[WrapperFactory]" domain service that allows the generic UI provided to in essence be simulated. On a more pragmatic level, the http://github.com/isisaddons/isis-module-fakedata[Isis addons' fakedata] module does "what it says on the tin", allowing both unit- and integration-tests to focus on the salient data and fake out the rest.
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_isis-itself.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_isis-itself.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_isis-itself.adoc
deleted file mode 100644
index e577de5..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_isis-itself.adoc
+++ /dev/null
@@ -1,47 +0,0 @@
-[[_ug_core-concepts_principles_isis-itself]]
-= Apache Isis itself
-: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 section discusses some of the principles and values we apply to the development of the Apache Isis framework itself.
-
-== Full-stack but Extensible
-
-NOTE: TODO
-
-
-== Focuses on its USP
-
-NOTE: TODO
-
-
-add-ons
-
-* Apache 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
-
-
-
-... all code has legacy in it.... parts of the Isis codebase are well over a decade old; and back then a lot of the JEE technologies that we'd like to be using just didn't exist, so we had to invent the features we required ourselves.
-
-... also, Apache Isis today is more pragmatic than previously
-* a client/server solution, with AWT-based client
-* a HTML browser, Scimpi (JSF-like, but not using JSF), ...
-* security
-* objectstores
-
-We're working hard to remove duplication, reuse existing open source/JEE, and simplify.
-
-
-The areas of Apache Isis we consider mature are those that have been developed in support of real-world applications implemented by the committers.  Foremost among these is Estatio.
-
-
-Focus on enterprise / line-of-business applications, for use by internal staff.
-
-* problem solvers, not process followers
-
-* view models
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_your-apps.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_your-apps.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_your-apps.adoc
deleted file mode 100644
index e256dac..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_your-apps.adoc
+++ /dev/null
@@ -1,39 +0,0 @@
-[[_ug_core-concepts_principles_your-apps]]
-= Your Applications
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-Apache Isis is primarily aimed at custom-built "enterprise" applications.  The UI exposed by the xref:ugvw.adoc#[Wicket viewer] is intended to be usable by domain experts, typically end-users within the organization.  The REST API exposed by the xref:ugvro.adoc#[RestfulObjects viewer] allows custom apps to be developed - eg using AngularJS or similar - for use by those requiring more guidance; typically end-users outside of the organization.
-
-But should your organization buy, or build?  Buying packaged software makes sense for statutory requirements, such as payroll or general ledger, or document management/retrieval.  But it makes much less sense to buy packaged software for the systems that support the core business: the software should fit the business, not the other way around.
-
-
-NOTE: TODO - flesh out the following:
-
-*  Flexible, "just enough"
-
-*  Decoupled
-
-* Long-term Cost of ownership
-
-** dependency injection of services
-** OO design techniques, eg dependency inversion principle
-** an in-memory event bus
-** applib
-
-** (no "Big Ball of Mud")
-
-* Honouring the Single Responsibility Principle
-**  behaviourally Complete vs Contributions/Mixins
-
-* Testable +
-+
-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.
-
-* Reusable building blocks +
-+
-Isis addons, catalog.incode.org
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_faqs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_faqs.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_faqs.adoc
deleted file mode 100644
index 6f2c0cf..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_faqs.adoc
+++ /dev/null
@@ -1,16 +0,0 @@
-[[_ug_faqs]]
-= FAQs
-: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 chapter has FAQs (with solutions) for problems we've encountered ourselves or have been raised on the
-Apache Isis mailing lists.
-
-
-include::_ug_faqs_enabling-logging.adoc[leveloffset=+1]
-include::_ug_faqs_subtype-entity-not-fully-populated.adoc[leveloffset=+1]
-include::_ug_faqs_restful-image-property.adoc[leveloffset=+1]
-include::_ug_faqs_enhance-only.adoc[leveloffset=+1]
-include::_ug_faqs_per-user-themes.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_faqs_enabling-logging.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_faqs_enabling-logging.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_faqs_enabling-logging.adoc
deleted file mode 100644
index a1e212e..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_faqs_enabling-logging.adoc
+++ /dev/null
@@ -1,39 +0,0 @@
-[[_ug_faqs_enabling-logging]]
-= Enabling Logging
-: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/
-
-Sometimes you just need to see what is going on. There are various ways in which logging can be enabled, here are the ones we tend to use.
-
-* In Apache Isis +
-+
-Modify `WEB-INF/logging.properties` (a log4j config file)
-
-* In DataNucleus +
-+
-As per the http://www.datanucleus.org/products/accessplatform/logging.html[DN logging page]
-
-* In the JDBC Driver +
-+
-Configure `log4jdbc` JDBC rather than the vanilla driver (see `WEB-INF/persistor_datanucleus.properties`) and configure log4j logging (see `WEB-INF/logging.properties`).  There are examples of both in the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype].
-
-* In the database +
-+
-Details below.
-
-
-Database logging can be configured:
-
-* for HSQLDB +
-+
-by adding`;sqllog=3` to the end of the JDBC URL.
-
-* for PostgreSQL: +
-+
-Can change `postgresql\9.2\data\postgresql.conf`; see link:http://www.postgresql.org/docs/9.2/static/runtime-config-logging.html[this article] for details.
-
-* for MS SQL Server Logging: +
-+
-We like to use the excellent SQL Profiler tool.
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_faqs_enhance-only.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_faqs_enhance-only.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_faqs_enhance-only.adoc
deleted file mode 100644
index de3a8f8..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_faqs_enhance-only.adoc
+++ /dev/null
@@ -1,17 +0,0 @@
-[[_ug_faqs_enhance-only]]
-= Enhance only (IntelliJ)
-: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/
-
-
-From the Apache Isis mailing list is:
-
-* _Is there a simple way to make a run configuration in IntelliJ for running the datanucleus enhancer before running integration test?_
-
-Yes, you can; here's one way:
-
-* Duplicate your run configuration for running the webapp
-** the one where the main class is `org.apache.isis.WebServer`
-** there's a button for this on the run configurations dialog.
-* then, on your copy change the main class to `org.apache.isis.Dummy`
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_faqs_per-user-themes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_faqs_per-user-themes.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_faqs_per-user-themes.adoc
deleted file mode 100644
index eda8bf9..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_faqs_per-user-themes.adoc
+++ /dev/null
@@ -1,85 +0,0 @@
-[[_ug_faqs_per-user-themes]]
-= Per-user Themes
-: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/
-
-From the Apache Isis mailing list is:
-
-* _Is it possible to have each of our resellers (using our Isis application) use there own theme/branding with their own logo and colors? Would this also be possible for the login page, possibly depending on the used host name?_
-
-
-Yes, you can do this, by installing a custom implementation of the Wicket Bootstrap's `ActiveThemeProvider`.
-
-The http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] (non-ASF) actually link:https://github.com/isisaddons/isis-app-todoapp/tree/61b8114a8e01dbb3c380b31cf09eaed456407570[does this], storing the info via the http://github.com/isisaddons/isis-module-settings[Isis addons' settings module] settings modules:
-
-[source,java]
-.IActiveThemeProvider implementation
-----
-public class UserSettingsThemeProvider implements ActiveThemeProvider {
-    ...
-    @Override
-    public ITheme getActiveTheme() {
-        if(IsisContext.getSpecificationLoader().isInitialized()) {
-            final String themeName = IsisContext.doInSession(new Callable<String>() {
-                @Override
-                public String call() throws Exception {
-                    final Class<UserSettingsService> serviceClass = UserSettingsService.class;
-                    final UserSettingsService userSettingsService = lookupService(serviceClass);
-                    final UserSetting activeTheme = userSettingsService.find(
-                            IsisContext.getAuthenticationSession().getUserName(), ACTIVE_THEME);
-                    return activeTheme != null ? activeTheme.valueAsString() : null;
-                }
-            });
-            return themeFor(themeName);
-        }
-        return new SessionThemeProvider().getActiveTheme();
-    }
-    @Override
-    public void setActiveTheme(final String themeName) {
-        IsisContext.doInSession(new Runnable() {
-            @Override
-            public void run() {
-                final String currentUsrName = IsisContext.getAuthenticationSession().getUserName();
-                final UserSettingsServiceRW userSettingsService =
-                        lookupService(UserSettingsServiceRW.class);
-                final UserSettingJdo activeTheme =
-                        (UserSettingJdo) userSettingsService.find(currentUsrName, ACTIVE_THEME);
-                if(activeTheme != null) {
-                    activeTheme.updateAsString(themeName);
-                } else {
-                    userSettingsService.newString(
-                        currentUsrName, ACTIVE_THEME, "Active Bootstrap theme for user", themeName);
-                }
-            }
-        });
-    }
-    private ITheme themeFor(final String themeName) {
-        final ThemeProvider themeProvider = settings.getThemeProvider();
-        if(themeName != null) {
-            for (final ITheme theme : themeProvider.available()) {
-                if (themeName.equals(theme.name()))
-                    return theme;
-            }
-        }
-        return themeProvider.defaultTheme();
-    }
-    ...
-}
-----
-
-and
-
-[source,java]
-.Using the ActiveThemeProvider
-----
-@Override
-protected void init() {
-    super.init();
-
-    final IBootstrapSettings settings = Bootstrap.getSettings();
-    settings.setThemeProvider(new BootswatchThemeProvider(BootswatchTheme.Flatly));
-
-    settings.setActiveThemeProvider(new UserSettingsThemeProvider(settings));
-}
-----

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_faqs_restful-image-property.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_faqs_restful-image-property.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_faqs_restful-image-property.adoc
deleted file mode 100644
index d025e8a..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_faqs_restful-image-property.adoc
+++ /dev/null
@@ -1,20 +0,0 @@
-[[_ug_faqs_restful-image-property]]
-= How parse image properties from Restful Objects?
-: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/
-
-
-ref: link:http://markmail.org/message/4kcu7sml4ufdsah3[mailing list thread]
-
-The RO viewer returns the image as a string, in the form:
-
-    "Tacos.jpg:image/jpeg:/9j//4AAQSkZJRgABAQEAlgCWAAD/  ...."
-
-This is in the form:
-
-    (filename):(mime type):(binary data in base64)
-
-This is basically the xref:rgcms.adoc#_rgcms_classes_value-types_Blob[`Blob`] value type, in string form.
-
-To use, split the parts then format the mime type and base64 data correctly before using as source in an `<img>` tag.

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_faqs_subtype-entity-not-fully-populated.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_faqs_subtype-entity-not-fully-populated.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_faqs_subtype-entity-not-fully-populated.adoc
deleted file mode 100644
index 2448556..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_faqs_subtype-entity-not-fully-populated.adoc
+++ /dev/null
@@ -1,67 +0,0 @@
-[[_ug_troubleshooting_faqs]]
-= (Subtype) entity not fully populated
-: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/
-
-
-ref: link:http://markmail.org/message/ovgai56uqgfgnrx7[mailing list thread]
-
-If it seems that Apache Isis (or rather DataNucleus) isn't fully populating domain entities (ie leaving some properties
-as `null`), then check that your actions are not accessing the fields directly.  Use getters instead.  that is:
-
-[WARNING]
-====
-Properties of domain entities should always be accessed using getters.  The only code that should access to fields
-should be the getters themselves.
-====
-
-Why so? Because DataNucleus will potentially lazy load some properties, but to do this it needs to know that the
-field is being requested.  This is the purpose of the enhancement phase: the bytecode of the original getter method is
-actually wrapped in code that does the lazy loading checking.  But hitting the field directly means that the lazy
-loading code does not run.
-
-This error can be subtle: sometimes "incorrect" code that accesses the fields will seem to work.  But that will be
-because the field has been populated already, for whatever reason.
-
-One case where you will find the issue highlighted is for subtype tables that have been mapped using an inheritance
-strategy of `NEW_TABLE`, eg:
-
-[source,java]
-----
-@javax.jdo.annotations.PersistenceCapable
-@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.NEW_TABLE)
-public class SupertypeEntity {
-    ...
-}
-----
-
-and then:
-
-[source,java]
-----
-@javax.jdo.annotations.PersistenceCapable
-@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.NEW_TABLE)
-public class SubtypeEntity extends SupertypeEntity {
-    ...
-}
-----
-
-This will generate two tables in the database, with the primary key of the supertype table propagated as a foreign key
-(also primary key) of the subtype table (sometimes called "table per type" strategy).  This means that DataNucleus
-might retrieve data from only the supertype table, and the lazily load the subtype fields only as required.  This is
-preferable to doing a left outer join from the super- to the subtype tables to retrieve data that might not be needed.
-
-On the other hand, if the `SUPERCLASS_TABLE` strategy (aka "table per hierarchy" or roll-up) or the `SUBCLASS_TABLE`
-strategy (roll-down) was used, then the problem is less likely to occur because DataNucleus would obtain all the data
-for any given instance from a single table.
-
-Final note: references to other objects (either scalar references or in collections) in particular require that getters
-rather than fields to be used to obtain them: it's hopefully obvious that DataNucleus (like all ORMs) should not and
-will not resolve such references (otherwise, where to stop... and the whole database would be loaded into memory).
-
-In summary, there's just one rule: *always use the getters, never the fields*.
-
-
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_getting-started.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_getting-started.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_getting-started.adoc
deleted file mode 100644
index ab84c1b..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_getting-started.adoc
+++ /dev/null
@@ -1,37 +0,0 @@
-[[_ug_getting-started]]
-= 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/
-
-
-
-
-To get you up and running quickly, Apache Isis provides a xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype] to setup a simple application as the basis of your own apps.  This is deliberately very minimal so that you won't have to spend lots of time removing generated artifacts.  On the other hand, it does set up a standard multi-module maven structure with unit- and integration tests pre-configured, as well as a webapp module so that you can easily run your app.  We strongly recommend that you preserve this structure as you develop your own Isis application.
-
-In this chapter we also discuss the xref:ug.adoc#_ug_getting-started_datanucleus-enhancer[DataNucleus enhancer].  link:http://www.datanucleus.org/[DataNucleus] is the reference implementation of the JDO (Java data objects) spec, and Apache Isis integrates with DataNucleus as its persistence layer.  The enhancer performs post-processing on the bytecode of your persistent domain entities, such that they can be persisted by Apache Isis' JDO/DataNucleus objectstore.
-
-[NOTE]
-====
-The xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype] automatically configures the enhancer, so there's little you need to do at this stage.  Even so we feel it's a good idea to be aware of this critical part of Apache Isis runtime; if the enhancer does not run, then you'll find the app fails to start with (what will seem like) quite an obscure exception message.
-====
-
-
-
-
-== Prerequisites
-
-Apache Isis is a Java based framework, so in terms of prerequisites, you'll need to install:
-
-* Java 7 or 8 JDK
-* link:http://maven.apache.org[Apache Maven] 3.0.5 or later
-
-You'll probably also want to use an IDE; the Apache Isis committers use either IntelliJ or Eclipse; in the xref:cg.adoc#_cg_ide[Contributors' Guide] we have detailed setup instructions for using these two IDEs.  If you're a NetBeans user you should have no problems as it too has strong support for Maven.
-
-When building and running within an IDE, you'll also need to configure the Datanucleus enhancer.  This is implemented as a Maven plugin, so in the case of IntelliJ, it's easy enough to run the enhancer as required. It should be just as straightforward for NetBeans too.
-
-For Eclipse the maven integration story is a little less refined.  All is not lost, however; DataNucleus also has an implementation of the enhancer as an Eclipse plugin, which usually works well enough.
-
-include::_ug_getting-started_simpleapp-archetype.adoc[leveloffset=+1]
-include::_ug_getting-started_datanucleus-enhancer.adoc[leveloffset=+1]
-

http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_getting-started_datanucleus-enhancer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_getting-started_datanucleus-enhancer.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_getting-started_datanucleus-enhancer.adoc
deleted file mode 100644
index 4b41244..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_getting-started_datanucleus-enhancer.adoc
+++ /dev/null
@@ -1,107 +0,0 @@
-[[_ug_getting-started_datanucleus-enhancer]]
-= Datanucleus Enhancer
-: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/
-
-
-
-link:http://www.datanucleus.org/[DataNucleus] is the reference implementation of the JDO (Java data objects) spec, and Apache Isis integrates with DataNucleus as its persistence layer.  Datanucleus is a very powerful library, allowing domain entities to be mapped not only to relational database tables, but also to NoSQL stores such as link:http://neo4j.com/[Neo4J], link:http://www.mongodb.org/[MongoDB] and link:http://cassandra.apache.org/[Apache Cassandra].
-
-With such power comes a little bit of complexity to the development environment: all domain entities must be enhanced through the DataNucleus enhancer.
-
-[NOTE]
-====
-Bytecode enhancement is actually a requirement of the JDO spec; the process is described in outline http://db.apache.org/jdo/enhancement.html[here].
-====
-
-What this means is that the enhancer -- available as both a Maven plugin and as an Eclipse plugin -- must, one way or another, be integrated into your development environment.
-
-If working from the Maven command line, JDO enhancement is done using the `maven-datanucleus-plugin`.  As of 1.9.0, we put all the configuration into an (always active) profile:
-
-[TIP]
-====
-The configuration described below is automatically set up by the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype].
-====
-
-
-[source,xml]
-----
-<profile>
-    <id>enhance</id>
-    <activation>
-        <activeByDefault>true</activeByDefault>
-    </activation>
-    <properties>
-        <datanucleus-maven-plugin.version>4.0.1</datanucleus-maven-plugin.version>
-    </properties>
-    <build>
-        <plugins>
-            <plugin>
-                <groupId>org.datanucleus</groupId>
-                <artifactId>datanucleus-maven-plugin</artifactId>
-                <version>${datanucleus-maven-plugin.version}</version>
-                <configuration>
-                    <fork>false</fork>
-                    <log4jConfiguration>${basedir}/log4j.properties</log4jConfiguration>
-                    <verbose>true</verbose>
-                    <props>${basedir}/datanucleus.properties</props>
-                </configuration>
-                <executions>
-                    <execution>
-                        <phase>process-classes</phase>
-                        <goals>
-                            <goal>enhance</goal>
-                        </goals>
-                    </execution>
-                </executions>
-            </plugin>
-        </plugins>
-    </build>
-    <dependencies>
-        <dependency>
-            <groupId>org.datanucleus</groupId>
-            <artifactId>datanucleus-core</artifactId>
-        </dependency>
-        <dependency>
-            <groupId>org.datanucleus</groupId>
-            <artifactId>datanucleus-jodatime</artifactId>
-        </dependency>
-        <dependency>
-            <groupId>org.datanucleus</groupId>
-            <artifactId>datanucleus-api-jdo</artifactId>
-        </dependency>
-    </dependencies>
-</profile>
-----
-
-The xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype]  sets up the plugin correctly in the `dom` (domain object model) module.  (It's actually a little bit more complex to cater for users of the Eclipse IDE using Eclipse's m2e plugin).
-
-
-
-
-== `META-INF/persistence.xml`
-
-It's also a good idea to ensure that the `dom` module has a JDO `META-INF/persistence.xml` file:
-
-[source,xml]
-----
-<?xml version="1.0" encoding="UTF-8" ?>
-<persistence xmlns="http://java.sun.com/xml/ns/persistence"
-    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-    xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd" version="1.0">
-
-    <persistence-unit name="simple"> <!--1-->
-    </persistence-unit>
-</persistence>
-----
-<1> change as required; typically is the name of the app.
-
-Again, the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype] does this.
-
-[WARNING]
-====
-If running on Windows, then there's a good chance you'll hit the http://msdn.microsoft.com/en-us/library/aa365247%28VS.85%29.aspx#maxpath[maximum path length limit].   In this case the `persistence.xml` file is mandatory rather than optional.
-
-This file is also required if you are using developing in Eclipse and relying on the DataNucleus plugin for Eclipse rather than the DataNucleus plugin for Maven.  More information can be found xref:cg.adoc#_cg_ide_eclipse[here].
-====


[17/52] [abbrv] isis git commit: ISIS-1243: removing manpage from .adoc file names.

Posted by mg...@apache.org.
ISIS-1243: removing manpage from .adoc file names.


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/43fc7bc1
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/43fc7bc1
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/43fc7bc1

Branch: refs/heads/ISIS-1224-select2-v4
Commit: 43fc7bc182273f2aa7ac921d994177eb0e3c9903
Parents: d0539e4
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Thu Dec 3 17:36:08 2015 +0000
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Dec 3 17:36:08 2015 +0000

----------------------------------------------------------------------
 ..._fixture-scripts-specification-provider.adoc |   2 +-
 ...1.8.0-to-1.9.0_specify-all-dom-packages.adoc |   2 +-
 .../src/main/asciidoc/documentation.adoc        |  14 +-
 .../asciidoc/guides/_cg_asciidoc-templates.adoc |  28 ++--
 .../guides/_rgant-Collection_editing.adoc       |   2 +-
 .../src/main/asciidoc/guides/_rgant-Column.adoc |   2 +-
 .../_rgant-DomainObjectLayout_cssClassFa.adoc   |   2 +-
 ...gant-DomainObjectLayout_cssClassUiEvent.adoc |   2 +-
 .../_rgant-DomainObjectLayout_iconUiEvent.adoc  |   2 +-
 .../_rgant-DomainObjectLayout_titleUiEvent.adoc |   2 +-
 ...ant-DomainObject_autoCompleteRepository.adoc |   2 +-
 .../guides/_rgant-DomainObject_bounded.adoc     |   2 +-
 .../guides/_rgant-DomainObject_nature.adoc      |   2 +-
 ...t-DomainObject_persistingLifecycleEvent.adoc |   2 +-
 ...ant-DomainObject_removingLifecycleEvent.adoc |   2 +-
 ...ant-DomainObject_updatingLifecycleEvent.adoc |   2 +-
 .../main/asciidoc/guides/_rgant-MinLength.adoc  |   2 +-
 .../main/asciidoc/guides/_rgant-Parameter.adoc  |   2 +-
 .../asciidoc/guides/_rgant-PostConstruct.adoc   |   2 +-
 .../main/asciidoc/guides/_rgant-PreDestroy.adoc |   2 +-
 .../guides/_rgant-Property_editing.adoc         |   2 +-
 .../_rgant-ViewModelLayout_cssClassFa.adoc      |   2 +-
 .../asciidoc/guides/_rgant-XmlRootElement.adoc  |   2 +-
 .../guides/_rgcfg_configuring-core.adoc         |   4 +-
 ...s_disabling-persistence-by-reachability.adoc |   2 +-
 ...atanucleus_eagerly-registering-entities.adoc |   2 +-
 ...gcfg_configuring-datanucleus_properties.adoc |   2 +-
 .../guides/_rgcfg_specifying-components.adoc    |   8 +-
 .../guides/_rgcms_classes_contributee.adoc      |   4 +-
 ...ms_classes_contributee_HasTransactionId.adoc |  31 ++++
 .../_rgcms_classes_contributee_HasUserName.adoc |  27 ++++
 ...es_contributee_manpage-HasTransactionId.adoc |  31 ----
 ...classes_contributee_manpage-HasUserName.adoc |  27 ----
 .../guides/_rgcms_classes_domainevent.adoc      |  16 +--
 ...classes_domainevent_AbstractDomainEvent.adoc |  20 +++
 ...s_classes_domainevent_ActionDomainEvent.adoc |  20 +++
 ...asses_domainevent_CollectionDomainEvent.adoc |  21 +++
 ...classes_domainevent_PropertyDomainEvent.adoc |  17 +++
 ...domainevent_manpage-AbstractDomainEvent.adoc |  20 ---
 ...s_domainevent_manpage-ActionDomainEvent.adoc |  20 ---
 ...mainevent_manpage-CollectionDomainEvent.adoc |  21 ---
 ...domainevent_manpage-PropertyDomainEvent.adoc |  17 ---
 .../asciidoc/guides/_rgcms_classes_i18n.adoc    |   2 +-
 .../_rgcms_classes_i18n_TranslatableString.adoc |  13 ++
 ...classes_i18n_manpage-TranslatableString.adoc |  13 --
 .../guides/_rgcms_classes_lifecycleevent.adoc   |  32 ++---
 ...s_lifecycleevent_AbstractLifecycleEvent.adoc |  27 ++++
 ...asses_lifecycleevent_ObjectCreatedEvent.adoc |  20 +++
 ...lasses_lifecycleevent_ObjectLoadedEvent.adoc |  17 +++
 ...ses_lifecycleevent_ObjectPersistedEvent.adoc |  19 +++
 ...es_lifecycleevent_ObjectPersistingEvent.adoc |  21 +++
 ...sses_lifecycleevent_ObjectRemovingEvent.adoc |  20 +++
 ...asses_lifecycleevent_ObjectUpdatedEvent.adoc |  21 +++
 ...sses_lifecycleevent_ObjectUpdatingEvent.adoc |  22 +++
 ...cleevent_manpage-AbstractLifecycleEvent.adoc |  27 ----
 ...fecycleevent_manpage-ObjectCreatedEvent.adoc |  20 ---
 ...ifecycleevent_manpage-ObjectLoadedEvent.adoc |  17 ---
 ...cycleevent_manpage-ObjectPersistedEvent.adoc |  19 ---
 ...ycleevent_manpage-ObjectPersistingEvent.adoc |  21 ---
 ...ecycleevent_manpage-ObjectRemovingEvent.adoc |  20 ---
 ...fecycleevent_manpage-ObjectUpdatedEvent.adoc |  21 ---
 ...ecycleevent_manpage-ObjectUpdatingEvent.adoc |  22 ---
 .../asciidoc/guides/_rgcms_classes_roles.adoc   |  10 +-
 .../guides/_rgcms_classes_roles_Dto.adoc        |  61 ++++++++
 .../_rgcms_classes_roles_HoldsUpdatedAt.adoc    |  44 ++++++
 .../_rgcms_classes_roles_HoldsUpdatedBy.adoc    |  19 +++
 .../_rgcms_classes_roles_Persistable.adoc       |  34 +++++
 .../_rgcms_classes_roles_Timestampable.adoc     |  23 +++
 .../_rgcms_classes_roles_manpage-Dto.adoc       |  61 --------
 ...ms_classes_roles_manpage-HoldsUpdatedAt.adoc |  44 ------
 ...ms_classes_roles_manpage-HoldsUpdatedBy.adoc |  19 ---
 ...rgcms_classes_roles_manpage-Persistable.adoc |  34 -----
 ...cms_classes_roles_manpage-Timestampable.adoc |  23 ---
 .../asciidoc/guides/_rgcms_classes_spec.adoc    |   2 +-
 .../asciidoc/guides/_rgcms_classes_super.adoc   |  32 ++---
 ...s_classes_super_AbstractContainedObject.adoc |  32 +++++
 ...gcms_classes_super_AbstractDomainObject.adoc |  14 ++
 ...sses_super_AbstractFactoryAndRepository.adoc |  15 ++
 .../_rgcms_classes_super_AbstractService.adoc   |  10 ++
 ..._rgcms_classes_super_AbstractSubscriber.adoc |  18 +++
 .../_rgcms_classes_super_AbstractViewModel.adoc |  15 ++
 .../_rgcms_classes_super_FixtureScript.adoc     |  21 +++
 .../_rgcms_classes_super_FixtureScripts.adoc    |  12 ++
 ...s_super_manpage-AbstractContainedObject.adoc |  32 -----
 ...sses_super_manpage-AbstractDomainObject.adoc |  14 --
 ...er_manpage-AbstractFactoryAndRepository.adoc |  15 --
 ...s_classes_super_manpage-AbstractService.adoc |  10 --
 ...lasses_super_manpage-AbstractSubscriber.adoc |  18 ---
 ...classes_super_manpage-AbstractViewModel.adoc |  15 --
 ...cms_classes_super_manpage-FixtureScript.adoc |  21 ---
 ...ms_classes_super_manpage-FixtureScripts.adoc |  12 --
 .../asciidoc/guides/_rgcms_classes_uievent.adoc |  18 +--
 .../_rgcms_classes_uievent_CssClassUiEvent.adoc |  22 +++
 .../_rgcms_classes_uievent_IconUiEvent.adoc     |  23 +++
 .../_rgcms_classes_uievent_TitleUiEvent.adoc    |  22 +++
 ...classes_uievent_manpage-CssClassUiEvent.adoc |  22 ---
 ...cms_classes_uievent_manpage-IconUiEvent.adoc |  23 ---
 ...ms_classes_uievent_manpage-TitleUiEvent.adoc |  22 ---
 .../asciidoc/guides/_rgcms_classes_utility.adoc |   8 +-
 .../guides/_rgcms_classes_utility_Enums.adoc    |   8 ++
 .../_rgcms_classes_utility_ObjectContracts.adoc | 107 ++++++++++++++
 .../guides/_rgcms_classes_utility_Reasons.adoc  |  31 ++++
 .../_rgcms_classes_utility_TitleBuffer.adoc     |  13 ++
 .../_rgcms_classes_utility_manpage-Enums.adoc   |   8 --
 ...classes_utility_manpage-ObjectContracts.adoc | 107 --------------
 .../_rgcms_classes_utility_manpage-Reasons.adoc |  31 ----
 ...cms_classes_utility_manpage-TitleBuffer.adoc |  13 --
 .../guides/_rgcms_classes_value-types.adoc      |  10 +-
 .../guides/_rgcms_classes_value-types_Blob.adoc |   8 ++
 .../guides/_rgcms_classes_value-types_Clob.adoc |   8 ++
 .../_rgcms_classes_value-types_Color.adoc       |   8 ++
 .../_rgcms_classes_value-types_Money.adoc       |   8 ++
 .../_rgcms_classes_value-types_Password.adoc    |   8 ++
 ..._rgcms_classes_value-types_manpage-Blob.adoc |   8 --
 ..._rgcms_classes_value-types_manpage-Clob.adoc |   8 --
 ...rgcms_classes_value-types_manpage-Color.adoc |   8 --
 ...rgcms_classes_value-types_manpage-Money.adoc |   8 --
 ...ms_classes_value-types_manpage-Password.adoc |   8 --
 .../guides/_rgcms_methods_lifecycle.adoc        |  40 +++---
 .../_rgcms_methods_lifecycle_created.adoc       |  17 +++
 .../guides/_rgcms_methods_lifecycle_loaded.adoc |  15 ++
 ...rgcms_methods_lifecycle_manpage-created.adoc |  17 ---
 ..._rgcms_methods_lifecycle_manpage-loaded.adoc |  15 --
 ...cms_methods_lifecycle_manpage-persisted.adoc |  16 ---
 ...ms_methods_lifecycle_manpage-persisting.adoc |  16 ---
 ...rgcms_methods_lifecycle_manpage-removed.adoc |  16 ---
 ...gcms_methods_lifecycle_manpage-removing.adoc |  16 ---
 ...rgcms_methods_lifecycle_manpage-updated.adoc |  18 ---
 ...gcms_methods_lifecycle_manpage-updating.adoc |  15 --
 .../_rgcms_methods_lifecycle_persisted.adoc     |  16 +++
 .../_rgcms_methods_lifecycle_persisting.adoc    |  16 +++
 .../_rgcms_methods_lifecycle_removed.adoc       |  16 +++
 .../_rgcms_methods_lifecycle_removing.adoc      |  16 +++
 .../_rgcms_methods_lifecycle_updated.adoc       |  18 +++
 .../_rgcms_methods_lifecycle_updating.adoc      |  15 ++
 .../guides/_rgcms_methods_prefixes.adoc         |  76 +++++-----
 .../guides/_rgcms_methods_prefixes_addTo.adoc   |  37 +++++
 .../_rgcms_methods_prefixes_autoComplete.adoc   |  96 +++++++++++++
 .../guides/_rgcms_methods_prefixes_choices.adoc | 143 +++++++++++++++++++
 .../guides/_rgcms_methods_prefixes_clear.adoc   |  32 +++++
 .../guides/_rgcms_methods_prefixes_default.adoc | 129 +++++++++++++++++
 .../guides/_rgcms_methods_prefixes_disable.adoc |  93 ++++++++++++
 .../guides/_rgcms_methods_prefixes_get.adoc     |  19 +++
 .../guides/_rgcms_methods_prefixes_hide.adoc    |  82 +++++++++++
 .../_rgcms_methods_prefixes_manpage-addTo.adoc  |  37 -----
 ...s_methods_prefixes_manpage-autoComplete.adoc |  96 -------------
 ..._rgcms_methods_prefixes_manpage-choices.adoc | 143 -------------------
 .../_rgcms_methods_prefixes_manpage-clear.adoc  |  32 -----
 ..._rgcms_methods_prefixes_manpage-default.adoc | 129 -----------------
 ..._rgcms_methods_prefixes_manpage-disable.adoc |  93 ------------
 .../_rgcms_methods_prefixes_manpage-get.adoc    |  19 ---
 .../_rgcms_methods_prefixes_manpage-hide.adoc   |  82 -----------
 .../_rgcms_methods_prefixes_manpage-modify.adoc |  37 -----
 ...cms_methods_prefixes_manpage-removeFrom.adoc |  37 -----
 .../_rgcms_methods_prefixes_manpage-set.adoc    |  13 --
 ...rgcms_methods_prefixes_manpage-validate.adoc | 113 ---------------
 ..._methods_prefixes_manpage-validateAddTo.adoc |  45 ------
 ...ods_prefixes_manpage-validateRemoveFrom.adoc |  45 ------
 .../guides/_rgcms_methods_prefixes_modify.adoc  |  37 +++++
 .../_rgcms_methods_prefixes_removeFrom.adoc     |  37 +++++
 .../guides/_rgcms_methods_prefixes_set.adoc     |  13 ++
 .../_rgcms_methods_prefixes_validate.adoc       | 113 +++++++++++++++
 .../_rgcms_methods_prefixes_validateAddTo.adoc  |  45 ++++++
 ...cms_methods_prefixes_validateRemoveFrom.adoc |  45 ++++++
 .../guides/_rgcms_methods_reserved.adoc         |  34 ++---
 .../_rgcms_methods_reserved_cssClass.adoc       |  46 ++++++
 .../guides/_rgcms_methods_reserved_disable.adoc | 102 +++++++++++++
 .../guides/_rgcms_methods_reserved_getId.adoc   |  19 +++
 .../guides/_rgcms_methods_reserved_hide.adoc    |  39 +++++
 .../_rgcms_methods_reserved_iconName.adoc       |  36 +++++
 ...rgcms_methods_reserved_manpage-cssClass.adoc |  46 ------
 ..._rgcms_methods_reserved_manpage-disable.adoc | 102 -------------
 .../_rgcms_methods_reserved_manpage-getId.adoc  |  19 ---
 .../_rgcms_methods_reserved_manpage-hide.adoc   |  39 -----
 ...rgcms_methods_reserved_manpage-iconName.adoc |  36 -----
 .../_rgcms_methods_reserved_manpage-title.adoc  |  65 ---------
 ...rgcms_methods_reserved_manpage-validate.adoc |  27 ----
 .../guides/_rgcms_methods_reserved_title.adoc   |  65 +++++++++
 .../_rgcms_methods_reserved_validate.adoc       |  27 ++++
 .../src/main/asciidoc/guides/_rgsvc-api.adoc    |   4 +-
 ...mainObjectContainer_object-creation-api.adoc |   6 +-
 ..._DomainObjectContainer_presentation-api.adoc |   2 +-
 ...pi_DomainObjectContainer_validation-api.adoc |   4 +-
 .../guides/_rgsvc-api_EventBusService.adoc      |   2 +-
 .../_rgsvc-api_FixtureScriptsDefault.adoc       |   6 +-
 .../asciidoc/guides/_rgsvc-api_JaxbService.adoc |   2 +-
 .../guides/_rgsvc-api_MementoService.adoc       |   2 +-
 .../guides/_rgsvc-api_WrapperFactory.adoc       |   4 +-
 .../src/main/asciidoc/guides/_rgsvc-spi.adoc    |   2 +-
 .../guides/_rgsvc-spi_AuditingService.adoc      |   4 +-
 .../_rgsvc-spi_ClassDiscoveryService.adoc       |   2 +-
 .../guides/_rgsvc-spi_CommandService.adoc       |   6 +-
 .../guides/_rgsvc-spi_EventSerializer.adoc      |   2 +-
 ...spi_FixtureScriptsSpecificationProvider.adoc |   2 +-
 .../guides/_rgsvc-spi_PublishingService.adoc    |   4 +-
 .../_tg_stop-scaffolding-start-coding.adoc      |  16 +--
 ...concepts_principles_apache-isis-vs_cqrs.adoc |   2 +-
 ...rinciples_apache-isis-vs_event-sourcing.adoc |   2 +-
 .../guides/_ug_faqs_restful-image-property.adoc |   2 +-
 .../guides/_ug_how-tos_business-rules.adoc      |   6 +-
 .../guides/_ug_how-tos_derived-members.adoc     |   4 +-
 .../guides/_ug_how-tos_domain-services.adoc     |   2 +-
 .../_ug_how-tos_drop-downs-and-defaults.adoc    |  14 +-
 ...aged-1-to-m-bidirectional-relationships.adoc |   2 +-
 ...ow-tos_ui-hints_object-titles-and-icons.adoc |   8 +-
 .../guides/_ug_how-tos_ui_are-you-sure.adoc     |   2 +-
 .../guides/_ugbtb_deployment_cmd-line.adoc      |   4 +-
 .../_ugbtb_more-advanced_decoupling_mixins.adoc |   2 +-
 ...ore-advanced_decoupling_pushing-changes.adoc |   4 +-
 .../guides/_ugbtb_more-advanced_i18n.adoc       |   2 +-
 ...-advanced_view-models_programming-model.adoc |   2 +-
 .../src/main/asciidoc/guides/_ugtst_aaa.adoc    |   2 +-
 ..._ugtst_integ-test-support_typical-usage.adoc |   2 +-
 ..._ugtst_unit-test-support_contract-tests.adoc |   2 +-
 .../guides/_ugvw_features_blob-attachments.adoc |   2 +-
 .../src/main/asciidoc/guides/rg.adoc            |  27 ----
 .../src/main/asciidoc/guides/rgcms.adoc         |  27 ++++
 217 files changed, 2570 insertions(+), 2574 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_fixture-scripts-specification-provider.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_fixture-scripts-specification-provider.adoc b/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_fixture-scripts-specification-provider.adoc
index 21264e5..d525740 100644
--- a/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_fixture-scripts-specification-provider.adoc
+++ b/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_fixture-scripts-specification-provider.adoc
@@ -6,7 +6,7 @@
 
 
 
-The `FixtureScriptsSpecificationProvider` SPI service is an alternative to subclassing the xref:rgcms.adoc#_rgcms_classes_super_manpage-FixtureScripts[`FixtureScripts`] domain service.  The logic that would normally be in the subclass moves to the provider service instead, and the framework instantiates a fallback default instance, xref:rgsvc.adoc#_rgsvc-api_FixtureScriptsDefault[`FixtureScriptsDefault`].
+The `FixtureScriptsSpecificationProvider` SPI service is an alternative to subclassing the xref:rgcms.adoc#_rgcms_classes_super_FixtureScripts[`FixtureScripts`] domain service.  The logic that would normally be in the subclass moves to the provider service instead, and the framework instantiates a fallback default instance, xref:rgsvc.adoc#_rgsvc-api_FixtureScriptsDefault[`FixtureScriptsDefault`].
 
 This new design is optional; if you continue to provide your own subclass then everything will continue as before.  However the new design is more flexible and involves less code.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_specify-all-dom-packages.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_specify-all-dom-packages.adoc b/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_specify-all-dom-packages.adoc
index 7afeecc..faac52c 100644
--- a/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_specify-all-dom-packages.adoc
+++ b/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_specify-all-dom-packages.adoc
@@ -10,7 +10,7 @@ Apache Isis automatically scans for certain classes on the classpath in order to
 
 * searching for classes annotated with xref:rgant.adoc#_rgant-DomainService[`@DomainService`].
 
-* searching for classes extending xref:rgcms.adoc#_rgcms_classes_super_manpage-FixtureScript[`FixtureScript`]
+* searching for classes extending xref:rgcms.adoc#_rgcms_classes_super_FixtureScript[`FixtureScript`]
 
 * searching for classes annotated with xref:rgant.adoc#_rgant-PersistenceCapable[`@PersistenceCapable`].
 

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/documentation.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/documentation.adoc b/adocs/documentation/src/main/asciidoc/documentation.adoc
index 8d8b46c..6e8d6de 100644
--- a/adocs/documentation/src/main/asciidoc/documentation.adoc
+++ b/adocs/documentation/src/main/asciidoc/documentation.adoc
@@ -59,18 +59,18 @@ pass:[<br/>]
 
 |*User Guides:*
 
-* link:./guides/ug.html[Fundamentals^]
+* *link:./guides/ug.html[Fundamentals^]*
 * link:./guides/ugvw.html[Wicket Viewer^]
 * link:./guides/ugvro.html[Restful Objects Viewer^]
 * link:./guides/ugsec.html[Security^]
-* link:./guides/ugtst.html[Testing^]
+* *link:./guides/ugtst.html[Testing^]*
 * link:./guides/ugbtb.html[Beyond the Basics^]
 
 
 |*Reference Guides:*
 
-* link:./guides/rgant.html[Annotations^]
-* link:./guides/rgsvc.html[Domain Services^]
+* *link:./guides/rgant.html[Annotations^]*
+* *link:./guides/rgsvc.html[Domain Services^]*
 * link:./guides/rgcfg.html[Configuration Properties^]
 * link:./guides/rgcms.html[Classes, Methods and Schema^]
 
@@ -79,16 +79,12 @@ pass:[<br/>]
 
 |*Contributors' Guide*
 
-IDE setup, build the framework, writing docs, how to contribute patches (pull requests); for committers: publishing docs, applying patches, release process.
-
-pass:[<a class="button guide" href="./guides/cg.html" role="button" target="_blank">Contributors' Guide »</a>]
+* *link:./guides/cg.html[Contributors Guide^]*
 
 including:
 
 * Setting up link:./guides/cg.html#_cg_ide_intellij[IntelliJ] or link:./guides/cg.html#_cg_ide_eclipse[Eclipse]
-* link:./guides/cg.html#_cg_ide-templates[*IDE templates*] (IntelliJ and Eclipse)
 * link:./guides/cg.html#_cg_contributing[Contributing patches] (pull requests)
-* link:./guides/cg.html#_cg_isis-maven-plugin[Isis Maven plugin]
 * link:./guides/cg.html#_cg_committers_cutting-a-release[Cutting a release] ; link:./guides/cg.html#_cg_committers_verifying-releases[Verifying a release]
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_cg_asciidoc-templates.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_asciidoc-templates.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_asciidoc-templates.adoc
index 3366b1a..5b6e3ea 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_cg_asciidoc-templates.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_asciidoc-templates.adoc
@@ -217,7 +217,7 @@ a hyperlink to the reference guide's catalogue of the Apache Isis configuration
 
 
 |`adrgcs`
-|pass:[<pre>xref:rgcms.adoc#_rgcms_classes_super_manpage-xxx[`xxx`\]</pre>]
+|pass:[<pre>xref:rgcms.adoc#_rgcms_classes_super_xxx[`xxx`\]</pre>]
 
 a hyperlink to the "man page" for a superclass, where:
 
@@ -225,14 +225,14 @@ a hyperlink to the "man page" for a superclass, where:
 
 for example:
 
-pass:[<pre>xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractService[`AbstractService`\]</pre>]
+pass:[<pre>xref:rgcms.adoc#_rgcms_classes_super_AbstractService[`AbstractService`\]</pre>]
 
-|xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractService[`AbstractService`]
+|xref:rgcms.adoc#_rgcms_classes_super_AbstractService[`AbstractService`]
 
 
 
 |`adrgcu`
-|pass:[<pre>xref:rgcms.adoc#_rgcms_classes_utility_manpage-xxx[`xxx`\]</pre>]
+|pass:[<pre>xref:rgcms.adoc#_rgcms_classes_utility_xxx[`xxx`\]</pre>]
 
 a hyperlink to the "man page" for a utility class, where:
 
@@ -240,14 +240,14 @@ a hyperlink to the "man page" for a utility class, where:
 
 for example:
 
-pass:[<pre>xref:rgcms.adoc#_rgcms_classes_utility_manpage-TitleBuffer[`TitleBuffer`\]</pre>]
+pass:[<pre>xref:rgcms.adoc#_rgcms_classes_utility_TitleBuffer[`TitleBuffer`\]</pre>]
 
-|xref:rgcms.adoc#_rgcms_classes_utility_manpage-TitleBuffer[`TitleBuffer`]
+|xref:rgcms.adoc#_rgcms_classes_utility_TitleBuffer[`TitleBuffer`]
 
 
 
 |`adrgcv`
-|pass:[<pre>xref:rgcms.adoc#_rgcms_classes_value-types_manpage-xxx[`xxx`\]</pre>]
+|pass:[<pre>xref:rgcms.adoc#_rgcms_classes_value-types_xxx[`xxx`\]</pre>]
 
 
 a hyperlink to the "man page" for an applib value class, where:
@@ -256,14 +256,14 @@ a hyperlink to the "man page" for an applib value class, where:
 
 for example:
 
-pass:[<pre>xref:rgcms.adoc#_rgcms_classes_value-types_manpage-Blob[`Blob`\]</pre>]
+pass:[<pre>xref:rgcms.adoc#_rgcms_classes_value-types_Blob[`Blob`\]</pre>]
 
-|xref:rgcms.adoc#_rgcms_classes_value-types_manpage-Blob[`Blob`]
+|xref:rgcms.adoc#_rgcms_classes_value-types_Blob[`Blob`]
 
 
 
 |`adrgmp`
-|pass:[<pre>xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-xxx[`xxx...()`\]</pre>]
+|pass:[<pre>xref:rgcms.adoc#_rgcms_methods_prefixes_xxx[`xxx...()`\]</pre>]
 
 a hyperlink to the "man page" for a prefixed method, where:
 
@@ -271,9 +271,9 @@ a hyperlink to the "man page" for a prefixed method, where:
 
 for example:
 
-pass:[<pre>xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-disable[`disable...()`\]</pre>]
+pass:[<pre>xref:rgcms.adoc#_rgcms_methods_prefixes_disable[`disable...()`\]</pre>]
 
-|xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-disable[`disable...()`]
+|xref:rgcms.adoc#_rgcms_methods_prefixes_disable[`disable...()`]
 
 
 
@@ -286,9 +286,9 @@ a hyperlink to the "man page" for a reserved method, where:
 
 for example:
 
-pass:[<pre>xref:rgcms.adoc#_rgcms_methods_reserved_manpage-title[`title()`\]</pre>]
+pass:[<pre>xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`\]</pre>]
 
-|xref:rgcms.adoc#_rgcms_methods_reserved_manpage-title[`title()`]
+|xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`]
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgant-Collection_editing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-Collection_editing.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-Collection_editing.adoc
index 7b148d2..9bc524e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-Collection_editing.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-Collection_editing.adoc
@@ -25,7 +25,7 @@ Whether a collection is enabled or disabled depends upon these factors:
 
 * else, then the value of the `@Collection(editing=...)` attribute itself.
 
-* else, the result of invoking any supporting xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-disable[`disable...()`] supporting methods
+* else, the result of invoking any supporting xref:rgcms.adoc#_rgcms_methods_prefixes_disable[`disable...()`] supporting methods
 
 
 Thus, to make a collection read-only even if the object would otherwise be editable, use:

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgant-Column.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-Column.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-Column.adoc
index 2069ee1..97a1b12 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-Column.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-Column.adoc
@@ -116,7 +116,7 @@ public class PartyRelationship {
 
 == Mapping ``Blob``s and ``Clob``s
 
-Isis provides custom value types for xref:rgcms.adoc#_rgcms_classes_value-types_manpage-Blob[`Blob`]s and xref:rgcms.adoc#_rgcms_classes_value-types_manpage-Clob[`Clob`]s.  These value types have multiple internal fields, meaning that they corresponding to multiple columns in the database.  Mapping this correctly requires using  `@Column` within JDO's `@Persistent` annotation.
+Isis provides custom value types for xref:rgcms.adoc#_rgcms_classes_value-types_Blob[`Blob`]s and xref:rgcms.adoc#_rgcms_classes_value-types_Clob[`Clob`]s.  These value types have multiple internal fields, meaning that they corresponding to multiple columns in the database.  Mapping this correctly requires using  `@Column` within JDO's `@Persistent` annotation.
 
 For example, here's how to map a `Blob` (taken from (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp]):
 

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClassFa.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClassFa.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClassFa.adoc
index 0ed1955..ae8c7ef 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClassFa.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClassFa.adoc
@@ -10,7 +10,7 @@ The `cssClassFa()` attribute is used to specify the name of a link:http://fortaw
 
 These attributes can also be applied to xref:rgant.adoc#_rgant-ViewModelLayout_cssClassFa[view models] to specify the object's icon, and to xref:rgant.adoc#_rgant-ActionLayout_cssClassFa[actions] to specify an icon for the action's representation as a button or menu item.
 
-If necessary the icon specified can be overridden by a particular object instance using the xref:rgcms.adoc#_rgcms_methods_reserved_manpage-iconName[`iconName()`] method.
+If necessary the icon specified can be overridden by a particular object instance using the xref:rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`] method.
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClassUiEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClassUiEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClassUiEvent.adoc
index 31d1a56..4e80dd2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClassUiEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClassUiEvent.adoc
@@ -7,7 +7,7 @@
 
 Whenever a domain object is to be rendered, the framework fires off an CSS class UI event to obtain a CSS class to use
 in any wrapping ``<div>``s and ``<span>``s that render the domain object.  This is as an alternative to implementing
-xref:rgcms.adoc#_rgcms_methods_reserved_manpage-cssClass[`cssClass()`] reserved method.  (If `cssClass()` is present, then
+xref:rgcms.adoc#_rgcms_methods_reserved_cssClass[`cssClass()`] reserved method.  (If `cssClass()` is present, then
 it will take precedence).
 
 Subscribers subscribe through the xref:rgsvc.adoc#_rgsvc-api_EventBusService[`EventBusService`] and can

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_iconUiEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_iconUiEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_iconUiEvent.adoc
index 2d20e91..ab98026 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_iconUiEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_iconUiEvent.adoc
@@ -7,7 +7,7 @@
 
 Whenever a domain object is to be rendered, the framework fires off an icon UI event to obtain an icon (name) for the
 object (if possible). This is as an alternative to implementing
-xref:rgcms.adoc#_rgcms_methods_reserved_manpage-iconName[`iconName()`] reserved method.  (If `iconName()` is present, then
+xref:rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`] reserved method.  (If `iconName()` is present, then
 it will take precedence).
 
 Subscribers subscribe through the xref:rgsvc.adoc#_rgsvc-api_EventBusService[`EventBusService`] and can

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_titleUiEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_titleUiEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_titleUiEvent.adoc
index 5cf0051..86a8856 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_titleUiEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_titleUiEvent.adoc
@@ -6,7 +6,7 @@
 
 
 Whenever a domain object is to be rendered, the framework fires off a title UI event to obtain a title for the object.
-This is as an alternative to implementing xref:rgcms.adoc#_rgcms_methods_reserved_manpage-title[`title()`] reserved method, or
+This is as an alternative to implementing xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`] reserved method, or
 using the xref:rgant.adoc#_rgant-Title[`@Title`] annotation, within the class itself.  (If either
 `title()` or `@Title` are present, then they will take precedence).
 

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_autoCompleteRepository.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_autoCompleteRepository.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_autoCompleteRepository.adoc
index 95f7899..97e0182 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_autoCompleteRepository.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_autoCompleteRepository.adoc
@@ -13,7 +13,7 @@ For example, this might search for a customer by their name or number.  Or it co
 
 [TIP]
 ====
-If you require additional control - for example restricting the returned results based on the object being interacted with - then use the xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-autoComplete[`autoComplete...()`] supporting method instead.
+If you require additional control - for example restricting the returned results based on the object being interacted with - then use the xref:rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`] supporting method instead.
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_bounded.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_bounded.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_bounded.adoc
index 6ee3f4b..d0f4de6 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_bounded.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_bounded.adoc
@@ -28,7 +28,7 @@ public class Currency {
 
 [TIP]
 ====
-There is nothing to prevent you from using this attribute for regular mutable entities, and indeed this is sometimes worth doing during early prototyping.  However, if there is no realistic upper bound to the number of instances of an entity that might be created, generally you should use xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-autoComplete[`autoComplete...()`] supporting method or the xref:rgant.adoc#_rgant-DomainObject_autoCompleteRepository[`@DomainObject#autoCompleteRepository()`] attribute instead.
+There is nothing to prevent you from using this attribute for regular mutable entities, and indeed this is sometimes worth doing during early prototyping.  However, if there is no realistic upper bound to the number of instances of an entity that might be created, generally you should use xref:rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`] supporting method or the xref:rgant.adoc#_rgant-DomainObject_autoCompleteRepository[`@DomainObject#autoCompleteRepository()`] attribute instead.
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_nature.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_nature.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_nature.adoc
index 7ba07cd..0625cc0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_nature.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_nature.adoc
@@ -53,7 +53,7 @@ indicates that the domain object is conceptually part of the application layer,
 
 The identity of an inmemory entity is determined solely by the state of entity's properties.  The framework will automatically recreate the domain object each time it is interacted with.
 
-Those natures that indicate the domain object is an entity (of some sort or another) mean then that the domain object is considered to be part of the domain model layer.  As such the domain object's class cannot be annotated with xref:rgant.adoc#_rgant-ViewModel[`@ViewModel`] or implement the xref:rgcms.adoc#_rgcms_classes_super_manpage-ViewModel[`ViewModel`] interface.
+Those natures that indicate the domain object is an entity (of some sort or another) mean then that the domain object is considered to be part of the domain model layer.  As such the domain object's class cannot be annotated with xref:rgant.adoc#_rgant-ViewModel[`@ViewModel`] or implement the xref:rgcms.adoc#_rgcms_classes_super_ViewModel[`ViewModel`] interface.
 
 
 [NOTE]

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_persistingLifecycleEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_persistingLifecycleEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_persistingLifecycleEvent.adoc
index 76a25ba..9b5518c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_persistingLifecycleEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_persistingLifecycleEvent.adoc
@@ -17,7 +17,7 @@ link:https://lucene.apache.org/[Apache Lucene] or similar.
 ====
 Another use case is to maintain "last updated by"/"last updated at" properties.  While you can roll your own, note that
 the framework provides built-in support for this use case through the
-xref:rgcms.adoc#_rgcms_classes_roles_manpage-Timestampable[`Timestampable`] role interface.
+xref:rgcms.adoc#_rgcms_classes_roles_Timestampable[`Timestampable`] role interface.
 ====
 
 By default the event raised is `ObjectPersistingEvent.Default`. For example:

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_removingLifecycleEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_removingLifecycleEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_removingLifecycleEvent.adoc
index 9390c3a..9ba1710 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_removingLifecycleEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_removingLifecycleEvent.adoc
@@ -17,7 +17,7 @@ using link:https://lucene.apache.org/[Apache Lucene] or similar.
 ====
 Another use case is to maintain "last updated by"/"last updated at" properties.  While you can roll your own, note that
 the framework provides built-in support for this use case through the
-xref:rgcms.adoc#_rgcms_classes_roles_manpage-Timestampable[`Timestampable`] role interface.
+xref:rgcms.adoc#_rgcms_classes_roles_Timestampable[`Timestampable`] role interface.
 ====
 
 By default the event raised is `ObjectRemovingEvent.Default`. For example:

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_updatingLifecycleEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_updatingLifecycleEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_updatingLifecycleEvent.adoc
index ef1c456..e644c8d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_updatingLifecycleEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_updatingLifecycleEvent.adoc
@@ -17,7 +17,7 @@ using link:https://lucene.apache.org/[Apache Lucene] or similar.
 ====
 Another use case is to maintain "last updated by"/"last updated at" properties.  While you can roll your own, note that
 the framework provides built-in support for this use case through the
-xref:rgcms.adoc#_rgcms_classes_roles_manpage-Timestampable[`Timestampable`] role interface.
+xref:rgcms.adoc#_rgcms_classes_roles_Timestampable[`Timestampable`] role interface.
 ====
 
 By default the event raised is `ObjectUpdatingEvent.Default`. For example:

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgant-MinLength.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-MinLength.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-MinLength.adoc
index d896a6c..c797013 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-MinLength.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-MinLength.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-The `@MinLength` annotation is used to specify the minimum number of characters in a search of an xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-autoComplete[`autoComplete...()`] supporting method.
+The `@MinLength` annotation is used to specify the minimum number of characters in a search of an xref:rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`] supporting method.
 
 
 For example:

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgant-Parameter.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-Parameter.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-Parameter.adoc
index a191b90..ebf8410 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-Parameter.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-Parameter.adoc
@@ -27,7 +27,7 @@ The table below summarizes the annotation's attributes.
 |Positive integer
 |Deprecated; use xref:rgant.adoc#_rgant-MinLength[`@MinLength`] instead. +
 
-Can be used to specify the minimum length for xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-autoComplete[`autoComplete...()`] supporting method; but because this _is a_ supporting method rather than the action method itself, we now feel it is misleading to use the `@Parameter` annotation in this situation.
+Can be used to specify the minimum length for xref:rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`] supporting method; but because this _is a_ supporting method rather than the action method itself, we now feel it is misleading to use the `@Parameter` annotation in this situation.
 
 
 |xref:rgant.adoc#_rgant-Parameter_mustSatisfy[`mustSatisfy()`]

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgant-PostConstruct.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-PostConstruct.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-PostConstruct.adoc
index 78e4cf7..bf2eb25 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-PostConstruct.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-PostConstruct.adoc
@@ -58,7 +58,7 @@ public class MySubscribingService {
 
 [TIP]
 ====
-In this particular use case, it is generally simpler to just subclass from xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractSubscriber[`AbstractSubscriber`].
+In this particular use case, it is generally simpler to just subclass from xref:rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[`AbstractSubscriber`].
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgant-PreDestroy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-PreDestroy.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-PreDestroy.adoc
index 268846a..4588986 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-PreDestroy.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-PreDestroy.adoc
@@ -43,7 +43,7 @@ public class MySubscribingService {
 
 [TIP]
 ====
-In this particular use case, it is generally simpler to just subclass from xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractSubscriber[`AbstractSubscriber`].
+In this particular use case, it is generally simpler to just subclass from xref:rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[`AbstractSubscriber`].
 ====
 
 Other use cases include obtaining connections to external datasources, eg subscribing to an ActiveMQ router, say, or initializing/cleaning up a background scheduler such as Quartz.

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgant-Property_editing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-Property_editing.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-Property_editing.adoc
index f28a5d2..61cff58 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-Property_editing.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-Property_editing.adoc
@@ -17,7 +17,7 @@ Whether a property is enabled or disabled depends upon these factors:
 
 * else, then the value of the `@Property(editing=...)` attribute itself
 
-* else, the result of invoking any supporting xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-disable[`disable...()`] supporting methods
+* else, the result of invoking any supporting xref:rgcms.adoc#_rgcms_methods_prefixes_disable[`disable...()`] supporting methods
 
 
 Thus, to make a property read-only even if the object would otherwise be editable, use:

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgant-ViewModelLayout_cssClassFa.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-ViewModelLayout_cssClassFa.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-ViewModelLayout_cssClassFa.adoc
index e653485..dd3a058 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-ViewModelLayout_cssClassFa.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-ViewModelLayout_cssClassFa.adoc
@@ -12,7 +12,7 @@ The `cssClassFa()` attribute is used to specify the name of a link:http://fortaw
 These attribute can also be applied to xref:rgant.adoc#_rgant-DomainObjectLayout_cssClassFa[domain objects] to specify the object's icon, and to xref:rgant.adoc#_rgant-ActionLayout_cssClassFa[actions] to specify an icon for the action's representation as a button or menu item.
 
 
-If necessary the icon specified can be overridden by a particular object instance using the xref:rgcms.adoc#_rgcms_methods_reserved_manpage-iconName[`iconName()`] method.
+If necessary the icon specified can be overridden by a particular object instance using the xref:rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`] method.
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgant-XmlRootElement.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-XmlRootElement.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-XmlRootElement.adoc
index 0e36b15..d5874f1 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-XmlRootElement.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-XmlRootElement.adoc
@@ -13,7 +13,7 @@ A view model is a non-persisted domain object whose state is converted to/from a
 JAXB-annotated object this memento is its XML representation.  JAXB generally requires that the root element of the
 XML representation is annotated with `@XmlRootElement`.  Apache Isis makes this a mandatory requirement.
 
-In comparison to using either the xref:rgcms.adoc#_rgcms_classes_super_manpage-ViewModel[`ViewModel`] interface or the
+In comparison to using either the xref:rgcms.adoc#_rgcms_classes_super_ViewModel[`ViewModel`] interface or the
 xref:rgant.adoc#_rgant-ViewModel[`@ViewModel`] annotation, using `@XmlRootElement` has a couple of
 significant advantages:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-core.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-core.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-core.adoc
index 925f032..4462047 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-core.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-core.adoc
@@ -214,7 +214,7 @@ See xref:ugbtb.adoc#_ugbtb_programming-model_custom-validator[Custom Validator]
 
 Each entry can be optionally prefixed by "n:" specifying the relative order on the menu (corresponds to xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`]).
 
-This property is IGNORED if the xref:rgcfg.adoc#_rgcfg_configuring-components[`isis.appManifest`] configuration property is specified, or if an xref:rgcms.adoc#_rgcms_classes_super_manpage-AppManifest[`AppManifest`] is provided programmatically.
+This property is IGNORED if the xref:rgcfg.adoc#_rgcfg_configuring-components[`isis.appManifest`] configuration property is specified, or if an xref:rgcms.adoc#_rgcms_classes_super_AppManifest[`AppManifest`] is provided programmatically.
 
 
 |`isis.services.` +
@@ -347,7 +347,7 @@ This implementation provides a default set of recognizers to convert RDBMS const
 |fully qualified package names (CSV)
 |to search for domain services (including all subpackages).
 
-This property is IGNORED if the xref:rgcfg.adoc#_rgcfg_configuring-components[`isis.appManifest`] configuration property is specified, or if an xref:rgcms.adoc#_rgcms_classes_super_manpage-AppManifest[`AppManifest`] is provided programmatically.
+This property is IGNORED if the xref:rgcfg.adoc#_rgcfg_configuring-components[`isis.appManifest`] configuration property is specified, or if an xref:rgcms.adoc#_rgcms_classes_super_AppManifest[`AppManifest`] is provided programmatically.
 
 
 |`isis.services.` +

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_disabling-persistence-by-reachability.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_disabling-persistence-by-reachability.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_disabling-persistence-by-reachability.adoc
index d4ea0df..afc22c0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_disabling-persistence-by-reachability.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_disabling-persistence-by-reachability.adoc
@@ -14,7 +14,7 @@ However, convenient though this feature is, you may find that it causes performa
 DataNucleus' persistence-by-reachability may cause performance issues.  We strongly recommend that you disable it.
 ====
 
-One scenario in particular where this performance issues can arise is if your entities implement the `java.lang.Comparable` interface, and you have used Apache Isis' xref:rgcms.adoc#_rgcms_classes_utility_manpage-ObjectContracts[`ObjectContracts`] utility class. The issue here is that `ObjectContracts` implementation can cause DataNucleus to recursively rehydrate a larger number of associated entities. (More detail below).
+One scenario in particular where this performance issues can arise is if your entities implement the `java.lang.Comparable` interface, and you have used Apache Isis' xref:rgcms.adoc#_rgcms_classes_utility_ObjectContracts[`ObjectContracts`] utility class. The issue here is that `ObjectContracts` implementation can cause DataNucleus to recursively rehydrate a larger number of associated entities. (More detail below).
 
 We therefore recommend that you disable persistence-by-reachability by adding the following to `persistor_datanucleus.properties`:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_eagerly-registering-entities.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_eagerly-registering-entities.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_eagerly-registering-entities.adoc
index 232f17d..e6f0c37 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_eagerly-registering-entities.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_eagerly-registering-entities.adoc
@@ -14,7 +14,7 @@ Apache Isis is quite happy for the metamodel to be lazily created, and - to be f
 
 The framework thus provide mechanisms to search for all `@PersistenceCapable` entities under specified package(s), and registers them all eagerly.  In fact there are two:
 
-* as of 1.9.0 the recommended (and simpler) approach is to specify an xref:rgcms.adoc#_rgcms_classes_super_manpage-AppManifest[`AppManifest`], either as a xref:rgcfg.adoc#_rgcfg_configuring-components[`isis.appManifest`] configuration property or programmatically.
+* as of 1.9.0 the recommended (and simpler) approach is to specify an xref:rgcms.adoc#_rgcms_classes_super_AppManifest[`AppManifest`], either as a xref:rgcfg.adoc#_rgcfg_configuring-components[`isis.appManifest`] configuration property or programmatically.
 
 * for earlier versions the `isis.persistor.datanucleus.RegisterEntities.packagePrefix` configuration property can be specified.  To bootstrap as a webapp this is usually specified in `persistor_datanucleus.properties`.  (This is also supported in 1.9.0 if no `AppManifest` is specified.  For integration testing this can be specified programatically.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_properties.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_properties.adoc
index c53b489..c454d61 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_properties.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_properties.adoc
@@ -30,7 +30,7 @@ These configuration properties are typically stored in `WEB-INF/persistor_datanu
 |fully qualified package names (CSV)
 |that specifies the entities early rather than allow DataNucleus to find the entities lazily.  Further xref:rgcfg.adoc#_rgcfg_configuring-datanucleus_eagerly-registering-entities[discussion below].
 
-This property is IGNORED if the xref:rgcfg.adoc#_rgcfg_configuring-components[`isis.appManifest`] configuration property is specified, or if an xref:rgcms.adoc#_rgcms_classes_super_manpage-AppManifest[`AppManifest`] is provided programmatically.
+This property is IGNORED if the xref:rgcfg.adoc#_rgcfg_configuring-components[`isis.appManifest`] configuration property is specified, or if an xref:rgcms.adoc#_rgcms_classes_super_AppManifest[`AppManifest`] is provided programmatically.
 
 
 |`isis.persistor.datanucleus.` +

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcfg_specifying-components.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_specifying-components.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_specifying-components.adoc
index d1a7176..a984e9f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_specifying-components.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_specifying-components.adoc
@@ -11,7 +11,7 @@ Bootstrapping an Apache Isis application involves identifying both:
 * the major components (authentication, persistence mechanisms, viewers) of Apache Isis, and also
 * specifying the domain services and persistent entities that make up the application itself.
 
-As of 1.9.0 there are two different ways to perform this bootstrapping.  The recommended (newer) approach is to use an xref:rgcms.adoc#_rgcms_classes_super_manpage-AppManifest[`AppManifest`], specified either programmatically or through the configuration properties.  This allows the components, services and entities to be specified from a single class.  The alternative (and older, pre 1.9.0) approach is to specify this information individually, through configuration properties.
+As of 1.9.0 there are two different ways to perform this bootstrapping.  The recommended (newer) approach is to use an xref:rgcms.adoc#_rgcms_classes_super_AppManifest[`AppManifest`], specified either programmatically or through the configuration properties.  This allows the components, services and entities to be specified from a single class.  The alternative (and older, pre 1.9.0) approach is to specify this information individually, through configuration properties.
 
 To specify the `AppManifest` as a configuration property, use:
 
@@ -49,7 +49,7 @@ If the `AppManifest` approach is _not_ being used, then the following configurat
 (`_shiro_`)
 |`o.a.i.core.runtime.authentication.` `AuthenticationManagerInstaller` +
 
-This property is IGNORED if the `isis.appManifest` configuration property is specified, or if an xref:rgcms.adoc#_rgcms_classes_super_manpage-AppManifest[`AppManifest`] is provided programmatically.
+This property is IGNORED if the `isis.appManifest` configuration property is specified, or if an xref:rgcms.adoc#_rgcms_classes_super_AppManifest[`AppManifest`] is provided programmatically.
 
 
 |`isis.authorization`
@@ -57,7 +57,7 @@ This property is IGNORED if the `isis.appManifest` configuration property is spe
 (`_shiro_`)
 |`o.a.i.core.runtime.authorization.` `AuthorizationManagerInstaller` +
 
-This property is IGNORED if the `isis.appManifest` configuration property is specified, or if an xref:rgcms.adoc#_rgcms_classes_super_manpage-AppManifest[`AppManifest`] is provided programmatically.
+This property is IGNORED if the `isis.appManifest` configuration property is specified, or if an xref:rgcms.adoc#_rgcms_classes_super_AppManifest[`AppManifest`] is provided programmatically.
 
 |`isis.persistor`
 |`datanucleus`
@@ -80,7 +80,7 @@ The mechanism to discover and load domain services:
 
 * Otherwise an alternative implementation of the `o.a.i.core.runtime.services.ServicesInstaller` internal API can be provided. +
 
-This property is IGNORED if the `isis.appManifest` configuration property is specified, or if an xref:rgcms.adoc#_rgcms_classes_super_manpage-AppManifest[`AppManifest`] is provided programmatically.
+This property is IGNORED if the `isis.appManifest` configuration property is specified, or if an xref:rgcms.adoc#_rgcms_classes_super_AppManifest[`AppManifest`] is provided programmatically.
 
 
 |===

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_contributee.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_contributee.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_contributee.adoc
index 6c39e33..445b89e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_contributee.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_contributee.adoc
@@ -8,6 +8,6 @@
 The interfaces listed in this chapter act as contributees; they allow domain services to contribute actions/properties/collections to any domain objects that implement these interfaces.
 
 
-include::_rgcms_classes_contributee_manpage-HasTransactionId.adoc[leveloffset=+1]
-include::_rgcms_classes_contributee_manpage-HasUserName.adoc[leveloffset=+1]
+include::_rgcms_classes_contributee_HasTransactionId.adoc[leveloffset=+1]
+include::_rgcms_classes_contributee_HasUserName.adoc[leveloffset=+1]
 

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_contributee_HasTransactionId.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_contributee_HasTransactionId.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_contributee_HasTransactionId.adoc
new file mode 100644
index 0000000..89ee031
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_contributee_HasTransactionId.adoc
@@ -0,0 +1,31 @@
+[[_rgcms_classes_mixins_HasTransactionId]]
+= `HasTransactionId`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+The `HasTransactionId` interface is a mix-in for any domain objects that reference a transaction id, such as
+auditing entries or commands.
+
+The interface is defined is:
+
+[source,java]
+----
+public interface HasTransactionId {
+
+    public UUID getTransactionId();                             // <1>
+    public void setTransactionId(final UUID transactionId);
+}
+----
+<1> unique identifier (a GUID) of the transaction in which this interaction occurred.
+
+
+
+Modules that either have domain entity that implement and/or services that contribute this interface are:
+
+* (non-ASF) http://github.com/isisaddons/isis-module-audit[Isis addons' audit] module (`AuditEntry` entity, `AuditingServiceContributions` service)
+* (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module (`CommandJdo` entity, `CommandServiceJdoContributions` service)
+* (non-ASF) http://github.com/isisaddons/isis-module-publishing[Isis addons' publishing] module (`PublishedEvent` entity, `PublishingServiceContributions`)
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_contributee_HasUserName.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_contributee_HasUserName.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_contributee_HasUserName.adoc
new file mode 100644
index 0000000..d73ca06
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_contributee_HasUserName.adoc
@@ -0,0 +1,27 @@
+[[_rgcms_classes_mixins_HasUserName]]
+= `HasUsername`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+The `HasUsername` interface is a mix-in for domain objects to be associated with a username.  Other services and modules can then contribute actions/collections to render such additional information relating to the activities of the user.
+
+The interface is defined is:
+
+[source,java]
+----
+public interface HasUsername {
+    public String getUsername();
+}
+----
+
+Modules that either have domain entity that implement and/or services that contribute this interface are:
+
+* (non-ASF) http://github.com/isisaddons/isis-module-security[Isis addons' security] module ( `ApplicationUser` entity, `HasUsernameContributions` service)
+* (non-ASF) http://github.com/isisaddons/isis-module-audit[Isis addons' audit] module (`AuditEntry` entity,
+* (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module's `CommandJdo` entity, `HasUsernameContributions` service)
+* (non-ASF) http://github.com/isisaddons/isis-module-publishing[Isis addons' publishing] module (`PublishedEvent` entity)
+* (non-ASF) http://github.com/isisaddons/isis-module-sessionlogger[Isis addons' sessionlogger] module (`SessionLogEntry` entity, `HasUsernameContributions` service)
+* (non-ASF) http://github.com/isisaddons/isis-module-settings[Isis addons' settings] module (`UserSettingJdo` entity)
+

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_contributee_manpage-HasTransactionId.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_contributee_manpage-HasTransactionId.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_contributee_manpage-HasTransactionId.adoc
deleted file mode 100644
index f0c2a76..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_contributee_manpage-HasTransactionId.adoc
+++ /dev/null
@@ -1,31 +0,0 @@
-[[_rgcms_classes_mixins_manpage-HasTransactionId]]
-= `HasTransactionId`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-The `HasTransactionId` interface is a mix-in for any domain objects that reference a transaction id, such as
-auditing entries or commands.
-
-The interface is defined is:
-
-[source,java]
-----
-public interface HasTransactionId {
-
-    public UUID getTransactionId();                             // <1>
-    public void setTransactionId(final UUID transactionId);
-}
-----
-<1> unique identifier (a GUID) of the transaction in which this interaction occurred.
-
-
-
-Modules that either have domain entity that implement and/or services that contribute this interface are:
-
-* (non-ASF) http://github.com/isisaddons/isis-module-audit[Isis addons' audit] module (`AuditEntry` entity, `AuditingServiceContributions` service)
-* (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module (`CommandJdo` entity, `CommandServiceJdoContributions` service)
-* (non-ASF) http://github.com/isisaddons/isis-module-publishing[Isis addons' publishing] module (`PublishedEvent` entity, `PublishingServiceContributions`)
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_contributee_manpage-HasUserName.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_contributee_manpage-HasUserName.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_contributee_manpage-HasUserName.adoc
deleted file mode 100644
index 2fb0d4b..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_contributee_manpage-HasUserName.adoc
+++ /dev/null
@@ -1,27 +0,0 @@
-[[_rgcms_classes_mixins_manpage-HasUserName]]
-= `HasUsername`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-The `HasUsername` interface is a mix-in for domain objects to be associated with a username.  Other services and modules can then contribute actions/collections to render such additional information relating to the activities of the user.
-
-The interface is defined is:
-
-[source,java]
-----
-public interface HasUsername {
-    public String getUsername();
-}
-----
-
-Modules that either have domain entity that implement and/or services that contribute this interface are:
-
-* (non-ASF) http://github.com/isisaddons/isis-module-security[Isis addons' security] module ( `ApplicationUser` entity, `HasUsernameContributions` service)
-* (non-ASF) http://github.com/isisaddons/isis-module-audit[Isis addons' audit] module (`AuditEntry` entity,
-* (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module's `CommandJdo` entity, `HasUsernameContributions` service)
-* (non-ASF) http://github.com/isisaddons/isis-module-publishing[Isis addons' publishing] module (`PublishedEvent` entity)
-* (non-ASF) http://github.com/isisaddons/isis-module-sessionlogger[Isis addons' sessionlogger] module (`SessionLogEntry` entity, `HasUsernameContributions` service)
-* (non-ASF) http://github.com/isisaddons/isis-module-settings[Isis addons' settings] module (`UserSettingJdo` entity)
-

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent.adoc
index 6cbfabd..82f2942 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent.adoc
@@ -23,7 +23,7 @@ Impl'n (g: a:)
 |Notes
 
 
-|xref:rgcms.adoc#_rgcms_classes_domainevent_manpage-AbstractDomainEvent[`o.a.i.applib.` +
+|xref:rgcms.adoc#_rgcms_classes_domainevent_AbstractDomainEvent[`o.a.i.applib.` +
 `AbstractDomainEvent`]
 |``o.a.i.core`` +
 ``services.eventbus`` +
@@ -32,7 +32,7 @@ Impl'n (g: a:)
 |Superclass of the other domain events, listed below in this table.
 
 
-|xref:rgcms.adoc#_rgcms_classes_domainevent_manpage-ActionDomainEvent[`o.a.i.applib.` +
+|xref:rgcms.adoc#_rgcms_classes_domainevent_ActionDomainEvent[`o.a.i.applib.` +
 `ActionDomainEvent`]
 |``o.a.i.core`` +
 ``services.eventbus`` +
@@ -42,7 +42,7 @@ Impl'n (g: a:)
 |Broadcast whenever there is an interaction (hide/disable/validate/pre-execute/post-execute) with an object's action.
 
 
-|xref:rgcms.adoc#_rgcms_classes_domainevent_manpage-CollectionDomainEvent[`o.a.i.applib.` +
+|xref:rgcms.adoc#_rgcms_classes_domainevent_CollectionDomainEvent[`o.a.i.applib.` +
 `CollectionDomainEvent`]
 |``o.a.i.core`` +
 ``services.eventbus`` +
@@ -53,7 +53,7 @@ is specified.
 |Broadcast whenever there is an interaction (hide/disable/validate/access) with an object's collection.
 
 
-|xref:rgcms.adoc#_rgcms_classes_domainevent_manpage-PropertyDomainEvent[`o.a.i.applib.` +
+|xref:rgcms.adoc#_rgcms_classes_domainevent_PropertyDomainEvent[`o.a.i.applib.` +
 `PropertyDomainEvent`]
 |``o.a.i.core`` +
 ``services.eventbus`` +
@@ -69,8 +69,8 @@ is specified.
 
 
 
-include::_rgcms_classes_domainevent_manpage-AbstractDomainEvent.adoc[leveloffset=+1]
-include::_rgcms_classes_domainevent_manpage-ActionDomainEvent.adoc[leveloffset=+1]
-include::_rgcms_classes_domainevent_manpage-CollectionDomainEvent.adoc[leveloffset=+1]
-include::_rgcms_classes_domainevent_manpage-PropertyDomainEvent.adoc[leveloffset=+1]
+include::_rgcms_classes_domainevent_AbstractDomainEvent.adoc[leveloffset=+1]
+include::_rgcms_classes_domainevent_ActionDomainEvent.adoc[leveloffset=+1]
+include::_rgcms_classes_domainevent_CollectionDomainEvent.adoc[leveloffset=+1]
+include::_rgcms_classes_domainevent_PropertyDomainEvent.adoc[leveloffset=+1]
 

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_AbstractDomainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_AbstractDomainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_AbstractDomainEvent.adoc
new file mode 100644
index 0000000..44e31a7
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_AbstractDomainEvent.adoc
@@ -0,0 +1,20 @@
+[[_rgcms_classes_domainevent_AbstractDomainEvent]]
+= `AbstractDomainEvent`
+: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 class is the superclass for all domain events that are raised by the framework when interacting with actions, properties or collections.
+
+Its immediate subclasses are:
+
+* xref:rgcms.adoc#_rgcms_classes_domainevent_ActionDomainEvent[`ActionDomainEvent`]
+
+* xref:rgcms.adoc#_rgcms_classes_domainevent_PropertyDomainEvent[`PropertyDomainEvent`]
+
+* xref:rgcms.adoc#_rgcms_classes_domainevent_CollectionDomainEvent[`CollectionDomainEvent`]
+
+This class defines the `Phase` enum that is common to all domain events (hide/disable/validate/pre-execute/post-execute), and provides methods such as `veto(...)` by which subscribers can influence the interaction (eg hide a collection, disable a property, validate action arguments).
+
+It class also provides `get(...)` and `put(...)` methods that allow adhoc sharing of user data between different phases.  One event instance is used for both the hide and disable phases, and a different event instance is shared between validate/pre-execute/post-execute.

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_ActionDomainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_ActionDomainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_ActionDomainEvent.adoc
new file mode 100644
index 0000000..645569b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_ActionDomainEvent.adoc
@@ -0,0 +1,20 @@
+[[_rgcms_classes_domainevent_ActionDomainEvent]]
+= `ActionDomainEvent`
+: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/
+
+
+Subclass of xref:rgcms.adoc#_rgcms_classes_domainevent_AbstractDomainEvent[`AbstractDomainEvent`] for actions.
+
+The class has a number of responsibilities (in addition to those it inherits):
+
+* capture the target object being interacted with
+
+* capture the arguments for each of the action's parameters
+
+* provide selected metadata about the action parameters from the metamodel (names, types)
+
+* link back to the xref:rgsvc.adoc#_rgsvc-api_CommandContext[`CommandContext`] service's `Command` object
+
+The class itself is instantiated automatically by the framework whenever interacting with a rendered object's action.

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_CollectionDomainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_CollectionDomainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_CollectionDomainEvent.adoc
new file mode 100644
index 0000000..f41c954
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_CollectionDomainEvent.adoc
@@ -0,0 +1,21 @@
+[[_rgcms_classes_domainevent_CollectionDomainEvent]]
+= `CollectionDomainEvent`
+: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/
+
+
+Subclass of xref:rgcms.adoc#_rgcms_classes_domainevent_AbstractDomainEvent[`AbstractDomainEvent`] for collections.
+
+The class has a couple of responsibilities (in addition to those it inherits):
+
+* capture the target object being interacted with
+
+* indicate whether the interaction is to add or remove an object from the collection (or simply to indicate that the collection is being accessed/read)
+
+* capture the object reference being added or removed
+
+
+The class itself is instantiated automatically by the framework whenever interacting with a rendered object's collection.
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_PropertyDomainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_PropertyDomainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_PropertyDomainEvent.adoc
new file mode 100644
index 0000000..4e3d078
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_PropertyDomainEvent.adoc
@@ -0,0 +1,17 @@
+[[_rgcms_classes_domainevent_PropertyDomainEvent]]
+= `PropertyDomainEvent`
+: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/
+
+
+Subclass of xref:rgcms.adoc#_rgcms_classes_domainevent_AbstractDomainEvent[`AbstractDomainEvent`] for properties.
+
+The class has a couple of responsibilities (in addition to those it inherits):
+
+* capture the target object being interacted with
+
+* capture the old and new values of the property
+
+
+The class itself is instantiated automatically by the framework whenever interacting with a rendered object's property.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_manpage-AbstractDomainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_manpage-AbstractDomainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_manpage-AbstractDomainEvent.adoc
deleted file mode 100644
index 80ed308..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_manpage-AbstractDomainEvent.adoc
+++ /dev/null
@@ -1,20 +0,0 @@
-[[_rgcms_classes_domainevent_manpage-AbstractDomainEvent]]
-= `AbstractDomainEvent`
-: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 class is the superclass for all domain events that are raised by the framework when interacting with actions, properties or collections.
-
-Its immediate subclasses are:
-
-* xref:rgcms.adoc#_rgcms_classes_domainevent_manpage-ActionDomainEvent[`ActionDomainEvent`]
-
-* xref:rgcms.adoc#_rgcms_classes_domainevent_manpage-PropertyDomainEvent[`PropertyDomainEvent`]
-
-* xref:rgcms.adoc#_rgcms_classes_domainevent_manpage-CollectionDomainEvent[`CollectionDomainEvent`]
-
-This class defines the `Phase` enum that is common to all domain events (hide/disable/validate/pre-execute/post-execute), and provides methods such as `veto(...)` by which subscribers can influence the interaction (eg hide a collection, disable a property, validate action arguments).
-
-It class also provides `get(...)` and `put(...)` methods that allow adhoc sharing of user data between different phases.  One event instance is used for both the hide and disable phases, and a different event instance is shared between validate/pre-execute/post-execute.

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_manpage-ActionDomainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_manpage-ActionDomainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_manpage-ActionDomainEvent.adoc
deleted file mode 100644
index cf74368..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_manpage-ActionDomainEvent.adoc
+++ /dev/null
@@ -1,20 +0,0 @@
-[[_rgcms_classes_domainevent_manpage-ActionDomainEvent]]
-= `ActionDomainEvent`
-: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/
-
-
-Subclass of xref:rgcms.adoc#_rgcms_classes_domainevent_manpage-AbstractDomainEvent[`AbstractDomainEvent`] for actions.
-
-The class has a number of responsibilities (in addition to those it inherits):
-
-* capture the target object being interacted with
-
-* capture the arguments for each of the action's parameters
-
-* provide selected metadata about the action parameters from the metamodel (names, types)
-
-* link back to the xref:rgsvc.adoc#_rgsvc-api_CommandContext[`CommandContext`] service's `Command` object
-
-The class itself is instantiated automatically by the framework whenever interacting with a rendered object's action.

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_manpage-CollectionDomainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_manpage-CollectionDomainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_manpage-CollectionDomainEvent.adoc
deleted file mode 100644
index 05f2157..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_manpage-CollectionDomainEvent.adoc
+++ /dev/null
@@ -1,21 +0,0 @@
-[[_rgcms_classes_domainevent_manpage-CollectionDomainEvent]]
-= `CollectionDomainEvent`
-: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/
-
-
-Subclass of xref:rgcms.adoc#_rgcms_classes_domainevent_manpage-AbstractDomainEvent[`AbstractDomainEvent`] for collections.
-
-The class has a couple of responsibilities (in addition to those it inherits):
-
-* capture the target object being interacted with
-
-* indicate whether the interaction is to add or remove an object from the collection (or simply to indicate that the collection is being accessed/read)
-
-* capture the object reference being added or removed
-
-
-The class itself is instantiated automatically by the framework whenever interacting with a rendered object's collection.
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_manpage-PropertyDomainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_manpage-PropertyDomainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_manpage-PropertyDomainEvent.adoc
deleted file mode 100644
index 0878ee1..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_manpage-PropertyDomainEvent.adoc
+++ /dev/null
@@ -1,17 +0,0 @@
-[[_rgcms_classes_domainevent_manpage-PropertyDomainEvent]]
-= `PropertyDomainEvent`
-: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/
-
-
-Subclass of xref:rgcms.adoc#_rgcms_classes_domainevent_manpage-AbstractDomainEvent[`AbstractDomainEvent`] for properties.
-
-The class has a couple of responsibilities (in addition to those it inherits):
-
-* capture the target object being interacted with
-
-* capture the old and new values of the property
-
-
-The class itself is instantiated automatically by the framework whenever interacting with a rendered object's property.
\ No newline at end of file


[07/52] [abbrv] isis git commit: ISIS-1243: renamed rg.adoc to rgcms.adoc

Posted by mg...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_manpage-ActionDomainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_manpage-ActionDomainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_manpage-ActionDomainEvent.adoc
new file mode 100644
index 0000000..cf74368
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_manpage-ActionDomainEvent.adoc
@@ -0,0 +1,20 @@
+[[_rgcms_classes_domainevent_manpage-ActionDomainEvent]]
+= `ActionDomainEvent`
+: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/
+
+
+Subclass of xref:rgcms.adoc#_rgcms_classes_domainevent_manpage-AbstractDomainEvent[`AbstractDomainEvent`] for actions.
+
+The class has a number of responsibilities (in addition to those it inherits):
+
+* capture the target object being interacted with
+
+* capture the arguments for each of the action's parameters
+
+* provide selected metadata about the action parameters from the metamodel (names, types)
+
+* link back to the xref:rgsvc.adoc#_rgsvc-api_CommandContext[`CommandContext`] service's `Command` object
+
+The class itself is instantiated automatically by the framework whenever interacting with a rendered object's action.

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_manpage-CollectionDomainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_manpage-CollectionDomainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_manpage-CollectionDomainEvent.adoc
new file mode 100644
index 0000000..05f2157
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_manpage-CollectionDomainEvent.adoc
@@ -0,0 +1,21 @@
+[[_rgcms_classes_domainevent_manpage-CollectionDomainEvent]]
+= `CollectionDomainEvent`
+: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/
+
+
+Subclass of xref:rgcms.adoc#_rgcms_classes_domainevent_manpage-AbstractDomainEvent[`AbstractDomainEvent`] for collections.
+
+The class has a couple of responsibilities (in addition to those it inherits):
+
+* capture the target object being interacted with
+
+* indicate whether the interaction is to add or remove an object from the collection (or simply to indicate that the collection is being accessed/read)
+
+* capture the object reference being added or removed
+
+
+The class itself is instantiated automatically by the framework whenever interacting with a rendered object's collection.
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_manpage-PropertyDomainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_manpage-PropertyDomainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_manpage-PropertyDomainEvent.adoc
new file mode 100644
index 0000000..0878ee1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_manpage-PropertyDomainEvent.adoc
@@ -0,0 +1,17 @@
+[[_rgcms_classes_domainevent_manpage-PropertyDomainEvent]]
+= `PropertyDomainEvent`
+: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/
+
+
+Subclass of xref:rgcms.adoc#_rgcms_classes_domainevent_manpage-AbstractDomainEvent[`AbstractDomainEvent`] for properties.
+
+The class has a couple of responsibilities (in addition to those it inherits):
+
+* capture the target object being interacted with
+
+* capture the old and new values of the property
+
+
+The class itself is instantiated automatically by the framework whenever interacting with a rendered object's property.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_i18n.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_i18n.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_i18n.adoc
new file mode 100644
index 0000000..c6c2fcf
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_i18n.adoc
@@ -0,0 +1,11 @@
+[[_rgcms_classes_i18n]]
+= i18n support
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+The `org.apache.isis.applib.services.i18n` package contains a single class to support i18n.
+
+
+include::_rgcms_classes_i18n_manpage-TranslatableString.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_i18n_manpage-TranslatableString.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_i18n_manpage-TranslatableString.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_i18n_manpage-TranslatableString.adoc
new file mode 100644
index 0000000..9611a1e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_i18n_manpage-TranslatableString.adoc
@@ -0,0 +1,13 @@
+[[_rgcms_classes_i18n_manpage-TranslatableString]]
+= `TranslatableString`
+: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 - see xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[user guide, i18n].
+
+The `TranslatableString` utility class ...
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent.adoc
new file mode 100644
index 0000000..cd99543
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent.adoc
@@ -0,0 +1,130 @@
+[[_rgcms_classes_lifecycleevent]]
+= Lifecycle Events
+: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 section catalogues the various lifecycle event classes defined by Apache Isis.  These events
+are fired automatically when a domain object is loaded, created, updated and so forth.
+
+The lifecycle event classes are listed in the table below:
+
+
+.Lifecycle Event Classes
+[cols="2,4a,1,1", options="header"]
+|===
+
+|API
+|Maven Module +
+Impl'n (g: a:)
+|Implementation
+|Notes
+
+
+|xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-AbstractLifecycleEvent[`o.a.i.applib.` +
+`AbstractLifecycleEvent`]
+|``o.a.i.core`` +
+``services.eventbus`` +
+``isis-core-applib``
+|(abstract class)
+|Superclass of the other lifecycle events, listed below in this table.
+
+
+|xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-ObjectCreatedDomainEvent[`o.a.i.applib.` +
+`ObjectCreatedEvent`]
+|``o.a.i.core`` +
+``services.eventbus`` +
+``isis-core-applib``
+|(abstract class). +
+`ObjectCreatedEvent.Default` is the concrete implementation that is used.
+|Broadcast when an object is first instantiated
+using the xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-creation-api[`DomainObjectContainer`]'s
+`#newTransientInstance(...)` method.
+
+
+|xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-ObjectLoadedDomainEvent[`o.a.i.applib.` +
+`ObjectLoadedEvent`]
+|``o.a.i.core`` +
+``services.eventbus`` +
+``isis-core-applib``
+|(abstract class). +
+`ObjectLoadedEvent.Default` is the concrete implementation that is  used.
+|Broadcast when an object is retrieved from the database.
+
+
+|xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-ObjectPersistedDomainEvent[`o.a.i.applib.` +
+`ObjectPersistedEvent`]
+|``o.a.i.core`` +
+``services.eventbus`` +
+``isis-core-applib``
+|(abstract class). +
+`ObjectPersistedEvent.Default` is the concrete implementation that is used.
+|Broadcast when an object is first saved (inserted) into the database using the
+xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
+`#persist(...)` method.
+
+
+|xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-ObjectPersistingDomainEvent[`o.a.i.applib.` +
+`ObjectPersistingEvent`]
+|``o.a.i.core`` +
+``services.eventbus`` +
+``isis-core-applib``
+|(abstract class). +
+`ObjectPersistingEvent.Default` is the concrete implementation that is used.
+|Broadcast when an object is about to be saved (inserted) into the database using the
+xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
+`#persist(...)` method.
+
+
+|xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-ObjectRemovingDomainEvent[`o.a.i.applib.` +
+`ObjectRemovingEvent`]
+|``o.a.i.core`` +
+``services.eventbus`` +
+``isis-core-applib``
+|(abstract class). +
+`ObjectRemovingEvent.Default` is the concrete implementation that is used.
+|Broadcast when an object is about to be deleted from the database using the
+xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
+`#remove(...)` method.
+
+
+|xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-ObjectUpdatedDomainEvent[`o.a.i.applib.` +
+`ObjectUpdatedEvent`]
+|``o.a.i.core`` +
+``services.eventbus`` +
+``isis-core-applib``
+|(abstract class). +
+`ObjectUpdatedEvent.Default` is the concrete implementation that is used.
+|Broadcast when an object has just been updated in the database.  This is done either explicitly when the current
+transaction is flushed using the
+xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
+`#flush(...)` method, else is done implicitly when the transaction commits at the end of the user request.
+
+
+|xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-ObjectUpdatingDomainEvent[`o.a.i.applib.` +
+`ObjectUpdatingEvent`]
+|``o.a.i.core`` +
+``services.eventbus`` +
+``isis-core-applib``
+|(abstract class). +
+`ObjectUpdatingEvent.Default` is the concrete implementation that is used.
+|Broadcast when an object is about to be updated in the database.  This is done either explicitly when the current
+transaction is flushed using the
+xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
+`#flush(...)` method, else is done implicitly when the transaction commits at the end of the user request.
+
+
+|===
+
+
+
+include::_rgcms_classes_lifecycleevent_manpage-AbstractLifecycleEvent.adoc[leveloffset=+1]
+include::_rgcms_classes_lifecycleevent_manpage-ObjectCreatedEvent.adoc[leveloffset=+1]
+include::_rgcms_classes_lifecycleevent_manpage-ObjectLoadedEvent.adoc[leveloffset=+1]
+include::_rgcms_classes_lifecycleevent_manpage-ObjectPersistedEvent.adoc[leveloffset=+1]
+include::_rgcms_classes_lifecycleevent_manpage-ObjectPersistingEvent.adoc[leveloffset=+1]
+include::_rgcms_classes_lifecycleevent_manpage-ObjectRemovingEvent.adoc[leveloffset=+1]
+include::_rgcms_classes_lifecycleevent_manpage-ObjectUpdatedEvent.adoc[leveloffset=+1]
+include::_rgcms_classes_lifecycleevent_manpage-ObjectUpdatingEvent.adoc[leveloffset=+1]
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-AbstractLifecycleEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-AbstractLifecycleEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-AbstractLifecycleEvent.adoc
new file mode 100644
index 0000000..590c85c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-AbstractLifecycleEvent.adoc
@@ -0,0 +1,27 @@
+[[_rgcms_classes_lifecycleevent_manpage-AbstractLifecycleEvent]]
+= `AbstractLifecycleEvent`
+: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 class is the superclass for all lifecycle events that are raised by the framework when loading, saving, updating
+or deleting objects from the database.
+
+Its immediate subclasses are:
+
+* xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-ObjectCreatedEvent[`ObjectCreatedEvent`]
+
+* xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-ObjectLoadedEvent[`ObjectLoadedEvent`]
+
+* xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-ObjectPersistedEvent[`ObjectPersistedEvent`]
+
+* xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-ObjectPersistingEvent[`ObjectPersistingEvent`]
+
+* xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-ObjectRemovingEvent[`ObjectRemovingEvent`]
+
+* xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-ObjectUpdatedEvent[`ObjectUpdatedEvent`]
+
+* xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-ObjectUpdatingEvent[`ObjectUpdatingEvent`]
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectCreatedEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectCreatedEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectCreatedEvent.adoc
new file mode 100644
index 0000000..788a628
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectCreatedEvent.adoc
@@ -0,0 +1,20 @@
+[[_rgcms_classes_lifecycleevent_manpage-ObjectCreatedEvent]]
+= `ObjectCreatedEvent`
+: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/
+
+
+
+Subclass of xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-AbstractLifecycleEvent[`AbstractLifecycleEvent`], broadcast
+when an object is first instantiated using the
+xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-creation-api[`DomainObjectContainer`]'s
+`#newTransientInstance(...)` method.
+
+`ObjectCreatedEvent.Default` is the concrete implementation that is used.
+
+[NOTE]
+====
+In the future this may be generalized to allow arbitrary subclasses to be broadcast, see ISIS-803.
+====
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectLoadedEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectLoadedEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectLoadedEvent.adoc
new file mode 100644
index 0000000..7d65cf7
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectLoadedEvent.adoc
@@ -0,0 +1,17 @@
+[[_rgcms_classes_lifecycleevent_manpage-ObjectLoadedEvent]]
+= `ObjectLoadedEvent`
+: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/
+
+
+
+Subclass of xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-AbstractLifecycleEvent[`AbstractLifecycleEvent`], broadcast
+when an object is retrieved from the database.
+
+`ObjectLoadedEvent.Default` is the concrete implementation that is used.
+
+[NOTE]
+====
+In the future this may be generalized to allow arbitrary subclasses to be broadcast, see ISIS-803.
+====

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectPersistedEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectPersistedEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectPersistedEvent.adoc
new file mode 100644
index 0000000..95bd2e8
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectPersistedEvent.adoc
@@ -0,0 +1,19 @@
+[[_rgcms_classes_lifecycleevent_manpage-ObjectPersistedEvent]]
+= `ObjectPersistedEvent`
+: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/
+
+
+Subclass of xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-AbstractLifecycleEvent[`AbstractLifecycleEvent`], broadcast
+when an object is first saved (inserted) into the database using the
+xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
+`#persist(...)` method.
+
+
+`ObjectPersistedEvent.Default` is the concrete implementation that is used.
+
+[NOTE]
+====
+In the future this may be generalized to allow arbitrary subclasses to be broadcast, see ISIS-803.
+====

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectPersistingEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectPersistingEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectPersistingEvent.adoc
new file mode 100644
index 0000000..376bc25
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectPersistingEvent.adoc
@@ -0,0 +1,21 @@
+[[_rgcms_classes_lifecycleevent_manpage-ObjectPersistingEvent]]
+= `ObjectPersistingEvent`
+: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/
+
+
+Subclass of xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-AbstractLifecycleEvent[`AbstractLifecycleEvent`], broadcast
+when an object is about to be saved (inserted) into the database using the
+xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
+`#persist(...)` method.
+
+
+`ObjectPersistingEvent.Default` is the concrete implementation that is used.
+
+[NOTE]
+====
+In the future this may be generalized to allow arbitrary subclasses to be broadcast, see ISIS-803.
+====
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectRemovingEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectRemovingEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectRemovingEvent.adoc
new file mode 100644
index 0000000..0235513
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectRemovingEvent.adoc
@@ -0,0 +1,20 @@
+[[_rgcms_classes_lifecycleevent_manpage-ObjectRemovingEvent]]
+= `ObjectRemovingEvent`
+: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/
+
+
+Subclass of xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-AbstractLifecycleEvent[`AbstractLifecycleEvent`], broadcast
+when an object is about to be deleted from the database using the
+xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
+`#remove(...)` method.
+
+
+`ObjectRemovingEvent.Default` is the concrete implementation that is used.
+
+[NOTE]
+====
+In the future this may be generalized to allow arbitrary subclasses to be broadcast, see ISIS-803.
+====
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectUpdatedEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectUpdatedEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectUpdatedEvent.adoc
new file mode 100644
index 0000000..58695e5
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectUpdatedEvent.adoc
@@ -0,0 +1,21 @@
+[[_rgcms_classes_lifecycleevent_manpage-ObjectUpdatedEvent]]
+= `ObjectUpdatedEvent`
+: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/
+
+
+
+Subclass of xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-AbstractLifecycleEvent[`AbstractLifecycleEvent`], broadcast
+when an object has just been updated in the database.  This is done either explicitly when the current
+transaction is flushed using the
+xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
+`#flush(...)` method, else is done implicitly when the transaction commits at the end of the user request.
+
+`ObjectUpdatedEvent.Default` is the concrete implementation that is used.
+
+[NOTE]
+====
+In the future this may be generalized to allow arbitrary subclasses to be broadcast, see ISIS-803.
+====
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectUpdatingEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectUpdatingEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectUpdatingEvent.adoc
new file mode 100644
index 0000000..e78c649
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_lifecycleevent_manpage-ObjectUpdatingEvent.adoc
@@ -0,0 +1,22 @@
+[[_rgcms_classes_lifecycleevent_manpage-ObjectUpdatingEvent]]
+= `ObjectUpdatingEvent`
+: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/
+
+
+
+Subclass of xref:rgcms.adoc#_rgcms_classes_lifecycleevent_manpage-AbstractLifecycleEvent[`AbstractLifecycleEvent`], broadcast
+when an object is about to be updated in the database.  This is done either explicitly when the current
+transaction is flushed using the
+xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
+`#flush(...)` method, else is done implicitly when the transaction commits at the end of the user request.
+
+
+`ObjectUpdatingEvent.Default` is the concrete implementation that is used.
+
+[NOTE]
+====
+In the future this may be generalized to allow arbitrary subclasses to be broadcast, see ISIS-803.
+====
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles.adoc
new file mode 100644
index 0000000..6277ec5
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles.adoc
@@ -0,0 +1,18 @@
+[[_rgcms_classes_roles]]
+= Roles
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+The interfaces listed in this chapter are role interfaces; they define a contract for the framework
+ to interact with those domain objects that implement these interfaces.
+
+
+include::_rgcms_classes_roles_manpage-HoldsUpdatedAt.adoc[leveloffset=+1]
+include::_rgcms_classes_roles_manpage-HoldsUpdatedBy.adoc[leveloffset=+1]
+include::_rgcms_classes_roles_manpage-Timestampable.adoc[leveloffset=+1]
+include::_rgcms_classes_roles_manpage-Dto.adoc[leveloffset=+1]
+include::_rgcms_classes_roles_manpage-Persistable.adoc[leveloffset=+1]
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_manpage-Dto.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_manpage-Dto.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_manpage-Dto.adoc
new file mode 100644
index 0000000..b7e4790
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_manpage-Dto.adoc
@@ -0,0 +1,61 @@
+[[_rgcms_classes_mixins_Dto]]
+= `Dto` (`1.11.0-SNAPSHOT`)
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+The `Dto` role interface (`1.11.0-SNAPSHOT`) is intended to be implemented by JAXB-annotated view models, that is, annotated using
+xref:rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`].  It enables the ability to download the XML and
+XSD schema of those objects using two xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling_mixins[mixins],
+`Dto_downloadXml` and `Dto_downloadXsd`.
+
+The interface is just a marker interface (with no members), and is defined as:
+
+[source,java]
+----
+public interface Dto { }
+----
+
+The `Dto_downloadXml` mixin defines the following action:
+
+[source,java]
+----
+@Mixin
+public class Dto_downloadXml {
+    public Dto_downloadXml(final Dto dto) { ... }     // <1>
+    public Object downloadXml(final String fileName) { ... }   // <2>
+    ...
+}
+----
+<1> provided as an action to any class that (trivially) implements the `Dto` interface
+<2> actually this is '$$' in the code, a "special case" that means to use the derive the action name from the class name.
+
+This will return the XML text wrapped up in a xref:rgcms.adoc#_rgcms_classes_value-types_manpage-Clob[`Clob`].
+
+The `Dto_downloadXsd` mixin is similar:
+
+[source,java]
+----
+@Mixin
+public class Dto_downloadXsd {
+    public Dto_downloadXsd(final Dto dto) { ... }                                             // <1>
+    public Object downloadXsd(final String fileName, final IsisSchemes isisSchemas) { ... }   // <2>
+}
+----
+<1> provided as an action to any class that (trivially) implements the `Dto` interface
+<2> actually this is '$$' in the code, a "special case" that means to use the derive the action name from the class name.
+
+If the domain object's JAXB annotations reference only a single XSD schema then this will return that XML text as
+a xref:rgcms.adoc#_rgcms_classes_value-types_manpage-Clob[`Clob`] of that XSD.  If there are multiple XSD schemas referenced
+then the action will return a zip of those schemas, wrapped up in a
+xref:rgcms.adoc#_rgcms_classes_value-types_manpage-Blob[`Blob`].  The `IsisSchemas` parameter to the action can be used to
+optionally ignore the common xref:rgcms.adoc#_rgcms_schema[Apache Isis schemas] (useful if there is only one other XSD schema
+referenced by the DTO).
+
+
+
+== Related Services
+
+The `Dto_downloadXml` and `Dto_downloadXsd` delegate to the
+xref:rgsvc.adoc#_rgsvc-api_JaxbService[`JaxbService`] to actually generate the XML/XSD.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_manpage-HoldsUpdatedAt.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_manpage-HoldsUpdatedAt.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_manpage-HoldsUpdatedAt.adoc
new file mode 100644
index 0000000..d286c5d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_manpage-HoldsUpdatedAt.adoc
@@ -0,0 +1,44 @@
+[[_rgcms_classes_roles_manpage-HoldsUpdatedAt]]
+= `HoldsUpdatedAt`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+The `HoldsUpdatedAt` role interface allows the (framework-provided) `TimestampService` to update each object with
+the current timestamp whenever it is modified in a transaction.
+
+The interface is defined as:
+
+[source,java]
+----
+public interface HoldsUpdatedAt {
+    void setUpdatedAt(java.sql.Timestamp updatedAt);
+}
+----
+
+The current time is obtained from the xref:rgsvc.adoc#_rgsvc-api_ClockService[`ClockService`].
+
+Entities that implement this interface often also implement xref:rgcms.adoc#_rgcms_classes_roles_manpage-HoldsUpdatedBy[`HoldsUpdatedBy`] role interface; as a convenience the xref:rgcms.adoc#_rgcms_classes_roles_manpage-Timestampable[`Timestampable`] interface combines the two roles.
+
+
+
+== Alternative approaches
+
+An alternative way to maintain a timestamp is to use JDO's `@Version` annotation.  With this approach, it is the JDO/DataNucleus that maintains the version, rather than the framework's `TimestampService`.
+
+For example:
+
+[source,java]
+----
+@javax.jdo.annotations.Version(
+        strategy=VersionStrategy.DATE_TIME,
+        column="version")
+public class Customer {
+    ...
+    public java.sql.Timestamp getVersionSequence() {
+        return (java.sql.Timestamp) JDOHelper.getVersion(this);
+    }
+}
+----
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_manpage-HoldsUpdatedBy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_manpage-HoldsUpdatedBy.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_manpage-HoldsUpdatedBy.adoc
new file mode 100644
index 0000000..9552043
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_manpage-HoldsUpdatedBy.adoc
@@ -0,0 +1,19 @@
+[[_rgcms_classes_roles_manpage-HoldsUpdatedBy]]
+= `HoldsUpdatedBy`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+The `HoldsUpdatedBy` role interface ...
+
+[source,java]
+----
+public interface HoldsUpdatedBy {
+    void setUpdatedBy(String updatedBy);
+}
+----
+
+Entities that implement this interface often also implement xref:rgcms.adoc#_rgcms_classes_roles_manpage-HoldsUpdatedAt[`HoldsUpdatedAt`] role interface; as a convenience the xref:rgcms.adoc#_rgcms_classes_roles_manpage-Timestampable[`Timestampable`] interface combines the two roles.
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_manpage-Persistable.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_manpage-Persistable.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_manpage-Persistable.adoc
new file mode 100644
index 0000000..757cade
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_manpage-Persistable.adoc
@@ -0,0 +1,34 @@
+[[_rgcms_classes_mixins_Persistable]]
+= `Persistable` (`1.11.0-SNAPSHOT`)
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+All domain entities automatically implement the DataNucleus `Persistable` role interface as a result of the enhancer
+process (the fully qualified class name is `org.datanucleus.enhancement.Persistable`).  So as a developer you do not
+need to write any code for this role interface.
+
+Nevertheless, the `Persistable_downloadJdoMetadata` mixin (`1.11.0-SNAPSHOT`) provides the ability to download the
+JDO link:http://www.datanucleus.org/products/datanucleus/jdo/metadata_xml.html[class metadata in XML] form.  The mixin
+defines the following action:
+
+[source,java]
+----
+@Mixin
+public class Persistable_downloadJdoMetadata {
+    public Persistable_downloadJdoMetadata(final Persistable persistable) { ... }   // <1>
+    public Object downloadJdoMetadata(final String fileName) { ... }                // <2>
+    ...
+}
+----
+<1> provided as an action to any domain entity
+<2> actually this is '$$' in the code, a "special case" that means to use the derive the action name from the class name.
+
+This will return the XML text wrapped up in a xref:rgcms.adoc#_rgcms_classes_value-types_manpage-Clob[`Clob`].
+
+
+== Related Services
+
+The mixin delegates to the xref:rgsvc.adoc#_rgsvc-api_IsisJdoSupport[`IsisJdoSupport`] service to obtain
+a reference to the JDO `PersistenceManagerFactory`.

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_manpage-Timestampable.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_manpage-Timestampable.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_manpage-Timestampable.adoc
new file mode 100644
index 0000000..a69d213
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_roles_manpage-Timestampable.adoc
@@ -0,0 +1,23 @@
+[[_rgcms_classes_roles_manpage-Timestampable]]
+= `Timestampable`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+The `Timestampable` role interface is a convenience that combines the xref:rgcms.adoc#_rgcms_classes_roles_manpage-HoldsUpdatedAt[`HoldsUpdatedAt`] and xref:rgcms.adoc#_rgcms_classes_roles_manpage-HoldsUpdatedBy[`HoldsUpdatedBy`] interfaces.  It is defined as:
+
+[source,java]
+----
+public interface Timestampable
+    extends HoldsUpdatedAt, HoldsUpdatedBy {
+}
+----
+
+The interface no additional methods of its own.
+
+
+
+== Alternatives
+
+An alternative way to maintain a timestamp is to use JDO's `@Version` annotation.  With this approach, it is the JDO/DataNucleus that maintains the version, rather than the framework's `TimestampService`.  See xref:rgcms.adoc#_rgcms_classes_roles_manpage-HoldsUpdatedBy[`HoldsUpdatedBy`] for further details.

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_spec.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_spec.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_spec.adoc
new file mode 100644
index 0000000..01b5745
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_spec.adoc
@@ -0,0 +1,108 @@
+[[_rgcms_classes_spec]]
+= Specification pattern
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+The interfaces and classes listed in this chapter provide support for the  `Specification` pattern, as described in Eric Evans' book _Domain Driven Design_, p224.
+
+Apache Isis will automatically apply such specifications as validation rules on properties (as per xref:rgant.adoc#_rgant-Property_mustSatisfy[`@Property#mustSatisfy()`]) and on action parameters (as per xref:rgant.adoc#_rgant-Parameter_mustSatisfy[`@Parameter#mustSatisfy()`]).
+
+
+
+[_rgcms_classes_spec-Specification]
+== `Specification`
+
+The heart of the support for this pattern is the `Specification` interface:
+
+[source,java]
+----
+public interface Specification {
+    public String satisfies(Object obj);  // <1>
+}
+----
+<1> if returns `null`, then the constraint is satisfies; otherwise returns the reason why the constraint has not been satisfied.
+
+
+For example:
+
+[source,java]
+----
+public class StartWithCapitalLetterSpecification implements Specification {
+    public String satisfies(Object proposedObj) {
+        String proposed = (String)proposedObj;               // <1>
+        return "".equals(proposed)
+            ? "Empty string"
+            : !Character.isUpperCase(proposed.charAt(0))
+                ? "Does not start with a capital letter"
+                : null;
+    }
+}
+public class Customer {
+    @Property(mustSatisfy=StartWithCapitalLetterSpecification.class)
+    public String getFirstName() { ... }
+    ...
+}
+----
+<1> this ugly cast can be avoided using some of the other classes available; see below.
+
+
+
+[_rgcms_classes_spec-Specification2]
+== `Specification2`
+
+The `Specification2` interface extends the `Specification` API to add support for i18n.  This is done by defining an additional method that returns a xref:rgcms.adoc#_rgcms_classes_i18n_manpage-TranslatableString[translatable string]:
+
+[source,java]
+----
+public interface Specification2 extends Specification {
+    public TranslatableString satisfiesTranslatable(Object obj);  // <1>
+}
+----
+<1> if returns `null`, then the constraint is satisfies; otherwise returns the reason why the constraint has not been satisfied.
+
+
+Note that if implementing `Specification2` then there is no need to also provide an implementation of the inherited `satisfies(Object)` method; this will never be called by the framework for `Specification2` instances.
+
+
+
+
+[_rgcms_classes_spec-adapter_classes]
+== Adapter classes
+
+The `AbstractSpecification` and `AbstractSpecification2` adapter classes provide a partial implementation of the respective interfaces, providing type-safety.  (Their design is modelled on the `TypesafeMatcher` class within link:http://hamcrest.org/JavaHamcrest/[Hamcrest]).
+
+For example:
+
+[source,java]
+----
+public class StartWithCapitalLetterSpecification extends AbstractSpecification<String> {
+    public String satisfiesSafely(String proposed) {
+        return "".equals(proposed)
+            ? "Empty string"
+            : !Character.isUpperCase(proposed.charAt(0))
+                ? "Does not start with a capital letter"
+                : null;
+    }
+}
+public class Customer {
+    @Property(mustSatisfy=StartWithCapitalLetterSpecification.class)
+    public String getFirstName() { ... }
+    ...
+}
+----
+
+The `AbstractSpecification2` class is almost identical; its type-safe method is `satisfiesTranslatableSafely(T)` instead.
+
+
+[_rgcms_classes_spec-combining_specifications]
+== Combining specifications
+
+There are also adapter classes that can be inherited from to combine specifications:
+
+* `SpecificationAnd` - all provided specifications' constraints must be met
+* `SpecificationOr` - at least one provided specifications' constraints must be met
+* `SpecificationNot` - its constraints are met if-and-only-if the provided specification's constraint was _not_ met.
+
+Note that these adapter classes inherit `Specification` but do not inherit `Specification2`; in other words they do not support i18n.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super.adoc
new file mode 100644
index 0000000..71ea4a4
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super.adoc
@@ -0,0 +1,105 @@
+[[_rgcms_classes_super]]
+= Superclasses
+: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 section catalogues the various convenience (non event) superclasses defined by Apache Isis.  These are listed in the table below.
+
+
+.Convenience Superclasses
+[cols="2,4a,1,1", options="header"]
+|===
+
+|API
+|Maven Module +
+Impl'n (g: a:)
+|Implementation
+|Notes
+
+
+|xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractContainedObject[`o.a.i.applib.` +
+`AbstractContainedObject`]
+|``o.a.i.core`` +
+``isis-core-applib``
+|(abstract class)
+|
+
+
+|xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractDomainObject[`o.a.i.applib.` +
+`AbstractDomainObject`]
+|``o.a.i.core`` +
+``isis-core-applib``
+|(abstract class)
+|
+
+
+|xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractFactoryAndRepository[`o.a.i.applib.` +
+`AbstractFactoryAndRepository`]
+|``o.a.i.core`` +
+``isis-core-applib``
+|(abstract class)
+|
+
+
+|xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractService[`o.a.i.applib.` +
+`AbstractService`]
+|``o.a.i.core`` +
+``isis-core-applib``
+|(abstract class)
+|
+
+
+|xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractSubscriber[`o.a.i.applib.` +
+`AbstractSubscriber`]
+|``o.a.i.core`` +
+``isis-core-applib``
+|(abstract class)
+|
+
+
+|xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractViewModel[`o.a.i.applib.` +
+`AbstractViewModel`]
+|``o.a.i.core`` +
+``isis-core-applib``
+|(abstract class)
+|
+
+
+|xref:rgcms.adoc#_rgcms_classes_super_manpage-FixtureScript[`o.a.i.applib.` +
+`fixturescript` +
+`FixtureScript`]
+|``o.a.i.core`` +
+``isis-core-applib``
+|(abstract class)
+|
+
+
+|xref:rgcms.adoc#_rgcms_classes_super_manpage-FixtureScripts[`o.a.i.applib.` +
+`fixturescripts` +
+`FixtureScripts`]
+|``o.a.i.core`` +
+``isis-core-applib``
+|(abstract class). +
+`FixtureScriptsDefault` is a default implementation that is used when the alternative xref:rgsvc.adoc#_rgsvc-api_FixtureScriptsSpecificationProvider[`FixtureScriptsSpecificationProvider`] is provided
+  (and no other implementation of `FixtureScripts` was found).
+|depends on: +
+`ClassDiscoveryService`
+
+
+|===
+
+
+
+
+include::_rgcms_classes_super_manpage-AbstractContainedObject.adoc[leveloffset=+1]
+include::_rgcms_classes_super_manpage-AbstractDomainObject.adoc[leveloffset=+1]
+include::_rgcms_classes_super_manpage-AbstractFactoryAndRepository.adoc[leveloffset=+1]
+include::_rgcms_classes_super_manpage-AbstractService.adoc[leveloffset=+1]
+include::_rgcms_classes_super_manpage-AbstractSubscriber.adoc[leveloffset=+1]
+include::_rgcms_classes_super_manpage-AbstractViewModel.adoc[leveloffset=+1]
+include::_rgcms_classes_super_manpage-FixtureScript.adoc[leveloffset=+1]
+include::_rgcms_classes_super_manpage-FixtureScripts.adoc[leveloffset=+1]
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractContainedObject.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractContainedObject.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractContainedObject.adoc
new file mode 100644
index 0000000..df8aaf9
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractContainedObject.adoc
@@ -0,0 +1,32 @@
+[[_rgcms_classes_super_manpage-AbstractContainedObject]]
+= `AbstractContainedObject`
+: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 class is a convenience superclass for domain objects and services, providing general purpose methods for interacting with the framework.  These include:
+
+* `allMatches(Query)` - search for all objects matching the specified `Query`. +
++
++ Note that this, and other similar methods (eg `firstMatch(...)`, `uniqueMatch(...)`) will automatically flush the
+current transactoin.
+
+* `newTransientInstance(Class)` - to create a new instance of an object, with any services injected into it
+
+* `persistIfNotAlready(Object)` - to persist an object +
++
+In fact, the object is queued up to be persisted, and is only actually persisted either when the transaction commits, or
+when the transaction is flushed (typically when a query is performed).
+
+* `warnUser(String)` - generate a warning to the user
+
+* `getContainer()` - which returns the `DomainObjectContainer`
+
+Each of these methods simply delegates to an equivalent method in xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer[`DomainObjectContainer`].
+
+[TIP]
+====
+In practice we find that there's little to gain from subclassing; it's easier/less obscure to simply inject xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer[`DomainObjectContainer`] into a simple pojo class.
+====
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractDomainObject.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractDomainObject.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractDomainObject.adoc
new file mode 100644
index 0000000..064b3ed
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractDomainObject.adoc
@@ -0,0 +1,14 @@
+[[_rgcms_classes_super_manpage-AbstractDomainObject]]
+= `AbstractDomainObject`
+: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 class extends xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractContainedObject[`AbstractContainedObject`], adding
+in convenience methods for managing the persistence lifecycle of the object instance.
+
+Each of these methods, eg `isPersistent(...)`, delegates to an equivalent method in
+xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer[`DomainObjectContainer`].
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractFactoryAndRepository.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractFactoryAndRepository.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractFactoryAndRepository.adoc
new file mode 100644
index 0000000..3403756
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractFactoryAndRepository.adoc
@@ -0,0 +1,15 @@
+[[_rgcms_classes_super_manpage-AbstractFactoryAndRepository]]
+= `AbstractFactoryAndRepository`
+: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 class extends xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractContainedObject[`AbstractContainedObject`].  Its
+intent was to be a convenience subclass for services acting as either a repository or a factory, however note that
+ all of the methods that it defines are now deprecated.
+
+Instead, indicate that a service is repository using the xref:rgant.adoc#_rgant-DomainService_repositoryFor[`@DomainService#repositoryFor()`] attribute.
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractService.adoc
new file mode 100644
index 0000000..fa9207a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractService.adoc
@@ -0,0 +1,10 @@
+[[_rgcms_classes_super_manpage-AbstractService]]
+= `AbstractService`
+: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 class extends xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractContainedObject[`AbstractContainedObject`], adding
+in an implementation of `getId()` based upon the classes name.
+
+In practice there is little to gain from subclassing; simply inject xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer[`DomainObjectContainer`] for broadly equivalent functionality.

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractSubscriber.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractSubscriber.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractSubscriber.adoc
new file mode 100644
index 0000000..4a715e4
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractSubscriber.adoc
@@ -0,0 +1,18 @@
+[[_rgcms_classes_super_manpage-AbstractSubscriber]]
+= `AbstractSubscriber`
+: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 convenience superclass for creating subscriber domain services on the xref:rgsvc.adoc#_rgsvc-api_EventBusService[`EventBusService`].  It uses xref:rgant.adoc#_rgant-PostConstruct[`@PostConstruct`] and
+xref:rgant.adoc#_rgant-PreDestroy[`@PreDestroy`] callbacks to automatically register/unregister itself
+with the `EventBusService`.
+
+It's important that subscribers register before any domain services that might emit events on the
+xref:rgsvc.adoc#_rgsvc-api_EventBusService[`EventBusService`].  For example, the (non-ASF) http://github.com/isisaddons/isis-module-security[Isis addons' security] module provides a domain service that automatically
+seeds certain domain entities; these will generate xref:rgcms.adoc#_rgcms_classes_lifecycleevent[lifecycle events] and so
+any subscribers must be registered before such seed services.  The easiest way to do this is to use the
+xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] attribute.
+
+As a convenience, (as of `1.11.0-SNAPSHOT`) the `AbstractSubscriber` specifies this attribute.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractViewModel.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractViewModel.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractViewModel.adoc
new file mode 100644
index 0000000..b77460d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-AbstractViewModel.adoc
@@ -0,0 +1,15 @@
+[[_rgcms_classes_super_manpage-AbstractViewModel]]
+= `AbstractViewModel`
+: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 class extends xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractContainedObject[`AbstractContainedObject`], also
+implementing the xref:rgcms.adoc#_rgcms_classes_super_manpage-ViewModel[`ViewModel`] interface.  In and of itself it provides no new behaviour.
+
+[TIP]
+====
+As an alternative, consider simply annotating the view model class with {@link org.apache.isis.applib.annotation.ViewModel}.
+====
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-FixtureScript.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-FixtureScript.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-FixtureScript.adoc
new file mode 100644
index 0000000..d4cf98a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-FixtureScript.adoc
@@ -0,0 +1,21 @@
+[[_rgcms_classes_super_manpage-FixtureScript]]
+= `FixtureScript`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+The `FixtureScript` class is an abstract class defining an API to set up data within the object store, either for integration tests or while demoing/prototyping.
+
+The primary method that subclasses must implement is:
+
+[source,java]
+----
+protected abstract void execute(final ExecutionContext executionContext);
+----
+
+In this method the fixture script can in theory do anything, but in practice it is recommended that it uses injected
+domain services to set up data.  The provided `ExecutionContext` is used to invoke child fixture scripts, and alsocan be used to store references to any created objects (so that the calling test can access these objects/so that they are rendered in the view model).
+
+See the see the xref:ugtst.adoc#_ugtst_fixture-scripts[user guide's testing chapter] for further discussion on the use of fixture scripts, in particular xref:ugtst.adoc#_ugtst_fixture-scripts_api-and-usage[fixture scripts' API and usage].
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-FixtureScripts.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-FixtureScripts.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-FixtureScripts.adoc
new file mode 100644
index 0000000..a562aea
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_super_manpage-FixtureScripts.adoc
@@ -0,0 +1,12 @@
+[[_rgcms_classes_super_manpage-FixtureScripts]]
+= `FixtureScripts`
+: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 abstract class is intended to allow a domain service that can execute xref:rgcms.adoc#_rgcms_classes_super_manpage-FixtureScript[`FixtureScript`]s to be easily written.
+
+However, it has now been deprecated; instead we recommend that the xref:rgsvc.adoc#_rgsvc-spi_FixtureScriptsSpecificationProvider[`FixtureScriptsSpecificationProvider`] service is
+implemented instead.  The framework will then automatically use xref:rgsvc.adoc#_rgsvc-api_FixtureScriptsDefault[`FixtureScriptsDefault`] as a fallback implementation of this class.
+
+See the see the xref:ugtst.adoc#_ugtst_fixture-scripts[user guide's testing chapter] for further discussion on the use of fixture scripts, in particular xref:ugtst.adoc#_ugtst_fixture-scripts_api-and-usage[fixture scripts' API and usage].

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_uievent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_uievent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_uievent.adoc
new file mode 100644
index 0000000..91ade0f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_uievent.adoc
@@ -0,0 +1,62 @@
+[[_rgcms_classes_uievent]]
+= UI Event Classes (`1.11.0-SNAPSHOT`)
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+This section catalogues the various UI event classes defined by Apache Isis.
+
+These events are broadcast on the xref:rgsvc.adoc#_rgsvc-api_EventBusService[`EventBusService`].  The domain
+events are broadcast as a result of being specified in the xref:rgant.adoc#_rgant-DomainObjectLayout_titleUiEvent[`@DomainObjectLayout#titleUiEvent()`],  xref:rgant.adoc#_rgant-DomainObjectLayout_iconUiEvent[`@DomainObjectLayout#iconUiEvent()`] or xref:rgant.adoc#_rgant-DomainObjectLayout_cssClassUiEvent[`@DomainObjectLayout#cssClassUiEvent()`] attributes.
+
+They are listed in the table below.
+
+.UI Event Classes
+[cols="2,4a,1,1", options="header"]
+|===
+
+|API
+|Maven Module +
+Impl'n (g: a:)
+|Implementation
+|Notes
+
+
+|xref:rgcms.adoc#_rgcms_classes_uievent_manpage-TitleUiEvent[`o.a.i.applib.` +
+`TitleUiEvent`]
+|``o.a.i.core`` +
+``services.eventbus`` +
+``isis-core-applib``
+|(abstract class). +
+`TitleUiEvent.Default` is the concrete implementation used if no `@DomainObjectLayout#titleUiEvent` attribute is specified
+|Broadcast whenever there is a requirement to obtain a title for a domain object.  Note that if the domain object defines its own xref:rgcms.adoc#_rgcms_methods_reserved_manpage-title[`title()`] supporting method, or has xref:rgant.adoc#_rgant-Title[`@Title`] annotation(s) on its properties, then these will take precedence.
+
+|xref:rgcms.adoc#_rgcms_classes_uievent_manpage-IconUiEvent[`o.a.i.applib.` +
+`IconUiEvent`]
+|``o.a.i.core`` +
+``services.eventbus`` +
+``isis-core-applib``
+|(abstract class). +
+`IconUiEvent.Default` is the concrete implementation used if no `@DomainObjectLayout#iconUiEvent` attribute is specified
+|Broadcast whenever there is a requirement to obtain an icon (or rather, the name of an icon) for a domain object.  Note that if the domain object defines its own xref:rgcms.adoc#_rgcms_methods_reserved_manpage-iconName[`iconName()`] supporting method, or if it has the xref:rgant.adoc#_rgant-DomainObjectLayout#cssClassFa[`@DomainObjectLayout#cssClassFa()`] attribute, then these will take precedence.
+
+|xref:rgcms.adoc#_rgcms_classes_uievent_manpage-CssClassUiEvent[`o.a.i.applib.` +
+`CssClassUiEvent`]
+|``o.a.i.core`` +
+``services.eventbus`` +
+``isis-core-applib``
+|(abstract class). +
+`CssClassUiEvent.Default` is the concrete implementation used if no `@DomainObjectLayout#cssClassUiEvent` attribute is specified
+|Broadcast whenever there is a requirement to obtain a CSS class hint for a domain object.  Note that if the domain object defines its own xref:rgcms.adoc#_rgcms_methods_reserved_manpage-cssClass[`cssClass()`] supporting method then this
+will take precedence.
+
+|===
+
+
+
+
+include::_rgcms_classes_uievent_manpage-TitleUiEvent.adoc[leveloffset=+1]
+include::_rgcms_classes_uievent_manpage-IconUiEvent.adoc[leveloffset=+1]
+include::_rgcms_classes_uievent_manpage-CssClassUiEvent.adoc[leveloffset=+1]
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_uievent_manpage-CssClassUiEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_uievent_manpage-CssClassUiEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_uievent_manpage-CssClassUiEvent.adoc
new file mode 100644
index 0000000..30b8f5b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_uievent_manpage-CssClassUiEvent.adoc
@@ -0,0 +1,22 @@
+[[_rgcms_classes_uievent_manpage-CssClassUiEvent]]
+= `CssClassUiEvent`  (`1.11.0-SNAPSHOT`)
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+This event class represents a request to obtain the a CSS class hint of a domain object.  The class has a number of
+responsibilities:
+
+* capture the target object being interacted with
+
+* capture the CSS class, if any, as specified to one of the subscribers
+
+The class itself is instantiated automatically by the framework whenever interacting with a rendered object's action.
+
+
+[NOTE]
+====
+if the domain object defines its own xref:rgcms.adoc#_rgcms_methods_reserved_manpage-cssClass[`cssClass()`] supporting
+method then this will take precedence.
+====

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_uievent_manpage-IconUiEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_uievent_manpage-IconUiEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_uievent_manpage-IconUiEvent.adoc
new file mode 100644
index 0000000..20fdbbc
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_uievent_manpage-IconUiEvent.adoc
@@ -0,0 +1,23 @@
+[[_rgcms_classes_uievent_manpage-IconUiEvent]]
+= `TitleUiEvent` (`1.11.0-SNAPSHOT`)
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+This event class represents a request to obtain the icon (or rather, name of icon) of a domain object.  The class has a number of responsibilities:
+
+* capture the target object being interacted with
+
+* capture the icon (name), if any, as specified to one of the subscribers
+
+The class itself is instantiated automatically by the framework whenever interacting with a rendered object's action.
+
+
+[NOTE]
+====
+If the domain object defines its own xref:rgcms.adoc#_rgcms_methods_reserved_manpage-iconName[`iconName()`] supporting method,
+or if it has the
+xref:rgant.adoc#_rgant-DomainObjectLayout#cssClassFa[`@DomainObjectLayout#cssClassFa()`] attribute, then
+these will take precedence.
+====

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_uievent_manpage-TitleUiEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_uievent_manpage-TitleUiEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_uievent_manpage-TitleUiEvent.adoc
new file mode 100644
index 0000000..8b76b05
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_uievent_manpage-TitleUiEvent.adoc
@@ -0,0 +1,22 @@
+[[_rgcms_classes_uievent_manpage-TitleUiEvent]]
+= `TitleUiEvent`  (`1.11.0-SNAPSHOT`)
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+This event class represents a request to obtain the title of a domain object.  The class has a number of responsibilities:
+
+* capture the target object being interacted with
+
+* capture the title, if any, as specified to one of the subscribers
+
+The class itself is instantiated automatically by the framework whenever interacting with a rendered object's action.
+
+
+[NOTE]
+====
+If the domain object defines its own xref:rgcms.adoc#_rgcms_methods_reserved_manpage-title[`title()`] supporting method, or
+has xref:rgant.adoc#_rgant-Title[`@Title`] annotation(s) on its properties, then these will take
+precedence.
+====

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility.adoc
new file mode 100644
index 0000000..fd35ffc
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility.adoc
@@ -0,0 +1,16 @@
+[[_rgcms_classes_utility]]
+= Applib Utility Classes
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+The `org.apache.isis.applib.util` package has a number of simple utility
+classes designed to simplify the coding of some common tasks.
+
+
+include::_rgcms_classes_utility_manpage-Enums.adoc[leveloffset=+1]
+include::_rgcms_classes_utility_manpage-ObjectContracts.adoc[leveloffset=+1]
+include::_rgcms_classes_utility_manpage-Reasons.adoc[leveloffset=+1]
+include::_rgcms_classes_utility_manpage-TitleBuffer.adoc[leveloffset=+1]
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_manpage-Enums.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_manpage-Enums.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_manpage-Enums.adoc
new file mode 100644
index 0000000..064b423
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_utility_manpage-Enums.adoc
@@ -0,0 +1,8 @@
+[[_rgcms_classes_utility_manpage-Enums]]
+= `Enums`
+: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/
+
+
+NOTE: TODO


[47/52] [abbrv] isis git commit: ISIS-1237: factored out Generation context class to keep track of references vs definitions; factored out Tagger; factored out ClassExcluder.

Posted by mg...@apache.org.
ISIS-1237: factored out Generation context class to keep track of references vs definitions; factored out Tagger; factored out ClassExcluder.


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/2efbf48f
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/2efbf48f
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/2efbf48f

Branch: refs/heads/ISIS-1224-select2-v4
Commit: 2efbf48f5ea8a4d65e6a80361c8977d4e7a28ac1
Parents: c64caa1
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Fri Dec 11 15:53:26 2015 +0000
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Fri Dec 11 15:53:26 2015 +0000

----------------------------------------------------------------------
 .../swagger/internal/ClassExcluder.java         |  52 ++
 .../services/swagger/internal/Generation.java   | 831 +++++++++++++++++++
 .../swagger/internal/SwaggerSpecGenerator.java  | 770 +----------------
 .../services/swagger/internal/Tagger.java       |  61 ++
 .../services/swagger/internal/Util.java         |   6 +-
 .../swagger/internal/ValuePropertyFactory.java  |   2 +
 .../swagger/internal/GenerationTest.java        |  48 ++
 .../internal/SwaggerSpecGeneratorTest.java      |  69 --
 .../services/swagger/internal/TaggerTest.java   |  69 ++
 9 files changed, 1071 insertions(+), 837 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/2efbf48f/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/ClassExcluder.java
----------------------------------------------------------------------
diff --git a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/ClassExcluder.java b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/ClassExcluder.java
new file mode 100644
index 0000000..6ae8deb
--- /dev/null
+++ b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/ClassExcluder.java
@@ -0,0 +1,52 @@
+/*
+ *  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.
+ */
+package org.apache.isis.core.metamodel.services.swagger.internal;
+
+import java.util.List;
+
+import org.apache.isis.applib.fixturescripts.FixtureResult;
+import org.apache.isis.applib.fixturescripts.FixtureScript;
+import org.apache.isis.core.metamodel.spec.ObjectSpecification;
+import org.apache.isis.core.metamodel.spec.feature.ObjectAction;
+
+public class ClassExcluder {
+
+    protected boolean exclude(final ObjectSpecification objectSpec) {
+        if(objectSpec == null) {
+            return false;
+        }
+        Class<?> correspondingClass = objectSpec.getCorrespondingClass();
+        return correspondingClass == FixtureResult.class || FixtureScript.class.isAssignableFrom(correspondingClass) || correspondingClass == FixtureScript.ExecutionContext.class;
+    }
+
+    public boolean exclude(final ObjectAction objectAction) {
+        final ObjectSpecification returnType = objectAction.getReturnType();
+        if(exclude(returnType)) {
+            return true;
+        }
+
+        final List<ObjectSpecification> parameterTypes = objectAction.getParameterTypes();
+        for (ObjectSpecification parameterType : parameterTypes) {
+            if(exclude(parameterType)) {
+                return true;
+            }
+        }
+        return false;
+    }
+}

http://git-wip-us.apache.org/repos/asf/isis/blob/2efbf48f/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/Generation.java
----------------------------------------------------------------------
diff --git a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/Generation.java b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/Generation.java
new file mode 100644
index 0000000..1cce186
--- /dev/null
+++ b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/Generation.java
@@ -0,0 +1,831 @@
+/*
+ *  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.
+ */
+package org.apache.isis.core.metamodel.services.swagger.internal;
+
+import java.util.Arrays;
+import java.util.Collection;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Set;
+
+import com.google.common.base.Strings;
+import com.google.common.collect.Lists;
+import com.google.common.collect.Sets;
+
+import org.apache.isis.applib.annotation.ActionSemantics;
+import org.apache.isis.applib.annotation.NatureOfService;
+import org.apache.isis.applib.services.swagger.SwaggerService;
+import org.apache.isis.core.commons.factory.InstanceUtil;
+import org.apache.isis.core.metamodel.facets.actcoll.typeof.TypeOfFacet;
+import org.apache.isis.core.metamodel.facets.object.domainservice.DomainServiceFacet;
+import org.apache.isis.core.metamodel.facets.object.mixin.MixinFacet;
+import org.apache.isis.core.metamodel.facets.object.objectspecid.ObjectSpecIdFacet;
+import org.apache.isis.core.metamodel.services.ServiceUtil;
+import org.apache.isis.core.metamodel.spec.ObjectSpecification;
+import org.apache.isis.core.metamodel.spec.SpecificationLoader;
+import org.apache.isis.core.metamodel.spec.feature.ObjectAction;
+import org.apache.isis.core.metamodel.spec.feature.ObjectActionParameter;
+import org.apache.isis.core.metamodel.spec.feature.OneToManyAssociation;
+import org.apache.isis.core.metamodel.spec.feature.OneToOneAssociation;
+
+import io.swagger.models.Info;
+import io.swagger.models.ModelImpl;
+import io.swagger.models.Operation;
+import io.swagger.models.Path;
+import io.swagger.models.Response;
+import io.swagger.models.Swagger;
+import io.swagger.models.parameters.BodyParameter;
+import io.swagger.models.parameters.PathParameter;
+import io.swagger.models.parameters.QueryParameter;
+import io.swagger.models.properties.ArrayProperty;
+import io.swagger.models.properties.MapProperty;
+import io.swagger.models.properties.ObjectProperty;
+import io.swagger.models.properties.Property;
+import io.swagger.models.properties.RefProperty;
+import io.swagger.models.properties.StringProperty;
+
+class Generation {
+
+    private final String basePath;
+    private final SwaggerService.Visibility visibility;
+    private final SpecificationLoader specificationLoader;
+
+    private final ValuePropertyFactory valuePropertyFactory;
+    private final Tagger tagger;
+    private final ClassExcluder classExcluder;
+
+    private final Set<String> references = Sets.newLinkedHashSet();
+    private final Set<String> definitions = Sets.newLinkedHashSet();
+    private Swagger swagger;
+
+    public Generation(
+            final String basePath,
+            final SwaggerService.Visibility visibility,
+            final SpecificationLoader specificationLoader) {
+        this.basePath = basePath;
+        this.visibility = visibility;
+        this.specificationLoader = specificationLoader;
+
+        this.valuePropertyFactory = newValuePropertyFactory();
+        this.tagger = newTagger();
+        this.classExcluder = newClassExcluder();
+    }
+
+    protected ValuePropertyFactory newValuePropertyFactory() {
+        return new ValuePropertyFactory();
+    }
+
+    protected ClassExcluder newClassExcluder() {
+        return new ClassExcluder();
+    }
+
+    protected Tagger newTagger() {
+        return new Tagger();
+    }
+
+    Swagger generate() {
+        this.swagger = new Swagger();
+
+        swagger.basePath(basePath);
+        swagger.info(new Info()
+                .version("0.0.0") // TODO: provide some way of passing the name, version etc (some sort of SPI service?)
+                .title(visibility.name() + " API")
+        );
+
+
+        appendRestfulObjectsSupportingPathsAndDefinitions();
+        appendLinkModelDefinition();
+
+        appendServicePathsAndDefinitions();
+        appendObjectPathsAndDefinitions();
+
+        appendDefinitionsForOrphanedReferences();
+
+        return swagger;
+    }
+
+    void appendServicePathsAndDefinitions() {
+        // take copy to avoid concurrent modification exception
+        final Collection<ObjectSpecification> allSpecs = Lists.newArrayList(specificationLoader.allSpecifications());
+        for (final ObjectSpecification serviceSpec :  allSpecs) {
+
+            final DomainServiceFacet domainServiceFacet = serviceSpec.getFacet(DomainServiceFacet.class);
+            if (domainServiceFacet == null) {
+                continue;
+            }
+            if (visibility.isPublic() &&
+                    domainServiceFacet.getNatureOfService() != NatureOfService.VIEW_REST_ONLY) {
+                continue;
+            }
+            if (domainServiceFacet.getNatureOfService() != NatureOfService.VIEW_MENU_ONLY &&
+                    domainServiceFacet.getNatureOfService() != NatureOfService.VIEW) {
+                continue;
+            }
+
+            final List<ObjectAction> serviceActions = Util.actionsOf(serviceSpec, visibility, classExcluder);
+            if(serviceActions.isEmpty()) {
+                continue;
+            }
+            appendServicePath(serviceSpec);
+
+            for (final ObjectAction serviceAction : serviceActions) {
+                appendServiceActionInvokePath(serviceSpec, serviceAction);
+            }
+        }
+    }
+
+    void appendObjectPathsAndDefinitions() {
+        // take copy to avoid concurrent modification exception
+        final Collection<ObjectSpecification> allSpecs = Lists.newArrayList(specificationLoader.allSpecifications());
+        for (final ObjectSpecification objectSpec : allSpecs) {
+
+            final DomainServiceFacet domainServiceFacet = objectSpec.getFacet(DomainServiceFacet.class);
+            if (domainServiceFacet != null) {
+                continue;
+            }
+            final MixinFacet mixinFacet = objectSpec.getFacet(MixinFacet.class);
+            if (mixinFacet != null) {
+                continue;
+            }
+            if(visibility.isPublic() && !Util.isVisibleForPublic(objectSpec)) {
+                continue;
+            }
+            if(objectSpec.isAbstract()) {
+                continue;
+            }
+            if(objectSpec.isValue()) {
+                continue;
+            }
+            // special cases
+            if(classExcluder.exclude(objectSpec)) {
+                continue;
+            }
+
+            final List<OneToOneAssociation> objectProperties = Util.propertiesOf(objectSpec, visibility);
+            final List<OneToManyAssociation> objectCollections = Util.collectionsOf(objectSpec, visibility);
+            final List<ObjectAction> objectActions = Util.actionsOf(objectSpec, visibility, classExcluder);
+
+            if(objectProperties.isEmpty() && objectCollections.isEmpty()) {
+                continue;
+            }
+            final ModelImpl isisModel = appendObjectPathAndModelDefinitions(objectSpec);
+            updateObjectModel(isisModel, objectSpec, objectProperties, objectCollections);
+
+            for (final OneToManyAssociation objectCollection : objectCollections) {
+                appendCollectionTo(objectSpec, objectCollection);
+            }
+
+            for (final ObjectAction objectAction : objectActions) {
+                appendObjectActionInvokePath(objectSpec, objectAction);
+            }
+        }
+    }
+
+    void appendRestfulObjectsSupportingPathsAndDefinitions() {
+
+        final String tag = "> restful objects supporting resources";
+
+        swagger.path("/",
+                new Path()
+                        .get(new Operation()
+                                .tag(tag)
+                                .description(Util.roSpec("5.1"))
+                                .produces("application/json")
+                                .produces("application/json;profile=urn:org.restfulobjects:repr-types/home-page")
+                                .response(200,
+                                        newResponse(Caching.NON_EXPIRING)
+                                                .description("OK")
+                                                .schema(newRefProperty("RestfulObjectsSupportingHomePageRepr"))
+                                )));
+        addDefinition("RestfulObjectsSupportingHomePageRepr", newModel(Util.roSpec("5.2")));
+
+        swagger.path("/user",
+                new Path()
+                        .get(new Operation()
+                                .tag(tag)
+                                .description(Util.roSpec("6.1"))
+                                .produces("application/json")
+                                .produces("application/json;profile=urn:org.restfulobjects:repr-types/user")
+                                .response(200,
+                                        newResponse(Caching.USER_INFO)
+                                                .description("OK")
+                                                .schema(newRefProperty("RestfulObjectsSupportingUserRepr"))
+                                )));
+        addDefinition("RestfulObjectsSupportingUserRepr",
+                newModel(Util.roSpec("6.2"))
+                        .property("userName", stringProperty())
+                        .property("roles", arrayOfStrings())
+                        .property("links", arrayOfLinks())
+                        .required("userName")
+                        .required("roles"));
+
+        swagger.path("/services",
+                new Path()
+                        .get(new Operation()
+                                .tag(tag)
+                                .description(Util.roSpec("7.1"))
+                                .produces("application/json")
+                                .produces("application/json;profile=urn:org.restfulobjects:repr-types/services")
+                                .response(200,
+                                        newResponse(Caching.USER_INFO)
+                                                .description("OK")
+                                                .schema(newRefProperty("RestfulObjectsSupportingServicesRepr"))
+                                )));
+        addDefinition("RestfulObjectsSupportingServicesRepr",
+                newModel(Util.roSpec("7.2"))
+                        .property("value", arrayOfLinks())
+                        .required("userName")
+                        .required("roles"));
+
+        swagger.path("/version",
+                new Path()
+                        .get(new Operation()
+                                .tag(tag)
+                                .description(Util.roSpec("8.1"))
+                                .produces("application/json")
+                                .produces("application/json;profile=urn:org.restfulobjects:repr-types/RestfulObjectsSupportingServicesRepr")
+                                .response(200,
+                                        newResponse(Caching.NON_EXPIRING)
+                                                .description("OK")
+                                                .schema(new ObjectProperty())
+                                )));
+        swagger.addDefinition("RestfulObjectsSupportingServicesRepr",
+                newModel(Util.roSpec("8.2"))
+                        .property("specVersion", stringProperty())
+                        .property("implVersion", stringProperty())
+                        .property("optionalCapabilities",
+                                new ObjectProperty()
+                                        .property("blobsClobs", stringProperty())
+                                        .property("deleteObjects", stringProperty())
+                                        .property("domainModel", stringProperty())
+                                        .property("validateOnly", stringProperty())
+                                        .property("protoPersistentObjects", stringProperty())
+                        )
+                        .required("userName")
+                        .required("roles"));
+    }
+
+    void appendLinkModelDefinition() {
+        swagger.addDefinition("LinkRepr",
+                new ModelImpl()
+                        .type("object")
+                        .property("rel", stringProperty().description("the relationship of the resource to this referencing resource"))
+                        .property("href", stringProperty().description("the hyperlink reference (URL) of the resource"))
+                        .property("title", stringProperty().description("title to render"))
+                        .property("method", stringPropertyEnum("GET", "POST", "PUT", "DELETE").description("HTTP verb to access"))
+                        .property("type", stringProperty().description("Content-Type recognized by the resource (for HTTP Accept header)"))
+                        .property("arguments", new ObjectProperty().description("Any arguments, to send as query strings or in body"))
+                        .property("value", stringProperty().description("the representation of the link if followed"))
+                        .required("rel")
+                        .required("href")
+                        .required("method")
+        );
+
+        swagger.addDefinition("HrefRepr",
+                new ModelImpl()
+                        .type("object")
+                        .description("Abbreviated version of the Link resource, used primarily to reference non-value objects")
+                        .property("href", stringProperty().description("the hyperlink reference (URL) of the resource"))
+                        .required("href")
+        );
+
+    }
+
+    void appendServicePath(final ObjectSpecification objectSpec) {
+
+        final String serviceId = serviceIdFor(objectSpec);
+
+        final Path path = new Path();
+        swagger.path(String.format("/services/%s", serviceId), path);
+
+        final String serviceModelDefinition = serviceId + "Repr";
+
+        final String tag = tagFor(serviceId, "> services");
+        path.get(
+                new Operation()
+                        .tag(tag)
+                        .description(Util.roSpec("15.1"))
+                        .produces("application/json")
+                        .produces("application/json;profile=urn:org.restfulobjects:repr-types/object")
+                        .response(200,
+                                newResponse(Caching.TRANSACTIONAL)
+                                        .description("OK")
+                                        .schema(newRefProperty(serviceModelDefinition)))
+        );
+
+        final ModelImpl model =
+                newModel(Util.roSpec("15.1.2") + ": representation of " + serviceId)
+                        .property("title", stringProperty())
+                        .property("serviceId", stringProperty()._default(serviceId))
+                        .property("members", new ObjectProperty());
+
+        addDefinition(serviceModelDefinition, model);
+    }
+
+    ModelImpl appendObjectPathAndModelDefinitions(final ObjectSpecification objectSpec) {
+
+        final String objectType = objectTypeFor(objectSpec);
+
+        final Path path = new Path();
+        swagger.path(String.format("/objects/%s/{objectId}", objectType), path);
+
+        final String tag = tagFor(objectType, null);
+        final Operation operation = new Operation();
+        path.get(operation);
+        operation
+                .tag(tag)
+                .description(Util.roSpec("14.1"))
+                .parameter(
+                        new PathParameter()
+                                .name("objectId")
+                                .type("string"))
+                .produces("application/json;profile=urn:org.apache.isis/v1")
+                .produces("application/json;profile=urn:org.apache.isis/v1;suppress=true")
+                .produces("application/json;profile=urn:org.restfulobjects:repr-types/object");
+
+
+        // per https://github.com/swagger-api/swagger-spec/issues/146, swagger 2.0 doesn't support multiple
+        // modelled representations per path and response code;
+        // in particular cannot associate representation/model with Accept header ('produces(...) method)
+        final String restfulObjectsModelDefinition = objectType + "RestfulObjectsRepr";
+        if (false) {
+            operation.response(200,
+                    newResponse(Caching.TRANSACTIONAL)
+                            .description("if Accept: application/json;profile=urn:org.restfulobjects:repr-types/object")
+                            .schema(newRefProperty(restfulObjectsModelDefinition)));
+
+            final ModelImpl roSpecModel =
+                    newModel(Util.roSpec("14.4") + ": representation of " + objectType)
+                            .property("title", stringProperty())
+                            .property("domainType", stringProperty()._default(objectType))
+                            .property("instanceId", stringProperty())
+                            .property("members", new ObjectProperty());
+            swagger.addDefinition(restfulObjectsModelDefinition, roSpecModel);
+        }
+
+        final String isisModelDefinition = objectType + "Repr";
+        operation
+                .response(200,
+                        newResponse(Caching.TRANSACTIONAL)
+                                .description(objectType + " , if Accept: application/json;profile=urn:org.apache.isis/v1")
+                                .schema(newRefProperty(isisModelDefinition)));
+
+        final ModelImpl isisModel = new ModelImpl();
+        addDefinition(isisModelDefinition, isisModel);
+
+        // return so can be appended to
+        return isisModel;
+    }
+
+    // UNUSED
+    void appendServiceActionPromptTo(final ObjectProperty serviceMembers, final ObjectAction action) {
+        String actionId = action.getId();
+
+        serviceMembers.property(actionId,
+                new ObjectProperty()
+                        .property("id", stringPropertyEnum(actionId))
+                        .property("memberType", stringPropertyEnum("action"))
+                        .property("links",
+                                new ObjectProperty()
+                                        .property("rel", stringPropertyEnum( String.format(
+                                                "urn:org.restfulobjects:rels/details;action=%s", actionId)))
+                                        .property("href", stringPropertyEnum(String.format(
+                                                "actions/%s", actionId))))
+                        .property("method", stringPropertyEnum("GET"))
+                        .property("type", stringPropertyEnum(
+                                "application/json;profile=urn:org.restfulobjects:repr-types/object-action"))
+        );
+    }
+
+    void appendServiceActionInvokePath(
+            final ObjectSpecification serviceSpec,
+            final ObjectAction serviceAction) {
+
+        final String serviceId = serviceIdFor(serviceSpec);
+        final String actionId = serviceAction.getId();
+
+        final List<ObjectActionParameter> parameters = serviceAction.getParameters();
+        final Path path = new Path();
+        swagger.path(String.format("/services/%s/actions/%s/invoke", serviceId, actionId), path);
+
+        final String tag = tagFor(serviceId, "> services");
+        final Operation invokeOperation =
+                new Operation()
+                        .tag(tag)
+                        .description(Util.roSpec("19.1") + ": (invoke) resource of " + serviceId + "#" + actionId)
+                        .produces("application/json;profile=urn:org.apache.isis/v1")
+                        .produces("application/json;profile=urn:org.apache.isis/v1;suppress=true")
+                        .produces("application/json;profile=urn:org.restfulobjects:repr-types/action-result")
+                ;
+
+        final ActionSemantics.Of semantics = serviceAction.getSemantics();
+        if(semantics.isSafeInNature()) {
+            path.get(invokeOperation);
+
+            for (final ObjectActionParameter parameter : parameters) {
+                invokeOperation
+                        .parameter(
+                                new QueryParameter()
+                                        .name(parameter.getId())
+                                        .description(Util.roSpec("2.9.1") + (!Strings.isNullOrEmpty(parameter.getDescription())? (": " + parameter.getDescription()) : ""))
+                                        .required(false)
+                                        .type("string")
+                        );
+            }
+            if(!parameters.isEmpty()) {
+                invokeOperation.parameter(new QueryParameter()
+                        .name("x-isis-querystring")
+                        .description(Util.roSpec("2.10") + ": all (formal) arguments as base64 encoded string")
+                        .required(false)
+                        .type("string"));
+            }
+
+        } else {
+            if (semantics.isIdempotentInNature()) {
+                path.put(invokeOperation);
+            } else {
+                path.post(invokeOperation);
+            }
+
+            final ModelImpl bodyParam =
+                    new ModelImpl()
+                            .type("object");
+            for (final ObjectActionParameter parameter : parameters) {
+
+                final Property valueProperty;
+                // TODO: need to switch on parameter's type and create appropriate impl of valueProperty
+                // if(parameter.getSpecification().isValue()) ...
+                valueProperty = stringProperty();
+
+                bodyParam
+                        .property(parameter.getId(),
+                                new ObjectProperty()
+                                        .property("value", valueProperty)
+                        );
+            }
+
+            invokeOperation
+                    .consumes("application/json")
+                    .parameter(
+                            new BodyParameter()
+                                    .name("body")
+                                    .schema(bodyParam));
+
+        }
+
+        invokeOperation
+                .response(
+                        200, new Response()
+                                .description(serviceId + "#" + actionId + " , if Accept: application/json;profile=urn:org.apache.isis/v1")
+                                .schema(actionReturnTypeFor(serviceAction))
+                );
+    }
+
+    void appendCollectionTo(
+            final ObjectSpecification objectSpec,
+            final OneToManyAssociation collection) {
+
+        final String objectType = objectTypeFor(objectSpec);
+        final String collectionId = collection.getId();
+
+        final Path path = new Path();
+        swagger.path(String.format("/objects/%s/{objectId}/collections/%s", objectType, collectionId), path);
+
+        final String tag = tagFor(objectType, null);
+        final Operation collectionOperation =
+                new Operation()
+                        .tag(tag)
+                        .description(Util.roSpec("17.1") + ": resource of " + objectType + "#" + collectionId)
+                        .parameter(
+                                new PathParameter()
+                                        .name("objectId")
+                                        .type("string"))
+                        .produces("application/json;profile=urn:org.apache.isis/v1")
+                        .produces("application/json;profile=urn:org.apache.isis/v1;suppress=true")
+                        .produces("application/json;profile=urn:org.restfulobjects:repr-types/object-collection");
+
+        path.get(collectionOperation);
+        collectionOperation
+                .response(
+                        200, new Response()
+                                .description(objectType + "#" + collectionId + " , if Accept: application/json;profile=urn:org.apache.isis/v1")
+                                .schema(modelFor(collection))
+                );
+    }
+
+    void appendObjectActionInvokePath(
+            final ObjectSpecification objectSpec,
+            final ObjectAction objectAction) {
+
+        final String objectType = objectTypeFor(objectSpec);
+        final String actionId = objectAction.getId();
+
+        final List<ObjectActionParameter> parameters = objectAction.getParameters();
+        final Path path = new Path();
+        swagger.path(String.format("/objects/%s/{objectId}/actions/%s/invoke", objectType, actionId), path);
+
+        final String tag = tagFor(objectType, null);
+        final Operation invokeOperation =
+                new Operation()
+                        .tag(tag)
+                        .description(Util.roSpec("19.1") + ": (invoke) resource of " + objectType + "#" + actionId)
+                        .parameter(
+                                new PathParameter()
+                                        .name("objectId")
+                                        .type("string"))
+                        .produces("application/json;profile=urn:org.apache.isis/v1")
+                        .produces("application/json;profile=urn:org.apache.isis/v1;suppress=true")
+                        .produces("application/json;profile=urn:org.restfulobjects:repr-types/action-result");
+
+        final ActionSemantics.Of semantics = objectAction.getSemantics();
+        if(semantics.isSafeInNature()) {
+            path.get(invokeOperation);
+
+            for (final ObjectActionParameter parameter : parameters) {
+                invokeOperation
+                        .parameter(
+                                new QueryParameter()
+                                        .name(parameter.getId())
+                                        .description(Util.roSpec("2.9.1") + (!Strings.isNullOrEmpty(parameter.getDescription())? (": " + parameter.getDescription()) : ""))
+                                        .required(false)
+                                        .type("string")
+                        );
+            }
+            if(!parameters.isEmpty()) {
+                invokeOperation.parameter(new QueryParameter()
+                        .name("x-isis-querystring")
+                        .description(Util.roSpec("2.10") + ": all (formal) arguments as base64 encoded string")
+                        .required(false)
+                        .type("string"));
+            }
+
+        } else {
+            if (semantics.isIdempotentInNature()) {
+                path.put(invokeOperation);
+            } else {
+                path.post(invokeOperation);
+            }
+
+            final ModelImpl bodyParam =
+                    new ModelImpl()
+                            .type("object");
+            for (final ObjectActionParameter parameter : parameters) {
+
+                final ObjectSpecification specification = parameter.getSpecification();
+                final Property valueProperty = specification.isValue() ? modelFor(specification) : refToLinkModel() ;
+                bodyParam
+                        .property(parameter.getId(),
+                                new ObjectProperty()
+                                        .property("value", valueProperty)
+                        );
+            }
+
+            invokeOperation
+                    .consumes("application/json")
+                    .parameter(
+                            new BodyParameter()
+                                    .name("body")
+                                    .schema(bodyParam));
+
+        }
+
+        invokeOperation
+                .response(
+                        200, new Response()
+                                .description(objectType + "#" + actionId)
+                                .schema(actionReturnTypeFor(objectAction))
+                );
+    }
+
+    void appendDefinitionsForOrphanedReferences() {
+        final Set<String> referencesWithoutDefinition = getReferencesWithoutDefinition();
+        for (String reference : referencesWithoutDefinition) {
+            swagger.addDefinition(reference, new ModelImpl());
+        }
+    }
+
+    Property actionReturnTypeFor(final ObjectAction objectAction) {
+
+        final ObjectSpecification specification = objectAction.getReturnType();
+        TypeOfFacet typeOfFacet = objectAction.getFacet(TypeOfFacet.class);
+        if(typeOfFacet != null) {
+            ObjectSpecification elementSpec = typeOfFacet.valueSpec();
+            if(elementSpec != null) {
+                return arrayPropertyOf(elementSpec);
+            }
+        }
+        return modelFor(specification);
+    }
+
+    private Property modelFor(final OneToManyAssociation collection) {
+        ObjectSpecification collectionSpecification = collection.getSpecification();
+        return arrayPropertyOf(collectionSpecification);
+    }
+
+    private Property arrayPropertyOf(final ObjectSpecification objectSpecification) {
+        final ArrayProperty arrayProperty = new ArrayProperty();
+        if(objectSpecification != null && objectSpecification.getCorrespondingClass() != Object.class) {
+            arrayProperty
+                    .description("List of " + objectTypeFor(objectSpecification))
+                    .items(modelFor(objectSpecification));
+        } else {
+            arrayProperty.items(new ObjectProperty());
+        }
+        return arrayProperty;
+    }
+
+    private Property modelFor(final ObjectSpecification specification) {
+        if(specification == null) {
+            return new ObjectProperty();
+        }
+
+        // no "simple" representation for void or values
+        final Class<?> correspondingClass = specification.getCorrespondingClass();
+        if(correspondingClass == void.class || correspondingClass == Void.class) {
+            return new ObjectProperty();
+        }
+        // no "simple" representation for values
+        final Property property = valuePropertyFactory.newProperty(correspondingClass);
+        if(property != null) {
+            // was recognized as a value
+            return new ObjectProperty();
+        }
+
+        if(specification.isParentedOrFreeCollection()) {
+            TypeOfFacet typeOfFacet = specification.getFacet(TypeOfFacet.class);
+            if(typeOfFacet != null) {
+                ObjectSpecification elementSpec = typeOfFacet.valueSpec();
+                if(elementSpec != null) {
+                    return arrayPropertyOf(elementSpec);
+                }
+            }
+        }
+
+        if(specification.getCorrespondingClass() == java.lang.Object.class) {
+            return new ObjectProperty();
+        }
+        if(specification.getCorrespondingClass() == java.lang.Enum.class) {
+            return new StringProperty();
+        }
+        return newRefProperty(objectTypeFor(specification) + "Repr");
+    }
+
+    void updateObjectModel(
+            final ModelImpl model,
+            final ObjectSpecification objectSpecification,
+            final List<OneToOneAssociation> objectProperties,
+            final List<OneToManyAssociation> objectCollections) {
+
+        final String objectType = objectTypeFor(objectSpecification);
+        final String className = objectSpecification.getFullIdentifier();
+
+        model
+                .type("object")
+                .description(String.format("%s (%s)", objectType, className));
+
+        for (OneToOneAssociation objectProperty : objectProperties) {
+            model.property(
+                    objectProperty.getId(),
+                    propertyFor(objectProperty.getSpecification()));
+        }
+
+        for (OneToManyAssociation objectCollection : objectCollections) {
+            final ObjectSpecification elementSpec = objectCollection.getSpecification();
+            model.property(
+                    objectCollection.getId(),
+                    arrayPropertyOf(elementSpec)
+            );
+        }
+    }
+
+    Property propertyFor(final ObjectSpecification objectSpecification) {
+        final Property property =
+                valuePropertyFactory.newProperty(objectSpecification.getCorrespondingClass());
+        if (property != null) {
+            return property;
+        }
+        else {
+            // assume this is a reference to an entity/view model, meaning we use an href
+            return refToHrefModel();
+        }
+    }
+
+    // unused
+    static String roSpecForResponseOf(final ObjectAction action) {
+        final ActionSemantics.Of semantics = action.getSemantics();
+        switch (semantics) {
+        case SAFE_AND_REQUEST_CACHEABLE:
+        case SAFE:
+            return "19.2";
+        case IDEMPOTENT:
+        case IDEMPOTENT_ARE_YOU_SURE:
+            return "19.3";
+        default:
+            return "19.4";
+        }
+    }
+
+    static ModelImpl newModel(final String description) {
+        return new ModelImpl()
+                .description(description)
+                .type("object")
+                .property("links", arrayOfLinks())
+                .property("extensions", new MapProperty())
+                .required("links")
+                .required("extensions");
+    }
+
+    // TODO: this is horrid, there ought to be a facet we can call instead...
+    static String serviceIdFor(final ObjectSpecification serviceSpec) {
+        Object tempServiceInstance = InstanceUtil.createInstance(serviceSpec.getCorrespondingClass());
+        return serviceId(tempServiceInstance);
+    }
+
+    static String serviceId(final Object object) {
+        return ServiceUtil.id(object);
+    }
+
+    static String objectTypeFor(final ObjectSpecification objectSpec) {
+        return objectSpec.getFacet(ObjectSpecIdFacet.class).value().asString();
+    }
+
+    static StringProperty stringProperty() {
+        return new StringProperty();
+    }
+
+    static StringProperty stringPropertyEnum(String... enumValues) {
+        StringProperty stringProperty = stringProperty();
+        stringProperty._enum(Arrays.asList(enumValues));
+        if(enumValues.length >= 1) {
+            stringProperty._default(enumValues[0]);
+        }
+        return stringProperty;
+    }
+
+    static ArrayProperty arrayOfLinks() {
+        return new ArrayProperty()
+                .items(refToLinkModel());
+    }
+
+    static RefProperty refToLinkModel() {
+        return new RefProperty("#/definitions/LinkRepr");
+    }
+
+    static RefProperty refToHrefModel() {
+        return new RefProperty("#/definitions/HrefRepr");
+    }
+
+    static ArrayProperty arrayOfStrings() {
+        return new ArrayProperty().items(stringProperty());
+    }
+
+    static Response newResponse(final Caching caching) {
+        return Util.withCachingHeaders(new Response(), caching);
+    }
+
+    String tagFor(final String str, final String fallback) {
+        return tagger.tagFor(str, fallback);
+    }
+
+    private Property newRefProperty(final String model) {
+        addSwaggerReference(model);
+        return new RefProperty("#/definitions/" + model);
+    }
+
+    private void addDefinition(final String key, final ModelImpl model) {
+        addSwaggerDefinition(key);
+        swagger.addDefinition(key, model);
+    }
+
+    void addSwaggerReference(final String model) {
+        references.add(model);
+    }
+
+    void addSwaggerDefinition(final String model) {
+        definitions.add(model);
+    }
+
+    Set<String> getReferencesWithoutDefinition() {
+        LinkedHashSet<String> referencesCopy = Sets.newLinkedHashSet(references);
+        referencesCopy.removeAll(definitions);
+        return referencesCopy;
+    }
+
+
+}

http://git-wip-us.apache.org/repos/asf/isis/blob/2efbf48f/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGenerator.java
----------------------------------------------------------------------
diff --git a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGenerator.java b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGenerator.java
index b1eaf1d..25cb917 100644
--- a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGenerator.java
+++ b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGenerator.java
@@ -18,57 +18,18 @@
  */
 package org.apache.isis.core.metamodel.services.swagger.internal;
 
-import java.lang.reflect.InvocationTargetException;
-import java.lang.reflect.Method;
-import java.util.Arrays;
-import java.util.Collection;
-import java.util.List;
-import java.util.regex.Matcher;
-import java.util.regex.Pattern;
-
 import com.fasterxml.jackson.core.JsonProcessingException;
-import com.google.common.base.Strings;
-import com.google.common.collect.Lists;
 
-import org.apache.isis.applib.annotation.ActionSemantics;
-import org.apache.isis.applib.annotation.NatureOfService;
-import org.apache.isis.applib.fixturescripts.FixtureResult;
 import org.apache.isis.applib.services.swagger.SwaggerService;
-import org.apache.isis.core.commons.exceptions.IsisException;
-import org.apache.isis.core.commons.factory.InstanceUtil;
-import org.apache.isis.core.metamodel.facets.actcoll.typeof.TypeOfFacet;
-import org.apache.isis.core.metamodel.facets.object.domainservice.DomainServiceFacet;
-import org.apache.isis.core.metamodel.facets.object.mixin.MixinFacet;
-import org.apache.isis.core.metamodel.facets.object.objectspecid.ObjectSpecIdFacet;
-import org.apache.isis.core.metamodel.spec.ObjectSpecification;
 import org.apache.isis.core.metamodel.spec.SpecificationLoader;
-import org.apache.isis.core.metamodel.spec.feature.ObjectAction;
-import org.apache.isis.core.metamodel.spec.feature.ObjectActionParameter;
-import org.apache.isis.core.metamodel.spec.feature.OneToManyAssociation;
-import org.apache.isis.core.metamodel.spec.feature.OneToOneAssociation;
 
-import io.swagger.models.Info;
-import io.swagger.models.ModelImpl;
-import io.swagger.models.Operation;
-import io.swagger.models.Path;
-import io.swagger.models.Response;
 import io.swagger.models.Swagger;
-import io.swagger.models.parameters.BodyParameter;
-import io.swagger.models.parameters.PathParameter;
-import io.swagger.models.parameters.QueryParameter;
-import io.swagger.models.properties.ArrayProperty;
-import io.swagger.models.properties.MapProperty;
-import io.swagger.models.properties.ObjectProperty;
-import io.swagger.models.properties.Property;
-import io.swagger.models.properties.RefProperty;
-import io.swagger.models.properties.StringProperty;
 import io.swagger.util.Json;
 import io.swagger.util.Yaml;
 
 public class SwaggerSpecGenerator {
 
     private final SpecificationLoader specificationLoader;
-    private final ValuePropertyFactory valuePropertyFactory = new ValuePropertyFactory();
 
     public SwaggerSpecGenerator(final SpecificationLoader specificationLoader) {
         this.specificationLoader = specificationLoader;
@@ -79,18 +40,8 @@ public class SwaggerSpecGenerator {
             final SwaggerService.Visibility visibility,
             final SwaggerService.Format format) {
 
-        final Swagger swagger = new Swagger();
-        swagger.basePath(basePath);
-        swagger.info(new Info()
-                        //.version("1.0.0") // TODO: provide some way of passing the name, version etc (some sort of SPI service?)
-                        .title(visibility.name() + " API")
-        );
-
-        appendRestfulObjectsSupportingPathsAndDefinitions(swagger);
-        appendLinkModelDefinition(swagger);
-
-        appendServicePathsAndDefinitions(swagger, visibility);
-        appendObjectPathsAndDefinitions(swagger, visibility);
+        final Generation generation = newGeneration(basePath, visibility);
+        final Swagger swagger = generation.generate();
 
         switch (format) {
             case JSON:
@@ -106,721 +57,8 @@ public class SwaggerSpecGenerator {
         }
     }
 
-    void appendServicePathsAndDefinitions(final Swagger swagger, final SwaggerService.Visibility visibility) {
-        // take copy to avoid concurrent modification exception
-        final Collection<ObjectSpecification> allSpecs = Lists.newArrayList(specificationLoader.allSpecifications());
-        for (final ObjectSpecification serviceSpec :  allSpecs) {
-
-            final DomainServiceFacet domainServiceFacet = serviceSpec.getFacet(DomainServiceFacet.class);
-            if (domainServiceFacet == null) {
-                continue;
-            }
-            if (visibility.isPublic() &&
-                domainServiceFacet.getNatureOfService() != NatureOfService.VIEW_REST_ONLY) {
-                continue;
-            }
-            if (domainServiceFacet.getNatureOfService() != NatureOfService.VIEW_MENU_ONLY &&
-                domainServiceFacet.getNatureOfService() != NatureOfService.VIEW) {
-                continue;
-            }
-
-            final List<ObjectAction> serviceActions = Util.actionsOf(serviceSpec, visibility);
-            if(serviceActions.isEmpty()) {
-                continue;
-            }
-            appendServicePath(swagger, serviceSpec);
-
-            for (final ObjectAction serviceAction : serviceActions) {
-                appendServiceActionInvokePath(swagger, serviceSpec, serviceAction);
-            }
-        }
-    }
-
-    void appendObjectPathsAndDefinitions(final Swagger swagger, final SwaggerService.Visibility visibility) {
-        // take copy to avoid concurrent modification exception
-        final Collection<ObjectSpecification> allSpecs = Lists.newArrayList(specificationLoader.allSpecifications());
-        for (final ObjectSpecification objectSpec : allSpecs) {
-
-            final DomainServiceFacet domainServiceFacet = objectSpec.getFacet(DomainServiceFacet.class);
-            if (domainServiceFacet != null) {
-                continue;
-            }
-            final MixinFacet mixinFacet = objectSpec.getFacet(MixinFacet.class);
-            if (mixinFacet != null) {
-                continue;
-            }
-            if(visibility.isPublic() && !Util.isVisibleForPublic(objectSpec)) {
-                continue;
-            }
-            if(objectSpec.isAbstract()) {
-                continue;
-            }
-            if(objectSpec.isValue()) {
-                continue;
-            }
-            // special cases
-            if(objectSpec.getCorrespondingClass() == FixtureResult.class) {
-                continue;
-            }
-
-            final List<OneToOneAssociation> objectProperties = Util.propertiesOf(objectSpec, visibility);
-            final List<OneToManyAssociation> objectCollections = Util.collectionsOf(objectSpec, visibility);
-            final List<ObjectAction> objectActions = Util.actionsOf(objectSpec, visibility);
-
-            if(objectProperties.isEmpty() && objectCollections.isEmpty()) {
-                continue;
-            }
-            final ModelImpl isisModel = appendObjectPathAndModelDefinitions(swagger, objectSpec);
-            updateObjectModel(isisModel, objectSpec, objectProperties, objectCollections);
-
-            for (final OneToManyAssociation objectCollection : objectCollections) {
-                appendCollectionTo(swagger, objectSpec, objectCollection);
-            }
-
-            for (final ObjectAction objectAction : objectActions) {
-                appendObjectActionInvokePath(swagger, objectSpec, objectAction);
-            }
-        }
+    protected Generation newGeneration(final String basePath, final SwaggerService.Visibility visibility) {
+        return new Generation(basePath, visibility, specificationLoader);
     }
 
-    void appendRestfulObjectsSupportingPathsAndDefinitions(final Swagger swagger) {
-
-        final String tag = "> restful objects supporting resources";
-
-        swagger.path("/",
-                new Path()
-                        .get(new Operation()
-                                .tag(tag)
-                                .description(Util.roSpec("5.1"))
-                                .produces("application/json")
-                                .produces("application/json;profile=urn:org.restfulobjects:repr-types/home-page")
-                                .response(200,
-                                        newResponse(Caching.NON_EXPIRING)
-                                                .description("OK")
-                                                .schema(new RefProperty("#/definitions/RestfulObjectsSupportingHomePageModel"))
-                                )));
-        swagger.addDefinition("RestfulObjectsSupportingHomePageModel",
-                newModel(Util.roSpec("5.2")));
-
-        swagger.path("/user",
-                new Path()
-                        .get(new Operation()
-                                .tag(tag)
-                                .description(Util.roSpec("6.1"))
-                                .produces("application/json")
-                                .produces("application/json;profile=urn:org.restfulobjects:repr-types/user")
-                                .response(200,
-                                        newResponse(Caching.USER_INFO)
-                                                .description("OK")
-                                                .schema(new RefProperty("#/definitions/RestfulObjectsSupportingUserModel"))
-                                )));
-        swagger.addDefinition("RestfulObjectsSupportingUserModel",
-                newModel(Util.roSpec("6.2"))
-                        .property("userName", stringProperty())
-                        .property("roles", arrayOfStrings())
-                        .property("links", arrayOfLinks())
-                        .required("userName")
-                        .required("roles"));
-
-        swagger.path("/services",
-                new Path()
-                        .get(new Operation()
-                                .tag(tag)
-                                .description(Util.roSpec("7.1"))
-                                .produces("application/json")
-                                .produces("application/json;profile=urn:org.restfulobjects:repr-types/services")
-                                .response(200,
-                                        newResponse(Caching.USER_INFO)
-                                                .description("OK")
-                                                .schema(new RefProperty("#/definitions/RestfulObjectsSupportingServicesModel"))
-                                )));
-        swagger.addDefinition("RestfulObjectsSupportingServicesModel",
-                newModel(Util.roSpec("7.2"))
-                        .property("value", arrayOfLinks())
-                        .required("userName")
-                        .required("roles"));
-
-        swagger.path("/version",
-                new Path()
-                        .get(new Operation()
-                                .tag(tag)
-                                .description(Util.roSpec("8.1"))
-                                .produces("application/json")
-                                .produces("application/json;profile=urn:org.restfulobjects:repr-types/RestfulObjectsSupportingServicesModel")
-                                .response(200,
-                                        newResponse(Caching.NON_EXPIRING)
-                                                .description("OK")
-                                                .schema(new ObjectProperty())
-                                )));
-        swagger.addDefinition("RestfulObjectsSupportingServicesModel",
-                newModel(Util.roSpec("8.2"))
-                        .property("specVersion", stringProperty())
-                        .property("implVersion", stringProperty())
-                        .property("optionalCapabilities",
-                                new ObjectProperty()
-                                        .property("blobsClobs", stringProperty())
-                                        .property("deleteObjects", stringProperty())
-                                        .property("domainModel", stringProperty())
-                                        .property("validateOnly", stringProperty())
-                                        .property("protoPersistentObjects", stringProperty())
-                        )
-                        .required("userName")
-                        .required("roles"));
-    }
-
-    void appendLinkModelDefinition(final Swagger swagger) {
-        swagger.addDefinition("LinkModel",
-                new ModelImpl()
-                    .type("object")
-                    .property("rel", stringProperty().description("the relationship of the resource to this referencing resource"))
-                    .property("href", stringProperty().description("the hyperlink reference (URL) of the resource"))
-                    .property("title", stringProperty().description("title to render"))
-                    .property("method", stringPropertyEnum("GET", "POST", "PUT", "DELETE").description("HTTP verb to access"))
-                    .property("type", stringProperty().description("Content-Type recognized by the resource (for HTTP Accept header)"))
-                    .property("arguments", new ObjectProperty().description("Any arguments, to send as query strings or in body"))
-                    .property("value", stringProperty().description("the representation of the link if followed"))
-                    .required("rel")
-                    .required("href")
-                    .required("method")
-        );
-
-        swagger.addDefinition("HrefModel",
-                new ModelImpl()
-                    .type("object")
-                    .description("Abbreviated version of the Link resource, used primarily to reference non-value objects")
-                    .property("href", stringProperty().description("the hyperlink reference (URL) of the resource"))
-                    .required("href")
-        );
-
-    }
-
-    void appendServicePath(final Swagger swagger, final ObjectSpecification objectSpec) {
-
-        final String serviceId = serviceIdFor(objectSpec);
-
-        final Path path = new Path();
-        swagger.path(String.format("/services/%s", serviceId), path);
-
-        final String serviceModelDefinition = serviceId + "Model";
-
-        final String tag = tagFor(serviceId);
-        path.get(
-                new Operation()
-                        .tag(tag)
-                        .description(Util.roSpec("15.1"))
-                        .produces("application/json")
-                        .produces("application/json;profile=urn:org.restfulobjects:repr-types/object")
-                        .response(200,
-                                newResponse(Caching.TRANSACTIONAL)
-                                        .description("OK")
-                                        .schema(new RefProperty("#/definitions/" + serviceModelDefinition)))
-        );
-
-        final ModelImpl model =
-                newModel(Util.roSpec("15.1.2") + ": representation of " + serviceId)
-                        .property("title", stringProperty())
-                        .property("serviceId", stringProperty()._default(serviceId))
-                        .property("members", new ObjectProperty());
-
-        swagger.addDefinition(serviceModelDefinition, model);
-    }
-
-    ModelImpl appendObjectPathAndModelDefinitions(final Swagger swagger, final ObjectSpecification objectSpec) {
-
-        final String objectType = objectTypeFor(objectSpec);
-
-        final Path path = new Path();
-        swagger.path(String.format("/objects/%s/{objectId}", objectType), path);
-
-        final String tag = tagFor(objectType);
-        final Operation operation = new Operation();
-        path.get(operation);
-        operation
-                .tag(tag)
-                .description(Util.roSpec("14.1"))
-                .parameter(
-                    new PathParameter()
-                        .name("objectId")
-                        .type("string"))
-                .produces("application/json;profile=urn:org.apache.isis/v1")
-                .produces("application/json;profile=urn:org.apache.isis/v1;suppress=true")
-                .produces("application/json;profile=urn:org.restfulobjects:repr-types/object");
-
-
-        // per https://github.com/swagger-api/swagger-spec/issues/146, swagger 2.0 doesn't support multiple
-        // modelled representations per path and response code;
-        // in particular cannot associate representation/model with Accept header ('produces(...) method)
-        final String restfulObjectsModelDefinition = objectType + "RestfulObjectsModel";
-        if (false) {
-            operation.response(200,
-                    newResponse(Caching.TRANSACTIONAL)
-                            .description("if Accept: application/json;profile=urn:org.restfulobjects:repr-types/object")
-                            .schema(new RefProperty("#/definitions/" + restfulObjectsModelDefinition)));
-
-            final ModelImpl roSpecModel =
-                    newModel(Util.roSpec("14.4") + ": representation of " + objectType)
-                            .property("title", stringProperty())
-                            .property("domainType", stringProperty()._default(objectType))
-                            .property("instanceId", stringProperty())
-                            .property("members", new ObjectProperty());
-            swagger.addDefinition(restfulObjectsModelDefinition, roSpecModel);
-        }
-
-        final String isisModelDefinition = objectType + "Model";
-        operation
-                .response(200,
-                        newResponse(Caching.TRANSACTIONAL)
-                                .description(objectType + " , if Accept: application/json;profile=urn:org.apache.isis/v1")
-                                .schema(new RefProperty("#/definitions/" + isisModelDefinition)));
-
-        final ModelImpl isisModel = new ModelImpl();
-        swagger.addDefinition(isisModelDefinition, isisModel);
-
-        // return so can be appended to
-        return isisModel;
-    }
-
-    // UNUSED
-    void appendServiceActionPromptTo(final ObjectProperty serviceMembers, final ObjectAction action) {
-        String actionId = action.getId();
-
-        serviceMembers.property(actionId,
-                new ObjectProperty()
-                        .property("id", stringPropertyEnum(actionId))
-                        .property("memberType", stringPropertyEnum("action"))
-                        .property("links",
-                                new ObjectProperty()
-                                        .property("rel", stringPropertyEnum( String.format(
-                                                "urn:org.restfulobjects:rels/details;action=%s", actionId)))
-                                        .property("href", stringPropertyEnum(String.format(
-                                                "actions/%s", actionId))))
-                        .property("method", stringPropertyEnum("GET"))
-                        .property("type", stringPropertyEnum(
-                                "application/json;profile=urn:org.restfulobjects:repr-types/object-action"))
-        );
-    }
-
-    void appendServiceActionInvokePath(
-            final Swagger swagger,
-            final ObjectSpecification serviceSpec,
-            final ObjectAction serviceAction) {
-
-        final String serviceId = serviceIdFor(serviceSpec);
-        final String actionId = serviceAction.getId();
-
-        final List<ObjectActionParameter> parameters = serviceAction.getParameters();
-        final Path path = new Path();
-        swagger.path(String.format("/services/%s/actions/%s/invoke", serviceId, actionId), path);
-
-        final String tag = tagFor(serviceId);
-        final Operation invokeOperation =
-                new Operation()
-                        .tag(tag)
-                        .description(Util.roSpec("19.1") + ": (invoke) resource of " + serviceId + "#" + actionId)
-                        .produces("application/json;profile=urn:org.apache.isis/v1")
-                        .produces("application/json;profile=urn:org.apache.isis/v1;suppress=true")
-                        .produces("application/json;profile=urn:org.restfulobjects:repr-types/action-result")
-                ;
-
-        final ActionSemantics.Of semantics = serviceAction.getSemantics();
-        if(semantics.isSafeInNature()) {
-            path.get(invokeOperation);
-
-            for (final ObjectActionParameter parameter : parameters) {
-                invokeOperation
-                        .parameter(
-                                new QueryParameter()
-                                        .name(parameter.getId())
-                                        .description(Util.roSpec("2.9.1") + (!Strings.isNullOrEmpty(parameter.getDescription())? (": " + parameter.getDescription()) : ""))
-                                        .required(false)
-                                        .type("string")
-                        );
-            }
-            if(!parameters.isEmpty()) {
-                invokeOperation.parameter(new QueryParameter()
-                        .name("x-isis-querystring")
-                        .description(Util.roSpec("2.10") + ": all (formal) arguments as base64 encoded string")
-                        .required(false)
-                        .type("string"));
-            }
-
-        } else {
-            if (semantics.isIdempotentInNature()) {
-                path.put(invokeOperation);
-            } else {
-                path.post(invokeOperation);
-            }
-
-            final ModelImpl bodyParam =
-                    new ModelImpl()
-                            .type("object");
-            for (final ObjectActionParameter parameter : parameters) {
-
-                final Property valueProperty;
-                // TODO: need to switch on parameter's type and create appropriate impl of valueProperty
-                // if(parameter.getSpecification().isValue()) ...
-                valueProperty = stringProperty();
-
-                bodyParam
-                        .property(parameter.getId(),
-                                new ObjectProperty()
-                                        .property("value", valueProperty)
-                        );
-            }
-
-            invokeOperation
-                    .consumes("application/json")
-                    .parameter(
-                            new BodyParameter()
-                                    .name("body")
-                                    .schema(bodyParam));
-
-        }
-
-        invokeOperation
-                .response(
-                        200, new Response()
-                                .description(serviceId + "#" + actionId + " , if Accept: application/json;profile=urn:org.apache.isis/v1")
-                                .schema(actionReturnTypeFor(serviceAction))
-                );
-    }
-
-    void appendCollectionTo(
-            final Swagger swagger,
-            final ObjectSpecification objectSpec,
-            final OneToManyAssociation collection) {
-
-        final String objectType = objectTypeFor(objectSpec);
-        final String collectionId = collection.getId();
-
-        final Path path = new Path();
-        swagger.path(String.format("/objects/%s/{objectId}/collections/%s", objectType, collectionId), path);
-
-        final String tag = tagFor(objectType);
-        final Operation collectionOperation =
-                new Operation()
-                        .tag(tag)
-                        .description(Util.roSpec("17.1") + ": resource of " + objectType + "#" + collectionId)
-                        .parameter(
-                                new PathParameter()
-                                        .name("objectId")
-                                        .type("string"))
-                        .produces("application/json;profile=urn:org.apache.isis/v1")
-                        .produces("application/json;profile=urn:org.apache.isis/v1;suppress=true")
-                        .produces("application/json;profile=urn:org.restfulobjects:repr-types/object-collection");
-
-        path.get(collectionOperation);
-        collectionOperation
-                .response(
-                        200, new Response()
-                                .description(objectType + "#" + collectionId + " , if Accept: application/json;profile=urn:org.apache.isis/v1")
-                                .schema(modelFor(collection))
-                );
-    }
-
-    private Property modelFor(final OneToManyAssociation collection) {
-        ObjectSpecification collectionSpecification = collection.getSpecification();
-        return new ArrayProperty()
-                .description("List of " + objectTypeFor(collectionSpecification))
-                    .items(modelFor(collectionSpecification));
-    }
-
-    void appendObjectActionInvokePath(
-            final Swagger swagger,
-            final ObjectSpecification objectSpec,
-            final ObjectAction objectAction) {
-
-        final String objectType = objectTypeFor(objectSpec);
-        final String actionId = objectAction.getId();
-
-        final List<ObjectActionParameter> parameters = objectAction.getParameters();
-        final Path path = new Path();
-        swagger.path(String.format("/objects/%s/{objectId}/actions/%s/invoke", objectType, actionId), path);
-
-        final String tag = tagFor(objectType);
-        final Operation invokeOperation =
-                new Operation()
-                        .tag(tag)
-                        .description(Util.roSpec("19.1") + ": (invoke) resource of " + objectType + "#" + actionId)
-                        .parameter(
-                                new PathParameter()
-                                        .name("objectId")
-                                        .type("string"))
-                        .produces("application/json;profile=urn:org.apache.isis/v1")
-                        .produces("application/json;profile=urn:org.apache.isis/v1;suppress=true")
-                        .produces("application/json;profile=urn:org.restfulobjects:repr-types/action-result");
-
-        final ActionSemantics.Of semantics = objectAction.getSemantics();
-        if(semantics.isSafeInNature()) {
-            path.get(invokeOperation);
-
-            for (final ObjectActionParameter parameter : parameters) {
-                invokeOperation
-                        .parameter(
-                                new QueryParameter()
-                                        .name(parameter.getId())
-                                        .description(Util.roSpec("2.9.1") + (!Strings.isNullOrEmpty(parameter.getDescription())? (": " + parameter.getDescription()) : ""))
-                                        .required(false)
-                                        .type("string")
-                        );
-            }
-            if(!parameters.isEmpty()) {
-                invokeOperation.parameter(new QueryParameter()
-                        .name("x-isis-querystring")
-                        .description(Util.roSpec("2.10") + ": all (formal) arguments as base64 encoded string")
-                        .required(false)
-                        .type("string"));
-            }
-
-        } else {
-            if (semantics.isIdempotentInNature()) {
-                path.put(invokeOperation);
-            } else {
-                path.post(invokeOperation);
-            }
-
-            final ModelImpl bodyParam =
-                    new ModelImpl()
-                            .type("object");
-            for (final ObjectActionParameter parameter : parameters) {
-
-                final Property valueProperty;
-                // TODO: need to switch on parameter's type and create appropriate impl of valueProperty
-                // if(parameter.getSpecification().isValue()) ...
-                valueProperty = stringProperty();
-
-                bodyParam
-                        .property(parameter.getId(),
-                                new ObjectProperty()
-                                        .property("value", valueProperty)
-                        );
-            }
-
-            invokeOperation
-                    .consumes("application/json")
-                    .parameter(
-                            new BodyParameter()
-                                    .name("body")
-                                    .schema(bodyParam));
-
-        }
-
-        invokeOperation
-                .response(
-                        200, new Response()
-                                .description(objectType + "#" + actionId)
-                                .schema(actionReturnTypeFor(objectAction))
-                );
-    }
-
-    Property actionReturnTypeFor(final ObjectAction objectAction) {
-
-        final ObjectSpecification specification = objectAction.getReturnType();
-        TypeOfFacet typeOfFacet = objectAction.getFacet(TypeOfFacet.class);
-        if(typeOfFacet != null) {
-            ObjectSpecification elementSpec = typeOfFacet.valueSpec();
-            if(elementSpec != null) {
-                return new ArrayProperty()
-                        .items(modelFor(elementSpec));
-            }
-        }
-        return modelFor(specification);
-    }
-
-    private Property modelFor(final ObjectSpecification specification) {
-        if(specification == null) {
-            return new ObjectProperty();
-        }
-
-        // no "simple" representation for void or values
-        final Class<?> correspondingClass = specification.getCorrespondingClass();
-        if(correspondingClass == void.class || correspondingClass == Void.class) {
-            return new ObjectProperty();
-        }
-        // no "simple" representation for values
-        final Property property = valuePropertyFactory.newProperty(correspondingClass);
-        if(property != null) {
-            // was recognized as a value
-            return new ObjectProperty();
-        }
-
-        if(specification.isParentedOrFreeCollection()) {
-            TypeOfFacet typeOfFacet = specification.getFacet(TypeOfFacet.class);
-            if(typeOfFacet != null) {
-                ObjectSpecification elementSpec = typeOfFacet.valueSpec();
-                if(elementSpec != null) {
-                    return new ArrayProperty()
-                            .items(modelFor(elementSpec));
-                }
-            }
-        }
-
-        return new RefProperty("#/definitions/" + objectTypeFor(specification) + "Model");
-    }
-
-    void updateObjectModel(
-            final ModelImpl model,
-            final ObjectSpecification objectSpecification,
-            final List<OneToOneAssociation> objectProperties,
-            final List<OneToManyAssociation> objectCollections) {
-
-        final String objectType = objectTypeFor(objectSpecification);
-        final String className = objectSpecification.getFullIdentifier();
-
-        model
-                .type("object")
-                .description(String.format("%s (%s)", objectType, className));
-
-        for (OneToOneAssociation objectProperty : objectProperties) {
-            model.property(
-                    objectProperty.getId(),
-                    propertyFor(objectProperty.getSpecification()));
-        }
-
-        for (OneToManyAssociation objectCollection : objectCollections) {
-            final ObjectSpecification elementSpec = objectCollection.getSpecification();
-            final String elementModelDefinition = objectTypeFor(elementSpec) + "Model";
-
-            model.property(
-                    objectCollection.getId(),
-                    new ArrayProperty()
-                    .items(new RefProperty("#/definitions/" + elementModelDefinition))
-            );
-        }
-    }
-
-    Property propertyFor(final ObjectSpecification objectSpecification) {
-        final Property property =
-                valuePropertyFactory.newProperty(objectSpecification.getCorrespondingClass());
-        if (property != null) {
-            return property;
-        }
-        else {
-            // assume this is a reference to an entity/view model, meaning we use an href
-            return refToHrefModel();
-        }
-    }
-
-    static String roSpecForResponseOf(final ObjectAction action) {
-        final ActionSemantics.Of semantics = action.getSemantics();
-        switch (semantics) {
-            case SAFE_AND_REQUEST_CACHEABLE:
-            case SAFE:
-                return "19.2";
-            case IDEMPOTENT:
-            case IDEMPOTENT_ARE_YOU_SURE:
-                return "19.3";
-            default:
-                return "19.4";
-        }
-    }
-
-    static ModelImpl newModel(final String description) {
-        return new ModelImpl()
-                .description(description)
-                .type("object")
-                .property("links", arrayOfLinks())
-                .property("extensions", new MapProperty())
-                .required("links")
-                .required("extensions");
-    }
-
-    // TODO: this is horrid, there ought to be a facet we can call instead...
-    static String serviceIdFor(final ObjectSpecification serviceSpec) {
-        Object tempServiceInstance = InstanceUtil.createInstance(serviceSpec.getCorrespondingClass());
-        return serviceId(tempServiceInstance);
-    }
-
-    static String serviceId(final Object object) {
-        final Class<?> cls = object.getClass();
-        try {
-            final Method m = cls.getMethod("getId", new Class[0]);
-            return (String) m.invoke(object, new Object[0]);
-        } catch (final SecurityException e) {
-            throw new IsisException(e);
-        } catch (final NoSuchMethodException e) {
-            return object.getClass().getName();
-        } catch (final IllegalArgumentException e) {
-            throw new IsisException(e);
-        } catch (final IllegalAccessException e) {
-            throw new IsisException(e);
-        } catch (final InvocationTargetException e) {
-            throw new IsisException(e);
-        }
-    }
-
-    static String objectTypeFor(final ObjectSpecification objectSpec) {
-        return objectSpec.getFacet(ObjectSpecIdFacet.class).value().asString();
-    }
-
-    static StringProperty stringProperty() {
-        return new StringProperty();
-    }
-
-    static StringProperty stringPropertyEnum(String... enumValues) {
-        StringProperty stringProperty = stringProperty();
-        stringProperty._enum(Arrays.asList(enumValues));
-        if(enumValues.length >= 1) {
-            stringProperty._default(enumValues[0]);
-        }
-        return stringProperty;
-    }
-
-    static ArrayProperty arrayOfLinks() {
-        return new ArrayProperty()
-                .items(refToLinkModel());
-    }
-
-    static RefProperty refToLinkModel() {
-        return new RefProperty("#/definitions/LinkModel");
-    }
-
-    static RefProperty refToHrefModel() {
-        return new RefProperty("#/definitions/HrefModel");
-    }
-
-    static ArrayProperty arrayOfStrings() {
-        return new ArrayProperty().items(stringProperty());
-    }
-
-    static Response newResponse(final Caching caching) {
-        return Util.withCachingHeaders(new Response(), caching);
-    }
-
-    static Pattern tagPatternIsisAddons = Pattern.compile("^org\\.isisaddons\\.module\\.([^\\.]+)\\.(.+)$");
-    static Pattern tagPatternForFqcn = Pattern.compile("^.*\\.([^\\.]+)\\.([^\\.]+)$");
-    static Pattern tagPatternForSchemaTable = Pattern.compile("^([^\\.]+)\\.([^\\.]+)$");
-    static Pattern tagPatternForJaxbDto = Pattern.compile("^([^\\.]+)\\.(v[0-9][^\\.]*)([^\\.]+)$");
-    static String tagFor(final String str) {
-        if (str.startsWith("org.apache.isis")) {
-            return "> apache isis internals";
-        }
-
-        Matcher matcher;
-        matcher = tagPatternIsisAddons.matcher(str);
-        if (matcher.matches()) {
-            return "isisaddons " + matcher.group(1);
-        }
-        matcher = Pattern.compile("^.*\\.([^\\.]+)\\.(v[0-9][^\\.]*)\\.([^\\.]+)$").matcher(str);
-        if (matcher.matches()) {
-            return matcher.group(1);
-        }
-        matcher = tagPatternForFqcn.matcher(str);
-        if (matcher.matches()) {
-            return matcher.group(1);
-        }
-        matcher = tagPatternForSchemaTable.matcher(str);
-        if (matcher.matches()) {
-            // special cases for other Isis addons
-            if(str.startsWith("isis")) {
-                return "isisaddons " + str.substring(4, str.indexOf("."));
-            }
-            return matcher.group(1);
-        }
-
-
-        return str;
-    }
-
-
 }

http://git-wip-us.apache.org/repos/asf/isis/blob/2efbf48f/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/Tagger.java
----------------------------------------------------------------------
diff --git a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/Tagger.java b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/Tagger.java
new file mode 100644
index 0000000..19f71d9
--- /dev/null
+++ b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/Tagger.java
@@ -0,0 +1,61 @@
+/*
+ *  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.
+ */
+package org.apache.isis.core.metamodel.services.swagger.internal;
+
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+class Tagger {
+
+    static Pattern tagPatternIsisAddons = Pattern.compile("^org\\.isisaddons\\.module\\.([^\\.]+)\\.(.+)$");
+    static Pattern tagPatternForFqcn = Pattern.compile("^.*\\.([^\\.]+)\\.([^\\.]+)$");
+    static Pattern tagPatternForSchemaTable = Pattern.compile("^([^\\.]+)\\.([^\\.]+)$");
+    static Pattern tagPatternForJaxbDto = Pattern.compile("^.*\\.([^\\.]+)\\.(v[0-9][^\\.]*)\\.([^\\.]+)$");
+
+    String tagFor(final String str, final String fallback) {
+        if (str.startsWith("org.apache.isis")) {
+            return "> apache isis internals";
+        }
+
+        Matcher matcher;
+        matcher = tagPatternIsisAddons.matcher(str);
+        if (matcher.matches()) {
+            return "isisaddons " + matcher.group(1);
+        }
+        matcher = tagPatternForJaxbDto.matcher(str);
+        if (matcher.matches()) {
+            return matcher.group(1);
+        }
+        matcher = tagPatternForFqcn.matcher(str);
+        if (matcher.matches()) {
+            return matcher.group(1);
+        }
+        matcher = tagPatternForSchemaTable.matcher(str);
+        if (matcher.matches()) {
+            // special cases for other Isis addons
+            if (str.startsWith("isis")) {
+                return "isisaddons " + str.substring(4, str.indexOf("."));
+            }
+            return matcher.group(1);
+        }
+
+        return fallback != null? fallback: str;
+    }
+
+}

http://git-wip-us.apache.org/repos/asf/isis/blob/2efbf48f/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/Util.java
----------------------------------------------------------------------
diff --git a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/Util.java b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/Util.java
index 4ab66e2..1ad9264 100644
--- a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/Util.java
+++ b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/Util.java
@@ -129,13 +129,15 @@ public final class Util {
 
     static List<ObjectAction> actionsOf(
             final ObjectSpecification objectSpec,
-            final SwaggerService.Visibility visibility) {
+            final SwaggerService.Visibility visibility,
+            final ClassExcluder classExcluder) {
         final List<ActionType> actionTypes = actionTypesFor(visibility);
 
         return objectSpec.getObjectActions(actionTypes, Contributed.INCLUDED, new Filter<ObjectAction>() {
             @Override
             public boolean accept(final ObjectAction objectAction) {
-                return !visibility.isPublic() || isVisibleForPublic(objectAction);
+                return !classExcluder.exclude(objectAction) &&
+                        !visibility.isPublic() || isVisibleForPublic(objectAction);
             }
         });
     }

http://git-wip-us.apache.org/repos/asf/isis/blob/2efbf48f/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/ValuePropertyFactory.java
----------------------------------------------------------------------
diff --git a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/ValuePropertyFactory.java b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/ValuePropertyFactory.java
index c00990e..9b3a4d0 100644
--- a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/ValuePropertyFactory.java
+++ b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/ValuePropertyFactory.java
@@ -116,6 +116,8 @@ public class ValuePropertyFactory {
                 return new StringProperty();
             }
         };
+        propertyFactoryByClass.put(char.class, stringFactory);
+        propertyFactoryByClass.put(Character.class, stringFactory);
         propertyFactoryByClass.put(char[].class, stringFactory);
         propertyFactoryByClass.put(String.class, stringFactory);
 

http://git-wip-us.apache.org/repos/asf/isis/blob/2efbf48f/core/metamodel/src/test/java/org/apache/isis/core/metamodel/services/swagger/internal/GenerationTest.java
----------------------------------------------------------------------
diff --git a/core/metamodel/src/test/java/org/apache/isis/core/metamodel/services/swagger/internal/GenerationTest.java b/core/metamodel/src/test/java/org/apache/isis/core/metamodel/services/swagger/internal/GenerationTest.java
new file mode 100644
index 0000000..f89c9bf
--- /dev/null
+++ b/core/metamodel/src/test/java/org/apache/isis/core/metamodel/services/swagger/internal/GenerationTest.java
@@ -0,0 +1,48 @@
+/*
+ *  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.
+ */
+package org.apache.isis.core.metamodel.services.swagger.internal;
+
+import java.util.Set;
+
+import org.junit.Test;
+
+import static org.hamcrest.CoreMatchers.is;
+import static org.hamcrest.Matchers.contains;
+import static org.junit.Assert.assertThat;
+
+public class GenerationTest {
+
+    @Test
+    public void testAddReference() throws Exception {
+
+        Generation context = new Generation(null, null, null);
+
+        context.addSwaggerReference("foo");
+        context.addSwaggerReference("bar");
+        context.addSwaggerReference("baz");
+
+        context.addSwaggerDefinition("foo");
+        context.addSwaggerDefinition("box");
+
+        Set<String> referencesWithoutDefinition = context.getReferencesWithoutDefinition();
+        assertThat(referencesWithoutDefinition.size(), is(2));
+        assertThat(referencesWithoutDefinition, contains("bar", "baz"));
+
+    }
+}
\ No newline at end of file


[04/52] [abbrv] isis git commit: ISIS-1243: renamed rg.adoc to rgcms.adoc

Posted by mg...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_AuditingService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_AuditingService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_AuditingService.adoc
index bc58a97..a07c4fb 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_AuditingService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_AuditingService.adoc
@@ -46,7 +46,7 @@ The module also provides:
 
 * `AuditingServiceRepository` service to to search for persisted `AuditEntry``s.  None of its actions are visible in the user interface (they are all `@Programmatic`).
 
-* `AuditingServiceContributions` which contrbutes collections to the xref:rg.adoc#_rg_classes_mixins_manpage-HasTransactionId[ `HasTransactionId`] interface. This will therefore display all audit entries that occurred in a given transaction, in other words whenever a command, a published event or another audit entry is displayed.
+* `AuditingServiceContributions` which contrbutes collections to the xref:rgcms.adoc#_rgcms_classes_mixins_manpage-HasTransactionId[ `HasTransactionId`] interface. This will therefore display all audit entries that occurred in a given transaction, in other words whenever a command, a published event or another audit entry is displayed.
 
 
 
@@ -67,7 +67,7 @@ The (non-ASF) http://github.com/isisaddons/isis-module-audit[Isis addons' audit]
 this service (`AuditingService`), and also provides a number of related domain services (`AuditingServiceMenu`,
 `AuditingServiceRepository` and `AuditingServiceContributions`).
 
-Assuming that an `AppManifest` is being used to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app])
+Assuming that an `AppManifest` is being used to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app])
 then this can be activated by updating the `pom.xml` and updating the `AppManifest#getModules()` method.
 
 If menu items or contributions are not required in the UI, these can be suppressed either using security or by
@@ -81,5 +81,5 @@ The auditing service works very well with the xref:rgsvc.adoc#_rgsvc-spi_Command
 
 You may also want to configure the xref:rgsvc.adoc#_rgsvc-spi_PublishingService[`PublishingService`].
 
-All three of these services collaborate implicitly by way of the xref:rg.adoc#_rg_classes_mixins_manpage-HasTransactionId[`HasTransactionId`] interface.
+All three of these services collaborate implicitly by way of the xref:rgcms.adoc#_rgcms_classes_mixins_manpage-HasTransactionId[`HasTransactionId`] interface.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_BackgroundCommandService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_BackgroundCommandService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_BackgroundCommandService.adoc
index 7bfed67..45518b9 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_BackgroundCommandService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_BackgroundCommandService.adoc
@@ -109,7 +109,7 @@ of this service (`BackgroundCommandService`), and also provides a number of rela
 module also provides service implementations of the
 xref:rgsvc.adoc#_rgsvc-spi_CommandService[`CommandService`].
 
-Assuming that an `AppManifest` is being used to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app])
+Assuming that an `AppManifest` is being used to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app])
 then this can be activated by updating the `pom.xml` and updating the `AppManifest#getModules()` method.
 
 If contributions are not required in the UI, these can be suppressed either using security or by implementing a

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ClassDiscoveryService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ClassDiscoveryService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ClassDiscoveryService.adoc
index 13576ff..583acef 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ClassDiscoveryService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ClassDiscoveryService.adoc
@@ -8,7 +8,7 @@
 
 The `ClassDiscovery` service is used to automatically discover subclasses of any given type on the classpath.  The primary use case is to support "convention-over-configuration" designs that work with a minimum of configuration.
 
-This service is used by the xref:rg.adoc#_rg_classes_super_manpage-FixtureScripts[`FixtureScripts`] service to automatically locate any xref:rg.adoc#_rg_classes_super_manpage-FixtureScript[`FixtureScript`] implementations.
+This service is used by the xref:rgcms.adoc#_rgcms_classes_super_manpage-FixtureScripts[`FixtureScripts`] service to automatically locate any xref:rgcms.adoc#_rgcms_classes_super_manpage-FixtureScript[`FixtureScript`] implementations.
 
 
 
@@ -44,7 +44,7 @@ This implementation is also used to discover domain services annotated with xref
 == Usage
 
 The usage will vary depending upon the conventions of the design.  As of 1.9.0, the usage of the service has been
-centralized such that the packages to be scanned are located from the xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[`AppManifest`]'s `#getModules()` method.
+centralized such that the packages to be scanned are located from the xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`]'s `#getModules()` method.
 
 For example, the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype]'s app manifest includes:
 
@@ -71,7 +71,7 @@ Other usages of the `ClassDiscoveryService` are likely to work in a similar way,
 == Registering the Services
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `ClassDiscoveryService2` service is automatically registered and injected (it is annotated with
 `@DomainService`) so no further configuration is required.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_CommandService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_CommandService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_CommandService.adoc
index d795b11..0382e91 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_CommandService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_CommandService.adoc
@@ -12,8 +12,8 @@ Persistent `Command`s support several use cases:
 
 * they enable profiling of the running application (which actions are invoked then most often, what is their response time)
 * they act as a parent to any background commands that might be invoked through the xref:rgsvc.adoc#_rgsvc-api_BackgroundService[`BackgroundService`]
-* if xref:rgsvc.adoc#_rgsvc-spi_AuditingService[auditing] is configured, they provide better audit information, since the `Command` (the 'cause' of an action) can be correlated to the audit records (the "effect" of the action) by way of the xref:rg.adoc#_rg_classes_mixins_manpage-HasTransactionId[`transactionId`]
-* if xref:rgsvc.adoc#_rgsvc-spi_PublishingService[publishing] is configured, they provide better traceability as the `Command` is also correlated with any published events, again through the unique  xref:rg.adoc#_rg_classes_mixins_manpage-HasTransactionId[`transactionId`]
+* if xref:rgsvc.adoc#_rgsvc-spi_AuditingService[auditing] is configured, they provide better audit information, since the `Command` (the 'cause' of an action) can be correlated to the audit records (the "effect" of the action) by way of the xref:rgcms.adoc#_rgcms_classes_mixins_manpage-HasTransactionId[`transactionId`]
+* if xref:rgsvc.adoc#_rgsvc-spi_PublishingService[publishing] is configured, they provide better traceability as the `Command` is also correlated with any published events, again through the unique  xref:rgcms.adoc#_rgcms_classes_mixins_manpage-HasTransactionId[`transactionId`]
 * the associated xref:rgant.adoc#_rgant-Action_command[`@Action#command()`] annotation attribute also allows action invocations to be performed in the background. In this case the act of invoking the action on an object instead returns the `Command` to the user.
 
 
@@ -76,7 +76,7 @@ of this service (`CommandService`), and also provides a number of related domain
 module also provides service implementations of the
 xref:rgsvc.adoc#_rgsvc-spi_CommandService[`BackgroundCommandService`].
 
-Assuming that an `AppManifest` is being used to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app])
+Assuming that an `AppManifest` is being used to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app])
 then this can be activated by updating the `pom.xml` and updating the `AppManifest#getModules()` method.
 
 If contributions are not required in the UI, these can be suppressed either using security or by implementing a
@@ -96,5 +96,5 @@ The services provided by this module combines very well with the xref:rgsvc.adoc
 
 You may also want to configure the xref:rgsvc.adoc#_rgsvc-spi_PublishingService[`PublishingService`].
 
-All three of these services collaborate implicitly by way of the xref:rg.adoc#_rg_classes_mixins_manpage-HasTransactionId[`HasTransactionId`] interface.
+All three of these services collaborate implicitly by way of the xref:rgcms.adoc#_rgcms_classes_mixins_manpage-HasTransactionId[`HasTransactionId`] interface.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ContentNegotiationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ContentNegotiationService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ContentNegotiationService.adoc
index e6098d9..1f2f08b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ContentNegotiationService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ContentNegotiationService.adoc
@@ -187,7 +187,7 @@ If the property is not set, then the default depends on the xref:rgcfg.adoc#_rgc
 == Registering the Services
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' default
+`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' default
 implementation of `ContentNegotiationService` service is automatically registered and injected (it is annotated with
 `@DomainService`) so no further configuration is required.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_EmailNotificationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_EmailNotificationService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_EmailNotificationService.adoc
index 6e51637..9b63d8e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_EmailNotificationService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_EmailNotificationService.adoc
@@ -64,7 +64,7 @@ To ensure that your alternative implementation takes the place of the default im
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' default
+`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' default
 implementation of `EmailNotificationService` service is automatically registered and injected (it is annotated with
 `@DomainService`) so no further configuration is required.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ErrorReportingService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ErrorReportingService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ErrorReportingService.adoc
index 976c610..32573ea 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ErrorReportingService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ErrorReportingService.adoc
@@ -100,7 +100,7 @@ image::{_imagesdir}reference-services-spi/ErrorReportingService/kitchensink-exam
 == Registering the Services
 
 There is no default implementation of this service.  To register your own implementation (and assuming that an
-`AppManifest` is being used to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]), then just
+`AppManifest` is being used to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]), then just
 ensure that the implementation is on the classpath and the module containing the implementation is returned in
 `AppManifest#getModules()`.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_EventSerializer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_EventSerializer.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_EventSerializer.adoc
index 10b29cf..9aed9ab 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_EventSerializer.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_EventSerializer.adoc
@@ -25,7 +25,7 @@ public interface EventSerializer {
 }
 ----
 <1> returns an object for maximum flexibility, which is then handed off to the `PublishingService`.
-<2> standard metadata about the event, such as the user, the xref:rg.adoc#_rg_classes_mixins_manpage-HasTransactionId[`transactionId`], date/time etc
+<2> standard metadata about the event, such as the user, the xref:rgcms.adoc#_rgcms_classes_mixins_manpage-HasTransactionId[`transactionId`], date/time etc
 <3> for published actions, will generally be an `EventPayloadForActionInvocation` (or subclass thereof); for published objects, will generally be an `EventPayloadForObjectChanged` (or subclass thereof)
 
 It's important to make sure that the publishing service implementation is able to handle the serialized form.  Strings are a good lowest common denominator, but in some cases a type-safe equivalent, such as a w3c DOM `Document` or JSON node might be passed instead.
@@ -62,7 +62,7 @@ implementation of this service (`RestfulObjectsSpecEventSerializer`) that serial
 objects into a format based on the Restful Objects specification.  It also (as you might imagine) provides an
 implementation of the xref:rgsvc.adoc#_rgsvc-spi_PublishingService[`PublishingService`].
 
-Assuming that an `AppManifest` is being used to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app])
+Assuming that an `AppManifest` is being used to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app])
 then this can be activated by updating the `pom.xml` and updating the `AppManifest#getModules()` method.
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ExceptionRecognizer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ExceptionRecognizer.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ExceptionRecognizer.adoc
index a120ccd..200b11f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ExceptionRecognizer.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ExceptionRecognizer.adoc
@@ -97,7 +97,7 @@ If you want to recognize and handle additional exceptions (for example to captur
 == Registering the Services
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then the default
+`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then the default
 implementations provided by the framework (`DomainObjectContainerDefault` and
 `ExceptionRecognizerCompositeForJdoObjectStore`) will be registered.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_FixtureScriptsSpecificationProvider.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_FixtureScriptsSpecificationProvider.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_FixtureScriptsSpecificationProvider.adoc
index 5a8d854..4fffe73 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_FixtureScriptsSpecificationProvider.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_FixtureScriptsSpecificationProvider.adoc
@@ -11,7 +11,7 @@ xref:rgsvc.adoc#_rgsvc-api_FixtureScriptsDefault[`FixtureScriptsDefault`] domain
 location to search for fixture scripts and other settings.
 
 The service is only used if the `FixtureScriptsDefault` service is instantiated as a fallback by the framework.  If
-the application provides its own subclass of xref:rg.adoc#_rg_classes_super_manpage-FixtureScripts[`FixtureScripts`]
+the application provides its own subclass of xref:rgcms.adoc#_rgcms_classes_super_manpage-FixtureScripts[`FixtureScripts`]
 superclass, then this provider service is not used.
 
 [TIP]

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_LocaleProvider.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_LocaleProvider.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_LocaleProvider.adoc
index 90a5a97..4677e31 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_LocaleProvider.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_LocaleProvider.adoc
@@ -50,7 +50,7 @@ Currently there is no equivalent implementation for the xref:ugvro.adoc#[Restful
 == Registering the Services
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]), _and_ that the
+`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]), _and_ that the
 xref:ugvw.adoc#[Wicket viewer] is being used, then an implementation of `LocaleProvider` is
 automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_PublishingService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_PublishingService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_PublishingService.adoc
index 9450b7c..62634ff 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_PublishingService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_PublishingService.adoc
@@ -25,7 +25,7 @@ public interface PublishingService {
     void setEventSerializer(EventSerializer eventSerializer);   // <3>
 }
 ----
-<1> standard metadata about the event, such as the user, the xref:rg.adoc#_rg_classes_mixins_manpage-HasTransactionId[`transactionId`], date/time etc
+<1> standard metadata about the event, such as the user, the xref:rgcms.adoc#_rgcms_classes_mixins_manpage-HasTransactionId[`transactionId`], date/time etc
 <2> for published actions, an `EventPayloadForActionInvocation` (or subclass thereof); for published objects, an `EventPayloadForObjectChanged` (or subclass thereof)
 <3> injects in the xref:rgsvc.adoc#_rgsvc-spi_EventSerializer[`EventSerializer`] service.  This is deprecated because not every implementation is required to use an `EventSerializer` so its inclusion within the SPI of `PublishingService` was in retrospect a mistake.
 
@@ -66,7 +66,7 @@ here is that an event bus can poll this table to grab pending events and dispatc
 The (non-ASF) http://github.com/isisaddons/isis-module-publishmq[Isis addons' publishmq] module provides an
 implementation (`org.isisaddons.module.publismq.dom.servicespi.PublishingServiceUsingActiveMq`) that publishes each 
 action invocation as an event on an link:http://activemq.apache.org[ActiveMQ] message queue.  These are converted into
-a canonical XML form (the xref:rg.adoc#_rg_schema-aim[ActionInvocationMemento] schema) using the
+a canonical XML form (the xref:rgcms.adoc#_rgcms_schema-aim[ActionInvocationMemento] schema) using the
 `ActionInvocationMementoDtoUtils` class; the idea
 being that subscribers on the ActiveMQ message queue can then query back for further information, for example using
 the xref:ugvro.adoc#[RestfulObjects viewer].
@@ -161,7 +161,7 @@ There is no default implementation of this service provided by the core Apache I
 
 Both the (non-ASF) Isis addons' http://github.com/isisaddons/isis-module-publishing[publishing] module and the
 http://github.com/isisaddons/isis-module-publishmq[publishmq] module provide implementations of this service.
-Assuming that an `AppManifest` is being used to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app])
+Assuming that an `AppManifest` is being used to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app])
 then this can be activated by updating the `pom.xml` and updating the `AppManifest#getModules()` method.
 
 The modules also provide services that contribute to the UI.  If contributions are not required in the UI, these can be
@@ -178,7 +178,7 @@ The `PublishingService` is intended for coarse-grained publish/subscribe for sys
 
 The xref:rgsvc.adoc#_rgsvc-api_EventBusService[`EventBusService`] meanwhile is intended for fine-grained publish/subscribe for object-to-object interactions within an Apache Isis domain object model. The event propagation is strictly in-memory, and there are no restrictions on the object acting as the event (it need not be serializable, for example).
 
-All three of these services collaborate implicitly by way of the xref:rg.adoc#_rg_classes_mixins_manpage-HasTransactionId[`HasTransactionId`] interface.
+All three of these services collaborate implicitly by way of the xref:rgcms.adoc#_rgcms_classes_mixins_manpage-HasTransactionId[`HasTransactionId`] interface.
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_RepresentationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_RepresentationService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_RepresentationService.adoc
index f7349bd..b85c8fe 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_RepresentationService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_RepresentationService.adoc
@@ -93,7 +93,7 @@ further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementatio
 == Registering the Services
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' default implementation of `RepresentationService` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
+`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' default implementation of `RepresentationService` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_TranslationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_TranslationService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_TranslationService.adoc
index cea968d..5f7b1a3 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_TranslationService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_TranslationService.adoc
@@ -61,7 +61,7 @@ For more details on the implementation, see xref:ugbtb.adoc#_ugbtb_more-advanced
 == Registering the Services
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `TranslationService` service (along with the supporting menu service) are automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
 
 If the menu items are not required then these can be suppressed either using security or by implementing a xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling_vetoing-visibility[vetoing subscriber].

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_TranslationsResolver.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_TranslationsResolver.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_TranslationsResolver.adoc
index 2f996d8..74d15b7 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_TranslationsResolver.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_TranslationsResolver.adoc
@@ -47,7 +47,7 @@ Currently there is no equivalent implementation for the xref:ugvro.adoc#[Restful
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]), _and_ that the xref:ugvw.adoc#[Wicket viewer] is being used, then an implementation of `TranslationsResolver` is
+`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]), _and_ that the xref:ugvw.adoc#[Wicket viewer] is being used, then an implementation of `TranslationsResolver` is
 automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
 
 To use an alternative implementation, use

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_tg_stop-scaffolding-start-coding.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_tg_stop-scaffolding-start-coding.adoc b/adocs/documentation/src/main/asciidoc/guides/_tg_stop-scaffolding-start-coding.adoc
index 9b144b8..0b88f42 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_tg_stop-scaffolding-start-coding.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_tg_stop-scaffolding-start-coding.adoc
@@ -307,7 +307,7 @@ Domain entities have state: either values (primitives, strings) or references to
 * for all non-optional properties will either need to prompt for a value, or calculate some suitable default
 * change the implementation of title, if need be
 * revisit the title, consider whether to use the xref:rgant.adoc#_rgant-Title[`@Title`] annotation
-** rather than the xref:rg.adoc#_rg_methods_reserved_manpage-title[`title()`] `title()` method
+** rather than the xref:rgcms.adoc#_rgcms_methods_reserved_manpage-title[`title()`] `title()` method
 * order the properties using the xref:rgant.adoc#_rgant-MemberOrder[`@MemberOrder`], also `@MemberGroupLayout`
 ** see also the docs on xref:ug.adoc#_ug_object-layout_static[static layouts]
 * use the xref:rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`] annotation to position property/action parameter labels either to the LEFT, TOP or NONE
@@ -324,10 +324,10 @@ Domain entities can also reference other domain entities. These references may b
 * update the corresponding domain service (for creation actoin)
 * use different techniques to obtain references (shown in drop-down list box)
 ** use the xref:rgant.adoc#_rgant-DomainObject_bounded[`@DomainObjectLayout(bounded=...)`] annotation on the referenced type if there are only a small number (bounded) of instances
-** use a xref:rg.adoc#_rg_methods_prefixes_manpage-choices[`choices...()`] supporting method
+** use a xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-choices[`choices...()`] supporting method
 *** on a property
 *** on an action parameter
-** use a xref:rg.adoc#_rg_methods_prefixes_manpage-autoComplete[`autoComplete...()`] supporting method
+** use a xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-autoComplete[`autoComplete...()`] supporting method
 *** on a property
 *** on an action parameter
 
@@ -348,7 +348,7 @@ Quick detour: often we want to set up defaults to go with choices. Sensible defa
 Returning back to references, Isis also supports vector (multi-valued) references to another object instances� in other words collections. We sometimes called these "parented" collections (to distinguish from a "standalone" collection as returned from an action)
 
 * Ensure that all domain classes implement `java.lang.Comparable`
-** use the xref:rg.adoc#_rg_classes_utility_manpage-ObjectContracts[`ObjectContracts`] utility class to help implement `Comparable`
+** use the xref:rgcms.adoc#_rgcms_classes_utility_manpage-ObjectContracts[`ObjectContracts`] utility class to help implement `Comparable`
 *** you can also `equals()`, `hashCode()`, `toString()`
 * Add a xref:ug.adoc#_ug_how-tos_class-structure_collections[collection] to one of the entities
 ** Use `SortedSet` as the class
@@ -413,7 +413,7 @@ Or, more pithily: "see it, use it, do it"
 * Use the xref:rgant.adoc#_rgant-Property_hidden[`Property(hidden=...)`] annotation to make properties invisible
 ** likewise xref:rgant.adoc#_rgant-Collection_hidden[`@Collection(hidden=...)`] for collections
 ** the xref:rgant.adoc#_rgant-Programmatic[`@Programmatic`]  annotation can also be used and in many cases is to be preferred; the difference is that the latter means the member is not part of the Apache Isis metamodel.
-* Use the xref:rg.adoc#_rg_methods_prefixes_manpage-hide[`hide...()`] supporting method on properties, collections and actions to make a property/collection/action invisible according to some imperative rule
+* Use the xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-hide[`hide...()`] supporting method on properties, collections and actions to make a property/collection/action invisible according to some imperative rule
 
 
 === Use it!
@@ -421,14 +421,14 @@ Or, more pithily: "see it, use it, do it"
 * Use the xref:rgant.adoc#_rgant-Property_editing[`Property(editing=...)`] annotation to make property read-only
 ** likewise xref:rgant.adoc#_rgant-Collection_editing[`@Collection(editing=...)`] for collections
 ** alternatively, use xref:rgant.adoc#_rgant-DomainObject_editing[`@DomainObject(editing=...)`] to disable editing for all properties/collections
-* Use the xref:rg.adoc#_rg_methods_prefixes_manpage-disable[`disable...()`] supporting method on properties and actions to make a property/action disabled according to some imperative rule
+* Use the xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-disable[`disable...()`] supporting method on properties and actions to make a property/action disabled according to some imperative rule
 
 
 === Do it!
 
 * use the xref:rgant.adoc#_rgant-Property_regexPattern[`@Property(regexPattern=...)`] annotation to specify a regex pattern for properties, and use xref:rgant.adoc#_rgant-Parameter_regexPattern[`@Parameter(regexPattern=...)`] for parameters
 * use the xref:rgant.adoc#_rgant-Property_maxLength[`@Property(maxLength=...)`] annotation to indicate a maxmum number of characters, and xref:rgant.adoc#_rgant-Parameter_maxLength[`@Parameter(maxLength=...)`] for parameters
-* Use the xref:rg.adoc#_rg_methods_prefixes_manpage-validate[`validate...()`] supporting method on properties or action parameter
+* Use the xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-validate[`validate...()`] supporting method on properties or action parameter
 * optional: for any data type:
 ** use the xref:rgant.adoc#_rgant-Property_mustSatisfy[`Property(mustSatisfy=...)`] and xref:rgant.adoc#_rgant-Parameter_mustSatisfy[`Parameter(mustSatisfy=...)`] annotations to specify arbitrary constraints on properties and parameters
 
@@ -602,7 +602,7 @@ In most cases users can accomplish the business operations they need by invoking
 
 Also, if using Apache Isis' REST API then the REST client may be a native application (on a smartphone or tablet, say) that is deployed by a third party. In these cases exposing the entities directly would be inadvisable because a refactoring of the domain entity would change the REST API and probably break that REST client.
 
-To support these use cases, Apache Isis therefore allows you to write a view model, either by annotating the class with xref:rgant.adoc#_rgant-ViewModel[`@ViewModel`] or (for more control) by implementing the xref:rg.adoc#_rg_classes_super_manpage-AbstractViewModel[`ViewModel`] interface.
+To support these use cases, Apache Isis therefore allows you to write a view model, either by annotating the class with xref:rgant.adoc#_rgant-ViewModel[`@ViewModel`] or (for more control) by implementing the xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractViewModel[`ViewModel`] interface.
 
 * build a view model summarizing the state of the app (a "dashboard")
 * write a new `@HomePage` domain service action returning this dashboard viewmodel (and remove the `@HomePage` annotation from any other domain service if present)

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_building-blocks.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_building-blocks.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_building-blocks.adoc
index 6e20ce9..1b7e2e5 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_building-blocks.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_building-blocks.adoc
@@ -273,13 +273,13 @@ xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling_mixins[this topic on mixin]s.
 [[_ug_core-concepts_building-blocks_domain-events]]
 == Domain Events
 
-NOTE: TODO; see xref:rg.adoc#_rg_classes_domainevent[domain event] classes.
+NOTE: TODO; see xref:rgcms.adoc#_rgcms_classes_domainevent[domain event] classes.
 
 
 
 === UI Events (`1.11.0-SNAPSHOT`)
 
-NOTE: TODO; see xref:rg.adoc#_rg_classes_uievent[UI event] classes.
+NOTE: TODO; see xref:rgcms.adoc#_rgcms_classes_uievent[UI event] classes.
 
 
 
@@ -321,7 +321,7 @@ xref:rgsvc.adoc#_rgsvc-api_BookmarkService[`BookmarkService`].  Deep links meanw
 the xref:rgant.adoc#_rgant-DeepLinkService[`@DeepLinkService`].
 
 OIDs can also be converted into XML format, useful for integration scenarios.  The
-xref:rg.adoc#_rg_schema-common[common schema] XSD defines the `oidDto` complex type for precisely this purpose.
+xref:rgcms.adoc#_rgcms_schema-common[common schema] XSD defines the `oidDto` complex type for precisely this purpose.
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_cqrs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_cqrs.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_cqrs.adoc
index e163058..5f5b82f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_cqrs.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_cqrs.adoc
@@ -17,7 +17,7 @@ Comparing CQRS to Apache Isis, the most obvious difference is that Apache Isis d
 
 There are other reasons though why a separate read model might make sense, such as to precompute particular queries, or against denormalized data.  In these cases Apache Isis can often provide a reasonable alternative, namely to map domain entities against RDBMS views, either materialized views or dynamic.  In such cases there is still only a single physical datastore, and so transactional integrity is retained.
 
-Or, the CQRS architecture can be more fully implemented with Apache Isis by introducing a separate read model, synchronized using the xref:rgsvc.adoc#_rgsvc-api_PublishingService[`PublishingService`], or using xref:rg.adoc#_rg_classes_super_manpage-AbstractSubscriber[subscribers]  on the xref:rgsvc.adoc#_rgsvc-api_EventBusService[`EventBusService`].  One can then use xref:ugbtb.adoc#_ugbtb_more-advanced_view-models[view models] to surface the data in the external read datastore.
+Or, the CQRS architecture can be more fully implemented with Apache Isis by introducing a separate read model, synchronized using the xref:rgsvc.adoc#_rgsvc-api_PublishingService[`PublishingService`], or using xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractSubscriber[subscribers]  on the xref:rgsvc.adoc#_rgsvc-api_EventBusService[`EventBusService`].  One can then use xref:ugbtb.adoc#_ugbtb_more-advanced_view-models[view models] to surface the data in the external read datastore.
 
 With respect to commands, Apache Isis does of course support the xref:rgsvc.adoc#_rgsvc-spi_CommandService[`CommandService`] which allows each business action to be reified into a `Command`.  However, names are misleading here: Apache Isis' commands are relatively passive, merely recording the intent of the user to invoke some operation.  In a CQRS architecture, though, commands take a more active role, locating and acting upon the domain objects.  More significantly, in CQRS each command has its own class, such as `PlaceOrderCommand`, instantiated by the client and then executed.  With Apache Isis, though, the end-user merely invokes the `placeOrder(...)` action upon the domain object; the framework itself creates the `Command` as a side-effect of this.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_event-sourcing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_event-sourcing.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_event-sourcing.adoc
index 77ff52b..f9653d8 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_event-sourcing.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_event-sourcing.adoc
@@ -14,6 +14,6 @@ Although it might seem counter-intuitive to be able store persistent state in th
 
 When combined with CQRS we see a command that triggers a business operation, and an event that results from it.  So, a `PlaceOrderCommand` command can result in an `OrderPlacedEvent` event.  A subscriber to this event might then generate a further command to act upon some other system (eg to dispatch the system).  Note that the event might be dispatched and consumed in-process or alternatively this might occur out-of-process.  If the latter, then the subscriber will operate within a separate transaction, meaning the usual eventual consistency concerns and also compensating actions if a rollback is required.  CQRS/event sourcing advocates point out - correctly  that this is just how things are in the "real world" too.
 
-In Apache Isis every business action (and indeed, property and collection) emits domain events through the xref:rgsvc.adoc#_rgsvc-api_EventBusService[`EventBusService`] , and can optionally also be published through the xref:rgsvc.adoc#_rgsvc-spi_PublishingService[`PublishingService`].  The former are dispatched and consumed in-process and within the same transaction, and for this reason the xref:rg.adoc#_rg_classes_super_manpage-AbstractSubscriber[subscribers] can also veto the events.  The latter are intended for out-of-process consumption; the (non-ASF) http://github.com/isisaddons/isis-module-publishing[Isis addons' publishing] and http://github.com/isisaddons/isis-module-publishmq[Isis addons' publishmq] modules provide implementations for dispatching either through a RDBMS database table, or directly through to an link:http://camel.apache.org[ActiveMQ] message queue (eg wired up to link:http://camel.apache.org[Apache Camel] event bus).
+In Apache Isis every business action (and indeed, property and collection) emits domain events through the xref:rgsvc.adoc#_rgsvc-api_EventBusService[`EventBusService`] , and can optionally also be published through the xref:rgsvc.adoc#_rgsvc-spi_PublishingService[`PublishingService`].  The former are dispatched and consumed in-process and within the same transaction, and for this reason the xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractSubscriber[subscribers] can also veto the events.  The latter are intended for out-of-process consumption; the (non-ASF) http://github.com/isisaddons/isis-module-publishing[Isis addons' publishing] and http://github.com/isisaddons/isis-module-publishmq[Isis addons' publishmq] modules provide implementations for dispatching either through a RDBMS database table, or directly through to an link:http://camel.apache.org[ActiveMQ] message queue (eg wired up to link:http://camel.apache.org[Apache Camel] event bus).
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_ug_faqs_restful-image-property.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_faqs_restful-image-property.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_faqs_restful-image-property.adoc
index 0c5a0db..12ddcf2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_faqs_restful-image-property.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_faqs_restful-image-property.adoc
@@ -15,6 +15,6 @@ This is in the form:
 
     (filename):(mime type):(binary data in base64)
 
-This is basically the xref:rg.adoc#_rg_classes_value-types_manpage-Blob[`Blob`] value type, in string form.
+This is basically the xref:rgcms.adoc#_rgcms_classes_value-types_manpage-Blob[`Blob`] value type, in string form.
 
 To use, split the parts then format the mime type and base64 data correctly before using as source in an `<img>` tag.

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_business-rules.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_business-rules.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_business-rules.adoc
index 53ec064..aeea83e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_business-rules.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_business-rules.adoc
@@ -10,7 +10,7 @@ NOTE: TODO
 
 == Visibility ("see it")
 
-NOTE: TODO - xref:rg.adoc#_rg_methods_prefixes_manpage-hide[`hide...()`]
+NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-hide[`hide...()`]
 
 ### Hide a Property
 
@@ -27,7 +27,7 @@ NOTE: TODO - xref:rg.adoc#_rg_methods_prefixes_manpage-hide[`hide...()`]
 
 == Usability ("use it")
 
-NOTE: TODO - xref:rg.adoc#_rg_methods_prefixes_manpage-disable[`disable...()`]
+NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-disable[`disable...()`]
 
 ### Disable a Property
 
@@ -53,7 +53,7 @@ In the Wicket viewer this means disabling the edit button.
 
 == Validity ("do it")
 
-NOTE: TODO - xref:rg.adoc#_rg_methods_prefixes_manpage-validate[`validate...()`], xref:rg.adoc#_rg_methods_prefixes_manpage-validateAddTo[`validateAddTo...()`], xref:rg.adoc#_rg_methods_prefixes_manpage-validateRemoveFrom[`validateRemoveFrom...()`] and xref:rg.adoc#_rg_methods_reserved_manpage-validate[`validate()`]
+NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-validate[`validate...()`], xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-validateAddTo[`validateAddTo...()`], xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-validateRemoveFrom[`validateRemoveFrom...()`] and xref:rgcms.adoc#_rgcms_methods_reserved_manpage-validate[`validate()`]
 
 
 ### Validate (change to) a Property

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_derived-members.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_derived-members.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_derived-members.adoc
index 7caa497..abe2ae8 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_derived-members.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_derived-members.adoc
@@ -39,10 +39,10 @@ public class Customer {
 
 == Trigger on property change
 
-NOTE: TODO - xref:rg.adoc#_rg_methods_prefixes_manpage-modify[`modify...()`], xref:rg.adoc#_rg_methods_prefixes_manpage-clear[`clear...()`]
+NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-modify[`modify...()`], xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-clear[`clear...()`]
 
 
 
 == Trigger on collection change
 
-NOTE: TODO - xref:rg.adoc#_rg_methods_prefixes_manpage-addTo[`addTo...()`], xref:rg.adoc#_rg_methods_prefixes_manpage-removeFrom[`removeFrom...()`]
+NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-addTo[`addTo...()`], xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-removeFrom[`removeFrom...()`]

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_domain-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_domain-services.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_domain-services.adoc
index 076007f..16c131a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_domain-services.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_domain-services.adoc
@@ -240,7 +240,7 @@ The framework provides a number of request-scoped services, include a scratchpad
 
 == Registering domain services
 
-The easiest way to register domain services is using xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[`AppManifest`] to specify the modules
+The easiest way to register domain services is using xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`] to specify the modules
 which contain xref:rgant.adoc#_rgant-DomainService[`@DomainService`]-annotated classes.
 
 For example:
@@ -309,5 +309,5 @@ Shutdown is similar; the framework will call any method annotated with xref:rgan
 
 == The getId() method
 
-Optionally, a service may provide a xref:rg.adoc#_rg_methods_reserved_manpage-getId[`getId()`] method.  This method returns a logical identifier for a service, independent of its implementation.
+Optionally, a service may provide a xref:rgcms.adoc#_rgcms_methods_reserved_manpage-getId[`getId()`] method.  This method returns a logical identifier for a service, independent of its implementation.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_drop-downs-and-defaults.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_drop-downs-and-defaults.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_drop-downs-and-defaults.adoc
index 35b4948..c6bc242 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_drop-downs-and-defaults.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_drop-downs-and-defaults.adoc
@@ -13,15 +13,15 @@ NOTE: TODO
 
 ### Choices for Property
 
-NOTE: TODO - xref:rg.adoc#_rg_methods_prefixes_manpage-choices[`choices...()`]
+NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-choices[`choices...()`]
 
 ### Auto-complete for property
 
-NOTE: TODO - xref:rg.adoc#_rg_methods_prefixes_manpage-autoComplete[`autoComplete...()`]
+NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-autoComplete[`autoComplete...()`]
 
 ### Default for property
 
-NOTE: TODO -  xref:rg.adoc#_rg_methods_prefixes_manpage-default[`default...()`]
+NOTE: TODO -  xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-default[`default...()`]
 
 
 
@@ -32,19 +32,19 @@ NOTE: TODO
 
 ### Choices for action parameter
 
-NOTE: TODO - xref:rg.adoc#_rg_methods_prefixes_manpage-choices[`choices...()`]
+NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-choices[`choices...()`]
 
 ### Dependent choices for action params
 
-NOTE: TODO - xref:rg.adoc#_rg_methods_prefixes_manpage-choices[`choices...()`]
+NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-choices[`choices...()`]
 
 ### Auto-complete for action param
 
-NOTE: TODO - xref:rg.adoc#_rg_methods_prefixes_manpage-autoComplete[`autoComplete...()`]
+NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-autoComplete[`autoComplete...()`]
 
 ### Default for action param
 
-NOTE: TODO -  xref:rg.adoc#_rg_methods_prefixes_manpage-default[`default...()`]
+NOTE: TODO -  xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-default[`default...()`]
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships.adoc
index f94cfab..f7ec25f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships.adoc
@@ -8,7 +8,7 @@
 
 When an object is added to a 1:m bidirectional relationship, the child object must refer to the parent and the child must be added to the parent's children collection.
 
-If there were no database involved then we would have recommended that you use the link:http://www.two-sdg.demon.co.uk/curbralan/papers/MutualRegistration.pdf[mutual registration] pattern to ensure that both the parent and child are updated correctly.  (The  xref:rg.adoc#_rg_methods_prefixes_manpage-modify[`modify...()`] and xref:rg.adoc#_rg_methods_prefixes_manpage-clear[`clear...()`] supporting methods were introduced in the framework primarily to help support implement the mutual registration pattern.
+If there were no database involved then we would have recommended that you use the link:http://www.two-sdg.demon.co.uk/curbralan/papers/MutualRegistration.pdf[mutual registration] pattern to ensure that both the parent and child are updated correctly.  (The  xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-modify[`modify...()`] and xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-clear[`clear...()`] supporting methods were introduced in the framework primarily to help support implement the mutual registration pattern.
 
 However, in a relational database, these two operations in the domain object model correspond simply to updating the foreign key of the child table to reference the parent's primary key.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_object-titles-and-icons.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_object-titles-and-icons.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_object-titles-and-icons.adoc
index 3829211..2e4274d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_object-titles-and-icons.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_object-titles-and-icons.adoc
@@ -75,7 +75,7 @@ Titles can sometimes get be long and therefore rather cumbersome in "parented" t
 
 === Imperative style
 
-NOTE: TODO - see xref:rg.adoc#_rg_methods_reserved_manpage-title[`title()`]
+NOTE: TODO - see xref:rgcms.adoc#_rgcms_methods_reserved_manpage-title[`title()`]
 
 
 
@@ -84,7 +84,7 @@ NOTE: TODO - see xref:rg.adoc#_rg_methods_reserved_manpage-title[`title()`]
 
 The icon is often the same for all instances of a particular class, but it's also possible for an individual instance to return a custom icon.  This could represent the state of that object (eg a shipped order, say, or overdue library book).
 
-NOTE: TODO - xref:rg.adoc#_rg_methods_reserved_manpage-iconName[`iconName()`], xref:rgant.adoc#_rgant-DomainObjectLayout_cssClassFa[`@DomainObjectLayout#cssClassFa()`]
+NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_reserved_manpage-iconName[`iconName()`], xref:rgant.adoc#_rgant-DomainObjectLayout_cssClassFa[`@DomainObjectLayout#cssClassFa()`]
 
 
 
@@ -92,6 +92,6 @@ NOTE: TODO - xref:rg.adoc#_rg_methods_reserved_manpage-iconName[`iconName()`], x
 == Object CSS Styling
 
 
-It is also possible for an object to return a xref:rg.adoc#_rg_methods_reserved_manpage-cssClass[CSS class].  In conjunction with xref:ugvw.adoc#_ugvw_customisation_tweaking-css-classes[customized CSS] this can be used to apply arbitrary styling; for example each object could be rendered in a page with a different background colour.
+It is also possible for an object to return a xref:rgcms.adoc#_rgcms_methods_reserved_manpage-cssClass[CSS class].  In conjunction with xref:ugvw.adoc#_ugvw_customisation_tweaking-css-classes[customized CSS] this can be used to apply arbitrary styling; for example each object could be rendered in a page with a different background colour.
 
-NOTE: TODO - xref:rg.adoc#_rg_methods_reserved_manpage-cssClass[`cssClass()`], xref:rgant.adoc#_rgant-DomainObjectLayout_cssClass[`@DomainObjectLayout#cssClass()`] xref:rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`], xref:rgant.adoc#_rgant-PropertyLayout_cssClass[`@PropertyLayout#cssClass()`], xref:rgant.adoc#_rgant-CollectionLayout_cssClass[`@CollectionLayout#cssClass()`]
+NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_reserved_manpage-cssClass[`cssClass()`], xref:rgant.adoc#_rgant-DomainObjectLayout_cssClass[`@DomainObjectLayout#cssClass()`] xref:rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`], xref:rgant.adoc#_rgant-PropertyLayout_cssClass[`@PropertyLayout#cssClass()`], xref:rgant.adoc#_rgant-CollectionLayout_cssClass[`@CollectionLayout#cssClass()`]

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui_are-you-sure.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui_are-you-sure.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui_are-you-sure.adoc
index 483b0dd..93d9fe8 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui_are-you-sure.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui_are-you-sure.adoc
@@ -73,4 +73,4 @@ public String validateDelete(boolean areYouSure) {
 <1> invalid to return `this` (cannot render a deleted object)
 
 Note that the action itself does not use the boolean parameter, it is only
-used by the supporting xref:rg.adoc#_rg_methods_prefixes_manpage-validate[`validate...()`] method.
\ No newline at end of file
+used by the supporting xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-validate[`validate...()`] method.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_ugbtb_deployment_cmd-line.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_deployment_cmd-line.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_deployment_cmd-line.adoc
index 75ca98d..7bc9c9c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_deployment_cmd-line.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_deployment_cmd-line.adoc
@@ -29,7 +29,7 @@ The class also supports a number of command line arguments:
 |`-m`
 |`--manifest`
 |FQCN
-|Fully qualified class name of the xref:rg.adoc#_rg_classes_super_manpage-AppManifest[`AppManifest`] to use to bootstrap the system. +
+|Fully qualified class name of the xref:rgcms.adoc#_rgcms_classes_super_manpage-AppManifest[`AppManifest`] to use to bootstrap the system. +
 
 This flag sets/overrides the `isis.appManifest` configuration property to the specified class name.
 
@@ -37,7 +37,7 @@ This flag sets/overrides the `isis.appManifest` configuration property to the sp
 |`-f`
 |`--fixture`
 |FQCN
-|Fully qualified class name of the fixture (extending xref:rg.adoc#_rg_classes_super_manpage-FixtureScript[`FixtureScript`]) to be run to setup data. +
+|Fully qualified class name of the fixture (extending xref:rgcms.adoc#_rgcms_classes_super_manpage-FixtureScript[`FixtureScript`]) to be run to setup data. +
 
 This flag sets/overrides the `isis.fixtures` configuration property to the specified class name, and also sets the `isis.persistor.datanucleus.install-fixtures` configuration property to `true` to instruct the JDO/DataNucleus objectstore to actually load in the fixtures. +
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_decoupling_mixins.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_decoupling_mixins.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_decoupling_mixins.adoc
index 335a985..ea72d13 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_decoupling_mixins.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_decoupling_mixins.adoc
@@ -144,7 +144,7 @@ DocumentHolder_documents mixin = container.mixin(DocumentHolder_documents.class,
 ----
 
 The xref:ugtst.adoc#_ugtst_integ-test-support_bootstrapping_IntegrationTestAbstract[`IntegrationTestAbstract`] and
-xref:rg.adoc#_rg_classes_super_manpage-FixtureScript[`FixtureScript`] classes both provide a `mixin(...)` convenience
+xref:rgcms.adoc#_rgcms_classes_super_manpage-FixtureScript[`FixtureScript`] classes both provide a `mixin(...)` convenience
 method.
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_decoupling_pushing-changes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_decoupling_pushing-changes.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_decoupling_pushing-changes.adoc
index 3e22862..b357ec9 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_decoupling_pushing-changes.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_decoupling_pushing-changes.adoc
@@ -134,7 +134,7 @@ public class Department {
 --
 <1> maintain a count of the number of male ...
 <2> ... and female employees (getters and setters omitted)
-<3> the xref:rg.adoc#_rg_methods_prefixes_manpage-addTo[`addTo...()`] method increments the derived properties
-<4> the xref:rg.adoc#_rg_methods_prefixes_manpage-removeFrom[`removeFrom...()`] method similarly decrements the derived properties
+<3> the xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-addTo[`addTo...()`] method increments the derived properties
+<4> the xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-removeFrom[`removeFrom...()`] method similarly decrements the derived properties
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_i18n.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_i18n.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_i18n.adoc
index 2f1d35e..fe40119 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_i18n.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_i18n.adoc
@@ -7,7 +7,7 @@
 
 Apache Isis' support for i18n allows every element of the domain model (the class names, property names, action names, parameter names and so forth) to be translated.
 
-It also supports translations of messages raised imperatively, by which we mean as the result of a call to `title()` to obtain an object's title, or messages resulting from any business rule violations (eg xref:rg.adoc#_rg_methods_prefixes_manpage-disable[`disable...()`] or xref:rg.adoc#_rg_methods_prefixes_manpage-validate[`validate...()`], and so on.
+It also supports translations of messages raised imperatively, by which we mean as the result of a call to `title()` to obtain an object's title, or messages resulting from any business rule violations (eg xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-disable[`disable...()`] or xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-validate[`validate...()`], and so on.
 
 Isis does not translate the values of your domain objects, though.  So, if you have a domain concept such as `Country` whose name is intended to be localized according to the current user, you will need to model
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_overriding-jdo-annotations.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_overriding-jdo-annotations.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_overriding-jdo-annotations.adoc
index 709dfaf..5601c75 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_overriding-jdo-annotations.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_overriding-jdo-annotations.adoc
@@ -43,7 +43,7 @@ This file should be placed can be placed in `src/main/java/META-INF` within your
 
 [TIP]
 ====
-(As of `1.11.0-SNAPSHOT`) you can use a mixin action on xref:rg.adoc#_rg_classes_mixins_Persistable[`Persistable`] mixin
+(As of `1.11.0-SNAPSHOT`) you can use a mixin action on xref:rgcms.adoc#_rgcms_classes_mixins_Persistable[`Persistable`] mixin
 to download the JDO class metadata in XML form.
 ====
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_persisted-title.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_persisted-title.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_persisted-title.adoc
index a057d93..59d3cb4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_persisted-title.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_persisted-title.adoc
@@ -8,7 +8,7 @@
 
 Normally the title of an object is not persisted to the database, rather it is recomputed automatically from underlying properties.  On occasion though you might want the title to also be persisted; either to make things easier for the DBA, or for an integration scenario, or some other purpose.
 
-We can implement this feature by leveraging the xref:rg.adoc#_rg_methods_lifecycle_jdo-api[JDO lifecycle].  In the design we discuss here we make it a responsibility of the entities to persist the title as a property, by implementing a `ObjectWithPersistedTitle` interface:
+We can implement this feature by leveraging the xref:rgcms.adoc#_rgcms_methods_lifecycle_jdo-api[JDO lifecycle].  In the design we discuss here we make it a responsibility of the entities to persist the title as a property, by implementing a `ObjectWithPersistedTitle` interface:
 
 [source,java]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_view-models_jaxb.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_view-models_jaxb.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_view-models_jaxb.adoc
index 865dc0b..a21ad06 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_view-models_jaxb.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_view-models_jaxb.adoc
@@ -155,7 +155,7 @@ It's quite common for view models to be "backed by" (be projections of) some und
 It wouldn't make sense to serialize out the state of a persistent entity: the point of a DTO is to act as a facade
 on top of the entity so that the implementation details (of the entity's structure) don't leak out to the consumer.
 However, the identity of the underlying entity can be well defined; Apache Isis defines the
-xref:rg.adoc#_rg_schema-common[Common schema] which defines the `<oid-dto>` element (and corresponding `OidDto` class):
+xref:rgcms.adoc#_rgcms_schema-common[Common schema] which defines the `<oid-dto>` element (and corresponding `OidDto` class):
 the object's type and its identifier.  This is basically a formal XML equivalent to the `Bookmark` object obtained
 from the xref:rgsvc.adoc#_rgsvc-api_BookmarkService[`BookmarkService`].
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_view-models_programming-model.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_view-models_programming-model.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_view-models_programming-model.adoc
index 763b64d..9f8bd86 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_view-models_programming-model.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_view-models_programming-model.adoc
@@ -66,7 +66,7 @@ public class ExcelUploadManager implements ViewModel {
   public String viewModelMemento() { ... }
   public void viewModelInit(String memento) { ... }
 }
-|Implement xref:rg.adoc#_rg_classes_super_manpage-ViewModel[`ViewModel`] interface.  The memento is as defined by the
+|Implement xref:rgcms.adoc#_rgcms_classes_super_manpage-ViewModel[`ViewModel`] interface.  The memento is as defined by the
 interface's methods: the programmer has full control (but also full responsibility) for the string memento.
 
 |DTO (`1.11.0-SNAPSHOT`)

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_view-models_use-cases.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_view-models_use-cases.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_view-models_use-cases.adoc
index baacc17..214fcd6 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_view-models_use-cases.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_more-advanced_view-models_use-cases.adoc
@@ -116,7 +116,7 @@ DTOs to be carefully and properly versioned using XML namespaces.
 
 [TIP]
 ====
-If the view model DTO implements the xref:rg.adoc#_rg_classes_mixins_Dto[`Dto`] marker interface, then the framework
+If the view model DTO implements the xref:rgcms.adoc#_rgcms_classes_mixins_Dto[`Dto`] marker interface, then the framework
 will also provide the ability to download the XML or its XSD directly from the UI.
 ====
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_ugtst_aaa.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugtst_aaa.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugtst_aaa.adoc
index 3755105..2e89107 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugtst_aaa.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugtst_aaa.adoc
@@ -125,7 +125,7 @@ In the previous section we discussed using given/when/then as a form of organizi
 
 For integration tests though it can be difficult to keep the "given" short; there could be a lot of prerequisite data that needs to exist before you can actually exercise your system.  Moreover, however we do set up that data, but we also want to do so in a way that is resilient to the system changing over time.
 
-The solution that Apache Isis provides is a domain service called xref:rg.adoc#_rg_classes_super_manpage-FixtureScripts[Fixture Scripts], that defines a pattern and supporting classes to help ensure that the "data setup" for your tests are reusable and maintainable over time.
+The solution that Apache Isis provides is a domain service called xref:rgcms.adoc#_rgcms_classes_super_manpage-FixtureScripts[Fixture Scripts], that defines a pattern and supporting classes to help ensure that the "data setup" for your tests are reusable and maintainable over time.
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_ugtst_integ-test-support_bootstrapping.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugtst_integ-test-support_bootstrapping.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugtst_integ-test-support_bootstrapping.adoc
index b017dc9..e7b8399 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugtst_integ-test-support_bootstrapping.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugtst_integ-test-support_bootstrapping.adoc
@@ -9,7 +9,7 @@ Integration tests instantiate an Apache Isis "runtime" (as a singleton) within a
 
 Nevertheless, we do need to bootstrap the runtime for the very first test.
 
-As of 1.9.0 the bootstrapping of integration tests and webapps has been simplified through the xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[`AppManifest`] class.  Since this isn't mandatory, for now we present both techniques.
+As of 1.9.0 the bootstrapping of integration tests and webapps has been simplified through the xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`] class.  Since this isn't mandatory, for now we present both techniques.
 
 The example code in this section is taken from the app generated by the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype].
 
@@ -59,7 +59,7 @@ public class DomainAppAppManifest implements AppManifest {
 }
 ----
 
-Further details on bootstrapping with the `AppManifest` can be found in the xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[reference guide].
+Further details on bootstrapping with the `AppManifest` can be found in the xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[reference guide].
 
 === 1.8.0 and earlier
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_ugtst_integ-test-support_typical-usage.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugtst_integ-test-support_typical-usage.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugtst_integ-test-support_typical-usage.adoc
index 5b9572c..d75f70c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugtst_integ-test-support_typical-usage.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugtst_integ-test-support_typical-usage.adoc
@@ -58,7 +58,7 @@ public class ToDoItemIntegTest extends AbstractToDoIntegTest {
     ...
 }
 ----
-<1> the xref:rg.adoc#_rg_classes_super_manpage-FixtureScripts[`FixtureScripts`] domain service is injected, providing us with the ability to run fixture scripts
+<1> the xref:rgcms.adoc#_rgcms_classes_super_manpage-FixtureScripts[`FixtureScripts`] domain service is injected, providing us with the ability to run fixture scripts
 <2> likewise, an instance of the `ToDoItems` domain service is injected.  We'll use this to lookup...
 <3> the object under test, held as a field
 <4> the fixture script for this test; it deletes all existing todo items (for the current user only) and then recreates them

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_ugtst_unit-test-support_contract-tests.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugtst_unit-test-support_contract-tests.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugtst_unit-test-support_contract-tests.adoc
index 691eb52..30c4f90 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugtst_unit-test-support_contract-tests.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugtst_unit-test-support_contract-tests.adoc
@@ -41,7 +41,7 @@ If using DataNucleus against an RDBMS (as you probably are) then we strongly rec
 
 * second, `SortedSet` is preferable to `Set` because then the order is well-defined and predictable (to an end user, to the programmer). +
 +
-The xref:rg.adoc#_rg_classes_utility_manpage-ObjectContracts[`ObjectContracts`]  utility class substantially simplifies the task of implementing `Comparable` in your domain classes.
+The xref:rgcms.adoc#_rgcms_classes_utility_manpage-ObjectContracts[`ObjectContracts`]  utility class substantially simplifies the task of implementing `Comparable` in your domain classes.
 
 * third, if the relationship is bidirectional then JDO/Objectstore will automatically maintain the relationship.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_ugvw_features_blob-attachments.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugvw_features_blob-attachments.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugvw_features_blob-attachments.adoc
index 6acc42b..f150240 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugvw_features_blob-attachments.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugvw_features_blob-attachments.adoc
@@ -6,7 +6,7 @@
 
 
 
-The Isis application library provides the xref:rg.adoc#_rg_classes_value-types_manpage-Blob[Blob] value type (binary large objects) and also the xref:rg.adoc#_rg_classes_value-types_manpage-Clob[Clob]
+The Isis application library provides the xref:rgcms.adoc#_rgcms_classes_value-types_manpage-Blob[Blob] value type (binary large objects) and also the xref:rgcms.adoc#_rgcms_classes_value-types_manpage-Clob[Clob]
 value type (character large object), each of which also includes metadata about the data (specifically the filename and mime type).
 
 A class can define a property using either of these types, for example:

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/rg.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rg.adoc b/adocs/documentation/src/main/asciidoc/guides/rg.adoc
index 8b49fba..0951d3b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rg.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rg.adoc
@@ -10,10 +10,10 @@
 = Classes, Methods and Schema
 
 This reference guide lists and describes various elements of the the Apache Isis Programming Model, specifically
-reserved and prefix xref:rg.adoc#_rg_methods[methods] (such as `title()` and `validate...()`) and various utility and
-supporting xref:rg.adoc#_rg_classes[classes].
+reserved and prefix xref:rgcms.adoc#_rgcms_methods[methods] (such as `title()` and `validate...()`) and various utility and
+supporting xref:rgcms.adoc#_rgcms_classes[classes].
 
-It also describes the xref:rg.adoc#_rg_schema[XSD schema] defined by Apache Isis.  One use case is for the
+It also describes the xref:rgcms.adoc#_rgcms_schema[XSD schema] defined by Apache Isis.  One use case is for the
 JAXB serialization of view models (`1.11.0-SNAPSHOT`).
 
 
@@ -22,6 +22,6 @@ This reference guide does _not_ describe how to actually build an Apache Isis ap
 
 
 
-include::_rg_methods.adoc[leveloffset=+1]
-include::_rg_classes.adoc[leveloffset=+1]
-include::_rg_schema.adoc[leveloffset=+1]
+include::_rgcms_methods.adoc[leveloffset=+1]
+include::_rgcms_classes.adoc[leveloffset=+1]
+include::_rgcms_schema.adoc[leveloffset=+1]


[36/52] [abbrv] isis git commit: ISIS-1237: a little more work on SwaggerService; can also access swagger-ui using /api-docs/index.html, hitting the internal /restful/swagger/private URL to access the swagger spec itself.

Posted by mg...@apache.org.
ISIS-1237: a little more work on SwaggerService; can also access swagger-ui using /api-docs/index.html, hitting the internal /restful/swagger/private URL to access the swagger spec itself.


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/86b960ac
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/86b960ac
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/86b960ac

Branch: refs/heads/ISIS-1224-select2-v4
Commit: 86b960ac88079bd23c91eaf13ccc01d4d11a758f
Parents: 72cae2f
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Wed Dec 9 00:19:57 2015 +0000
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Wed Dec 9 00:19:57 2015 +0000

----------------------------------------------------------------------
 .../applib/services/swagger/SwaggerService.java |  22 +-
 .../services/swagger/SwaggerServiceMenu.java    |  18 +-
 .../isis/applib/services/swagger/Util.java      |  15 +-
 core/metamodel/pom.xml                          |   6 +
 .../services/swagger/SwaggerServiceDefault.java |  14 +-
 .../services/swagger/internal/SwaggerSpec.java  | 259 --------------
 .../swagger/internal/SwaggerSpecGenerator.java  | 356 +++++++++++++++++++
 core/viewer-restfulobjects-server/pom.xml       |  11 +
 .../server/RestfulObjectsApplication.java       |   3 +
 .../server/resources/SwaggerSpecResource.java   | 125 +++++++
 example/application/simpleapp/webapp/pom.xml    |   1 -
 .../webapp/src/main/webapp/WEB-INF/web.xml      |  17 +-
 .../webapp/src/main/webapp/api-docs/index.html  | 130 +++++++
 13 files changed, 699 insertions(+), 278 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/86b960ac/core/applib/src/main/java/org/apache/isis/applib/services/swagger/SwaggerService.java
----------------------------------------------------------------------
diff --git a/core/applib/src/main/java/org/apache/isis/applib/services/swagger/SwaggerService.java b/core/applib/src/main/java/org/apache/isis/applib/services/swagger/SwaggerService.java
index 901cc62..c25d23f 100644
--- a/core/applib/src/main/java/org/apache/isis/applib/services/swagger/SwaggerService.java
+++ b/core/applib/src/main/java/org/apache/isis/applib/services/swagger/SwaggerService.java
@@ -21,11 +21,10 @@ import org.apache.isis.applib.annotation.DomainService;
 import org.apache.isis.applib.annotation.NatureOfService;
 import org.apache.isis.applib.annotation.RestrictTo;
 import org.apache.isis.applib.annotation.ViewModel;
-import org.apache.isis.applib.value.Clob;
 
 public interface SwaggerService {
 
-    public enum Type {
+    enum Visibility {
         /**
          * Specification for use by third-party clients, ie public use.
          *
@@ -52,11 +51,22 @@ public interface SwaggerService {
         public boolean isPublic() {
             return this == PUBLIC;
         }
-        public boolean isPrivateWithPrototyping() {
-            return this == PRIVATE_WITH_PROTOTYPING;
-        }
     }
 
-    public Clob downloadSwaggerSpec(final String fileName, final Type type);
+    enum Format {
+        JSON {
+            @Override public String mediaType() {
+                return "text/json";
+            }
+        },
+        YAML {
+            @Override public String mediaType() {
+                return "application/yaml";
+            }
+        };
+
+        public abstract String mediaType();
+    }
+    String generateSwaggerSpec(final Visibility visibility, final Format format);
 
 }    

http://git-wip-us.apache.org/repos/asf/isis/blob/86b960ac/core/applib/src/main/java/org/apache/isis/applib/services/swagger/SwaggerServiceMenu.java
----------------------------------------------------------------------
diff --git a/core/applib/src/main/java/org/apache/isis/applib/services/swagger/SwaggerServiceMenu.java b/core/applib/src/main/java/org/apache/isis/applib/services/swagger/SwaggerServiceMenu.java
index d1e72b0..7b4e4b0 100644
--- a/core/applib/src/main/java/org/apache/isis/applib/services/swagger/SwaggerServiceMenu.java
+++ b/core/applib/src/main/java/org/apache/isis/applib/services/swagger/SwaggerServiceMenu.java
@@ -57,11 +57,23 @@ public class SwaggerServiceMenu {
     @MemberOrder(sequence="500.800.1")
     public Clob downloadSwaggerSpec(
             @ParameterLayout(named = "Filename")
-            final String fileName,
-            final SwaggerService.Type type) {
-        return swaggerService.downloadSwaggerSpec(Util.withSuffix(fileName, "json"), type);
+            final String fileNamePrefix,
+            final SwaggerService.Visibility visibility,
+            final SwaggerService.Format format) {
+        final String fileName = Util.buildFileName(fileNamePrefix, visibility, format);
+        final String spec = swaggerService.generateSwaggerSpec(visibility, format);
+        return new Clob(fileName, format.mediaType(), spec);
     }
 
+    public String default0DownloadSwaggerSpec() {
+        return "swagger";
+    }
+    public SwaggerService.Visibility default1DownloadSwaggerSpec() {
+        return SwaggerService.Visibility.PRIVATE;
+    }
+    public SwaggerService.Format default2DownloadSwaggerSpec() {
+        return SwaggerService.Format.YAML;
+    }
 
     @Inject
     SwaggerService swaggerService;

http://git-wip-us.apache.org/repos/asf/isis/blob/86b960ac/core/applib/src/main/java/org/apache/isis/applib/services/swagger/Util.java
----------------------------------------------------------------------
diff --git a/core/applib/src/main/java/org/apache/isis/applib/services/swagger/Util.java b/core/applib/src/main/java/org/apache/isis/applib/services/swagger/Util.java
index ec07c7f..81af662 100644
--- a/core/applib/src/main/java/org/apache/isis/applib/services/swagger/Util.java
+++ b/core/applib/src/main/java/org/apache/isis/applib/services/swagger/Util.java
@@ -20,7 +20,19 @@ class Util {
 
     private Util(){}
 
-    static String withSuffix(String fileName, String suffix) {
+    static String buildFileName(
+            String fileNamePrefix,
+            final SwaggerService.Visibility visibility,
+            final SwaggerService.Format format) {
+        final String formatLower = format.name().toLowerCase();
+        int i = fileNamePrefix.lastIndexOf("." + formatLower);
+        if(i > 0) {
+            fileNamePrefix = fileNamePrefix.substring(0, i);
+        }
+        return withSuffix(fileNamePrefix + "-" + visibility.name().toLowerCase(), formatLower);
+    }
+
+    private static String withSuffix(String fileName, String suffix) {
         if(!suffix.startsWith(".")) {
             suffix = "." + suffix;
         }
@@ -30,4 +42,5 @@ class Util {
         return fileName;
     }
 
+
 }

http://git-wip-us.apache.org/repos/asf/isis/blob/86b960ac/core/metamodel/pom.xml
----------------------------------------------------------------------
diff --git a/core/metamodel/pom.xml b/core/metamodel/pom.xml
index 629b0a2..4ef1588 100644
--- a/core/metamodel/pom.xml
+++ b/core/metamodel/pom.xml
@@ -97,6 +97,12 @@
             <groupId>io.swagger</groupId>
             <artifactId>swagger-core</artifactId>
             <version>1.5.4</version>
+            <exclusions>
+                <exclusion>
+                    <groupId>org.apache.commons</groupId>
+                    <artifactId>commons-lang3</artifactId>
+                </exclusion>
+            </exclusions>
         </dependency>
     </dependencies>
 

http://git-wip-us.apache.org/repos/asf/isis/blob/86b960ac/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/SwaggerServiceDefault.java
----------------------------------------------------------------------
diff --git a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/SwaggerServiceDefault.java b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/SwaggerServiceDefault.java
index fbf3737..c447788 100644
--- a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/SwaggerServiceDefault.java
+++ b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/SwaggerServiceDefault.java
@@ -24,8 +24,7 @@ import org.slf4j.LoggerFactory;
 import org.apache.isis.applib.annotation.DomainService;
 import org.apache.isis.applib.annotation.NatureOfService;
 import org.apache.isis.applib.services.swagger.SwaggerService;
-import org.apache.isis.applib.value.Clob;
-import org.apache.isis.core.metamodel.services.swagger.internal.SwaggerSpec;
+import org.apache.isis.core.metamodel.services.swagger.internal.SwaggerSpecGenerator;
 import org.apache.isis.core.metamodel.spec.SpecificationLoader;
 import org.apache.isis.core.metamodel.spec.SpecificationLoaderAware;
 
@@ -38,12 +37,13 @@ public class SwaggerServiceDefault implements SwaggerService, SpecificationLoade
     private final static Logger LOG = LoggerFactory.getLogger(SwaggerServiceDefault.class);
 
     @Override
-    public Clob downloadSwaggerSpec(final String fileName, final Type type) {
+    public String generateSwaggerSpec(
+            final Visibility visibility,
+            final Format format) {
 
-        SwaggerSpec swaggerSpec = new SwaggerSpec(specificationLoader);
-
-        String yaml = swaggerSpec.generate(type);
-        return new Clob(fileName, "text/json", yaml);
+        final SwaggerSpecGenerator swaggerSpecGenerator = new SwaggerSpecGenerator(specificationLoader);
+        final String swaggerSpec = swaggerSpecGenerator.generate(visibility, format);
+        return swaggerSpec;
     }
 
     //region > injected dependencies

http://git-wip-us.apache.org/repos/asf/isis/blob/86b960ac/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpec.java
----------------------------------------------------------------------
diff --git a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpec.java b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpec.java
deleted file mode 100644
index a62c236..0000000
--- a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpec.java
+++ /dev/null
@@ -1,259 +0,0 @@
-/*
- *  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.
- */
-package org.apache.isis.core.metamodel.services.swagger.internal;
-
-import java.util.Arrays;
-import java.util.Collection;
-import java.util.List;
-
-import org.apache.isis.applib.annotation.NatureOfService;
-import org.apache.isis.applib.filter.Filters;
-import org.apache.isis.applib.services.swagger.SwaggerService;
-import org.apache.isis.core.metamodel.facets.object.domainservice.DomainServiceFacet;
-import org.apache.isis.core.metamodel.spec.ActionType;
-import org.apache.isis.core.metamodel.spec.ObjectSpecification;
-import org.apache.isis.core.metamodel.spec.SpecificationLoader;
-import org.apache.isis.core.metamodel.spec.feature.Contributed;
-import org.apache.isis.core.metamodel.spec.feature.ObjectAction;
-
-import io.swagger.models.Info;
-import io.swagger.models.ModelImpl;
-import io.swagger.models.Operation;
-import io.swagger.models.Path;
-import io.swagger.models.Response;
-import io.swagger.models.Swagger;
-import io.swagger.models.properties.ArrayProperty;
-import io.swagger.models.properties.IntegerProperty;
-import io.swagger.models.properties.ObjectProperty;
-import io.swagger.models.properties.RefProperty;
-import io.swagger.models.properties.StringProperty;
-import io.swagger.util.Json;
-
-public class SwaggerSpec {
-
-    private final SpecificationLoader specificationLoader;
-
-    public SwaggerSpec(final SpecificationLoader specificationLoader) {
-        this.specificationLoader = specificationLoader;
-    }
-
-    public String generate(final SwaggerService.Type type) {
-        final Swagger swagger = new Swagger();
-        swagger.info(new Info()
-                        .version("1.0.0")
-                        .title("Restful Objects"))
-                .path("/",
-                        new Path()
-                            .get(new Operation()
-                                    .description("RO Spec v1.0, section 5.1")
-                                    .consumes("application/json")
-                                    .consumes("application/json;profile=\"urn:org.restfulobjects:repr-types/home-page\"")
-                                    .produces("application/json;profile=\"urn:org.restfulobjects:repr-types/home-page\"")
-                                    .response(200,
-                                            newResponse(Caching.LONG_TERM)
-                                            .description("OK")
-                                            .schema(new RefProperty("#/definitions/home-page"))
-                                    )))
-                .path("/user",
-                        new Path()
-                            .get(new Operation()
-                                    .description("RO Spec v1.0, section 6.1")
-                                    .consumes("application/json")
-                                    .consumes("application/json;profile=\"urn:org.restfulobjects:repr-types/user\"")
-                                    .produces("application/json;profile=\"urn:org.restfulobjects:repr-types/user\"")
-                                    .response(200,
-                                            newResponse(Caching.SHORT_TERM)
-                                            .description("OK")
-                                            .schema(new RefProperty("#/definitions/user"))
-                                    )))
-                .path("/version",
-                        new Path()
-                            .get(new Operation()
-                                    .description("RO Spec v1.0, section 8.1")
-                                    .consumes("application/json")
-                                    .consumes("application/json;profile=\"urn:org.restfulobjects:repr-types/version\"")
-                                    .produces("application/json;profile=\"urn:org.restfulobjects:repr-types/version\"")
-                                    .response(200,
-                                            newResponse(Caching.LONG_TERM)
-                                            .description("OK")
-                                            .schema(new RefProperty("#/definitions/version"))
-                                    )));
-
-        swagger.addDefinition("home-page",
-                new ModelImpl()
-                    .description("RO Spec v1.0, section 5.2")
-                    .type("object")
-                    .property("links", arrayOfLinksGetOnly())
-                        .required("links")
-                    );
-
-        swagger.addDefinition("user",
-                new ModelImpl()
-                    .description("RO Spec v1.0, section 6.2")
-                    .type("object")
-                    .property("userName", stringProperty())
-                    .property("roles", arrayOfStrings())
-                    .property("links", arrayOfLinksGetOnly())
-                    .required("userName")
-                    .required("roles")
-                    .required("links")
-                );
-
-        swagger.addDefinition("version",
-                new ModelImpl()
-                    .description("RO Spec v1.0, section 8.2")
-                    .type("object")
-                    .property("specVersion", stringProperty())
-                    .property("implVersion", stringProperty())
-                    .property("optionalCapabilities",
-                            new ObjectProperty()
-                                .property("blobsClobs", stringProperty())
-                                .property("deleteObjects", stringProperty())
-                                .property("domainModel", stringProperty())
-                                .property("validateOnly", stringProperty())
-                                .property("protoPersistentObjects", stringProperty())
-                            )
-                    .property("links", arrayOfLinksGetOnly())
-                    .property("extensions", new ObjectProperty())
-                    .required("userName")
-                    .required("roles")
-                    .required("links")
-                );
-
-        swagger.addDefinition("link",
-                new ModelImpl()
-                    .type("object")
-                    .property("rel", stringProperty())
-                    .property("href", stringProperty())
-                    .property("title", stringProperty())
-                    .property("method", stringPropertyEnum("GET", "POST", "PUT", "DELETE"))
-                    .property("type", stringProperty())
-                    .property("arguments", new ObjectProperty())
-                    .required("rel")
-                    .required("href")
-                    .required("method")
-        );
-
-        swagger.addDefinition("link-get-only",
-                new ModelImpl()
-                    .type("object")
-                    .property("rel", stringProperty())
-                    .property("href", stringProperty())
-                    .property("title", stringProperty())
-                    .property("method", stringPropertyEnum("GET"))
-                    .property("type", stringProperty())
-                    .required("rel")
-                    .required("href")
-                    .required("method")
-        );
-
-
-        final Collection<ObjectSpecification> allSpecs = specificationLoader.allSpecifications();
-        for (ObjectSpecification serviceSpec : allSpecs) {
-            final DomainServiceFacet domainServiceFacet = serviceSpec.getFacet(DomainServiceFacet.class);
-            if (domainServiceFacet == null) {
-                continue;
-            }
-            if (type.isPublic() && domainServiceFacet.getNatureOfService() != NatureOfService.VIEW_REST_ONLY) {
-                continue;
-            }
-
-            List<ObjectAction> serviceActions = serviceSpec
-                    .getObjectActions(actionTypesFor(type), Contributed.EXCLUDED, Filters.<ObjectAction>any());
-            for (ObjectAction serviceAction : serviceActions) {
-
-            }
-
-        }
-
-
-        return Json.pretty(swagger);
-    }
-
-    StringProperty stringPropertyEnum(String... enumValues) {
-        StringProperty stringProperty = stringProperty();
-        stringProperty._enum(Arrays.asList(enumValues));
-        if(enumValues.length >= 1) {
-            stringProperty._default(enumValues[0]);
-        }
-        return stringProperty;
-    }
-
-    ArrayProperty arrayOfLinksGetOnly() {
-        return new ArrayProperty()
-                .items(new RefProperty("#/definitions/link-get-only"));
-    }
-
-    StringProperty stringProperty() {
-        return new StringProperty();
-    }
-
-    ArrayProperty arrayOfStrings() {
-        return new ArrayProperty().items(stringProperty());
-    }
-
-    private Response newResponse(final Caching caching) {
-        return withCachingHeaders(new Response(), caching);
-    }
-
-    enum Caching {
-        NO_CACHING {
-            @Override public void withHeaders(final Response response) {
-
-            }
-        },
-        SHORT_TERM {
-            @Override public void withHeaders(final Response response) {
-                response
-                        .header("Cache-Control",
-                                new IntegerProperty()
-                                        ._default(3600));
-            }
-        },
-        LONG_TERM {
-            @Override public void withHeaders(final Response response) {
-                response
-                        .header("Cache-Control",
-                                new IntegerProperty()
-                                        ._default(86400));
-            }
-        };
-
-        public abstract void withHeaders(final Response response);
-    }
-    private Response withCachingHeaders(final Response response, final Caching caching) {
-        caching.withHeaders(response);
-
-        return response;
-    }
-
-    private List<ActionType> actionTypesFor(final SwaggerService.Type type) {
-        switch (type) {
-        case PUBLIC:
-            return Arrays.asList(ActionType.USER);
-        case PRIVATE:
-            return Arrays.asList(ActionType.USER);
-        case PRIVATE_WITH_PROTOTYPING:
-            return Arrays.asList(ActionType.USER, ActionType.EXPLORATION, ActionType.PROTOTYPE, ActionType.DEBUG);
-        }
-        throw new IllegalArgumentException("Unrecognized type '" + type + "'");
-    }
-
-
-}

http://git-wip-us.apache.org/repos/asf/isis/blob/86b960ac/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGenerator.java
----------------------------------------------------------------------
diff --git a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGenerator.java b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGenerator.java
new file mode 100644
index 0000000..0e729ec
--- /dev/null
+++ b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGenerator.java
@@ -0,0 +1,356 @@
+/*
+ *  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.
+ */
+package org.apache.isis.core.metamodel.services.swagger.internal;
+
+import java.util.Arrays;
+import java.util.Collection;
+import java.util.List;
+
+import com.fasterxml.jackson.core.JsonProcessingException;
+
+import org.apache.isis.applib.annotation.NatureOfService;
+import org.apache.isis.applib.filter.Filters;
+import org.apache.isis.applib.services.swagger.SwaggerService;
+import org.apache.isis.core.commons.factory.InstanceUtil;
+import org.apache.isis.core.metamodel.facets.object.domainservice.DomainServiceFacet;
+import org.apache.isis.core.metamodel.services.ServiceUtil;
+import org.apache.isis.core.metamodel.spec.ActionType;
+import org.apache.isis.core.metamodel.spec.ObjectSpecification;
+import org.apache.isis.core.metamodel.spec.SpecificationLoader;
+import org.apache.isis.core.metamodel.spec.feature.Contributed;
+import org.apache.isis.core.metamodel.spec.feature.ObjectAction;
+
+import io.swagger.models.Info;
+import io.swagger.models.ModelImpl;
+import io.swagger.models.Operation;
+import io.swagger.models.Path;
+import io.swagger.models.Response;
+import io.swagger.models.Swagger;
+import io.swagger.models.properties.ArrayProperty;
+import io.swagger.models.properties.IntegerProperty;
+import io.swagger.models.properties.MapProperty;
+import io.swagger.models.properties.ObjectProperty;
+import io.swagger.models.properties.RefProperty;
+import io.swagger.models.properties.StringProperty;
+import io.swagger.util.Json;
+import io.swagger.util.Yaml;
+
+public class SwaggerSpecGenerator {
+
+    private final SpecificationLoader specificationLoader;
+
+    public SwaggerSpecGenerator(final SpecificationLoader specificationLoader) {
+        this.specificationLoader = specificationLoader;
+    }
+
+    public String generate(final SwaggerService.Visibility visibility, final SwaggerService.Format format) {
+        final Swagger swagger = new Swagger();
+        swagger.basePath("/restful");
+        swagger.info(new Info()
+                        .version("1.0.0")
+                        .title("Restful Objects"))
+                .path("/",
+                        new Path()
+                            .get(new Operation()
+                                    .description(roSpec("5.1"))
+                                    .consumes("application/json")
+                                    .consumes("application/json;profile=\"urn:org.restfulobjects:repr-types/home-page\"")
+                                    .produces("application/json;profile=\"urn:org.restfulobjects:repr-types/home-page\"")
+                                    .response(200,
+                                            newResponse(Caching.NON_EXPIRING)
+                                            .description("OK")
+                                            .schema(new RefProperty("#/definitions/home-page"))
+                                    )))
+                .path("/user",
+                        new Path()
+                            .get(new Operation()
+                                    .description(roSpec("6.1"))
+                                    .consumes("application/json")
+                                    .consumes("application/json;profile=\"urn:org.restfulobjects:repr-types/user\"")
+                                    .produces("application/json;profile=\"urn:org.restfulobjects:repr-types/user\"")
+                                    .response(200,
+                                            newResponse(Caching.USER_INFO)
+                                            .description("OK")
+                                            .schema(new RefProperty("#/definitions/user"))
+                                    )))
+                .path("/services",
+                        new Path()
+                                .get(new Operation()
+                                        .description(roSpec("7.1"))
+                                        .consumes("application/json")
+                                        .consumes("application/json;profile=\"urn:org.restfulobjects:repr-types/services\"")
+                                        .produces("application/json;profile=\"urn:org.restfulobjects:repr-types/services\"")
+                                        .response(200,
+                                                newResponse(Caching.USER_INFO)
+                                                        .description("OK")
+                                                        .schema(new RefProperty("#/definitions/services"))
+                                        )))
+
+                .path("/version",
+                        new Path()
+                            .get(new Operation()
+                                    .description(roSpec("8.1"))
+                                    .consumes("application/json")
+                                    .consumes("application/json;profile=\"urn:org.restfulobjects:repr-types/version\"")
+                                    .produces("application/json;profile=\"urn:org.restfulobjects:repr-types/version\"")
+                                    .response(200,
+                                            newResponse(Caching.NON_EXPIRING)
+                                            .description("OK")
+                                            .schema(new RefProperty("#/definitions/version"))
+                                    )));
+
+        swagger.addDefinition("home-page",
+                newModel(roSpec("5.2")));
+
+        swagger.addDefinition("user",
+                newModel(roSpec("6.2"))
+                    .property("userName", stringProperty())
+                    .property("roles", arrayOfStrings())
+                    .property("links", arrayOfLinksGetOnly())
+                    .required("userName")
+                    .required("roles")
+                );
+
+        swagger.addDefinition("services",
+                newModel(roSpec("7.2"))
+                    .property("value", arrayOfLinksGetOnly())
+                    .required("userName")
+                    .required("roles")
+                );
+
+        swagger.addDefinition("version",
+                newModel(roSpec("8.2"))
+                    .property("specVersion", stringProperty())
+                    .property("implVersion", stringProperty())
+                    .property("optionalCapabilities",
+                            new ObjectProperty()
+                                .property("blobsClobs", stringProperty())
+                                .property("deleteObjects", stringProperty())
+                                .property("domainModel", stringProperty())
+                                .property("validateOnly", stringProperty())
+                                .property("protoPersistentObjects", stringProperty())
+                            )
+                    .required("userName")
+                    .required("roles")
+                );
+
+        swagger.addDefinition("link",
+                new ModelImpl()
+                    .type("object")
+                    .property("rel", stringProperty())
+                    .property("href", stringProperty())
+                    .property("title", stringProperty())
+                    .property("method", stringPropertyEnum("GET", "POST", "PUT", "DELETE"))
+                    .property("type", stringProperty())
+                    .property("arguments", new ObjectProperty())
+                    .required("rel")
+                    .required("href")
+                    .required("method")
+        );
+
+        swagger.addDefinition("link-get-only",
+                new ModelImpl()
+                    .type("object")
+                    .property("rel", stringProperty())
+                    .property("href", stringProperty())
+                    .property("title", stringProperty())
+                    .property("method", stringPropertyEnum("GET"))
+                    .property("type", stringProperty())
+                    .required("rel")
+                    .required("href")
+                    .required("method")
+        );
+
+
+        final Collection<ObjectSpecification> allSpecs = specificationLoader.allSpecifications();
+        for (ObjectSpecification serviceSpec : allSpecs) {
+            final DomainServiceFacet domainServiceFacet = serviceSpec.getFacet(DomainServiceFacet.class);
+            if (domainServiceFacet == null) {
+                continue;
+            }
+            if (!isVisible(visibility, domainServiceFacet)) {
+                continue;
+            }
+
+            List<ObjectAction> serviceActions = serviceSpec
+                    .getObjectActions(actionTypesFor(visibility), Contributed.EXCLUDED, Filters.<ObjectAction>any());
+            if(serviceActions.isEmpty()) {
+                continue;
+            }
+
+            String serviceId = serviceIdFor(serviceSpec);
+            final String serviceDefinitionId = "service-" + serviceId;
+
+            final Path servicePath = new Path();
+            swagger.path("/services/" + serviceId, servicePath);
+
+            servicePath.get(
+                    new Operation()
+                        .description(roSpec("15.1"))
+                        .response(200,
+                                newResponse(Caching.TRANSACTIONAL)
+                                    .description("OK")
+                                    .schema(new RefProperty("#/definitions/"
+                                            + serviceDefinitionId)))
+            );
+
+            final ObjectProperty serviceMembers = new ObjectProperty();
+            ModelImpl serviceRepr =
+                    newModel(roSpec("15.1.2") + ": representation of " + serviceId)
+                    .property("title", stringProperty())
+                    .property("serviceId", stringProperty()._default(serviceId))
+                    .property("members", serviceMembers);
+
+            swagger.addDefinition(serviceDefinitionId, serviceRepr);
+
+            for (final ObjectAction serviceAction : serviceActions) {
+                String serviceActionId = serviceAction.getId();
+                serviceMembers.property(serviceActionId,
+                        new ObjectProperty()
+                            .property("id", stringPropertyEnum(serviceActionId))
+                            .property("memberType", stringPropertyEnum("action"))
+                            .property("links",
+                                    new ObjectProperty()
+                                        .property("rel", stringPropertyEnum("urn:org.restfulobjects:rels/details;action=\"" + serviceActionId + "\""))
+                                        .property("href", stringPropertyEnum("actions/"
+                                                + serviceActionId)))
+                            .property("method", stringPropertyEnum("GET"))
+                            .property("type", stringPropertyEnum("application/json;profile=\"urn:org.restfulobjects:repr-types/object-action\""))
+                );
+            }
+
+        }
+
+        switch (format) {
+            case JSON:
+                return Json.pretty(swagger);
+            case YAML:
+                try {
+                    return Yaml.pretty().writeValueAsString(swagger);
+                } catch (JsonProcessingException e) {
+                    throw new RuntimeException(e);
+                }
+            default:
+                throw new IllegalArgumentException("Unrecognized format: " + format);
+        }
+    }
+
+    boolean isVisible(final SwaggerService.Visibility visibility, final DomainServiceFacet domainServiceFacet) {
+        if (domainServiceFacet.getNatureOfService() == NatureOfService.VIEW_REST_ONLY) {
+            return true;
+        }
+        if (visibility.isPublic()) {
+            return false;
+        }
+        return domainServiceFacet.getNatureOfService() == NatureOfService.VIEW_MENU_ONLY ||
+               domainServiceFacet.getNatureOfService() == NatureOfService.VIEW;
+    }
+
+    private ModelImpl newModel(final String description) {
+        return new ModelImpl()
+                .description(description)
+                .type("object")
+                .property("links", arrayOfLinksGetOnly())
+                .property("extensions", new MapProperty())
+                .required("links")
+                .required("extensions");
+    }
+
+    // TODO: this is horrid, there ought to be a facet we can call instead...
+    String serviceIdFor(final ObjectSpecification serviceSpec) {
+        Object tempServiceInstance = InstanceUtil.createInstance(serviceSpec.getCorrespondingClass());
+        return ServiceUtil.id(tempServiceInstance);
+    }
+
+    StringProperty stringProperty() {
+        return new StringProperty();
+    }
+
+    StringProperty stringPropertyEnum(String... enumValues) {
+        StringProperty stringProperty = stringProperty();
+        stringProperty._enum(Arrays.asList(enumValues));
+        if(enumValues.length >= 1) {
+            stringProperty._default(enumValues[0]);
+        }
+        return stringProperty;
+    }
+
+    ArrayProperty arrayOfLinksGetOnly() {
+        return new ArrayProperty()
+                .items(new RefProperty("#/definitions/link-get-only"));
+    }
+
+    ArrayProperty arrayOfStrings() {
+        return new ArrayProperty().items(stringProperty());
+    }
+
+    private Response newResponse(final Caching caching) {
+        return withCachingHeaders(new Response(), caching);
+    }
+
+    enum Caching {
+        TRANSACTIONAL {
+            @Override public void withHeaders(final Response response) {
+
+            }
+        },
+        USER_INFO {
+            @Override public void withHeaders(final Response response) {
+                response
+                        .header("Cache-Control",
+                                new IntegerProperty()
+                                        ._default(3600));
+            }
+        },
+        NON_EXPIRING {
+            @Override public void withHeaders(final Response response) {
+                response
+                        .header("Cache-Control",
+                                new IntegerProperty()
+                                        ._default(86400).description(roSpec("2.13")));
+            }
+        };
+
+        public abstract void withHeaders(final Response response);
+    }
+
+    private static String roSpec(final String section) {
+        return "RO Spec v1.0, section " + section;
+    }
+
+    private Response withCachingHeaders(final Response response, final Caching caching) {
+        caching.withHeaders(response);
+
+        return response;
+    }
+
+    private List<ActionType> actionTypesFor(final SwaggerService.Visibility visibility) {
+        switch (visibility) {
+        case PUBLIC:
+            return Arrays.asList(ActionType.USER);
+        case PRIVATE:
+            return Arrays.asList(ActionType.USER);
+        case PRIVATE_WITH_PROTOTYPING:
+            return Arrays.asList(ActionType.USER, ActionType.EXPLORATION, ActionType.PROTOTYPE, ActionType.DEBUG);
+        }
+        throw new IllegalArgumentException("Unrecognized type '" + visibility + "'");
+    }
+
+
+}

http://git-wip-us.apache.org/repos/asf/isis/blob/86b960ac/core/viewer-restfulobjects-server/pom.xml
----------------------------------------------------------------------
diff --git a/core/viewer-restfulobjects-server/pom.xml b/core/viewer-restfulobjects-server/pom.xml
index 17768a0..b833b59 100644
--- a/core/viewer-restfulobjects-server/pom.xml
+++ b/core/viewer-restfulobjects-server/pom.xml
@@ -61,5 +61,16 @@
             <artifactId>geronimo-activation_1.1_spec</artifactId>
         </dependency>
 
+        <dependency>
+            <groupId>org.webjars</groupId>
+            <artifactId>swagger-ui</artifactId>
+            <version>2.1.3</version>
+        </dependency>
+
+        <dependency>
+            <groupId>org.webjars</groupId>
+            <artifactId>webjars-servlet-2.x</artifactId>
+            <version>1.1</version>
+        </dependency>
 	</dependencies>
 </project>

http://git-wip-us.apache.org/repos/asf/isis/blob/86b960ac/core/viewer-restfulobjects-server/src/main/java/org/apache/isis/viewer/restfulobjects/server/RestfulObjectsApplication.java
----------------------------------------------------------------------
diff --git a/core/viewer-restfulobjects-server/src/main/java/org/apache/isis/viewer/restfulobjects/server/RestfulObjectsApplication.java b/core/viewer-restfulobjects-server/src/main/java/org/apache/isis/viewer/restfulobjects/server/RestfulObjectsApplication.java
index 7adc430..d1dbcc6 100644
--- a/core/viewer-restfulobjects-server/src/main/java/org/apache/isis/viewer/restfulobjects/server/RestfulObjectsApplication.java
+++ b/core/viewer-restfulobjects-server/src/main/java/org/apache/isis/viewer/restfulobjects/server/RestfulObjectsApplication.java
@@ -23,6 +23,7 @@ import org.apache.isis.viewer.restfulobjects.server.resources.DomainObjectResour
 import org.apache.isis.viewer.restfulobjects.server.resources.DomainServiceResourceServerside;
 import org.apache.isis.viewer.restfulobjects.server.resources.DomainTypeResourceServerside;
 import org.apache.isis.viewer.restfulobjects.server.resources.HomePageResourceServerside;
+import org.apache.isis.viewer.restfulobjects.server.resources.SwaggerSpecResource;
 import org.apache.isis.viewer.restfulobjects.server.resources.UserResourceServerside;
 import org.apache.isis.viewer.restfulobjects.server.resources.VersionResourceServerside;
 
@@ -38,6 +39,8 @@ public class RestfulObjectsApplication extends AbstractJaxRsApplication {
         addClass(DomainServiceResourceServerside.class);
         addClass(VersionResourceServerside.class);
 
+        addClass(SwaggerSpecResource.class);
+
         final RestfulObjectsJaxbWriterForXml roWriter = new RestfulObjectsJaxbWriterForXml();
         addSingleton(roWriter);
         addSingleton(new RestfulObjectsApplicationExceptionMapper());

http://git-wip-us.apache.org/repos/asf/isis/blob/86b960ac/core/viewer-restfulobjects-server/src/main/java/org/apache/isis/viewer/restfulobjects/server/resources/SwaggerSpecResource.java
----------------------------------------------------------------------
diff --git a/core/viewer-restfulobjects-server/src/main/java/org/apache/isis/viewer/restfulobjects/server/resources/SwaggerSpecResource.java b/core/viewer-restfulobjects-server/src/main/java/org/apache/isis/viewer/restfulobjects/server/resources/SwaggerSpecResource.java
new file mode 100644
index 0000000..4032013
--- /dev/null
+++ b/core/viewer-restfulobjects-server/src/main/java/org/apache/isis/viewer/restfulobjects/server/resources/SwaggerSpecResource.java
@@ -0,0 +1,125 @@
+/**
+ *  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.
+ */
+package org.apache.isis.viewer.restfulobjects.server.resources;
+
+import java.util.List;
+import java.util.concurrent.Callable;
+
+import javax.inject.Inject;
+import javax.ws.rs.Consumes;
+import javax.ws.rs.GET;
+import javax.ws.rs.Path;
+import javax.ws.rs.Produces;
+import javax.ws.rs.core.Context;
+import javax.ws.rs.core.HttpHeaders;
+import javax.ws.rs.core.MediaType;
+
+import org.apache.isis.applib.services.swagger.SwaggerService;
+import org.apache.isis.core.metamodel.services.ServicesInjectorSpi;
+import org.apache.isis.core.runtime.system.context.IsisContext;
+import org.apache.isis.core.runtime.system.persistence.PersistenceSession;
+
+@Path("/swagger")
+public class SwaggerSpecResource {
+
+    @Context
+    HttpHeaders httpHeaders;
+
+    @Path("/private")
+    @GET
+    @Consumes({ MediaType.WILDCARD, MediaType.APPLICATION_JSON, "text/yaml" })
+    @Produces({
+            MediaType.APPLICATION_JSON, "text/yaml"
+    })
+    public String swaggerPrivate() {
+        return swagger(SwaggerService.Visibility.PRIVATE);
+    }
+
+    @Path("/prototyping")
+    @GET
+    @Consumes({ MediaType.WILDCARD, MediaType.APPLICATION_JSON, "text/yaml" })
+    @Produces({
+            MediaType.APPLICATION_JSON, "text/yaml"
+    })
+    public String swaggerPrototyping() {
+        return swagger(SwaggerService.Visibility.PRIVATE_WITH_PROTOTYPING);
+    }
+
+    @Path("/public")
+    @GET
+    @Consumes({ MediaType.WILDCARD, MediaType.APPLICATION_JSON, "text/yaml" })
+    @Produces({
+            MediaType.APPLICATION_JSON, "text/yaml"
+    })
+    public String swaggerPublic() {
+        return swagger(SwaggerService.Visibility.PUBLIC);
+    }
+
+    private String swagger(final SwaggerService.Visibility visibility) {
+        final SwaggerService.Format format = deriveFrom(httpHeaders);
+        String spec = IsisContext.doInSession(new MyCallable(visibility, format));
+        return spec;
+    }
+
+    private SwaggerService.Format deriveFrom(final HttpHeaders httpHeaders) {
+        final List<MediaType> acceptableMediaTypes = httpHeaders.getAcceptableMediaTypes();
+        for (MediaType acceptableMediaType : acceptableMediaTypes) {
+            if(acceptableMediaType.isCompatible(MediaType.APPLICATION_JSON_TYPE)) {
+                return SwaggerService.Format.JSON;
+            }
+        }
+        final MediaType applYaml = new MediaType("application", "yaml");
+        final MediaType textYaml = new MediaType("text", "yaml");
+        for (MediaType acceptableMediaType : acceptableMediaTypes) {
+            if (acceptableMediaType.isCompatible(applYaml) ||
+                acceptableMediaType.isCompatible(textYaml)) {
+                return SwaggerService.Format.YAML;
+            }
+        }
+        return SwaggerService.Format.JSON;
+    }
+
+    static class MyCallable implements Callable<String> {
+
+        private final SwaggerService.Visibility visibility;
+        private final SwaggerService.Format format;
+
+        public MyCallable(
+                final SwaggerService.Visibility visibility,
+                final SwaggerService.Format format) {
+            this.visibility = visibility;
+            this.format = format;
+        }
+
+        @Override
+        public String call() throws Exception {
+            getServicesInjector().injectServicesInto(this);
+            return swaggerService.generateSwaggerSpec(visibility, format);
+        }
+
+        @Inject
+        SwaggerService swaggerService;
+
+        ServicesInjectorSpi getServicesInjector() {
+            return getPersistenceSession().getServicesInjector();
+        }
+
+        PersistenceSession getPersistenceSession() {
+            return IsisContext.getPersistenceSession();
+        }
+    }
+}

http://git-wip-us.apache.org/repos/asf/isis/blob/86b960ac/example/application/simpleapp/webapp/pom.xml
----------------------------------------------------------------------
diff --git a/example/application/simpleapp/webapp/pom.xml b/example/application/simpleapp/webapp/pom.xml
index e81c6a5..eeb2285 100644
--- a/example/application/simpleapp/webapp/pom.xml
+++ b/example/application/simpleapp/webapp/pom.xml
@@ -323,5 +323,4 @@
         </profile>
     </profiles>
 
-
 </project>

http://git-wip-us.apache.org/repos/asf/isis/blob/86b960ac/example/application/simpleapp/webapp/src/main/webapp/WEB-INF/web.xml
----------------------------------------------------------------------
diff --git a/example/application/simpleapp/webapp/src/main/webapp/WEB-INF/web.xml b/example/application/simpleapp/webapp/src/main/webapp/WEB-INF/web.xml
index 1ef1f47..ac9d154 100644
--- a/example/application/simpleapp/webapp/src/main/webapp/WEB-INF/web.xml
+++ b/example/application/simpleapp/webapp/src/main/webapp/WEB-INF/web.xml
@@ -165,7 +165,22 @@
         <servlet-name>Resource</servlet-name>
         <url-pattern>*.swf</url-pattern>
     </servlet-mapping>
-    
+
+
+    <servlet>
+        <servlet-name>WebjarsServlet</servlet-name>
+        <servlet-class>org.webjars.servlet.WebjarsServlet</servlet-class>
+        <init-param>
+            <param-name>disableCache</param-name>
+            <param-value>true</param-value>
+        </init-param>
+        <load-on-startup>2</load-on-startup>
+    </servlet>
+    <servlet-mapping>
+        <servlet-name>WebjarsServlet</servlet-name>
+        <url-pattern>/webjars/*</url-pattern>
+    </servlet-mapping>
+
 
 
     <!--

http://git-wip-us.apache.org/repos/asf/isis/blob/86b960ac/example/application/simpleapp/webapp/src/main/webapp/api-docs/index.html
----------------------------------------------------------------------
diff --git a/example/application/simpleapp/webapp/src/main/webapp/api-docs/index.html b/example/application/simpleapp/webapp/src/main/webapp/api-docs/index.html
new file mode 100644
index 0000000..bc9415a
--- /dev/null
+++ b/example/application/simpleapp/webapp/src/main/webapp/api-docs/index.html
@@ -0,0 +1,130 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="UTF-8">
+    <base href="../webjars/swagger-ui/2.1.3/"/>
+    <title>Swagger UI</title>
+    <link rel="icon" type="image/png" href="images/favicon-32x32.png" sizes="32x32" />
+    <link rel="icon" type="image/png" href="images/favicon-16x16.png" sizes="16x16" />
+    <link href='css/typography.css' media='screen' rel='stylesheet' type='text/css'/>
+    <link href='css/reset.css' media='screen' rel='stylesheet' type='text/css'/>
+    <link href='css/screen.css' media='screen' rel='stylesheet' type='text/css'/>
+    <link href='css/reset.css' media='print' rel='stylesheet' type='text/css'/>
+    <link href='css/print.css' media='print' rel='stylesheet' type='text/css'/>
+    <script src='lib/jquery-1.8.0.min.js' type='text/javascript'></script>
+    <script src='lib/jquery.slideto.min.js' type='text/javascript'></script>
+    <script src='lib/jquery.wiggle.min.js' type='text/javascript'></script>
+    <script src='lib/jquery.ba-bbq.min.js' type='text/javascript'></script>
+    <script src='lib/handlebars-2.0.0.js' type='text/javascript'></script>
+    <script src='lib/underscore-min.js' type='text/javascript'></script>
+    <script src='lib/backbone-min.js' type='text/javascript'></script>
+    <script src='swagger-ui.js' type='text/javascript'></script>
+    <script src='lib/highlight.7.3.pack.js' type='text/javascript'></script>
+    <script src='lib/marked.js' type='text/javascript'></script>
+    <script src='lib/swagger-oauth.js' type='text/javascript'></script>
+
+    <!-- Some basic translations -->
+    <!-- <script src='lang/translator.js' type='text/javascript'></script> -->
+    <!-- <script src='lang/ru.js' type='text/javascript'></script> -->
+    <!-- <script src='lang/en.js' type='text/javascript'></script> -->
+
+    <script type="text/javascript">
+    $(function () {
+      var url = window.location.search.match(/url=([^&]+)/);
+      if (url && url.length > 1) {
+        url = decodeURIComponent(url[1]);
+      } else {
+        url = "/restful/swagger/private"
+      }
+
+      // Pre load translate...
+      if(window.SwaggerTranslator) {
+        window.SwaggerTranslator.translate();
+      }
+      window.swaggerUi = new SwaggerUi({
+        url: url,
+        dom_id: "swagger-ui-container",
+        supportedSubmitMethods: ['get', 'post', 'put', 'delete', 'patch'],
+        onComplete: function(swaggerApi, swaggerUi){
+          if(typeof initOAuth == "function") {
+            initOAuth({
+              clientId: "your-client-id",
+              clientSecret: "your-client-secret-if-required",
+              realm: "your-realms",
+              appName: "your-app-name",
+              scopeSeparator: ","
+            });
+          }
+
+          if(window.SwaggerTranslator) {
+            window.SwaggerTranslator.translate();
+          }
+
+          $('pre code').each(function(i, e) {
+            hljs.highlightBlock(e)
+          });
+
+          addApiKeyAuthorization();
+        },
+        onFailure: function(data) {
+          log("Unable to Load SwaggerUI");
+        },
+        docExpansion: "none",
+        apisSorter: "alpha",
+        defaultModelRendering: 'schema',
+        showRequestHeaders: false
+      });
+
+      function addApiKeyAuthorization(){
+        var key = encodeURIComponent($('#input_apiKey')[0].value);
+        if(key && key.trim() != "") {
+            var apiKeyAuth = new SwaggerClient.ApiKeyAuthorization("api_key", key, "query");
+            window.swaggerUi.api.clientAuthorizations.add("api_key", apiKeyAuth);
+            log("added key " + key);
+        }
+      }
+
+      $('#input_apiKey').change(addApiKeyAuthorization);
+
+      // if you have an apiKey you would like to pre-populate on the page for demonstration purposes...
+      /*
+        var apiKey = "myApiKeyXXXX123456789";
+        $('#input_apiKey').val(apiKey);
+      */
+
+      window.swaggerUi.load();
+
+      function log() {
+        if ('console' in window) {
+          console.log.apply(console, arguments);
+        }
+      }
+  });
+  </script>
+</head>
+
+<body class="swagger-section">
+<div id='header'>
+    <div class="swagger-ui-wrap">
+        <a id="logo" href="http://swagger.io">swagger</a>
+        <form id='api_selector'>
+            <div class='input'>
+                <!--
+                <select name="foo">
+                    <option id="public" label="public" value="/restful/swagger/public"/>
+                    <option id="private" label="private" value="/restful/swagger/private"/>
+                    <option id="prototyping" label="prototyping" value="/restful/swagger/prototyping"/>
+                </select>
+                -->
+                <input placeholder="http://example.com/api" id="input_baseUrl" name="baseUrl" type="text">
+            </div>
+            <div class='input' style="display:none;"><input placeholder="api_key" id="input_apiKey" name="apiKey" type="text"/></div>
+            <div class='input'><a id="explore" href="#" data-sw-translate>Explore</a></div>
+        </form>
+    </div>
+</div>
+
+<div id="message-bar" class="swagger-ui-wrap" data-sw-translate>&nbsp;</div>
+<div id="swagger-ui-container" class="swagger-ui-wrap"></div>
+</body>
+</html>
\ No newline at end of file


[40/52] [abbrv] isis git commit: ISIS-1237: removing the action prompt paths

Posted by mg...@apache.org.
ISIS-1237: removing the action prompt paths


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/6daa442d
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/6daa442d
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/6daa442d

Branch: refs/heads/ISIS-1224-select2-v4
Commit: 6daa442dc1515b451f705ca978e03654e3a61f96
Parents: f9a0b43
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Wed Dec 9 18:58:00 2015 +0000
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Wed Dec 9 18:58:00 2015 +0000

----------------------------------------------------------------------
 .../swagger/internal/SwaggerSpecGenerator.java  | 51 +-------------------
 1 file changed, 1 insertion(+), 50 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/6daa442d/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGenerator.java
----------------------------------------------------------------------
diff --git a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGenerator.java b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGenerator.java
index 07673d3..bfb1489 100644
--- a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGenerator.java
+++ b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGenerator.java
@@ -99,10 +99,6 @@ public class SwaggerSpecGenerator {
             for (final ObjectAction serviceAction : serviceActions) {
                 appendActionTo(serviceMembers, serviceAction);
 
-                if(false) {
-                    appendPromptPaths(swagger, serviceAction);
-                }
-
                 appendInvokePath(swagger, serviceAction);
             }
         }
@@ -299,51 +295,6 @@ public class SwaggerSpecGenerator {
         return serviceMembers;
     }
 
-    void appendPromptPaths(
-            final Swagger swagger,
-            final ObjectAction serviceAction) {
-
-        final ObjectSpecification serviceSpec = serviceAction.getOnType();
-        final String serviceId = serviceIdFor(serviceSpec);
-        final String servicePathStr = "/services/" + serviceId;
-        final String serviceActionId = serviceAction.getId();
-        final String serviceActionPromptPathRelStr = "actions/" + serviceActionId;
-
-        final ObjectProperty actionParametersRepr = new ObjectProperty();
-        swagger.path(servicePathStr + "/" + serviceActionPromptPathRelStr,
-                new Path()
-                        .get(
-                                new Operation()
-                                        .tag(serviceId)
-                                        .description(roSpec("18.1") + ": (prompt) resource for " + serviceId + "#" + serviceActionId)
-                                        .produces("application/json")
-                                        .produces("application/json;profile=urn:org.restfulobjects:repr-types/object-action")
-                                        .response(200,
-                                                new Response()
-                                                        .description(roSpec("18.2") + ": (prompt) representation of " + serviceId + "#" + serviceActionId)
-                                                        .schema(new ObjectProperty()
-                                                                .property("id",
-                                                                        stringPropertyEnum(serviceActionId))
-                                                                .property("memberType",
-                                                                        stringPropertyEnum("action"))
-                                                                .property("links", arrayOfLinksGetOnly())
-                                                                .property("parameters", actionParametersRepr)
-                                                        ))));
-        final List<ObjectActionParameter> parameters = serviceAction.getParameters();
-
-        int i = 0;
-        for (final ObjectActionParameter parameter : parameters) {
-            final String parameterId = parameter.getId();
-            actionParametersRepr.property(parameterId,
-                    new ObjectProperty()
-                        .property("num", new IntegerProperty()._default(i++))
-                        .property("id", stringPropertyEnum(parameterId))
-                        .property("name", stringPropertyEnum(parameter.getName()))
-                        .property("description", stringPropertyEnum(parameter.getDescription()))
-            );
-        }
-    }
-
     void appendInvokePath(
             final Swagger swagger,
             final ObjectAction serviceAction) {
@@ -400,7 +351,7 @@ public class SwaggerSpecGenerator {
             for (final ObjectActionParameter parameter : parameters) {
 
                 final Property valueProperty;
-                // TODO: need to switch on parameter's type and create appopriate impl of valueProperty
+                // TODO: need to switch on parameter's type and create appropriate impl of valueProperty
                 // if(parameter.getSpecification().isValue()) ...
                 valueProperty = stringProperty();
 


[08/52] [abbrv] isis git commit: ISIS-1243: renamed rg.adoc to rgcms.adoc

Posted by mg...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-iconName.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-iconName.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-iconName.adoc
deleted file mode 100644
index 86c836b..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-iconName.adoc
+++ /dev/null
@@ -1,36 +0,0 @@
-[[_rg_methods_reserved_manpage-iconName]]
-= `iconName()`
-: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/
-
-
-Every object is represented by an icon; this is based on the domain object's simple name.  The xref:ugvw.adoc#[Wicket viewer] searches for the image in the same package as the `.class` file for the domain object.
-
-The `iconName()` allows the icon that to be used to change for individual object instances.  These are usually quite subtle, for example to reflect the particular status of an object.  The value returned by the `iconName()` method is added as a suffix to the base icon name.
-
-For example, the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] uses this technique to add an overlay for todo items that have been completed:
-
-image::{_imagesdir}reference-methods/reserved/iconName/differing.png[width="200px",link="{_imagesdir}reference-methods/reserved/iconName/differing.png"]
-
-
-
-The screenshot below shows the location of these png icon files:
-
-image::{_imagesdir}reference-methods/reserved/iconName/png-files.png[width="200px",link="{_imagesdir}reference-methods/reserved/iconName/png-files.png"]
-
-
-
-The code to accomplish this is straightforward:
-
-[source,java]
-----
-public class ToDoItem ... {
-    public String iconName() {
-        return !isComplete() ? "todo" : "done";
-    }
-    ...
-}
-----
-
-See also xref:rg.adoc#_rg_methods_reserved_manpage-title[`title()`] and xref:rg.adoc#_rg_methods_reserved_manpage-cssClass[`cssClass()`]

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-title.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-title.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-title.adoc
deleted file mode 100644
index 0de6535..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-title.adoc
+++ /dev/null
@@ -1,65 +0,0 @@
-[[_rg_methods_reserved_manpage-title]]
-= `title()`
-: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/
-
-
-
-Every object is represented by a title.  This appears both as a main header for the object when viewed as well as being used as a hyperlink within properties and collections.   It therefore must contain enough information for the end-user to distinguish the object from any others.
-
-This is most commonly done by including some unique key within the title, for example a customer's SSN, or an order number, and so forth.  However note that Apache Isis itself does _not_ require the title to be unique; it is merely recommended in most cases.
-
-An object's title can be constructed in various ways, but the most flexible is to use the `title()` method.  The signature of this method is usually:
-
-[source,java]
-----
-public String title() { ... }
-----
-
-Note that Apache Isis' xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[i18n support] extends this so that titles can also be internationalized.
-
-For example, the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] uses this technique to add an overlay for todo items that have been completed:
-
-[source,java]
-----
-public String title() {
-    final TitleBuffer buf = new TitleBuffer();                              // <1>
-    buf.append(getDescription());
-    if (isComplete()) {                                                     // <2>
-        buf.append("- Completed!");
-    } else {
-        try {
-            final LocalDate dueBy = wrapperFactory.wrap(this).getDueBy();   // <3>
-            if (dueBy != null) {
-                buf.append(" due by", dueBy);
-            }
-        } catch(final HiddenException ignored) {                            // <4>
-        }
-    }
-    return buf.toString();
-}
-----
-<1> simple xref:rg.adoc#_rg_classes_utility_manpage-TitleBuffer[tility class] to help construct the title string
-<2> imperative conditional logic
-<3> using the xref:rgsvc.adoc#_rgsvc-api_WrapperFactory[`WrapperFactory`] to determine if the `dueBy` field is visible for this user ...
-<4> ... but ignore if not
-
-As the example above shows, the implementation can be as complex as you like.
-
-In many cases, though, you may be able to use the xref:rgant.adoc#_rgant-Title[`@Title`] annotation.
-
-
-See also xref:rg.adoc#_rg_methods_reserved_manpage-iconName[`iconName()`] and xref:rg.adoc#_rg_methods_reserved_manpage-cssClass[`cssClass()`]
-
-
-
-
-
-
-
-
-
-
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-validate.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-validate.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-validate.adoc
deleted file mode 100644
index 257cbf6..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-validate.adoc
+++ /dev/null
@@ -1,27 +0,0 @@
-[[_rg_methods_reserved_manpage-validate]]
-= `validate()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `validate()` method is used to specify that invariants pertaining to an object's state are enforced.
-
-
-[WARNING]
-====
-(As of 1.8.0) there are known limitations with this functionality.  Invariants are enforced when an object is initially created and when it is edited, however invariants are currently _not_ enforced if an action is invoked.
-====
-
-
-The signature of the method is:
-
-[source,java]
-----
-public String validate() { ... }
-----
-
-where the returned string is the reason that the invocation is vetoed.
-
-Note that Apache Isis' xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[i18n support] extends this so that the returned reason can also be internationalized.

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_schema-aim.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_schema-aim.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_schema-aim.adoc
deleted file mode 100644
index 67dff77..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_schema-aim.adoc
+++ /dev/null
@@ -1,97 +0,0 @@
-[[_rg_schema-aim]]
-= Action Invocation Memento
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-The "aim" schema defines the serialized form (or memento) of an action invocation.
-
-Action invocations are captured (in memory rather than in serialized form) when the end-user invokes the action
-"through" the UI, by way of the xref:rgsvc.adoc#_rgsvc-api_CommandContext[CommandContext] service. Using the
-`ActionInvocationMementoDtoUtils` utility class, a service can instantiate `ActionInvocationMementoDto` which can then
-be serialized to/from using the same `ActionInvocationMementoDtoUtils` class.
-
-[source,xml]
-----
-<?xml version="1.0" encoding="UTF-8"?>
-<xs:schema targetNamespace="http://isis.apache.org/schema/aim"                              <!--1-->
-           elementFormDefault="qualified"
-           xmlns:xs="http://www.w3.org/2001/XMLSchema"
-           xmlns="http://isis.apache.org/schema/aim"
-           xmlns:common="http://isis.apache.org/schema/common">
-
-    <xs:import namespace="http://isis.apache.org/schema/common"                             <!--2-->
-               schemaLocation="http://isis.apache.org/schema/common/common-1.0.xsd"/>
-
-    <xs:element name="actionInvocationMementoDto">                                          <!--3-->
-        <xs:complexType>
-            <xs:sequence>
-                <xs:element name="metadata">
-                    <xs:complexType>
-                        <xs:sequence>
-                            <xs:element name="transactionId" type="xs:string"/>             <!--4-->
-                            <xs:element name="sequence" type="xs:int"/>                     <!--5-->
-                            <xs:element name="timestamp" type="xs:dateTime"/>               <!--6-->
-                            <xs:element name="target" type="common:oidDto"/>                <!--7-->
-                            <xs:element name="targetClass" type="xs:string"/>               <!--8-->
-                            <xs:element name="targetAction" type="xs:string"/>              <!--9-->
-                            <xs:element name="actionIdentifier" type="xs:string"/>          <!--10-->
-                            <xs:element name="user" type="xs:string"/>                      <!--11-->
-                            <xs:element name="title" type="xs:string"/>                     <!--12-->
-                        </xs:sequence>
-                    </xs:complexType>
-                </xs:element>
-                <xs:element name="payload">
-                    <xs:complexType>
-                        <xs:sequence>
-                            <xs:element name="parameters">                                  <!--13-->
-                                <xs:complexType>
-                                    <xs:sequence maxOccurs="unbounded">
-                                        <xs:element name="param" type="paramDto"/>
-                                    </xs:sequence>
-                                    <xs:attribute name="num" use="required" type="xs:int"/>
-                                </xs:complexType>
-                            </xs:element>
-                            <xs:element name="return" type="common:valueDto"                <!--14-->
-                                        minOccurs="0" maxOccurs="1"/>
-                        </xs:sequence>
-                    </xs:complexType>
-                </xs:element>
-            </xs:sequence>
-        </xs:complexType>
-    </xs:element>
-
-    <xs:complexType name="paramDto">                                                        <!--15-->
-        <xs:sequence>
-            <xs:element name="value" type="common:valueDto"/>                               <!--16-->
-        </xs:sequence>
-        <xs:attribute name="parameterName" use="required" type="xs:string"/>                <!--17-->
-        <xs:attribute name="parameterType" use="required" type="common:valueType"/>
-        <xs:attribute name="null" use="optional" type="xs:boolean"/>
-    </xs:complexType>
-</xs:schema>
-----
-<1> the aim schema has a namespace URI of "http://isis.apache.org/schema/aim".  Although URIs are not the same as URLs, you will find that the schemas are also downloadable from this location.
-<2> reuses the xref:rg.adoc#_rg_schema-common[common] schema
-<3> definition of the `actionInvocationMementoDto` complex type. This consists of metadata (the transaction identifier, the target object, the initiating user) and the payload (the action parameter/arguments, the return value if known).
-<4> the unique transaction Id (a guid) allocated by the framework for each and every transaction
-<5> a sequence number within the transaction.  It is possible for there to be more than one action invocation to be
-<6> when the action was invoked
-<7> target object, as an OID (using `oidDto` from the xref:rg.adoc#_rg_schema-common[common] schema)
-<8> fully qualified class name of the target object, for information only
-<9> name of the action, for information only
-<10> Javadoc style unique identifier for the action.
-<11> User that invoked the action
-<12> title of the target object, for information only
-<13> Collection of parameter/arguments, defined in terms of the `paramDto` complex type (discussed just below)
-<14> The return value of the action, if known (and not void)
-<15> The `paramDto` defines both an action parameter and its corresponding argument values
-<16> The value of the parameter, in other words an argument value
-<17> Metadata about the parameter itself: its name, type, optionality.
-
-[NOTE]
-====
-As of `1.11.0` this schema is not used directly by the framework; in particular `Command#setMemento(...)` sets a similar
-but less formal XML structure.  This may change in the future.
-====

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_schema-common.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_schema-common.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_schema-common.adoc
deleted file mode 100644
index b9a5629..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_schema-common.adoc
+++ /dev/null
@@ -1,103 +0,0 @@
-[[_rg_schema-common]]
-= Common Schema
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The main purpose of the common schema is to define the `oidDto` complex type: the object's type and its identifier.
-This is basically a formal XML equivalent to the `Bookmark` object obtained from the
-xref:rgsvc.adoc#_rgsvc-api_BookmarkService[`BookmarkService`].
-
-Although simple, this is an enormously powerful concept, in that it represents a URI to any domain object managed by
-a given Apache Isis application.  With it, we have the ability to lookup any arbitrary object.  Further discussion and
-examples can be found xref:ug.adoc#_ug_core-concepts_building-blocks_oid[here].
-
-
-[source,xml]
-----
-<xs:schema targetNamespace="http://isis.apache.org/schema/common"                           <!--1-->
-           elementFormDefault="qualified"
-           xmlns="http://isis.apache.org/schema/common"
-           xmlns:xs="http://www.w3.org/2001/XMLSchema">
-
-    <xs:complexType name="oidDto">                                                          <!--2-->
-        <xs:sequence>
-            <xs:element name="objectType" type="xs:string"/>                                <!--3-->
-            <xs:element name="objectIdentifier" type="xs:string"/>                          <!--4-->
-        </xs:sequence>
-        <xs:attribute name="objectState" type="bookmarkObjectState" default="persistent"/>
-    </xs:complexType>
-
-    <xs:simpleType name="bookmarkObjectState">                                              <!--5-->
-        <xs:restriction base="xs:string">
-            <xs:enumeration value="persistent"/>
-            <xs:enumeration value="transient"/>
-            <xs:enumeration value="viewModel"/>
-        </xs:restriction>
-    </xs:simpleType>
-    ...
-</xs:schema>
-----
-<1> the common schema has a namespace URI of "http://isis.apache.org/schema/common".  Although URIs are not the same as URLs, you will find that the schemas are also downloadable from this location.
-<2> the `oidDto` complex type defines the unique identifier for any domain object: its type, and an identifier.  The `objectState` attribute is of type `bookmarkObjectState` and will typically be "transient" or "viewModel"
-<3> the object type, corresponding to either the
-xref:rgant.adoc#_rgant-DomainObject_objectType[`@DomainObject#objectType()`] attribute, or to the (JDO)
-xref:rgant.adoc#_rgant-PersistenceCapable[`@PersistenceCapable`] annotation (`schema` and/or `table`
-attributes), or to the (JDO) xref:rgant.adoc#_rgant-Discriminator[`@Discriminator`] annotation.  If none
-is specified, then the fully
-qualified class name will be used.
-<4> the object identifier (aka primary key), converted to string form.
-<5> the `bookmarkObjectState` enumerates the possible persistence states of the referenced object.  Although "transient" is shown,
-in practice the only types of objects will be "persistent" (entities) or "viewModel".
-
-The `oidDto` complex type is used in two specific places by the framework:
-
-* first, as a means of serializing JAXB view model/DTOs (annotated with
-xref:rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`]), that reference domain entities. +
-+
-These references are serialized instead into OIDs
-
-* second, as references to the target of action invocations, as described by the
-xref:rg.adoc#_rg_schema-aim[action invocation memento] schema. +
-+
-They are also used to represent references to any action arguments that take domain object entities.
-
-The common schema also defines two further types: the `valueDto` complex type and the `valueType` simple type:
-
-[source,xml]
-----
-<xs:schema targetNamespace="http://isis.apache.org/schema/common"
-           elementFormDefault="qualified"
-           xmlns="http://isis.apache.org/schema/common"
-           xmlns:xs="http://www.w3.org/2001/XMLSchema">
-    ...
-    <xs:complexType name="valueDto">                              <!--1-->
-        <xs:choice minOccurs="0" maxOccurs="1">
-            <xs:element name="string" type="xs:string"/>
-            <xs:element name="byte" type="xs:byte"/>
-            <xs:element name="short" type="xs:short"/>
-            ...
-            <xs:element name="localTime" type="xs:time"/>
-            <xs:element name="reference" type="oidDto"/>
-        </xs:choice>
-    </xs:complexType>
-
-    <xs:simpleType name="valueType">                              <!--2-->
-        <xs:restriction base="xs:string">
-            <xs:enumeration value="string"/>
-            <xs:enumeration value="byte"/>
-            <xs:enumeration value="short"/>
-            ...
-            <xs:enumeration value="isisApplibClob"/>
-            <xs:enumeration value="reference"/>
-        </xs:restriction>
-    </xs:simpleType>
-</xs:schema>
-----
-
-These two type definitions are just building blocks, also used within the
-xref:rg.adoc#_rg_schema-aim[action iInvocation memento] schema.  The first, `valueDto` is intended to hold any valid
-value, eg of an argument to an action.  The second, `valueType`, enumerates the different types of vales, eg of a
-formal parameter to an action.

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_schema.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_schema.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_schema.adoc
deleted file mode 100644
index b7e97ee..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_schema.adoc
+++ /dev/null
@@ -1,24 +0,0 @@
-[[_rg_schema]]
-= Schema
-: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/
-
-
-Most applications need to integrate with other apps in the enterprise.  To facilitate such integration scenarios,
-Apache Isis defines two standard XSD schemas:
-
-* the xref:rg.adoc#_rg_schema-common[common schema], which defines the `oidDto` complex type: the object's type and its identifier. +
-+
-It also defines some two further XSD types, which are building blocks used in...
-
-* the xref:rg.adoc#_rg_schema-aim[action memento invocation] schema, which allows action invocations to be captured
-and reified. +
-+
-The (non-ASF) http://github.com/isisaddons/isis-module-publishmq[Isis addons' publishmq] module uses this XML format
-to publish messages onto an link:http://activemq.apache.org[Apache ActiveMQ] message queue.
-
-The sections below discuss these schemas in more detail.
-
-include::_rg_schema-common.adoc[leveloffset=+1]
-include::_rg_schema-aim.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgant-Collection_editing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-Collection_editing.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-Collection_editing.adoc
index ed198ea..7b148d2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-Collection_editing.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-Collection_editing.adoc
@@ -25,7 +25,7 @@ Whether a collection is enabled or disabled depends upon these factors:
 
 * else, then the value of the `@Collection(editing=...)` attribute itself.
 
-* else, the result of invoking any supporting xref:rg.adoc#_rg_methods_prefixes_manpage-disable[`disable...()`] supporting methods
+* else, the result of invoking any supporting xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-disable[`disable...()`] supporting methods
 
 
 Thus, to make a collection read-only even if the object would otherwise be editable, use:

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgant-Column.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-Column.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-Column.adoc
index 9cca7cc..2069ee1 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-Column.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-Column.adoc
@@ -116,7 +116,7 @@ public class PartyRelationship {
 
 == Mapping ``Blob``s and ``Clob``s
 
-Isis provides custom value types for xref:rg.adoc#_rg_classes_value-types_manpage-Blob[`Blob`]s and xref:rg.adoc#_rg_classes_value-types_manpage-Clob[`Clob`]s.  These value types have multiple internal fields, meaning that they corresponding to multiple columns in the database.  Mapping this correctly requires using  `@Column` within JDO's `@Persistent` annotation.
+Isis provides custom value types for xref:rgcms.adoc#_rgcms_classes_value-types_manpage-Blob[`Blob`]s and xref:rgcms.adoc#_rgcms_classes_value-types_manpage-Clob[`Clob`]s.  These value types have multiple internal fields, meaning that they corresponding to multiple columns in the database.  Mapping this correctly requires using  `@Column` within JDO's `@Persistent` annotation.
 
 For example, here's how to map a `Blob` (taken from (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp]):
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClassFa.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClassFa.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClassFa.adoc
index cd3cc5e..0ed1955 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClassFa.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClassFa.adoc
@@ -10,7 +10,7 @@ The `cssClassFa()` attribute is used to specify the name of a link:http://fortaw
 
 These attributes can also be applied to xref:rgant.adoc#_rgant-ViewModelLayout_cssClassFa[view models] to specify the object's icon, and to xref:rgant.adoc#_rgant-ActionLayout_cssClassFa[actions] to specify an icon for the action's representation as a button or menu item.
 
-If necessary the icon specified can be overridden by a particular object instance using the xref:rg.adoc#_rg_methods_reserved_manpage-iconName[`iconName()`] method.
+If necessary the icon specified can be overridden by a particular object instance using the xref:rgcms.adoc#_rgcms_methods_reserved_manpage-iconName[`iconName()`] method.
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClassUiEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClassUiEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClassUiEvent.adoc
index 32890ed..31d1a56 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClassUiEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClassUiEvent.adoc
@@ -7,7 +7,7 @@
 
 Whenever a domain object is to be rendered, the framework fires off an CSS class UI event to obtain a CSS class to use
 in any wrapping ``<div>``s and ``<span>``s that render the domain object.  This is as an alternative to implementing
-xref:rg.adoc#_rg_methods_reserved_manpage-cssClass[`cssClass()`] reserved method.  (If `cssClass()` is present, then
+xref:rgcms.adoc#_rgcms_methods_reserved_manpage-cssClass[`cssClass()`] reserved method.  (If `cssClass()` is present, then
 it will take precedence).
 
 Subscribers subscribe through the xref:rgsvc.adoc#_rgsvc-api_EventBusService[`EventBusService`] and can

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_iconUiEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_iconUiEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_iconUiEvent.adoc
index 2b0c525..2d20e91 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_iconUiEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_iconUiEvent.adoc
@@ -7,7 +7,7 @@
 
 Whenever a domain object is to be rendered, the framework fires off an icon UI event to obtain an icon (name) for the
 object (if possible). This is as an alternative to implementing
-xref:rg.adoc#_rg_methods_reserved_manpage-iconName[`iconName()`] reserved method.  (If `iconName()` is present, then
+xref:rgcms.adoc#_rgcms_methods_reserved_manpage-iconName[`iconName()`] reserved method.  (If `iconName()` is present, then
 it will take precedence).
 
 Subscribers subscribe through the xref:rgsvc.adoc#_rgsvc-api_EventBusService[`EventBusService`] and can

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_titleUiEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_titleUiEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_titleUiEvent.adoc
index 3e5a4cd..5cf0051 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_titleUiEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_titleUiEvent.adoc
@@ -6,7 +6,7 @@
 
 
 Whenever a domain object is to be rendered, the framework fires off a title UI event to obtain a title for the object.
-This is as an alternative to implementing xref:rg.adoc#_rg_methods_reserved_manpage-title[`title()`] reserved method, or
+This is as an alternative to implementing xref:rgcms.adoc#_rgcms_methods_reserved_manpage-title[`title()`] reserved method, or
 using the xref:rgant.adoc#_rgant-Title[`@Title`] annotation, within the class itself.  (If either
 `title()` or `@Title` are present, then they will take precedence).
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_autoCompleteRepository.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_autoCompleteRepository.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_autoCompleteRepository.adoc
index f8fbaa1..95f7899 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_autoCompleteRepository.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_autoCompleteRepository.adoc
@@ -13,7 +13,7 @@ For example, this might search for a customer by their name or number.  Or it co
 
 [TIP]
 ====
-If you require additional control - for example restricting the returned results based on the object being interacted with - then use the xref:rg.adoc#_rg_methods_prefixes_manpage-autoComplete[`autoComplete...()`] supporting method instead.
+If you require additional control - for example restricting the returned results based on the object being interacted with - then use the xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-autoComplete[`autoComplete...()`] supporting method instead.
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_bounded.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_bounded.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_bounded.adoc
index 6ae3cec..6ee3f4b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_bounded.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_bounded.adoc
@@ -28,7 +28,7 @@ public class Currency {
 
 [TIP]
 ====
-There is nothing to prevent you from using this attribute for regular mutable entities, and indeed this is sometimes worth doing during early prototyping.  However, if there is no realistic upper bound to the number of instances of an entity that might be created, generally you should use xref:rg.adoc#_rg_methods_prefixes_manpage-autoComplete[`autoComplete...()`] supporting method or the xref:rgant.adoc#_rgant-DomainObject_autoCompleteRepository[`@DomainObject#autoCompleteRepository()`] attribute instead.
+There is nothing to prevent you from using this attribute for regular mutable entities, and indeed this is sometimes worth doing during early prototyping.  However, if there is no realistic upper bound to the number of instances of an entity that might be created, generally you should use xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-autoComplete[`autoComplete...()`] supporting method or the xref:rgant.adoc#_rgant-DomainObject_autoCompleteRepository[`@DomainObject#autoCompleteRepository()`] attribute instead.
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_nature.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_nature.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_nature.adoc
index fa39886..7ba07cd 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_nature.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_nature.adoc
@@ -53,7 +53,7 @@ indicates that the domain object is conceptually part of the application layer,
 
 The identity of an inmemory entity is determined solely by the state of entity's properties.  The framework will automatically recreate the domain object each time it is interacted with.
 
-Those natures that indicate the domain object is an entity (of some sort or another) mean then that the domain object is considered to be part of the domain model layer.  As such the domain object's class cannot be annotated with xref:rgant.adoc#_rgant-ViewModel[`@ViewModel`] or implement the xref:rg.adoc#_rg_classes_super_manpage-ViewModel[`ViewModel`] interface.
+Those natures that indicate the domain object is an entity (of some sort or another) mean then that the domain object is considered to be part of the domain model layer.  As such the domain object's class cannot be annotated with xref:rgant.adoc#_rgant-ViewModel[`@ViewModel`] or implement the xref:rgcms.adoc#_rgcms_classes_super_manpage-ViewModel[`ViewModel`] interface.
 
 
 [NOTE]

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_persistingLifecycleEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_persistingLifecycleEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_persistingLifecycleEvent.adoc
index de891eb..76a25ba 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_persistingLifecycleEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_persistingLifecycleEvent.adoc
@@ -17,7 +17,7 @@ link:https://lucene.apache.org/[Apache Lucene] or similar.
 ====
 Another use case is to maintain "last updated by"/"last updated at" properties.  While you can roll your own, note that
 the framework provides built-in support for this use case through the
-xref:rg.adoc#_rg_classes_roles_manpage-Timestampable[`Timestampable`] role interface.
+xref:rgcms.adoc#_rgcms_classes_roles_manpage-Timestampable[`Timestampable`] role interface.
 ====
 
 By default the event raised is `ObjectPersistingEvent.Default`. For example:

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_removingLifecycleEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_removingLifecycleEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_removingLifecycleEvent.adoc
index 567b56c..9390c3a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_removingLifecycleEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_removingLifecycleEvent.adoc
@@ -17,7 +17,7 @@ using link:https://lucene.apache.org/[Apache Lucene] or similar.
 ====
 Another use case is to maintain "last updated by"/"last updated at" properties.  While you can roll your own, note that
 the framework provides built-in support for this use case through the
-xref:rg.adoc#_rg_classes_roles_manpage-Timestampable[`Timestampable`] role interface.
+xref:rgcms.adoc#_rgcms_classes_roles_manpage-Timestampable[`Timestampable`] role interface.
 ====
 
 By default the event raised is `ObjectRemovingEvent.Default`. For example:

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_updatingLifecycleEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_updatingLifecycleEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_updatingLifecycleEvent.adoc
index 38f579b..ef1c456 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_updatingLifecycleEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_updatingLifecycleEvent.adoc
@@ -17,7 +17,7 @@ using link:https://lucene.apache.org/[Apache Lucene] or similar.
 ====
 Another use case is to maintain "last updated by"/"last updated at" properties.  While you can roll your own, note that
 the framework provides built-in support for this use case through the
-xref:rg.adoc#_rg_classes_roles_manpage-Timestampable[`Timestampable`] role interface.
+xref:rgcms.adoc#_rgcms_classes_roles_manpage-Timestampable[`Timestampable`] role interface.
 ====
 
 By default the event raised is `ObjectUpdatingEvent.Default`. For example:

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgant-MinLength.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-MinLength.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-MinLength.adoc
index 3109f01..d896a6c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-MinLength.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-MinLength.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-The `@MinLength` annotation is used to specify the minimum number of characters in a search of an xref:rg.adoc#_rg_methods_prefixes_manpage-autoComplete[`autoComplete...()`] supporting method.
+The `@MinLength` annotation is used to specify the minimum number of characters in a search of an xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-autoComplete[`autoComplete...()`] supporting method.
 
 
 For example:

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgant-Parameter.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-Parameter.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-Parameter.adoc
index 79f3150..a191b90 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-Parameter.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-Parameter.adoc
@@ -27,7 +27,7 @@ The table below summarizes the annotation's attributes.
 |Positive integer
 |Deprecated; use xref:rgant.adoc#_rgant-MinLength[`@MinLength`] instead. +
 
-Can be used to specify the minimum length for xref:rg.adoc#_rg_methods_prefixes_manpage-autoComplete[`autoComplete...()`] supporting method; but because this _is a_ supporting method rather than the action method itself, we now feel it is misleading to use the `@Parameter` annotation in this situation.
+Can be used to specify the minimum length for xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-autoComplete[`autoComplete...()`] supporting method; but because this _is a_ supporting method rather than the action method itself, we now feel it is misleading to use the `@Parameter` annotation in this situation.
 
 
 |xref:rgant.adoc#_rgant-Parameter_mustSatisfy[`mustSatisfy()`]

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgant-PostConstruct.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-PostConstruct.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-PostConstruct.adoc
index 46e2fde..78e4cf7 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-PostConstruct.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-PostConstruct.adoc
@@ -58,7 +58,7 @@ public class MySubscribingService {
 
 [TIP]
 ====
-In this particular use case, it is generally simpler to just subclass from xref:rg.adoc#_rg_classes_super_manpage-AbstractSubscriber[`AbstractSubscriber`].
+In this particular use case, it is generally simpler to just subclass from xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractSubscriber[`AbstractSubscriber`].
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgant-PreDestroy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-PreDestroy.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-PreDestroy.adoc
index a394c01..268846a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-PreDestroy.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-PreDestroy.adoc
@@ -43,7 +43,7 @@ public class MySubscribingService {
 
 [TIP]
 ====
-In this particular use case, it is generally simpler to just subclass from xref:rg.adoc#_rg_classes_super_manpage-AbstractSubscriber[`AbstractSubscriber`].
+In this particular use case, it is generally simpler to just subclass from xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractSubscriber[`AbstractSubscriber`].
 ====
 
 Other use cases include obtaining connections to external datasources, eg subscribing to an ActiveMQ router, say, or initializing/cleaning up a background scheduler such as Quartz.

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgant-Property_editing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-Property_editing.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-Property_editing.adoc
index d4b47ca..f28a5d2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-Property_editing.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-Property_editing.adoc
@@ -17,7 +17,7 @@ Whether a property is enabled or disabled depends upon these factors:
 
 * else, then the value of the `@Property(editing=...)` attribute itself
 
-* else, the result of invoking any supporting xref:rg.adoc#_rg_methods_prefixes_manpage-disable[`disable...()`] supporting methods
+* else, the result of invoking any supporting xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-disable[`disable...()`] supporting methods
 
 
 Thus, to make a property read-only even if the object would otherwise be editable, use:

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgant-ViewModelLayout_cssClassFa.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-ViewModelLayout_cssClassFa.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-ViewModelLayout_cssClassFa.adoc
index 8a49579..e653485 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-ViewModelLayout_cssClassFa.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-ViewModelLayout_cssClassFa.adoc
@@ -12,7 +12,7 @@ The `cssClassFa()` attribute is used to specify the name of a link:http://fortaw
 These attribute can also be applied to xref:rgant.adoc#_rgant-DomainObjectLayout_cssClassFa[domain objects] to specify the object's icon, and to xref:rgant.adoc#_rgant-ActionLayout_cssClassFa[actions] to specify an icon for the action's representation as a button or menu item.
 
 
-If necessary the icon specified can be overridden by a particular object instance using the xref:rg.adoc#_rg_methods_reserved_manpage-iconName[`iconName()`] method.
+If necessary the icon specified can be overridden by a particular object instance using the xref:rgcms.adoc#_rgcms_methods_reserved_manpage-iconName[`iconName()`] method.
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgant-XmlRootElement.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-XmlRootElement.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-XmlRootElement.adoc
index 058d1b2..0e36b15 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-XmlRootElement.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-XmlRootElement.adoc
@@ -13,7 +13,7 @@ A view model is a non-persisted domain object whose state is converted to/from a
 JAXB-annotated object this memento is its XML representation.  JAXB generally requires that the root element of the
 XML representation is annotated with `@XmlRootElement`.  Apache Isis makes this a mandatory requirement.
 
-In comparison to using either the xref:rg.adoc#_rg_classes_super_manpage-ViewModel[`ViewModel`] interface or the
+In comparison to using either the xref:rgcms.adoc#_rgcms_classes_super_manpage-ViewModel[`ViewModel`] interface or the
 xref:rgant.adoc#_rgant-ViewModel[`@ViewModel`] annotation, using `@XmlRootElement` has a couple of
 significant advantages:
 
@@ -33,7 +33,7 @@ all the code by hand
 The main disadvantages of using JAXB-annotated view models is that any referenced persistent entity must be annotated
 with the xref:rgant.adoc#_rgant-XmlJavaTypeAdapter[`@XmlJavaTypeAdapter`], using the
 framework-provided `PersistentEntityAdapter`.  This adapter converts any references to such domain entities using the
-`oidDto` complex type (as defined by the Apache Isis xref:rg.adoc#_rg_schema-common[common schema]):
+`oidDto` complex type (as defined by the Apache Isis xref:rgcms.adoc#_rgcms_schema-common[common schema]):
 the object's type and its identifier.
 
 [TIP]
@@ -75,7 +75,7 @@ Although (like any other viewmodel) a JAXB-annotated can have behaviour (actions
 the DTO "clean", just focused on specifying the data contract.
 
 Behaviour can therefore be provided using xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling_mixins[mixins] (annotated with
-xref:rgant.adoc#_rgant-Mixin[`@Mixin`]), while xref:rg.adoc#_rg_classes_uievent[UI events] can be used
+xref:rgant.adoc#_rgant-Mixin[`@Mixin`]), while xref:rgcms.adoc#_rgcms_classes_uievent[UI events] can be used
 to obtain title, icons and so on.
 
 For a more complete discussion of writing JAXB view models/DTOs, see xref:ugbtb.adoc#_ugbtb_more-advanced_view-models[this topic]

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-core.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-core.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-core.adoc
index 03fbc56..925f032 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-core.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-core.adoc
@@ -214,7 +214,7 @@ See xref:ugbtb.adoc#_ugbtb_programming-model_custom-validator[Custom Validator]
 
 Each entry can be optionally prefixed by "n:" specifying the relative order on the menu (corresponds to xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`]).
 
-This property is IGNORED if the xref:rgcfg.adoc#_rgcfg_configuring-components[`isis.appManifest`] configuration property is specified, or if an xref:rg.adoc#_rg_classes_super_manpage-AppManifest[`AppManifest`] is provided programmatically.
+This property is IGNORED if the xref:rgcfg.adoc#_rgcfg_configuring-components[`isis.appManifest`] configuration property is specified, or if an xref:rgcms.adoc#_rgcms_classes_super_manpage-AppManifest[`AppManifest`] is provided programmatically.
 
 
 |`isis.services.` +
@@ -347,7 +347,7 @@ This implementation provides a default set of recognizers to convert RDBMS const
 |fully qualified package names (CSV)
 |to search for domain services (including all subpackages).
 
-This property is IGNORED if the xref:rgcfg.adoc#_rgcfg_configuring-components[`isis.appManifest`] configuration property is specified, or if an xref:rg.adoc#_rg_classes_super_manpage-AppManifest[`AppManifest`] is provided programmatically.
+This property is IGNORED if the xref:rgcfg.adoc#_rgcfg_configuring-components[`isis.appManifest`] configuration property is specified, or if an xref:rgcms.adoc#_rgcms_classes_super_manpage-AppManifest[`AppManifest`] is provided programmatically.
 
 
 |`isis.services.` +

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_disabling-persistence-by-reachability.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_disabling-persistence-by-reachability.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_disabling-persistence-by-reachability.adoc
index 4bd6b69..d4ea0df 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_disabling-persistence-by-reachability.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_disabling-persistence-by-reachability.adoc
@@ -14,7 +14,7 @@ However, convenient though this feature is, you may find that it causes performa
 DataNucleus' persistence-by-reachability may cause performance issues.  We strongly recommend that you disable it.
 ====
 
-One scenario in particular where this performance issues can arise is if your entities implement the `java.lang.Comparable` interface, and you have used Apache Isis' xref:rg.adoc#_rg_classes_utility_manpage-ObjectContracts[`ObjectContracts`] utility class. The issue here is that `ObjectContracts` implementation can cause DataNucleus to recursively rehydrate a larger number of associated entities. (More detail below).
+One scenario in particular where this performance issues can arise is if your entities implement the `java.lang.Comparable` interface, and you have used Apache Isis' xref:rgcms.adoc#_rgcms_classes_utility_manpage-ObjectContracts[`ObjectContracts`] utility class. The issue here is that `ObjectContracts` implementation can cause DataNucleus to recursively rehydrate a larger number of associated entities. (More detail below).
 
 We therefore recommend that you disable persistence-by-reachability by adding the following to `persistor_datanucleus.properties`:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_eagerly-registering-entities.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_eagerly-registering-entities.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_eagerly-registering-entities.adoc
index cbe0c44..232f17d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_eagerly-registering-entities.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_eagerly-registering-entities.adoc
@@ -14,7 +14,7 @@ Apache Isis is quite happy for the metamodel to be lazily created, and - to be f
 
 The framework thus provide mechanisms to search for all `@PersistenceCapable` entities under specified package(s), and registers them all eagerly.  In fact there are two:
 
-* as of 1.9.0 the recommended (and simpler) approach is to specify an xref:rg.adoc#_rg_classes_super_manpage-AppManifest[`AppManifest`], either as a xref:rgcfg.adoc#_rgcfg_configuring-components[`isis.appManifest`] configuration property or programmatically.
+* as of 1.9.0 the recommended (and simpler) approach is to specify an xref:rgcms.adoc#_rgcms_classes_super_manpage-AppManifest[`AppManifest`], either as a xref:rgcfg.adoc#_rgcfg_configuring-components[`isis.appManifest`] configuration property or programmatically.
 
 * for earlier versions the `isis.persistor.datanucleus.RegisterEntities.packagePrefix` configuration property can be specified.  To bootstrap as a webapp this is usually specified in `persistor_datanucleus.properties`.  (This is also supported in 1.9.0 if no `AppManifest` is specified.  For integration testing this can be specified programatically.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_properties.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_properties.adoc
index d784d71..c53b489 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_properties.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_configuring-datanucleus_properties.adoc
@@ -30,7 +30,7 @@ These configuration properties are typically stored in `WEB-INF/persistor_datanu
 |fully qualified package names (CSV)
 |that specifies the entities early rather than allow DataNucleus to find the entities lazily.  Further xref:rgcfg.adoc#_rgcfg_configuring-datanucleus_eagerly-registering-entities[discussion below].
 
-This property is IGNORED if the xref:rgcfg.adoc#_rgcfg_configuring-components[`isis.appManifest`] configuration property is specified, or if an xref:rg.adoc#_rg_classes_super_manpage-AppManifest[`AppManifest`] is provided programmatically.
+This property is IGNORED if the xref:rgcfg.adoc#_rgcfg_configuring-components[`isis.appManifest`] configuration property is specified, or if an xref:rgcms.adoc#_rgcms_classes_super_manpage-AppManifest[`AppManifest`] is provided programmatically.
 
 
 |`isis.persistor.datanucleus.` +

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcfg_specifying-components.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_specifying-components.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_specifying-components.adoc
index f51b24f..d1a7176 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcfg_specifying-components.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcfg_specifying-components.adoc
@@ -11,7 +11,7 @@ Bootstrapping an Apache Isis application involves identifying both:
 * the major components (authentication, persistence mechanisms, viewers) of Apache Isis, and also
 * specifying the domain services and persistent entities that make up the application itself.
 
-As of 1.9.0 there are two different ways to perform this bootstrapping.  The recommended (newer) approach is to use an xref:rg.adoc#_rg_classes_super_manpage-AppManifest[`AppManifest`], specified either programmatically or through the configuration properties.  This allows the components, services and entities to be specified from a single class.  The alternative (and older, pre 1.9.0) approach is to specify this information individually, through configuration properties.
+As of 1.9.0 there are two different ways to perform this bootstrapping.  The recommended (newer) approach is to use an xref:rgcms.adoc#_rgcms_classes_super_manpage-AppManifest[`AppManifest`], specified either programmatically or through the configuration properties.  This allows the components, services and entities to be specified from a single class.  The alternative (and older, pre 1.9.0) approach is to specify this information individually, through configuration properties.
 
 To specify the `AppManifest` as a configuration property, use:
 
@@ -49,7 +49,7 @@ If the `AppManifest` approach is _not_ being used, then the following configurat
 (`_shiro_`)
 |`o.a.i.core.runtime.authentication.` `AuthenticationManagerInstaller` +
 
-This property is IGNORED if the `isis.appManifest` configuration property is specified, or if an xref:rg.adoc#_rg_classes_super_manpage-AppManifest[`AppManifest`] is provided programmatically.
+This property is IGNORED if the `isis.appManifest` configuration property is specified, or if an xref:rgcms.adoc#_rgcms_classes_super_manpage-AppManifest[`AppManifest`] is provided programmatically.
 
 
 |`isis.authorization`
@@ -57,7 +57,7 @@ This property is IGNORED if the `isis.appManifest` configuration property is spe
 (`_shiro_`)
 |`o.a.i.core.runtime.authorization.` `AuthorizationManagerInstaller` +
 
-This property is IGNORED if the `isis.appManifest` configuration property is specified, or if an xref:rg.adoc#_rg_classes_super_manpage-AppManifest[`AppManifest`] is provided programmatically.
+This property is IGNORED if the `isis.appManifest` configuration property is specified, or if an xref:rgcms.adoc#_rgcms_classes_super_manpage-AppManifest[`AppManifest`] is provided programmatically.
 
 |`isis.persistor`
 |`datanucleus`
@@ -80,7 +80,7 @@ The mechanism to discover and load domain services:
 
 * Otherwise an alternative implementation of the `o.a.i.core.runtime.services.ServicesInstaller` internal API can be provided. +
 
-This property is IGNORED if the `isis.appManifest` configuration property is specified, or if an xref:rg.adoc#_rg_classes_super_manpage-AppManifest[`AppManifest`] is provided programmatically.
+This property is IGNORED if the `isis.appManifest` configuration property is specified, or if an xref:rgcms.adoc#_rgcms_classes_super_manpage-AppManifest[`AppManifest`] is provided programmatically.
 
 
 |===

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes.adoc
new file mode 100644
index 0000000..72964eb
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes.adoc
@@ -0,0 +1,23 @@
+[[_rgcms_classes]]
+= Classes and Interfaces
+: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 chapter describes the usage of various classes and interfaces that are not otherwise associated with xref:rgsvc.adoc#_rgsvc-api[domain] xref:rgsvc.adoc#_rgsvc-spi[services], xref:ug.adoc#_ug_object-layout[object layout] or xref:rgcfg.adoc#_rgcfg[configuration].
+
+
+include::_rgcms_classes_AppManifest-bootstrapping.adoc[leveloffset=+1]
+include::_rgcms_classes_super.adoc[leveloffset=+1]
+include::_rgcms_classes_domainevent.adoc[leveloffset=+1]
+include::_rgcms_classes_uievent.adoc[leveloffset=+1]
+include::_rgcms_classes_lifecycleevent.adoc[leveloffset=+1]
+include::_rgcms_classes_value-types.adoc[leveloffset=+1]
+include::_rgcms_classes_utility.adoc[leveloffset=+1]
+include::_rgcms_classes_spec.adoc[leveloffset=+1]
+include::_rgcms_classes_i18n.adoc[leveloffset=+1]
+include::_rgcms_classes_contributee.adoc[leveloffset=+1]
+include::_rgcms_classes_roles.adoc[leveloffset=+1]
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_AppManifest-bootstrapping.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_AppManifest-bootstrapping.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_AppManifest-bootstrapping.adoc
new file mode 100644
index 0000000..25fd561
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_AppManifest-bootstrapping.adoc
@@ -0,0 +1,282 @@
+[[_rgcms_classes_AppManifest-bootstrapping]]
+= `AppManifest` (bootstrapping)
+: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 section describes how to implement the `AppManifest` interface to bootstrap both an Apache Isis web application, and also its integration tests.
+
+
+
+== API
+
+
+The `AppManifest` interface allows the constituent parts of an application to be defined programmatically, most specifically the packages that contain domain services and/or persistent entities.  Its API is defined as:
+
+[source,java]
+----
+public interface AppManifest {
+    public List<Class<?>> getModules();                         // <1>
+    public List<Class<?>> getAdditionalServices();              // <2>
+    public String getAuthenticationMechanism();                 // <3>
+    public String getAuthorizationMechanism();                  // <4>
+    public List<Class<? extends FixtureScript>> getFixtures();  // <5>
+    public Map<String,String> getConfigurationProperties();     // <6>
+}
+----
+<1> Must return a non-null list of classes, each of which representing the root of one of the modules containing services and possibly entities, which together makes up the running application.
+<2> If non-`null`, overrides the value of `isis.services` configuration property to specify a list of additional classes to be instantiated as domain services (over and above the domain services defined via `getModules()` method.
+<3> If non-`null`, overrides the value of `isis.authentication` configuration property to specify the authentication mechanism.
+<4> If non-`null`, overrides the value of `isis.authorization` configuration property to specify the authorization mechanism.
+<5> If non-`null`, overrides the value of `isis.fixtures` configuration property to specify a fixture script to be installed.
+<6> Overrides for any other configuration properties.
+
+The following sections describe each of these methods in a little more detail.
+
+
+
+
+=== `getModules()`
+
+The most significant method (the only one which must return a non-`null` value) is the `getModules()` method.  Each module is identified by a class; the framework simply uses that class' package as the root to search for domain services (annotated with xref:rgant.adoc#_rgant-DomainService[`@DomainService`]) and entities (annotated with xref:rgant.adoc#_rgant-PersistenceCapable[`@PersistenceCapable`]).  Generally there is one such module class per Maven module.
+
+A module class for a domain module might for example be defined as:
+
+[source,java]
+----
+package com.mycompany.myapp.dom;
+public final class MyAppDomainModule {
+    private MyAppDomainModule() {}
+}
+----
+
+This tells the framework that the package and subpackages under `com.mycompany.myapp.dom` should be searched for domain services and entities.
+
+As is perhaps apparent, the `getModules()` method replaces and overrides both the `isis.services.ServicesInstallerFromAnnotation.packagePrefix` key (usually found in the `isis.properties`  file) and also the`isis.persistor.datanucleus.RegisterEntities.packagePrefix` key (usually found in the `persistor_datanucleus.properties` file).  The value of the `isis.services-installer` configuration property is also ignored.
+
+For example, the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] defines the following:
+
+[source,java]
+----
+@Override
+public List<Class<?>> getModules() {
+    return Arrays.asList(
+            ToDoAppDomainModule.class,
+            ToDoAppFixtureModule.class,
+            ToDoAppAppModule.class,
+            org.isisaddons.module.audit.AuditModule.class,
+            org.isisaddons.module.command.CommandModule.class,
+            org.isisaddons.module.devutils.DevUtilsModule.class,
+            org.isisaddons.module.docx.DocxModule.class,
+            org.isisaddons.module.publishing.PublishingModule.class,
+            org.isisaddons.module.sessionlogger.SessionLoggerModule.class,
+            org.isisaddons.module.settings.SettingsModule.class,
+            org.isisaddons.wicket.gmap3.cpt.service.Gmap3ServiceModule.class
+    );
+}
+----
+
+As can be seen, the various (non-ASF) link:http://isisaddons.org[Isis Addons] modules also each provide a module class that can be easily referenced.
+
+
+=== `getAdditionalServices()`
+
+We normally we recommend that services are defined exclusively through `getModules()`, and that this method should therefore return an empty list.  However, there are certain use cases where the a service must be explicitly specified either because the service required does not (for whatever reason) have a xref:rgant.adoc#_rgant-DomainService[`@DomainService`] annotation.
+
+For example, the (non-ASF) http://github.com/isisaddons/isis-module-security[Isis addons' security] module (v1.9.0) allows the policy to evaluate conflicting permissions to be specified by explicitly registering either the `PermissionsEvaluationServiceAllowBeatsVeto` domain service or the `PermissionsEvaluationServiceVetoBeatsAllow` domain service:
+
+[source,java]
+----
+@Override
+public List<Class<?>> getAdditionalServices() {
+    return Arrays.asList(
+            org.isisaddons.module.security.dom.permission.PermissionsEvaluationServiceVetoBeatsAllow.class
+    );
+}
+----
+
+If this method returns a non-`null` value, then it overrides the value of `isis.services` configuration property.
+
+
+
+
+=== `getAuthenticationMechanism()`
+
+If non-`null`, this method specifies the authentication mechanism to use.  The valid values are currently `"shiro"`  or `"bypass"`.  If null is returned then the value of the `isis.authentication` configuration property (in `isis.properties` file) is used instead.
+
+See the xref:ugsec.adoc#[security guide] for further details on configuring shiro or bypass security.
+
+[NOTE]
+====
+This property is ignored for integration tests (which always uses the `"bypass"` mechanism).
+====
+
+
+
+=== `getAuthorizationMechanism()`
+
+If non-`null`, this method specifies the authorization mechanism to use.  The valid values are currently `"shiro"`  or `"bypass"`.  If null is returned then the value of the `isis.authorization` configuration property (in `isis.properties` file) is used instead.
+
+See the xref:ugsec.adoc#[security guide] for further details on configuring shiro or bypass security.
+
+[NOTE]
+====
+This property is ignored for integration tests (which always uses the `"bypass"` mechanism).
+====
+
+
+
+
+=== `getFixtures()`
+
+If non-`null`, this method specifies the fixture script(s) to be run on startup.  This is particularly useful when developing or demoing while using an in-memory database.
+
+For example:
+
+[source,java]
+----
+@Override
+public List<Class<? extends FixtureScript>> getFixtures() {
+    return Lists.newArrayList(todoapp.fixture.demo.DemoFixture.class);
+}
+----
+
+
+
+Note that in order for fixtures to be installed it is also necessary to set the `isis.persistor.datanucleus.install-fixtures` key to `true`.  This can most easily be done using the `getConfigurationProperties()` method, discussed below.
+
+
+
+=== `getConfigurationProperties()`
+
+This method allow arbitrary other configuration properties to be overridden.  One common use case is in conjunction with the `getFixtures()` method, discussed above:
+
+[source,java]
+----
+@Override
+public Map<String, String> getConfigurationProperties() {
+    Map<String, String> props = Maps.newHashMap();
+    props.put("isis.persistor.datanucleus.install-fixtures", "true");
+    return props;
+}
+----
+
+
+
+
+
+
+
+== Bootstrapping
+
+One of the primary goals of the `AppManifest` is to unify the bootstrapping of both integration tests and the webapp.  This requires that the integration tests and webapp can both reference the implementation.
+
+We strongly recommend using a `myapp-app` Maven module to hold the implementation of the `AppManifest`.  This Maven module can then also hold dependencies which are common to both integration tests and the webapp, specifically the `org.apache.isis.core:isis-core-runtime` and the `org.apache.isis.core:isis-core-wrapper` modules.
+
+We also strongly recommend that any application-layer domain services and view models (code that references persistent domain entities but that is not referenced back) is moved to this `myapp-app` module.  This will allow the architectural layering of the overall application to be enforced by Maven.
+
+What then remains is to update the bootstrapping code itself.
+
+
+=== Integration Tests
+
+Bootstrapping integration tests is still performed using the `IsisSystemForTest.Builder`, but very often the bootstrapping code can be substantially simplified (compared to not using an `AppManifest`, that is).
+
+For example, this is the bootstrapping code for the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype] looks something like:
+
+[source,java]
+----
+public class DomainAppSystemInitializer {
+    public static void initIsft() {
+        IsisSystemForTest isft = IsisSystemForTest.getElseNull();
+        if(isft == null) {
+            isft = new IsisSystemForTest.Builder()
+                    .withLoggingAt(org.apache.log4j.Level.INFO)
+                    .with(new MyAppAppManifest())
+                    .with(new IsisConfigurationForJdoIntegTests())
+                    .build()
+                    .setUpSystem();
+            IsisSystemForTest.set(isft);
+        }
+    }
+}
+----
+
+
+
+
+=== Webapps
+
+To bootstrap an Apache Isis webapp (using the xref:ugvw.adoc#[Wicket viewer]), there are two choices:
+
+* either specify the `AppManifest` by overriding the `IsisWicketApplication#newWicketModule()`, eg: +
++
+[source,java]
+----
+@Override
+protected Module newIsisWicketModule() {
+    final Module isisDefaults = super.newIsisWicketModule();
+    ...
+    final Module overrides = new AbstractModule() {
+        @Override
+        protected void configure() {
+            ...
+            bind(AppManifest.class).toInstance(new MyAppAppManifest());
+        }
+    };
+    return Modules.override(isisDefaults).with(overrides);
+}
+----
+
+* alternatively update `isis.properties`, using the `isis.appManifest` key to specify the `AppManifest` implementation, eg: +
++
+[source,ini]
+----
+isis.appManifest=domainapp.app.MyAppAppManifest
+----
+
+The first (programmatic) approach takes precedence over the second approach (configuration properties).
+
+[TIP]
+====
+If you use the `org.apache.isis.WebServer` class to launch your application from the xref:ugbtb.adoc#_ugbtb_deployment_cmd-line[command line], then note that you can specify the `AppManifest` using the `-m` (or `--manifest`) flag:
+
+[source,ini]
+----
+java org.apache.isis.WebServer -m com.mycompany.myapp.MyAppAppManifestWithFixtures
+----
+
+====
+
+
+
+
+
+
+
+
+
+
+== Subsidiary Goals
+
+There are a number of subsidiary goals of the `AppManifest` class (though as of v1.9.0 these have not yet implemented):
+
+* Allow different integration tests to run with different manifests.
+
+** Normally the running application is shared (on a thread-local) between integration tests. What the framework could do is to be intelligent enough to keep track of the manifest in use for each integration test and tear down the shared state if the "next" test uses a different manifest
+
+* Speed up bootstrapping by only scanning for classes annotated by `@DomainService` and `@PersistenceCapable` once.
+
+* Provide a programmatic way to contribute elements of `web.xml`.
+
+* Provide a programmatic way to configure Shiro security.
+
+* Anticipate the module changes forthcoming in Java 9.
+
+** Eventually we see that the `AppManifest` class acting as an "aggregator", with the list of modules will become Java 9 modules each advertising the types that they export.
+** It might even be possible for ``AppManifest``s to be switched on and off dynamically (eg if Java9 is compatible with OSGi, being one of the design goals).
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_contributee.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_contributee.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_contributee.adoc
new file mode 100644
index 0000000..6c39e33
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_contributee.adoc
@@ -0,0 +1,13 @@
+[[_rgcms_classes_contributee]]
+= Contributee
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+The interfaces listed in this chapter act as contributees; they allow domain services to contribute actions/properties/collections to any domain objects that implement these interfaces.
+
+
+include::_rgcms_classes_contributee_manpage-HasTransactionId.adoc[leveloffset=+1]
+include::_rgcms_classes_contributee_manpage-HasUserName.adoc[leveloffset=+1]
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_contributee_manpage-HasTransactionId.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_contributee_manpage-HasTransactionId.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_contributee_manpage-HasTransactionId.adoc
new file mode 100644
index 0000000..f0c2a76
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_contributee_manpage-HasTransactionId.adoc
@@ -0,0 +1,31 @@
+[[_rgcms_classes_mixins_manpage-HasTransactionId]]
+= `HasTransactionId`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+The `HasTransactionId` interface is a mix-in for any domain objects that reference a transaction id, such as
+auditing entries or commands.
+
+The interface is defined is:
+
+[source,java]
+----
+public interface HasTransactionId {
+
+    public UUID getTransactionId();                             // <1>
+    public void setTransactionId(final UUID transactionId);
+}
+----
+<1> unique identifier (a GUID) of the transaction in which this interaction occurred.
+
+
+
+Modules that either have domain entity that implement and/or services that contribute this interface are:
+
+* (non-ASF) http://github.com/isisaddons/isis-module-audit[Isis addons' audit] module (`AuditEntry` entity, `AuditingServiceContributions` service)
+* (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module (`CommandJdo` entity, `CommandServiceJdoContributions` service)
+* (non-ASF) http://github.com/isisaddons/isis-module-publishing[Isis addons' publishing] module (`PublishedEvent` entity, `PublishingServiceContributions`)
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_contributee_manpage-HasUserName.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_contributee_manpage-HasUserName.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_contributee_manpage-HasUserName.adoc
new file mode 100644
index 0000000..2fb0d4b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_contributee_manpage-HasUserName.adoc
@@ -0,0 +1,27 @@
+[[_rgcms_classes_mixins_manpage-HasUserName]]
+= `HasUsername`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+The `HasUsername` interface is a mix-in for domain objects to be associated with a username.  Other services and modules can then contribute actions/collections to render such additional information relating to the activities of the user.
+
+The interface is defined is:
+
+[source,java]
+----
+public interface HasUsername {
+    public String getUsername();
+}
+----
+
+Modules that either have domain entity that implement and/or services that contribute this interface are:
+
+* (non-ASF) http://github.com/isisaddons/isis-module-security[Isis addons' security] module ( `ApplicationUser` entity, `HasUsernameContributions` service)
+* (non-ASF) http://github.com/isisaddons/isis-module-audit[Isis addons' audit] module (`AuditEntry` entity,
+* (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module's `CommandJdo` entity, `HasUsernameContributions` service)
+* (non-ASF) http://github.com/isisaddons/isis-module-publishing[Isis addons' publishing] module (`PublishedEvent` entity)
+* (non-ASF) http://github.com/isisaddons/isis-module-sessionlogger[Isis addons' sessionlogger] module (`SessionLogEntry` entity, `HasUsernameContributions` service)
+* (non-ASF) http://github.com/isisaddons/isis-module-settings[Isis addons' settings] module (`UserSettingJdo` entity)
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent.adoc
new file mode 100644
index 0000000..6cbfabd
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent.adoc
@@ -0,0 +1,76 @@
+[[_rgcms_classes_domainevent]]
+= Domain Event Classes
+: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 section catalogues the various domain event classes defined by Apache Isis.
+
+These events are broadcast on the xref:rgsvc.adoc#_rgsvc-api_EventBusService[`EventBusService`].  The domain
+events are broadcast as a result of being specified in the xref:rgant.adoc#_rgant-Action_domainEvent[`@Action#domainEvent()`],  xref:rgant.adoc#_rgant-Property_domainEvent[`@Property#domainEvent()`] or xref:rgant.adoc#_rgant-Collection_domainEvent[`@Collection#domainEvent()`] attributes.
+
+They are listed in the table below.
+
+.Domain Event Classes
+[cols="2,4a,1,1", options="header"]
+|===
+
+|API
+|Maven Module +
+Impl'n (g: a:)
+|Implementation
+|Notes
+
+
+|xref:rgcms.adoc#_rgcms_classes_domainevent_manpage-AbstractDomainEvent[`o.a.i.applib.` +
+`AbstractDomainEvent`]
+|``o.a.i.core`` +
+``services.eventbus`` +
+``isis-core-applib``
+|(abstract class)
+|Superclass of the other domain events, listed below in this table.
+
+
+|xref:rgcms.adoc#_rgcms_classes_domainevent_manpage-ActionDomainEvent[`o.a.i.applib.` +
+`ActionDomainEvent`]
+|``o.a.i.core`` +
+``services.eventbus`` +
+``isis-core-applib``
+|(abstract class). +
+`ActionDomainEvent.Default` is the concrete implementation used if no `@Action#domainEvent` attribute is specified
+|Broadcast whenever there is an interaction (hide/disable/validate/pre-execute/post-execute) with an object's action.
+
+
+|xref:rgcms.adoc#_rgcms_classes_domainevent_manpage-CollectionDomainEvent[`o.a.i.applib.` +
+`CollectionDomainEvent`]
+|``o.a.i.core`` +
+``services.eventbus`` +
+``isis-core-applib``
+|(abstract class). +
+`CollectionDomainEvent.Default` is the concrete implementation used if no `@Collection#domainEvent` attribute
+is specified.
+|Broadcast whenever there is an interaction (hide/disable/validate/access) with an object's collection.
+
+
+|xref:rgcms.adoc#_rgcms_classes_domainevent_manpage-PropertyDomainEvent[`o.a.i.applib.` +
+`PropertyDomainEvent`]
+|``o.a.i.core`` +
+``services.eventbus`` +
+``isis-core-applib``
+|(abstract class). +
+`PropertyDomainEvent.Default` is the concrete implementation used if no `@Propert#domainEvent` attribute is specified
+|Broadcast whenever there is an interaction (hide/disable/validate/access) with an object's property.
+
+
+
+|===
+
+
+
+
+include::_rgcms_classes_domainevent_manpage-AbstractDomainEvent.adoc[leveloffset=+1]
+include::_rgcms_classes_domainevent_manpage-ActionDomainEvent.adoc[leveloffset=+1]
+include::_rgcms_classes_domainevent_manpage-CollectionDomainEvent.adoc[leveloffset=+1]
+include::_rgcms_classes_domainevent_manpage-PropertyDomainEvent.adoc[leveloffset=+1]
+

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_manpage-AbstractDomainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_manpage-AbstractDomainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_manpage-AbstractDomainEvent.adoc
new file mode 100644
index 0000000..80ed308
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_domainevent_manpage-AbstractDomainEvent.adoc
@@ -0,0 +1,20 @@
+[[_rgcms_classes_domainevent_manpage-AbstractDomainEvent]]
+= `AbstractDomainEvent`
+: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 class is the superclass for all domain events that are raised by the framework when interacting with actions, properties or collections.
+
+Its immediate subclasses are:
+
+* xref:rgcms.adoc#_rgcms_classes_domainevent_manpage-ActionDomainEvent[`ActionDomainEvent`]
+
+* xref:rgcms.adoc#_rgcms_classes_domainevent_manpage-PropertyDomainEvent[`PropertyDomainEvent`]
+
+* xref:rgcms.adoc#_rgcms_classes_domainevent_manpage-CollectionDomainEvent[`CollectionDomainEvent`]
+
+This class defines the `Phase` enum that is common to all domain events (hide/disable/validate/pre-execute/post-execute), and provides methods such as `veto(...)` by which subscribers can influence the interaction (eg hide a collection, disable a property, validate action arguments).
+
+It class also provides `get(...)` and `put(...)` methods that allow adhoc sharing of user data between different phases.  One event instance is used for both the hide and disable phases, and a different event instance is shared between validate/pre-execute/post-execute.


[37/52] [abbrv] isis git commit: ISIS-1237: can now invoke actions (GET and POST) via swagger-ui

Posted by mg...@apache.org.
ISIS-1237: can now invoke actions (GET and POST) via swagger-ui


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/15cd677e
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/15cd677e
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/15cd677e

Branch: refs/heads/ISIS-1224-select2-v4
Commit: 15cd677e70ba9adc53d5403d334a8de1774cf6c8
Parents: 86b960a
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Wed Dec 9 08:17:17 2015 +0000
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Wed Dec 9 08:17:17 2015 +0000

----------------------------------------------------------------------
 .../swagger/internal/SwaggerSpecGenerator.java  | 164 +++++++++++++++++--
 .../ContentNegotiationServiceAbstract.java      |  19 ++-
 ...estfulObjectsApplicationExceptionMapper.java |  12 +-
 .../webapp/src/main/webapp/WEB-INF/web.xml      |   2 +-
 4 files changed, 175 insertions(+), 22 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/15cd677e/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGenerator.java
----------------------------------------------------------------------
diff --git a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGenerator.java b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGenerator.java
index 0e729ec..fb40928 100644
--- a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGenerator.java
+++ b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGenerator.java
@@ -23,7 +23,9 @@ import java.util.Collection;
 import java.util.List;
 
 import com.fasterxml.jackson.core.JsonProcessingException;
+import com.google.common.base.Strings;
 
+import org.apache.isis.applib.annotation.ActionSemantics;
 import org.apache.isis.applib.annotation.NatureOfService;
 import org.apache.isis.applib.filter.Filters;
 import org.apache.isis.applib.services.swagger.SwaggerService;
@@ -35,6 +37,7 @@ import org.apache.isis.core.metamodel.spec.ObjectSpecification;
 import org.apache.isis.core.metamodel.spec.SpecificationLoader;
 import org.apache.isis.core.metamodel.spec.feature.Contributed;
 import org.apache.isis.core.metamodel.spec.feature.ObjectAction;
+import org.apache.isis.core.metamodel.spec.feature.ObjectActionParameter;
 
 import io.swagger.models.Info;
 import io.swagger.models.ModelImpl;
@@ -42,10 +45,13 @@ import io.swagger.models.Operation;
 import io.swagger.models.Path;
 import io.swagger.models.Response;
 import io.swagger.models.Swagger;
+import io.swagger.models.parameters.BodyParameter;
+import io.swagger.models.parameters.QueryParameter;
 import io.swagger.models.properties.ArrayProperty;
 import io.swagger.models.properties.IntegerProperty;
 import io.swagger.models.properties.MapProperty;
 import io.swagger.models.properties.ObjectProperty;
+import io.swagger.models.properties.Property;
 import io.swagger.models.properties.RefProperty;
 import io.swagger.models.properties.StringProperty;
 import io.swagger.util.Json;
@@ -69,9 +75,8 @@ public class SwaggerSpecGenerator {
                         new Path()
                             .get(new Operation()
                                     .description(roSpec("5.1"))
-                                    .consumes("application/json")
-                                    .consumes("application/json;profile=\"urn:org.restfulobjects:repr-types/home-page\"")
-                                    .produces("application/json;profile=\"urn:org.restfulobjects:repr-types/home-page\"")
+                                    .produces("application/json")
+                                    .produces("application/json;profile=urn:org.restfulobjects:repr-types/home-page")
                                     .response(200,
                                             newResponse(Caching.NON_EXPIRING)
                                             .description("OK")
@@ -81,9 +86,8 @@ public class SwaggerSpecGenerator {
                         new Path()
                             .get(new Operation()
                                     .description(roSpec("6.1"))
-                                    .consumes("application/json")
-                                    .consumes("application/json;profile=\"urn:org.restfulobjects:repr-types/user\"")
-                                    .produces("application/json;profile=\"urn:org.restfulobjects:repr-types/user\"")
+                                    .produces("application/json")
+                                    .produces("application/json;profile=urn:org.restfulobjects:repr-types/user")
                                     .response(200,
                                             newResponse(Caching.USER_INFO)
                                             .description("OK")
@@ -93,9 +97,8 @@ public class SwaggerSpecGenerator {
                         new Path()
                                 .get(new Operation()
                                         .description(roSpec("7.1"))
-                                        .consumes("application/json")
-                                        .consumes("application/json;profile=\"urn:org.restfulobjects:repr-types/services\"")
-                                        .produces("application/json;profile=\"urn:org.restfulobjects:repr-types/services\"")
+                                        .produces("application/json")
+                                        .produces("application/json;profile=urn:org.restfulobjects:repr-types/services")
                                         .response(200,
                                                 newResponse(Caching.USER_INFO)
                                                         .description("OK")
@@ -106,9 +109,8 @@ public class SwaggerSpecGenerator {
                         new Path()
                             .get(new Operation()
                                     .description(roSpec("8.1"))
-                                    .consumes("application/json")
-                                    .consumes("application/json;profile=\"urn:org.restfulobjects:repr-types/version\"")
-                                    .produces("application/json;profile=\"urn:org.restfulobjects:repr-types/version\"")
+                                    .produces("application/json")
+                                    .produces("application/json;profile=urn:org.restfulobjects:repr-types/version")
                                     .response(200,
                                             newResponse(Caching.NON_EXPIRING)
                                             .description("OK")
@@ -198,11 +200,14 @@ public class SwaggerSpecGenerator {
             final String serviceDefinitionId = "service-" + serviceId;
 
             final Path servicePath = new Path();
-            swagger.path("/services/" + serviceId, servicePath);
+            final String servicePathStr = "/services/" + serviceId;
+            swagger.path(servicePathStr, servicePath);
 
             servicePath.get(
                     new Operation()
                         .description(roSpec("15.1"))
+                        .produces("application/json")
+                        .produces("application/json;profile=urn:org.restfulobjects:repr-types/object")
                         .response(200,
                                 newResponse(Caching.TRANSACTIONAL)
                                     .description("OK")
@@ -221,18 +226,129 @@ public class SwaggerSpecGenerator {
 
             for (final ObjectAction serviceAction : serviceActions) {
                 String serviceActionId = serviceAction.getId();
+
+                // within the services representation itself
+                final String serviceActionPromptPathRelStr = "actions/" + serviceActionId;
                 serviceMembers.property(serviceActionId,
                         new ObjectProperty()
                             .property("id", stringPropertyEnum(serviceActionId))
                             .property("memberType", stringPropertyEnum("action"))
                             .property("links",
                                     new ObjectProperty()
-                                        .property("rel", stringPropertyEnum("urn:org.restfulobjects:rels/details;action=\"" + serviceActionId + "\""))
-                                        .property("href", stringPropertyEnum("actions/"
-                                                + serviceActionId)))
+                                        .property("rel", stringPropertyEnum("urn:org.restfulobjects:rels/details;action=" + serviceActionId + ""))
+                                        .property("href", stringPropertyEnum(serviceActionPromptPathRelStr)))
                             .property("method", stringPropertyEnum("GET"))
-                            .property("type", stringPropertyEnum("application/json;profile=\"urn:org.restfulobjects:repr-types/object-action\""))
+                            .property("type", stringPropertyEnum("application/json;profile=urn:org.restfulobjects:repr-types/object-action"))
                 );
+
+                // and for the service action's own resources (prompt and invoke)
+                final ObjectProperty actionParametersRepr = new ObjectProperty();
+                swagger.path(servicePathStr + "/" + serviceActionPromptPathRelStr,
+                        new Path()
+                                .get(
+                                        new Operation()
+                                                .description(roSpec("18.1") + ": (prompt) resource for " + serviceId + "#" + serviceActionId)
+                                                .produces("application/json")
+                                                .produces("application/json;profile=urn:org.restfulobjects:repr-types/object-action")
+                                                .response(200,
+                                                        new Response()
+                                                                .description(roSpec("18.2") + ": (prompt) representation of " + serviceId + "#" + serviceActionId)
+                                                                .schema(new ObjectProperty()
+                                                                        .property("id",
+                                                                                stringPropertyEnum(serviceActionId))
+                                                                        .property("memberType",
+                                                                                stringPropertyEnum("action"))
+                                                                        .property("links", arrayOfLinksGetOnly())
+                                                                        .property("parameters", actionParametersRepr)
+                                                                ))));
+                final List<ObjectActionParameter> parameters = serviceAction.getParameters();
+
+                int i = 0;
+                for (final ObjectActionParameter parameter : parameters) {
+                    final String parameterId = parameter.getId();
+                    actionParametersRepr.property(parameterId,
+                            new ObjectProperty()
+                                .property("num", new IntegerProperty()._default(i++))
+                                .property("id", stringPropertyEnum(parameterId))
+                                .property("name", stringPropertyEnum(parameter.getName()))
+                                .property("description", stringPropertyEnum(parameter.getDescription()))
+                    );
+                }
+
+                // invoke path
+                final Path serviceActionInvokePath = new Path();
+                swagger.path( servicePathStr + "/" + serviceActionPromptPathRelStr + "/invoke", serviceActionInvokePath);
+
+                final Operation invokeOperation =
+                        new Operation()
+                            .description(roSpec("19.1") + ": (invoke) resource of " + serviceId + "#" + serviceActionId)
+                            .produces("application/json")
+                            .produces("application/json;profile=urn:org.restfulobjects:repr-types/action-result")
+                            .produces("application/json;profile=urn:org.apache.isis/v1")
+                            .produces("application/json;profile=urn:org.apache.isis/v1;suppress=true");
+
+                final ActionSemantics.Of semantics = serviceAction.getSemantics();
+                if(semantics.isSafeInNature()) {
+                    serviceActionInvokePath.get(invokeOperation);
+
+                    for (final ObjectActionParameter parameter : parameters) {
+                        invokeOperation
+                                .parameter(
+                                        new QueryParameter()
+                                                .name(parameter.getId())
+                                                .description(roSpec("2.9.1") + (!Strings.isNullOrEmpty(parameter.getDescription())? (": " + parameter.getDescription()) : ""))
+                                                .required(false)
+                                                .type("string")
+                                );
+                    }
+                    if(!parameters.isEmpty()) {
+                        invokeOperation.parameter(new QueryParameter()
+                                .name("x-isis-querystring")
+                                .description(roSpec("2.10") + ": all (formal) arguments as base64 encoded string")
+                                .required(false)
+                                .type("string"));
+                    }
+
+                } else {
+                    if (semantics.isIdempotentInNature()) {
+                        serviceActionInvokePath.put(invokeOperation);
+                    } else {
+                        serviceActionInvokePath.post(invokeOperation);
+                    }
+
+                    final ModelImpl bodyParam =
+                            new ModelImpl()
+                                .type("object");
+                    for (final ObjectActionParameter parameter : parameters) {
+
+                        final Property valueProperty;
+                        // TODO: need to switch on parameter's type and create appopriate impl of valueProperty
+                        // if(parameter.getSpecification().isValue()) ...
+                        valueProperty = stringProperty();
+
+                        bodyParam
+                                .property(parameter.getId(),
+                                        new ObjectProperty()
+                                                .property("value", valueProperty)
+                                );
+                    }
+
+                    invokeOperation
+                            .consumes("application/json")
+                            .parameter(
+                                    new BodyParameter()
+                                            .name("body")
+                                            .schema(bodyParam));
+
+                }
+
+
+                invokeOperation
+                        .response(
+                                200, new Response()
+                                        .description(roSpecForResponseOf(serviceAction) + ": (invoke) representation of " + serviceId + "#" + serviceActionId)
+                                    .schema(new ObjectProperty())
+                        );
             }
 
         }
@@ -251,6 +367,20 @@ public class SwaggerSpecGenerator {
         }
     }
 
+    private String roSpecForResponseOf(final ObjectAction action) {
+        final ActionSemantics.Of semantics = action.getSemantics();
+        switch (semantics) {
+            case SAFE_AND_REQUEST_CACHEABLE:
+            case SAFE:
+                return "19.2";
+            case IDEMPOTENT:
+            case IDEMPOTENT_ARE_YOU_SURE:
+                return "19.3";
+            default:
+                return "19.4";
+        }
+    }
+
     boolean isVisible(final SwaggerService.Visibility visibility, final DomainServiceFacet domainServiceFacet) {
         if (domainServiceFacet.getNatureOfService() == NatureOfService.VIEW_REST_ONLY) {
             return true;

http://git-wip-us.apache.org/repos/asf/isis/blob/15cd677e/core/viewer-restfulobjects-rendering/src/main/java/org/apache/isis/viewer/restfulobjects/rendering/service/conneg/ContentNegotiationServiceAbstract.java
----------------------------------------------------------------------
diff --git a/core/viewer-restfulobjects-rendering/src/main/java/org/apache/isis/viewer/restfulobjects/rendering/service/conneg/ContentNegotiationServiceAbstract.java b/core/viewer-restfulobjects-rendering/src/main/java/org/apache/isis/viewer/restfulobjects/rendering/service/conneg/ContentNegotiationServiceAbstract.java
index 18dc7c1..2b3fe26 100644
--- a/core/viewer-restfulobjects-rendering/src/main/java/org/apache/isis/viewer/restfulobjects/rendering/service/conneg/ContentNegotiationServiceAbstract.java
+++ b/core/viewer-restfulobjects-rendering/src/main/java/org/apache/isis/viewer/restfulobjects/rendering/service/conneg/ContentNegotiationServiceAbstract.java
@@ -133,7 +133,7 @@ public abstract class ContentNegotiationServiceAbstract implements ContentNegoti
             final List<MediaType> acceptableMediaTypes,
             final String parameter, final String parameterValue) {
         for (MediaType mediaType : acceptableMediaTypes) {
-            final String paramValue = mediaType.getParameters().get(parameter);
+            final String paramValue = sanitize(mediaType.getParameters().get(parameter));
             if (Objects.equals(paramValue, parameterValue)) {
                 return true;
             }
@@ -141,6 +141,23 @@ public abstract class ContentNegotiationServiceAbstract implements ContentNegoti
         return false;
     }
 
+    /**
+     * Remove any single quotes.
+     */
+    private String sanitize(String mediaParam) {
+        if (mediaParam == null) {
+            return null;
+        }
+        mediaParam = mediaParam.trim();
+        if(mediaParam.startsWith("'")) {
+            mediaParam = mediaParam.substring(1);
+        }
+        if(mediaParam.endsWith("'")) {
+            mediaParam = mediaParam.substring(0, mediaParam.length()-1);
+        }
+        return mediaParam;
+    }
+
     //endregion
 
     @Inject

http://git-wip-us.apache.org/repos/asf/isis/blob/15cd677e/core/viewer-restfulobjects-server/src/main/java/org/apache/isis/viewer/restfulobjects/server/RestfulObjectsApplicationExceptionMapper.java
----------------------------------------------------------------------
diff --git a/core/viewer-restfulobjects-server/src/main/java/org/apache/isis/viewer/restfulobjects/server/RestfulObjectsApplicationExceptionMapper.java b/core/viewer-restfulobjects-server/src/main/java/org/apache/isis/viewer/restfulobjects/server/RestfulObjectsApplicationExceptionMapper.java
index 1bc04ed..9ad8be3 100644
--- a/core/viewer-restfulobjects-server/src/main/java/org/apache/isis/viewer/restfulobjects/server/RestfulObjectsApplicationExceptionMapper.java
+++ b/core/viewer-restfulobjects-server/src/main/java/org/apache/isis/viewer/restfulobjects/server/RestfulObjectsApplicationExceptionMapper.java
@@ -51,11 +51,17 @@ public class RestfulObjectsApplicationExceptionMapper implements ExceptionMapper
             builder.header(RestfulResponse.Header.WARNING.getName(), RestfulResponse.Header.WARNING.render(message));
         }
 
-        // xml handling
-        boolean xml = false;
+        // xml handling (only if also not text/html, ie what browsers would send).
+        boolean html = false;
         final List<MediaType> acceptableMediaTypes = httpHeaders.getAcceptableMediaTypes();
         for (MediaType acceptableMediaType : acceptableMediaTypes) {
-            xml = xml || acceptableMediaType.getSubtype().equals("xml");
+            html = html || (acceptableMediaType.getType().equals("text") && acceptableMediaType.getSubtype().equals("html"));
+        }
+        boolean xml = false;
+        if(!html) {
+            for (MediaType acceptableMediaType : acceptableMediaTypes) {
+                xml = xml || acceptableMediaType.getSubtype().equals("xml");
+            }
         }
 
         // body and content-type

http://git-wip-us.apache.org/repos/asf/isis/blob/15cd677e/example/application/simpleapp/webapp/src/main/webapp/WEB-INF/web.xml
----------------------------------------------------------------------
diff --git a/example/application/simpleapp/webapp/src/main/webapp/WEB-INF/web.xml b/example/application/simpleapp/webapp/src/main/webapp/WEB-INF/web.xml
index ac9d154..0d3dab6 100644
--- a/example/application/simpleapp/webapp/src/main/webapp/WEB-INF/web.xml
+++ b/example/application/simpleapp/webapp/src/main/webapp/WEB-INF/web.xml
@@ -172,7 +172,7 @@
         <servlet-class>org.webjars.servlet.WebjarsServlet</servlet-class>
         <init-param>
             <param-name>disableCache</param-name>
-            <param-value>true</param-value>
+            <param-value>false</param-value>
         </init-param>
         <load-on-startup>2</load-on-startup>
     </servlet>


[10/52] [abbrv] isis git commit: ISIS-1243: renamed rg.adoc to rgcms.adoc

Posted by mg...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_lifecycleevent_manpage-ObjectRemovingEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_lifecycleevent_manpage-ObjectRemovingEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_lifecycleevent_manpage-ObjectRemovingEvent.adoc
deleted file mode 100644
index 67836f1..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_lifecycleevent_manpage-ObjectRemovingEvent.adoc
+++ /dev/null
@@ -1,20 +0,0 @@
-[[_rg_classes_lifecycleevent_manpage-ObjectRemovingEvent]]
-= `ObjectRemovingEvent`
-: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/
-
-
-Subclass of xref:rg.adoc#_rg_classes_lifecycleevent_manpage-AbstractLifecycleEvent[`AbstractLifecycleEvent`], broadcast
-when an object is about to be deleted from the database using the
-xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
-`#remove(...)` method.
-
-
-`ObjectRemovingEvent.Default` is the concrete implementation that is used.
-
-[NOTE]
-====
-In the future this may be generalized to allow arbitrary subclasses to be broadcast, see ISIS-803.
-====
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_lifecycleevent_manpage-ObjectUpdatedEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_lifecycleevent_manpage-ObjectUpdatedEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_lifecycleevent_manpage-ObjectUpdatedEvent.adoc
deleted file mode 100644
index 17898ae..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_lifecycleevent_manpage-ObjectUpdatedEvent.adoc
+++ /dev/null
@@ -1,21 +0,0 @@
-[[_rg_classes_lifecycleevent_manpage-ObjectUpdatedEvent]]
-= `ObjectUpdatedEvent`
-: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/
-
-
-
-Subclass of xref:rg.adoc#_rg_classes_lifecycleevent_manpage-AbstractLifecycleEvent[`AbstractLifecycleEvent`], broadcast
-when an object has just been updated in the database.  This is done either explicitly when the current
-transaction is flushed using the
-xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
-`#flush(...)` method, else is done implicitly when the transaction commits at the end of the user request.
-
-`ObjectUpdatedEvent.Default` is the concrete implementation that is used.
-
-[NOTE]
-====
-In the future this may be generalized to allow arbitrary subclasses to be broadcast, see ISIS-803.
-====
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_lifecycleevent_manpage-ObjectUpdatingEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_lifecycleevent_manpage-ObjectUpdatingEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_lifecycleevent_manpage-ObjectUpdatingEvent.adoc
deleted file mode 100644
index 79755ac..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_lifecycleevent_manpage-ObjectUpdatingEvent.adoc
+++ /dev/null
@@ -1,22 +0,0 @@
-[[_rg_classes_lifecycleevent_manpage-ObjectUpdatingEvent]]
-= `ObjectUpdatingEvent`
-: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/
-
-
-
-Subclass of xref:rg.adoc#_rg_classes_lifecycleevent_manpage-AbstractLifecycleEvent[`AbstractLifecycleEvent`], broadcast
-when an object is about to be updated in the database.  This is done either explicitly when the current
-transaction is flushed using the
-xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
-`#flush(...)` method, else is done implicitly when the transaction commits at the end of the user request.
-
-
-`ObjectUpdatingEvent.Default` is the concrete implementation that is used.
-
-[NOTE]
-====
-In the future this may be generalized to allow arbitrary subclasses to be broadcast, see ISIS-803.
-====
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_roles.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_roles.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_roles.adoc
deleted file mode 100644
index 4f7cde8..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_roles.adoc
+++ /dev/null
@@ -1,18 +0,0 @@
-[[_rg_classes_roles]]
-= Roles
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-The interfaces listed in this chapter are role interfaces; they define a contract for the framework
- to interact with those domain objects that implement these interfaces.
-
-
-include::_rg_classes_roles_manpage-HoldsUpdatedAt.adoc[leveloffset=+1]
-include::_rg_classes_roles_manpage-HoldsUpdatedBy.adoc[leveloffset=+1]
-include::_rg_classes_roles_manpage-Timestampable.adoc[leveloffset=+1]
-include::_rg_classes_roles_manpage-Dto.adoc[leveloffset=+1]
-include::_rg_classes_roles_manpage-Persistable.adoc[leveloffset=+1]
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_roles_manpage-Dto.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_roles_manpage-Dto.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_roles_manpage-Dto.adoc
deleted file mode 100644
index fe3caee..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_roles_manpage-Dto.adoc
+++ /dev/null
@@ -1,61 +0,0 @@
-[[_rg_classes_mixins_Dto]]
-= `Dto` (`1.11.0-SNAPSHOT`)
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-The `Dto` role interface (`1.11.0-SNAPSHOT`) is intended to be implemented by JAXB-annotated view models, that is, annotated using
-xref:rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`].  It enables the ability to download the XML and
-XSD schema of those objects using two xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling_mixins[mixins],
-`Dto_downloadXml` and `Dto_downloadXsd`.
-
-The interface is just a marker interface (with no members), and is defined as:
-
-[source,java]
-----
-public interface Dto { }
-----
-
-The `Dto_downloadXml` mixin defines the following action:
-
-[source,java]
-----
-@Mixin
-public class Dto_downloadXml {
-    public Dto_downloadXml(final Dto dto) { ... }     // <1>
-    public Object downloadXml(final String fileName) { ... }   // <2>
-    ...
-}
-----
-<1> provided as an action to any class that (trivially) implements the `Dto` interface
-<2> actually this is '$$' in the code, a "special case" that means to use the derive the action name from the class name.
-
-This will return the XML text wrapped up in a xref:rg.adoc#_rg_classes_value-types_manpage-Clob[`Clob`].
-
-The `Dto_downloadXsd` mixin is similar:
-
-[source,java]
-----
-@Mixin
-public class Dto_downloadXsd {
-    public Dto_downloadXsd(final Dto dto) { ... }                                             // <1>
-    public Object downloadXsd(final String fileName, final IsisSchemes isisSchemas) { ... }   // <2>
-}
-----
-<1> provided as an action to any class that (trivially) implements the `Dto` interface
-<2> actually this is '$$' in the code, a "special case" that means to use the derive the action name from the class name.
-
-If the domain object's JAXB annotations reference only a single XSD schema then this will return that XML text as
-a xref:rg.adoc#_rg_classes_value-types_manpage-Clob[`Clob`] of that XSD.  If there are multiple XSD schemas referenced
-then the action will return a zip of those schemas, wrapped up in a
-xref:rg.adoc#_rg_classes_value-types_manpage-Blob[`Blob`].  The `IsisSchemas` parameter to the action can be used to
-optionally ignore the common xref:rg.adoc#_rg_schema[Apache Isis schemas] (useful if there is only one other XSD schema
-referenced by the DTO).
-
-
-
-== Related Services
-
-The `Dto_downloadXml` and `Dto_downloadXsd` delegate to the
-xref:rgsvc.adoc#_rgsvc-api_JaxbService[`JaxbService`] to actually generate the XML/XSD.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_roles_manpage-HoldsUpdatedAt.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_roles_manpage-HoldsUpdatedAt.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_roles_manpage-HoldsUpdatedAt.adoc
deleted file mode 100644
index 3e8beb9..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_roles_manpage-HoldsUpdatedAt.adoc
+++ /dev/null
@@ -1,44 +0,0 @@
-[[_rg_classes_roles_manpage-HoldsUpdatedAt]]
-= `HoldsUpdatedAt`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-The `HoldsUpdatedAt` role interface allows the (framework-provided) `TimestampService` to update each object with
-the current timestamp whenever it is modified in a transaction.
-
-The interface is defined as:
-
-[source,java]
-----
-public interface HoldsUpdatedAt {
-    void setUpdatedAt(java.sql.Timestamp updatedAt);
-}
-----
-
-The current time is obtained from the xref:rgsvc.adoc#_rgsvc-api_ClockService[`ClockService`].
-
-Entities that implement this interface often also implement xref:rg.adoc#_rg_classes_roles_manpage-HoldsUpdatedBy[`HoldsUpdatedBy`] role interface; as a convenience the xref:rg.adoc#_rg_classes_roles_manpage-Timestampable[`Timestampable`] interface combines the two roles.
-
-
-
-== Alternative approaches
-
-An alternative way to maintain a timestamp is to use JDO's `@Version` annotation.  With this approach, it is the JDO/DataNucleus that maintains the version, rather than the framework's `TimestampService`.
-
-For example:
-
-[source,java]
-----
-@javax.jdo.annotations.Version(
-        strategy=VersionStrategy.DATE_TIME,
-        column="version")
-public class Customer {
-    ...
-    public java.sql.Timestamp getVersionSequence() {
-        return (java.sql.Timestamp) JDOHelper.getVersion(this);
-    }
-}
-----
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_roles_manpage-HoldsUpdatedBy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_roles_manpage-HoldsUpdatedBy.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_roles_manpage-HoldsUpdatedBy.adoc
deleted file mode 100644
index 4852fd5..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_roles_manpage-HoldsUpdatedBy.adoc
+++ /dev/null
@@ -1,19 +0,0 @@
-[[_rg_classes_roles_manpage-HoldsUpdatedBy]]
-= `HoldsUpdatedBy`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-The `HoldsUpdatedBy` role interface ...
-
-[source,java]
-----
-public interface HoldsUpdatedBy {
-    void setUpdatedBy(String updatedBy);
-}
-----
-
-Entities that implement this interface often also implement xref:rg.adoc#_rg_classes_roles_manpage-HoldsUpdatedAt[`HoldsUpdatedAt`] role interface; as a convenience the xref:rg.adoc#_rg_classes_roles_manpage-Timestampable[`Timestampable`] interface combines the two roles.
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_roles_manpage-Persistable.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_roles_manpage-Persistable.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_roles_manpage-Persistable.adoc
deleted file mode 100644
index f12d6f1..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_roles_manpage-Persistable.adoc
+++ /dev/null
@@ -1,34 +0,0 @@
-[[_rg_classes_mixins_Persistable]]
-= `Persistable` (`1.11.0-SNAPSHOT`)
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-All domain entities automatically implement the DataNucleus `Persistable` role interface as a result of the enhancer
-process (the fully qualified class name is `org.datanucleus.enhancement.Persistable`).  So as a developer you do not
-need to write any code for this role interface.
-
-Nevertheless, the `Persistable_downloadJdoMetadata` mixin (`1.11.0-SNAPSHOT`) provides the ability to download the
-JDO link:http://www.datanucleus.org/products/datanucleus/jdo/metadata_xml.html[class metadata in XML] form.  The mixin
-defines the following action:
-
-[source,java]
-----
-@Mixin
-public class Persistable_downloadJdoMetadata {
-    public Persistable_downloadJdoMetadata(final Persistable persistable) { ... }   // <1>
-    public Object downloadJdoMetadata(final String fileName) { ... }                // <2>
-    ...
-}
-----
-<1> provided as an action to any domain entity
-<2> actually this is '$$' in the code, a "special case" that means to use the derive the action name from the class name.
-
-This will return the XML text wrapped up in a xref:rg.adoc#_rg_classes_value-types_manpage-Clob[`Clob`].
-
-
-== Related Services
-
-The mixin delegates to the xref:rgsvc.adoc#_rgsvc-api_IsisJdoSupport[`IsisJdoSupport`] service to obtain
-a reference to the JDO `PersistenceManagerFactory`.

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_roles_manpage-Timestampable.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_roles_manpage-Timestampable.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_roles_manpage-Timestampable.adoc
deleted file mode 100644
index 9a75da1..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_roles_manpage-Timestampable.adoc
+++ /dev/null
@@ -1,23 +0,0 @@
-[[_rg_classes_roles_manpage-Timestampable]]
-= `Timestampable`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-The `Timestampable` role interface is a convenience that combines the xref:rg.adoc#_rg_classes_roles_manpage-HoldsUpdatedAt[`HoldsUpdatedAt`] and xref:rg.adoc#_rg_classes_roles_manpage-HoldsUpdatedBy[`HoldsUpdatedBy`] interfaces.  It is defined as:
-
-[source,java]
-----
-public interface Timestampable
-    extends HoldsUpdatedAt, HoldsUpdatedBy {
-}
-----
-
-The interface no additional methods of its own.
-
-
-
-== Alternatives
-
-An alternative way to maintain a timestamp is to use JDO's `@Version` annotation.  With this approach, it is the JDO/DataNucleus that maintains the version, rather than the framework's `TimestampService`.  See xref:rg.adoc#_rg_classes_roles_manpage-HoldsUpdatedBy[`HoldsUpdatedBy`] for further details.

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_spec.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_spec.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_spec.adoc
deleted file mode 100644
index d7c166f..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_spec.adoc
+++ /dev/null
@@ -1,108 +0,0 @@
-[[_rg_classes_spec]]
-= Specification pattern
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-The interfaces and classes listed in this chapter provide support for the  `Specification` pattern, as described in Eric Evans' book _Domain Driven Design_, p224.
-
-Apache Isis will automatically apply such specifications as validation rules on properties (as per xref:rgant.adoc#_rgant-Property_mustSatisfy[`@Property#mustSatisfy()`]) and on action parameters (as per xref:rgant.adoc#_rgant-Parameter_mustSatisfy[`@Parameter#mustSatisfy()`]).
-
-
-
-[_rg_classes_spec-Specification]
-== `Specification`
-
-The heart of the support for this pattern is the `Specification` interface:
-
-[source,java]
-----
-public interface Specification {
-    public String satisfies(Object obj);  // <1>
-}
-----
-<1> if returns `null`, then the constraint is satisfies; otherwise returns the reason why the constraint has not been satisfied.
-
-
-For example:
-
-[source,java]
-----
-public class StartWithCapitalLetterSpecification implements Specification {
-    public String satisfies(Object proposedObj) {
-        String proposed = (String)proposedObj;               // <1>
-        return "".equals(proposed)
-            ? "Empty string"
-            : !Character.isUpperCase(proposed.charAt(0))
-                ? "Does not start with a capital letter"
-                : null;
-    }
-}
-public class Customer {
-    @Property(mustSatisfy=StartWithCapitalLetterSpecification.class)
-    public String getFirstName() { ... }
-    ...
-}
-----
-<1> this ugly cast can be avoided using some of the other classes available; see below.
-
-
-
-[_rg_classes_spec-Specification2]
-== `Specification2`
-
-The `Specification2` interface extends the `Specification` API to add support for i18n.  This is done by defining an additional method that returns a xref:rg.adoc#_rg_classes_i18n_manpage-TranslatableString[translatable string]:
-
-[source,java]
-----
-public interface Specification2 extends Specification {
-    public TranslatableString satisfiesTranslatable(Object obj);  // <1>
-}
-----
-<1> if returns `null`, then the constraint is satisfies; otherwise returns the reason why the constraint has not been satisfied.
-
-
-Note that if implementing `Specification2` then there is no need to also provide an implementation of the inherited `satisfies(Object)` method; this will never be called by the framework for `Specification2` instances.
-
-
-
-
-[_rg_classes_spec-adapter_classes]
-== Adapter classes
-
-The `AbstractSpecification` and `AbstractSpecification2` adapter classes provide a partial implementation of the respective interfaces, providing type-safety.  (Their design is modelled on the `TypesafeMatcher` class within link:http://hamcrest.org/JavaHamcrest/[Hamcrest]).
-
-For example:
-
-[source,java]
-----
-public class StartWithCapitalLetterSpecification extends AbstractSpecification<String> {
-    public String satisfiesSafely(String proposed) {
-        return "".equals(proposed)
-            ? "Empty string"
-            : !Character.isUpperCase(proposed.charAt(0))
-                ? "Does not start with a capital letter"
-                : null;
-    }
-}
-public class Customer {
-    @Property(mustSatisfy=StartWithCapitalLetterSpecification.class)
-    public String getFirstName() { ... }
-    ...
-}
-----
-
-The `AbstractSpecification2` class is almost identical; its type-safe method is `satisfiesTranslatableSafely(T)` instead.
-
-
-[_rg_classes_spec-combining_specifications]
-== Combining specifications
-
-There are also adapter classes that can be inherited from to combine specifications:
-
-* `SpecificationAnd` - all provided specifications' constraints must be met
-* `SpecificationOr` - at least one provided specifications' constraints must be met
-* `SpecificationNot` - its constraints are met if-and-only-if the provided specification's constraint was _not_ met.
-
-Note that these adapter classes inherit `Specification` but do not inherit `Specification2`; in other words they do not support i18n.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super.adoc
deleted file mode 100644
index af8e0bc..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super.adoc
+++ /dev/null
@@ -1,105 +0,0 @@
-[[_rg_classes_super]]
-= Superclasses
-: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 section catalogues the various convenience (non event) superclasses defined by Apache Isis.  These are listed in the table below.
-
-
-.Convenience Superclasses
-[cols="2,4a,1,1", options="header"]
-|===
-
-|API
-|Maven Module +
-Impl'n (g: a:)
-|Implementation
-|Notes
-
-
-|xref:rg.adoc#_rg_classes_super_manpage-AbstractContainedObject[`o.a.i.applib.` +
-`AbstractContainedObject`]
-|``o.a.i.core`` +
-``isis-core-applib``
-|(abstract class)
-|
-
-
-|xref:rg.adoc#_rg_classes_super_manpage-AbstractDomainObject[`o.a.i.applib.` +
-`AbstractDomainObject`]
-|``o.a.i.core`` +
-``isis-core-applib``
-|(abstract class)
-|
-
-
-|xref:rg.adoc#_rg_classes_super_manpage-AbstractFactoryAndRepository[`o.a.i.applib.` +
-`AbstractFactoryAndRepository`]
-|``o.a.i.core`` +
-``isis-core-applib``
-|(abstract class)
-|
-
-
-|xref:rg.adoc#_rg_classes_super_manpage-AbstractService[`o.a.i.applib.` +
-`AbstractService`]
-|``o.a.i.core`` +
-``isis-core-applib``
-|(abstract class)
-|
-
-
-|xref:rg.adoc#_rg_classes_super_manpage-AbstractSubscriber[`o.a.i.applib.` +
-`AbstractSubscriber`]
-|``o.a.i.core`` +
-``isis-core-applib``
-|(abstract class)
-|
-
-
-|xref:rg.adoc#_rg_classes_super_manpage-AbstractViewModel[`o.a.i.applib.` +
-`AbstractViewModel`]
-|``o.a.i.core`` +
-``isis-core-applib``
-|(abstract class)
-|
-
-
-|xref:rg.adoc#_rg_classes_super_manpage-FixtureScript[`o.a.i.applib.` +
-`fixturescript` +
-`FixtureScript`]
-|``o.a.i.core`` +
-``isis-core-applib``
-|(abstract class)
-|
-
-
-|xref:rg.adoc#_rg_classes_super_manpage-FixtureScripts[`o.a.i.applib.` +
-`fixturescripts` +
-`FixtureScripts`]
-|``o.a.i.core`` +
-``isis-core-applib``
-|(abstract class). +
-`FixtureScriptsDefault` is a default implementation that is used when the alternative xref:rgsvc.adoc#_rgsvc-api_FixtureScriptsSpecificationProvider[`FixtureScriptsSpecificationProvider`] is provided
-  (and no other implementation of `FixtureScripts` was found).
-|depends on: +
-`ClassDiscoveryService`
-
-
-|===
-
-
-
-
-include::_rg_classes_super_manpage-AbstractContainedObject.adoc[leveloffset=+1]
-include::_rg_classes_super_manpage-AbstractDomainObject.adoc[leveloffset=+1]
-include::_rg_classes_super_manpage-AbstractFactoryAndRepository.adoc[leveloffset=+1]
-include::_rg_classes_super_manpage-AbstractService.adoc[leveloffset=+1]
-include::_rg_classes_super_manpage-AbstractSubscriber.adoc[leveloffset=+1]
-include::_rg_classes_super_manpage-AbstractViewModel.adoc[leveloffset=+1]
-include::_rg_classes_super_manpage-FixtureScript.adoc[leveloffset=+1]
-include::_rg_classes_super_manpage-FixtureScripts.adoc[leveloffset=+1]
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractContainedObject.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractContainedObject.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractContainedObject.adoc
deleted file mode 100644
index 21bb400..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractContainedObject.adoc
+++ /dev/null
@@ -1,32 +0,0 @@
-[[_rg_classes_super_manpage-AbstractContainedObject]]
-= `AbstractContainedObject`
-: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 class is a convenience superclass for domain objects and services, providing general purpose methods for interacting with the framework.  These include:
-
-* `allMatches(Query)` - search for all objects matching the specified `Query`. +
-+
-+ Note that this, and other similar methods (eg `firstMatch(...)`, `uniqueMatch(...)`) will automatically flush the
-current transactoin.
-
-* `newTransientInstance(Class)` - to create a new instance of an object, with any services injected into it
-
-* `persistIfNotAlready(Object)` - to persist an object +
-+
-In fact, the object is queued up to be persisted, and is only actually persisted either when the transaction commits, or
-when the transaction is flushed (typically when a query is performed).
-
-* `warnUser(String)` - generate a warning to the user
-
-* `getContainer()` - which returns the `DomainObjectContainer`
-
-Each of these methods simply delegates to an equivalent method in xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer[`DomainObjectContainer`].
-
-[TIP]
-====
-In practice we find that there's little to gain from subclassing; it's easier/less obscure to simply inject xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer[`DomainObjectContainer`] into a simple pojo class.
-====
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractDomainObject.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractDomainObject.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractDomainObject.adoc
deleted file mode 100644
index ffa57d8..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractDomainObject.adoc
+++ /dev/null
@@ -1,14 +0,0 @@
-[[_rg_classes_super_manpage-AbstractDomainObject]]
-= `AbstractDomainObject`
-: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 class extends xref:rg.adoc#_rg_classes_super_manpage-AbstractContainedObject[`AbstractContainedObject`], adding
-in convenience methods for managing the persistence lifecycle of the object instance.
-
-Each of these methods, eg `isPersistent(...)`, delegates to an equivalent method in
-xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer[`DomainObjectContainer`].
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractFactoryAndRepository.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractFactoryAndRepository.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractFactoryAndRepository.adoc
deleted file mode 100644
index 3f63493..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractFactoryAndRepository.adoc
+++ /dev/null
@@ -1,15 +0,0 @@
-[[_rg_classes_super_manpage-AbstractFactoryAndRepository]]
-= `AbstractFactoryAndRepository`
-: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 class extends xref:rg.adoc#_rg_classes_super_manpage-AbstractContainedObject[`AbstractContainedObject`].  Its
-intent was to be a convenience subclass for services acting as either a repository or a factory, however note that
- all of the methods that it defines are now deprecated.
-
-Instead, indicate that a service is repository using the xref:rgant.adoc#_rgant-DomainService_repositoryFor[`@DomainService#repositoryFor()`] attribute.
-
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractService.adoc
deleted file mode 100644
index 07c1073..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractService.adoc
+++ /dev/null
@@ -1,10 +0,0 @@
-[[_rg_classes_super_manpage-AbstractService]]
-= `AbstractService`
-: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 class extends xref:rg.adoc#_rg_classes_super_manpage-AbstractContainedObject[`AbstractContainedObject`], adding
-in an implementation of `getId()` based upon the classes name.
-
-In practice there is little to gain from subclassing; simply inject xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer[`DomainObjectContainer`] for broadly equivalent functionality.

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractSubscriber.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractSubscriber.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractSubscriber.adoc
deleted file mode 100644
index b52c00c..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractSubscriber.adoc
+++ /dev/null
@@ -1,18 +0,0 @@
-[[_rg_classes_super_manpage-AbstractSubscriber]]
-= `AbstractSubscriber`
-: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 convenience superclass for creating subscriber domain services on the xref:rgsvc.adoc#_rgsvc-api_EventBusService[`EventBusService`].  It uses xref:rgant.adoc#_rgant-PostConstruct[`@PostConstruct`] and
-xref:rgant.adoc#_rgant-PreDestroy[`@PreDestroy`] callbacks to automatically register/unregister itself
-with the `EventBusService`.
-
-It's important that subscribers register before any domain services that might emit events on the
-xref:rgsvc.adoc#_rgsvc-api_EventBusService[`EventBusService`].  For example, the (non-ASF) http://github.com/isisaddons/isis-module-security[Isis addons' security] module provides a domain service that automatically
-seeds certain domain entities; these will generate xref:rg.adoc#_rg_classes_lifecycleevent[lifecycle events] and so
-any subscribers must be registered before such seed services.  The easiest way to do this is to use the
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] attribute.
-
-As a convenience, (as of `1.11.0-SNAPSHOT`) the `AbstractSubscriber` specifies this attribute.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractViewModel.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractViewModel.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractViewModel.adoc
deleted file mode 100644
index f7e718c..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractViewModel.adoc
+++ /dev/null
@@ -1,15 +0,0 @@
-[[_rg_classes_super_manpage-AbstractViewModel]]
-= `AbstractViewModel`
-: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 class extends xref:rg.adoc#_rg_classes_super_manpage-AbstractContainedObject[`AbstractContainedObject`], also
-implementing the xref:rg.adoc#_rg_classes_super_manpage-ViewModel[`ViewModel`] interface.  In and of itself it provides no new behaviour.
-
-[TIP]
-====
-As an alternative, consider simply annotating the view model class with {@link org.apache.isis.applib.annotation.ViewModel}.
-====
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-FixtureScript.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-FixtureScript.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-FixtureScript.adoc
deleted file mode 100644
index ae44538..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-FixtureScript.adoc
+++ /dev/null
@@ -1,21 +0,0 @@
-[[_rg_classes_super_manpage-FixtureScript]]
-= `FixtureScript`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-The `FixtureScript` class is an abstract class defining an API to set up data within the object store, either for integration tests or while demoing/prototyping.
-
-The primary method that subclasses must implement is:
-
-[source,java]
-----
-protected abstract void execute(final ExecutionContext executionContext);
-----
-
-In this method the fixture script can in theory do anything, but in practice it is recommended that it uses injected
-domain services to set up data.  The provided `ExecutionContext` is used to invoke child fixture scripts, and alsocan be used to store references to any created objects (so that the calling test can access these objects/so that they are rendered in the view model).
-
-See the see the xref:ugtst.adoc#_ugtst_fixture-scripts[user guide's testing chapter] for further discussion on the use of fixture scripts, in particular xref:ugtst.adoc#_ugtst_fixture-scripts_api-and-usage[fixture scripts' API and usage].
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-FixtureScripts.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-FixtureScripts.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-FixtureScripts.adoc
deleted file mode 100644
index 86102a9..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-FixtureScripts.adoc
+++ /dev/null
@@ -1,12 +0,0 @@
-[[_rg_classes_super_manpage-FixtureScripts]]
-= `FixtureScripts`
-: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 abstract class is intended to allow a domain service that can execute xref:rg.adoc#_rg_classes_super_manpage-FixtureScript[`FixtureScript`]s to be easily written.
-
-However, it has now been deprecated; instead we recommend that the xref:rgsvc.adoc#_rgsvc-spi_FixtureScriptsSpecificationProvider[`FixtureScriptsSpecificationProvider`] service is
-implemented instead.  The framework will then automatically use xref:rgsvc.adoc#_rgsvc-api_FixtureScriptsDefault[`FixtureScriptsDefault`] as a fallback implementation of this class.
-
-See the see the xref:ugtst.adoc#_ugtst_fixture-scripts[user guide's testing chapter] for further discussion on the use of fixture scripts, in particular xref:ugtst.adoc#_ugtst_fixture-scripts_api-and-usage[fixture scripts' API and usage].

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_uievent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_uievent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_uievent.adoc
deleted file mode 100644
index c1f903a..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_uievent.adoc
+++ /dev/null
@@ -1,62 +0,0 @@
-[[_rg_classes_uievent]]
-= UI Event Classes (`1.11.0-SNAPSHOT`)
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-This section catalogues the various UI event classes defined by Apache Isis.
-
-These events are broadcast on the xref:rgsvc.adoc#_rgsvc-api_EventBusService[`EventBusService`].  The domain
-events are broadcast as a result of being specified in the xref:rgant.adoc#_rgant-DomainObjectLayout_titleUiEvent[`@DomainObjectLayout#titleUiEvent()`],  xref:rgant.adoc#_rgant-DomainObjectLayout_iconUiEvent[`@DomainObjectLayout#iconUiEvent()`] or xref:rgant.adoc#_rgant-DomainObjectLayout_cssClassUiEvent[`@DomainObjectLayout#cssClassUiEvent()`] attributes.
-
-They are listed in the table below.
-
-.UI Event Classes
-[cols="2,4a,1,1", options="header"]
-|===
-
-|API
-|Maven Module +
-Impl'n (g: a:)
-|Implementation
-|Notes
-
-
-|xref:rg.adoc#_rg_classes_uievent_manpage-TitleUiEvent[`o.a.i.applib.` +
-`TitleUiEvent`]
-|``o.a.i.core`` +
-``services.eventbus`` +
-``isis-core-applib``
-|(abstract class). +
-`TitleUiEvent.Default` is the concrete implementation used if no `@DomainObjectLayout#titleUiEvent` attribute is specified
-|Broadcast whenever there is a requirement to obtain a title for a domain object.  Note that if the domain object defines its own xref:rg.adoc#_rg_methods_reserved_manpage-title[`title()`] supporting method, or has xref:rgant.adoc#_rgant-Title[`@Title`] annotation(s) on its properties, then these will take precedence.
-
-|xref:rg.adoc#_rg_classes_uievent_manpage-IconUiEvent[`o.a.i.applib.` +
-`IconUiEvent`]
-|``o.a.i.core`` +
-``services.eventbus`` +
-``isis-core-applib``
-|(abstract class). +
-`IconUiEvent.Default` is the concrete implementation used if no `@DomainObjectLayout#iconUiEvent` attribute is specified
-|Broadcast whenever there is a requirement to obtain an icon (or rather, the name of an icon) for a domain object.  Note that if the domain object defines its own xref:rg.adoc#_rg_methods_reserved_manpage-iconName[`iconName()`] supporting method, or if it has the xref:rgant.adoc#_rgant-DomainObjectLayout#cssClassFa[`@DomainObjectLayout#cssClassFa()`] attribute, then these will take precedence.
-
-|xref:rg.adoc#_rg_classes_uievent_manpage-CssClassUiEvent[`o.a.i.applib.` +
-`CssClassUiEvent`]
-|``o.a.i.core`` +
-``services.eventbus`` +
-``isis-core-applib``
-|(abstract class). +
-`CssClassUiEvent.Default` is the concrete implementation used if no `@DomainObjectLayout#cssClassUiEvent` attribute is specified
-|Broadcast whenever there is a requirement to obtain a CSS class hint for a domain object.  Note that if the domain object defines its own xref:rg.adoc#_rg_methods_reserved_manpage-cssClass[`cssClass()`] supporting method then this
-will take precedence.
-
-|===
-
-
-
-
-include::_rg_classes_uievent_manpage-TitleUiEvent.adoc[leveloffset=+1]
-include::_rg_classes_uievent_manpage-IconUiEvent.adoc[leveloffset=+1]
-include::_rg_classes_uievent_manpage-CssClassUiEvent.adoc[leveloffset=+1]
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_uievent_manpage-CssClassUiEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_uievent_manpage-CssClassUiEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_uievent_manpage-CssClassUiEvent.adoc
deleted file mode 100644
index ca0987e..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_uievent_manpage-CssClassUiEvent.adoc
+++ /dev/null
@@ -1,22 +0,0 @@
-[[_rg_classes_uievent_manpage-CssClassUiEvent]]
-= `CssClassUiEvent`  (`1.11.0-SNAPSHOT`)
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-This event class represents a request to obtain the a CSS class hint of a domain object.  The class has a number of
-responsibilities:
-
-* capture the target object being interacted with
-
-* capture the CSS class, if any, as specified to one of the subscribers
-
-The class itself is instantiated automatically by the framework whenever interacting with a rendered object's action.
-
-
-[NOTE]
-====
-if the domain object defines its own xref:rg.adoc#_rg_methods_reserved_manpage-cssClass[`cssClass()`] supporting
-method then this will take precedence.
-====

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_uievent_manpage-IconUiEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_uievent_manpage-IconUiEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_uievent_manpage-IconUiEvent.adoc
deleted file mode 100644
index 01c38cb..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_uievent_manpage-IconUiEvent.adoc
+++ /dev/null
@@ -1,23 +0,0 @@
-[[_rg_classes_uievent_manpage-IconUiEvent]]
-= `TitleUiEvent` (`1.11.0-SNAPSHOT`)
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-This event class represents a request to obtain the icon (or rather, name of icon) of a domain object.  The class has a number of responsibilities:
-
-* capture the target object being interacted with
-
-* capture the icon (name), if any, as specified to one of the subscribers
-
-The class itself is instantiated automatically by the framework whenever interacting with a rendered object's action.
-
-
-[NOTE]
-====
-If the domain object defines its own xref:rg.adoc#_rg_methods_reserved_manpage-iconName[`iconName()`] supporting method,
-or if it has the
-xref:rgant.adoc#_rgant-DomainObjectLayout#cssClassFa[`@DomainObjectLayout#cssClassFa()`] attribute, then
-these will take precedence.
-====

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_uievent_manpage-TitleUiEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_uievent_manpage-TitleUiEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_uievent_manpage-TitleUiEvent.adoc
deleted file mode 100644
index 9ad8603..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_uievent_manpage-TitleUiEvent.adoc
+++ /dev/null
@@ -1,22 +0,0 @@
-[[_rg_classes_uievent_manpage-TitleUiEvent]]
-= `TitleUiEvent`  (`1.11.0-SNAPSHOT`)
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-This event class represents a request to obtain the title of a domain object.  The class has a number of responsibilities:
-
-* capture the target object being interacted with
-
-* capture the title, if any, as specified to one of the subscribers
-
-The class itself is instantiated automatically by the framework whenever interacting with a rendered object's action.
-
-
-[NOTE]
-====
-If the domain object defines its own xref:rg.adoc#_rg_methods_reserved_manpage-title[`title()`] supporting method, or
-has xref:rgant.adoc#_rgant-Title[`@Title`] annotation(s) on its properties, then these will take
-precedence.
-====

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_utility.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_utility.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_utility.adoc
deleted file mode 100644
index 8091906..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_utility.adoc
+++ /dev/null
@@ -1,16 +0,0 @@
-[[_rg_classes_utility]]
-= Applib Utility Classes
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-The `org.apache.isis.applib.util` package has a number of simple utility
-classes designed to simplify the coding of some common tasks.
-
-
-include::_rg_classes_utility_manpage-Enums.adoc[leveloffset=+1]
-include::_rg_classes_utility_manpage-ObjectContracts.adoc[leveloffset=+1]
-include::_rg_classes_utility_manpage-Reasons.adoc[leveloffset=+1]
-include::_rg_classes_utility_manpage-TitleBuffer.adoc[leveloffset=+1]
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_utility_manpage-Enums.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_utility_manpage-Enums.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_utility_manpage-Enums.adoc
deleted file mode 100644
index d45f283..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_utility_manpage-Enums.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-[[_rg_classes_utility_manpage-Enums]]
-= `Enums`
-: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/
-
-
-NOTE: TODO

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/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
deleted file mode 100644
index 618fc8d..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_utility_manpage-ObjectContracts.adoc
+++ /dev/null
@@ -1,107 +0,0 @@
-[[_rg_classes_utility_manpage-ObjectContracts]]
-= `ObjectContracts`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-The `ObjectContracts` test provides a series of methods to make it easy for your domain objects to:
-
-* implement `Comparable` (eg so can be stored in ``java.util.SortedSet``s)
-* implement `toString()`
-* implement `equals()`
-* implement `hashCode()`
-
-For example:
-
-[source,java]
-----
-public class ToDoItem implements Comparable<ToDoItem> {
-
-    public boolean isComplete() { ... }
-    public LocalDate getDueBy() { ... }
-    public String getDescription() { ... }
-    public String getOwnedBy() { ... }
-
-    public int compareTo(final ToDoItem other) {
-        return ObjectContracts.compare(this, other, "complete","dueBy","description");
-    }
-
-    public String toString() {
-        return ObjectContracts.toString(this, "description","complete","dueBy","ownedBy");
-    }
-}
-----
-
-[WARNING]
-====
-Note that `ObjectContracts` makes heavy use of Java Reflection.  While it's great to get going quickly in prototyping, we recommend you use your IDE to code generate implementations of these methods for production code.
-
-Moreover (and perhaps even more importantly) `ObjectContracts` implementation can cause DataNucleus to recursively rehydrate a larger number of associated entities (More detail below).
-
-We therefore recommend that you disable persistence-by-reachability by adding:
-
-[source,ini]
-.persistor_datanucleus.properties
-----
-isis.persistor.datanucleus.impl.datanucleus.persistenceByReachabilityAtCommit=false
-----
-
-====
-
-== The issue in more detail
-
-Consider the link:http://yuml.me/edit/742ad446[entities]:
-
-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.
-
-All these entities implement `Comparable` using `ObjectContracts`, so that the implementation of ``AgreementRole``'s (simplified) is:
-
-[source,java]
-----
-public class AgreementRole {
-    ...
-    public int compareTo(AgreementRole other) {
-        return ObjectContracts.compareTo(this, other, "agreement","startDate","party");
-    }
-    ...
-}
-----
-
-while ``Agreement``'s is implemented as:
-
-[source,java]
-----
-    public class Agreement {
-        ...
-        public int compareTo(Agreement other) {
-            return ObjectContracts.compareTo(this, other, "reference");
-        }
-        ...
-    }
-----
-
-and ``Party``'s is similarly implemented as:
-
-[source,java]
-----
-public class Party {
-    ...
-    public int compareTo(Party other) {
-        return ObjectContracts.compareTo(this, other, "reference");
-    }
-    ...
-}
-----
-
-DataNucleus's persistence-by-reachability algorithm adds the ``AgreementRole``s into a `SortedSet`, which causes `AgreementRole#compareTo()` to fire:
-
-* the evaluation of the "agreement" property delegates back to the `Agreement`, whose own `Agreement#compareTo()` uses the scalar `reference` property.  As the `Agreement` is already in-memory, this does not trigger any further database queries
-
-* the evaluation of the "startDate" property is just a scalar property of the `AgreementRole`, so will already in-memory
-
-* the evaluation of the "party" property delegates back to the `Party`, whose own `Party#compareTo()` requires the uses the scalar `reference` property.  However, since the `Party` is not yet in-memory, using the `reference` property triggers a database query to "rehydrate" the `Party` instance.
-
-In other words, figuring out whether `AgreementRole` is comparable requires the persistence-by-reachability algorithm to run, causing the adjacent associated entity `Party` to also be retrieved.

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_utility_manpage-Reasons.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_utility_manpage-Reasons.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_utility_manpage-Reasons.adoc
deleted file mode 100644
index 5b35b29..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_utility_manpage-Reasons.adoc
+++ /dev/null
@@ -1,31 +0,0 @@
-[[_rg_classes_utility_manpage-Reasons]]
-= `Reasons`
-: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/
-
-
-
-There are two different classes provided to help build reasons returned
-by `disableXxX()` and `validateXxx()` methods:
-
-* the `org.apache.isis.applib.util.ReasonBuffer` helper class
-* the `org.apache.isis.applib.util.Reasons` helper class
-
-For example:
-
-[source,java]
-----
-public class Customer {
-    ...
-    public String validatePlaceOrder(Product p, int quantity) {
-        return Reasons.coalesce(
-            whetherCustomerBlacklisted(this),
-            whetherProductOutOfStock(p)
-        );
-    }
-}
-----
-
-Which you use (if any) is up to you.
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_utility_manpage-TitleBuffer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_utility_manpage-TitleBuffer.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_utility_manpage-TitleBuffer.adoc
deleted file mode 100644
index fe0f05c..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_utility_manpage-TitleBuffer.adoc
+++ /dev/null
@@ -1,13 +0,0 @@
-[[_rg_classes_utility_manpage-TitleBuffer]]
-= `TitleBuffer`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-The `TitleBuffer` utility class is intended to make it easy to construct title strings (returned from the xref:rg.adoc#_rg_methods_reserved_manpage-title[`title()`] method).
-
-For example, it has overloaded versions of methods called `append()` and `concat()`.
-
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_value-types.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_value-types.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_value-types.adoc
deleted file mode 100644
index 9b3e6c3..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_value-types.adoc
+++ /dev/null
@@ -1,119 +0,0 @@
-[[_rg_classes_value-types]]
-= Value Types
-: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/
-
-NOTE: TODO
-
-
-
-.JDK Classes
-[cols="1,1", options="header"]
-|===
-
-|Type
-|Description
-
-|`java.lang.Boolean`
-|
-
-|`java.lang.Character`
-|
-
-|`java.lang.Double`
-|
-
-|`java.lang.Float`
-|
-
-|`java.lang.Integer`
-|
-
-|`java.lang.Long`
-|
-
-|`java.lang.Short`
-|
-
-|`java.lang.String`
-|
-
-|`java.math.BigDecimal`
-|
-
-|`java.math.BigInteger`
-|
-
-|`java.sql.Date`
-|
-
-|`java.sql.Time`
-|
-
-|`java.sql.Timestamp`
-|
-
-|`java.util.Date`
-|
-
-|===
-
-
-.JodaTime classes
-[cols="1,1", options="header"]
-|===
-
-|Type
-|Description
-
-|`org.joda.time.DateTime`
-|
-
-|`org.joda.time.LocalDateTime`
-|
-
-|`org.joda.time.LocalDate`
-|
-
-|===
-
-
-
-
-.Isis Applib classes
-[cols="1,1", options="header"]
-|===
-
-|Type
-|Description
-
-|`o.a.i.applib.value.` +
-`Blob`
-|
-
-|`o.a.i.applib.value.` +
-`Clob`
-|
-
-|`o.a.i.applib.value.` +
-`Color`
-|
-
-|`o.a.i.applib.value.` +
-`Money`
-|
-
-|`o.a.i.applib.value.` +
-`Password`
-|
-
-|===
-
-
-
-include::_rg_classes_value-types_manpage-Blob.adoc[leveloffset=+1]
-include::_rg_classes_value-types_manpage-Clob.adoc[leveloffset=+1]
-include::_rg_classes_value-types_manpage-Color.adoc[leveloffset=+1]
-include::_rg_classes_value-types_manpage-Money.adoc[leveloffset=+1]
-include::_rg_classes_value-types_manpage-Password.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_value-types_manpage-Blob.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_value-types_manpage-Blob.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_value-types_manpage-Blob.adoc
deleted file mode 100644
index 6e8c67f..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_value-types_manpage-Blob.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-[[_rg_classes_value-types_manpage-Blob]]
-= `Blob`
-: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/
-
-
-NOTE: TODO - the `org.apache.isis.applib.value.Blob` class.

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_value-types_manpage-Clob.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_value-types_manpage-Clob.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_value-types_manpage-Clob.adoc
deleted file mode 100644
index de43105..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_value-types_manpage-Clob.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-[[_rg_classes_value-types_manpage-Clob]]
-= `Clob`
-: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/
-
-
-NOTE: TODO - the `org.apache.isis.applib.value.Clob` class.

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_value-types_manpage-Color.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_value-types_manpage-Color.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_value-types_manpage-Color.adoc
deleted file mode 100644
index 4bcdd63..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_value-types_manpage-Color.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-[[_rg_classes_value-types_manpage-Color]]
-= `Color`
-: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/
-
-
-NOTE: TODO - the `org.apache.isis.applib.value.Color` class.

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_value-types_manpage-Money.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_value-types_manpage-Money.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_value-types_manpage-Money.adoc
deleted file mode 100644
index 16c0192..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_value-types_manpage-Money.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-[[_rg_classes_value-types_manpage-Money]]
-= `Money`
-: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/
-
-
-NOTE: TODO - the `org.apache.isis.applib.value.Money` class.

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_classes_value-types_manpage-Password.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_value-types_manpage-Password.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_value-types_manpage-Password.adoc
deleted file mode 100644
index 1fd6b2d..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_value-types_manpage-Password.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-[[_rg_classes_value-types_manpage-Password]]
-= `Password`
-: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/
-
-
-NOTE: TODO

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_methods.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_methods.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_methods.adoc
deleted file mode 100644
index 1cb6064..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_methods.adoc
+++ /dev/null
@@ -1,17 +0,0 @@
-[[_rg_methods]]
-= Methods
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The Apache Isis metamodel is built up from declaratively (ie, xref:rgant.adoc#_rgant[annotations]) and imperatively, from "supporting" methods and other reserved methods.
-
-This chapter documents the supporting methods and the reserved methods.  It also documents (separately) the reserved methods that act as callback hooks into the persistence lifecycle of domain entities.
-
-
-include::_rg_methods_prefixes.adoc[leveloffset=+1]
-include::_rg_methods_reserved.adoc[leveloffset=+1]
-include::_rg_methods_lifecycle.adoc[leveloffset=+1]
-

http://git-wip-us.apache.org/repos/asf/isis/blob/d0539e43/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle.adoc
deleted file mode 100644
index 4e92563..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle.adoc
+++ /dev/null
@@ -1,102 +0,0 @@
-[[_rg_methods_lifecycle]]
-= Lifecycle Methods
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-
-The lifecycle callback methods notify a domain entity about its interaction within the persistence lifecycle.  For example, the entity is notified immediately prior to being persisted, or when it is about to be updated.
-
-[WARNING]
-====
-Note that these callbacks are fired by Apache Isis rather than JDO.  In the future we may deprecate them because there are better mechanisms available using listeners/subscribers:
-
-* in Isis 1.9.0 and earlier, you may therefore want to consider using the JDO API directly to set up a lifecycle
-listener; see xref:rg.adoc#_rg_methods_lifecycle_jdo-api[here] for further discussion.
-
-* alternatively, you can use a subscriber for the xref:rg.adoc#_rg_classes_lifecycleevent[lifecycle event]s fired in Isis.
-====
-
-The lifecycle callback methods supported by Isis are:
-
-.Lifecycle methods (partial support)
-[cols="1,4a", options="header"]
-|===
-
-|Method
-|Description
-
-|xref:rg.adoc#_rg_methods_lifecycle_manpage-created[`created()`]
-|called when an object has just been created using xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer[`newTransientInstance()`]
-
-|xref:rg.adoc#_rg_methods_lifecycle_manpage-loaded[`loaded()`]
-|called when a (persistent) object has just been loaded from the object store.
-
-|xref:rg.adoc#_rg_methods_lifecycle_manpage-persisted[`persisted()`]
-|called when object has just been persisted from the object store.
-
-|xref:rg.adoc#_rg_methods_lifecycle_manpage-persisting[`persisting()`]
-|called when a (not-yet-persistent) object is just about to be persisted from the object store
-
-|xref:rg.adoc#_rg_methods_lifecycle_manpage-removed[`removed()`]
-|called when a (persistent) object has just been deleted from the object store
-
-|xref:rg.adoc#_rg_methods_lifecycle_manpage-removing[`removing()`]
-|called when a (persistent) object is just about to be deleted from the object store
-
-|xref:rg.adoc#_rg_methods_lifecycle_manpage-updated[`updated()`]
-|called when a (persistent) object has just been updated in the object store
-
-|xref:rg.adoc#_rg_methods_lifecycle_manpage-updating[`updating()`]
-|called when a (persistent) object is just about to be updated in the object store
-
-|===
-
-
-
-Some lifecycle methods have been deprecated:
-
-.Deprecated lifecycle methods
-[cols="1,4a", options="header"]
-|===
-
-|Method
-|Notes
-
-|`deleted()`
-|Replaced by xref:rg.adoc#_rg_methods_lifecycle_manpage-removed[`removed()`]
-
-|`deleting()`
-|Replaced by xref:rg.adoc#_rg_methods_lifecycle_manpage-removing[`removing()`]
-
-|`loading()`
-|callback for when the (persistent) object is just about to be loaded from the object store. +
-
-[WARNING]
-====
-This method is never called.
-====
-
-|`saved()`
-|Replaced by xref:rg.adoc#_rg_methods_lifecycle_manpage-persisted[`persisted()`]
-
-|`saving()`
-|Replaced by xref:rg.adoc#_rg_methods_lifecycle_manpage-persisting[`persisting()`]
-
-|===
-
-
-
-
-include::_rg_methods_lifecycle_manpage-created.adoc[leveloffset=+1]
-include::_rg_methods_lifecycle_manpage-loaded.adoc[leveloffset=+1]
-include::_rg_methods_lifecycle_manpage-persisted.adoc[leveloffset=+1]
-include::_rg_methods_lifecycle_manpage-persisting.adoc[leveloffset=+1]
-include::_rg_methods_lifecycle_manpage-removed.adoc[leveloffset=+1]
-include::_rg_methods_lifecycle_manpage-removing.adoc[leveloffset=+1]
-include::_rg_methods_lifecycle_manpage-updated.adoc[leveloffset=+1]
-include::_rg_methods_lifecycle_manpage-updating.adoc[leveloffset=+1]
-
-include::_rg_methods_lifecycle_jdo-api.adoc[leveloffset=+1]


[43/52] [abbrv] isis git commit: ISIS-1237: now generates models for object, object collection and actions

Posted by mg...@apache.org.
ISIS-1237: now generates models for object, object collection and actions


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/4502dc10
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/4502dc10
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/4502dc10

Branch: refs/heads/ISIS-1224-select2-v4
Commit: 4502dc10a89c039d8350cb02b3437de1f0477ad6
Parents: 3d9f8fe
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Thu Dec 10 17:08:43 2015 +0000
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Dec 10 17:08:43 2015 +0000

----------------------------------------------------------------------
 .../_migration-notes_1.10.0-to-1.11.0.adoc      |  27 +++
 .../swagger/internal/SwaggerSpecGenerator.java  | 188 ++++++++++++++++---
 .../swagger/internal/ValuePropertyFactory.java  | 174 +++++++++++++++++
 .../java/domainapp/dom/simple/SimpleObject.java |   9 +
 .../webapp/src/main/webapp/about/index.html     |  19 +-
 5 files changed, 382 insertions(+), 35 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/4502dc10/adocs/documentation/src/main/asciidoc/_migration-notes_1.10.0-to-1.11.0.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/_migration-notes_1.10.0-to-1.11.0.adoc b/adocs/documentation/src/main/asciidoc/_migration-notes_1.10.0-to-1.11.0.adoc
index 65128a4..6dbd3b3 100644
--- a/adocs/documentation/src/main/asciidoc/_migration-notes_1.10.0-to-1.11.0.adoc
+++ b/adocs/documentation/src/main/asciidoc/_migration-notes_1.10.0-to-1.11.0.adoc
@@ -29,3 +29,30 @@ If your application is bootstrapped using an `AppManifest` (recommended; ee
 xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[here]) then the `JaxbService` will automatically be discovered and
  registered.  However, if you are still using the older `isis.properties` configuration file to explicitly register
  services then you will need to add in this service.
+
+
+== Swagger
+
+Update the `web.xml`:
+
+[source,xml]
+----
+<servlet>
+    <servlet-name>WebjarsServlet</servlet-name>
+    <servlet-class>org.webjars.servlet.WebjarsServlet</servlet-class>
+    <init-param>
+        <param-name>disableCache</param-name>
+        <param-value>false</param-value>
+    </init-param>
+    <load-on-startup>2</load-on-startup>
+</servlet>
+<servlet-mapping>
+    <servlet-name>WebjarsServlet</servlet-name>
+    <url-pattern>/webjars/*</url-pattern>
+</servlet-mapping>
+----
+
+
+The text of the simple archetype's `about/index.html` has also changed; the `<li`> for the `/restful` URL has been
+replaced with a `/swagger-ui` URL.
+

http://git-wip-us.apache.org/repos/asf/isis/blob/4502dc10/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGenerator.java
----------------------------------------------------------------------
diff --git a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGenerator.java b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGenerator.java
index f1ca3e5..c58ee23 100644
--- a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGenerator.java
+++ b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/SwaggerSpecGenerator.java
@@ -29,6 +29,7 @@ import org.apache.isis.applib.annotation.ActionSemantics;
 import org.apache.isis.applib.annotation.NatureOfService;
 import org.apache.isis.applib.services.swagger.SwaggerService;
 import org.apache.isis.core.commons.factory.InstanceUtil;
+import org.apache.isis.core.metamodel.facets.actcoll.typeof.TypeOfFacet;
 import org.apache.isis.core.metamodel.facets.object.domainservice.DomainServiceFacet;
 import org.apache.isis.core.metamodel.facets.object.mixin.MixinFacet;
 import org.apache.isis.core.metamodel.facets.object.objectspecid.ObjectSpecIdFacet;
@@ -61,6 +62,7 @@ import io.swagger.util.Yaml;
 public class SwaggerSpecGenerator {
 
     private final SpecificationLoader specificationLoader;
+    private final ValuePropertyFactory valuePropertyFactory = new ValuePropertyFactory();
 
     public SwaggerSpecGenerator(final SpecificationLoader specificationLoader) {
         this.specificationLoader = specificationLoader;
@@ -122,7 +124,7 @@ public class SwaggerSpecGenerator {
             appendServicePath(swagger, serviceSpec);
 
             for (final ObjectAction serviceAction : serviceActions) {
-                appendServiceActionInvokePath(swagger, serviceAction);
+                appendServiceActionInvokePath(swagger, serviceSpec, serviceAction);
             }
         }
     }
@@ -157,14 +159,14 @@ public class SwaggerSpecGenerator {
                 continue;
             }
             final ModelImpl isisModel = appendObjectPathAndModelDefinitions(swagger, objectSpec);
-            appendObjectModel(isisModel, objectProperties, objectCollections);
+            updateObjectModel(isisModel, objectSpec, objectProperties, objectCollections);
 
             for (final OneToManyAssociation objectCollection : objectCollections) {
-                appendCollectionTo(swagger, objectCollection);
+                appendCollectionTo(swagger, objectSpec, objectCollection);
             }
 
             for (final ObjectAction objectAction : objectActions) {
-                appendObjectActionInvokePath(swagger, objectAction);
+                appendObjectActionInvokePath(swagger, objectSpec, objectAction);
             }
         }
     }
@@ -258,17 +260,26 @@ public class SwaggerSpecGenerator {
         swagger.addDefinition("LinkModel",
                 new ModelImpl()
                     .type("object")
-                    .property("rel", stringProperty())
-                    .property("href", stringProperty())
-                    .property("title", stringProperty())
-                    .property("method", stringPropertyEnum("GET", "POST", "PUT", "DELETE"))
-                    .property("type", stringProperty())
-                    .property("arguments", new ObjectProperty())
+                    .property("rel", stringProperty().description("the relationship of the resource to this referencing resource"))
+                    .property("href", stringProperty().description("the hyperlink reference (URL) of the resource"))
+                    .property("title", stringProperty().description("title to render"))
+                    .property("method", stringPropertyEnum("GET", "POST", "PUT", "DELETE").description("HTTP verb to access"))
+                    .property("type", stringProperty().description("Content-Type recognized by the resource (for HTTP Accept header)"))
+                    .property("arguments", new ObjectProperty().description("Any arguments, to send as query strings or in body"))
+                    .property("value", stringProperty().description("the representation of the link if followed"))
                     .required("rel")
                     .required("href")
                     .required("method")
         );
 
+        swagger.addDefinition("HrefModel",
+                new ModelImpl()
+                    .type("object")
+                    .description("Abbreviated version of the Link resource, used primarily to reference non-value objects")
+                    .property("href", stringProperty().description("the hyperlink reference (URL) of the resource"))
+                    .required("href")
+        );
+
     }
 
     void appendServicePath(final Swagger swagger, final ObjectSpecification objectSpec) {
@@ -307,8 +318,6 @@ public class SwaggerSpecGenerator {
         final Path path = new Path();
         swagger.path(String.format("/objects/%s/{objectId}", objectType), path);
 
-        final String isisModelDefinition = objectType + "Model";
-        final String restfulObjectsModelDefinition = objectType + "RestfulObjectsModel";
         final String tag = objectType.startsWith("org.apache.isis")? "> apache isis internals": objectType;
         final Operation operation = new Operation();
         path.get(
@@ -328,6 +337,7 @@ public class SwaggerSpecGenerator {
         // per https://github.com/swagger-api/swagger-spec/issues/146, swagger 2.0 doesn't support multiple
         // modelled representations per path and response code;
         // in particular cannot associate representation/model with Accept header ('produces(...) method)
+        final String restfulObjectsModelDefinition = objectType + "RestfulObjectsModel";
         if (false) {
             operation.response(200,
                     newResponse(Caching.TRANSACTIONAL)
@@ -343,13 +353,12 @@ public class SwaggerSpecGenerator {
             swagger.addDefinition(restfulObjectsModelDefinition, roSpecModel);
         }
 
+        final String isisModelDefinition = objectType + "Model";
         operation
                 .response(200,
                         newResponse(Caching.TRANSACTIONAL)
-                                .description("if Accept: application/json;profile=urn:org.apache.isis/v1")
-                                .schema(new RefProperty("#/definitions/"
-                                        + isisModelDefinition)));
-
+                                .description(objectType + " , if Accept: application/json;profile=urn:org.apache.isis/v1")
+                                .schema(new RefProperty("#/definitions/" + isisModelDefinition)));
 
         final ModelImpl isisModel = new ModelImpl();
         swagger.addDefinition(isisModelDefinition, isisModel);
@@ -380,9 +389,9 @@ public class SwaggerSpecGenerator {
 
     void appendServiceActionInvokePath(
             final Swagger swagger,
+            final ObjectSpecification serviceSpec,
             final ObjectAction serviceAction) {
 
-        final ObjectSpecification serviceSpec = serviceAction.getOnType();
         final String serviceId = serviceIdFor(serviceSpec);
         final String actionId = serviceAction.getId();
 
@@ -457,16 +466,55 @@ public class SwaggerSpecGenerator {
         invokeOperation
                 .response(
                         200, new Response()
-                                .description(roSpecForResponseOf(serviceAction) + ": (invoke) representation of " + serviceId + "#" + actionId)
-                                .schema(new ObjectProperty())
+                                .description(serviceId + "#" + actionId + " , if Accept: application/json;profile=urn:org.apache.isis/v1")
+                                .schema(actionReturnTypeFor(serviceAction))
                 );
     }
 
+    void appendCollectionTo(
+            final Swagger swagger,
+            final ObjectSpecification objectSpec,
+            final OneToManyAssociation collection) {
+
+        final String objectType = objectTypeFor(objectSpec);
+        final String collectionId = collection.getId();
+
+        final Path path = new Path();
+        swagger.path(String.format("/objects/%s/{objectId}/collections/%s", objectType, collectionId), path);
+
+        final Operation collectionOperation =
+                new Operation()
+                        .tag(objectType)
+                        .description(Util.roSpec("17.1") + ": resource of " + objectType + "#" + collectionId)
+                        .parameter(
+                                new PathParameter()
+                                        .name("objectId")
+                                        .type("string"))
+                        .produces("application/json;profile=urn:org.apache.isis/v1")
+                        .produces("application/json;profile=urn:org.apache.isis/v1;suppress=true")
+                        .produces("application/json;profile=urn:org.restfulobjects:repr-types/object-collection");
+
+        path.get(collectionOperation);
+        collectionOperation
+                .response(
+                        200, new Response()
+                                .description(objectType + "#" + collectionId + " , if Accept: application/json;profile=urn:org.apache.isis/v1")
+                                .schema(modelFor(collection))
+                );
+    }
+
+    private Property modelFor(final OneToManyAssociation collection) {
+        ObjectSpecification collectionSpecification = collection.getSpecification();
+        return new ArrayProperty()
+                .description("List of " + objectTypeFor(collectionSpecification))
+                    .items(modelFor(collectionSpecification));
+    }
+
     void appendObjectActionInvokePath(
             final Swagger swagger,
+            final ObjectSpecification objectSpec,
             final ObjectAction objectAction) {
 
-        final ObjectSpecification objectSpec = objectAction.getOnType();
         final String objectType = objectTypeFor(objectSpec);
         final String actionId = objectAction.getId();
 
@@ -544,19 +592,97 @@ public class SwaggerSpecGenerator {
         invokeOperation
                 .response(
                         200, new Response()
-                                .description(roSpecForResponseOf(objectAction) + ": (invoke) representation of " + objectType + "#" + actionId)
-                                .schema(new ObjectProperty())
+                                .description(objectType + "#" + actionId)
+                                .schema(actionReturnTypeFor(objectAction))
                 );
     }
 
-    void appendCollectionTo(final Swagger members, final OneToManyAssociation serviceAction) {
+    Property actionReturnTypeFor(final ObjectAction objectAction) {
+
+        final ObjectSpecification specification = objectAction.getReturnType();
+        TypeOfFacet typeOfFacet = objectAction.getFacet(TypeOfFacet.class);
+        if(typeOfFacet != null) {
+            ObjectSpecification elementSpec = typeOfFacet.valueSpec();
+            if(elementSpec != null) {
+                return new ArrayProperty()
+                        .items(modelFor(elementSpec));
+            }
+        }
+        return modelFor(specification);
+    }
+
+    private Property modelFor(final ObjectSpecification specification) {
+        if(specification == null) {
+            return new ObjectProperty();
+        }
+
+        // no "simple" representation for void or values
+        final Class<?> correspondingClass = specification.getCorrespondingClass();
+        if(correspondingClass == void.class || correspondingClass == Void.class) {
+            return new ObjectProperty();
+        }
+        // no "simple" representation for values
+        final Property property = valuePropertyFactory.newProperty(correspondingClass);
+        if(property != null) {
+            // was recognized as a value
+            return new ObjectProperty();
+        }
+
+        if(specification.isParentedOrFreeCollection()) {
+            TypeOfFacet typeOfFacet = specification.getFacet(TypeOfFacet.class);
+            if(typeOfFacet != null) {
+                ObjectSpecification elementSpec = typeOfFacet.valueSpec();
+                if(elementSpec != null) {
+                    return new ArrayProperty()
+                            .items(modelFor(elementSpec));
+                }
+            }
+        }
 
+        return new RefProperty("#/definitions/" + objectTypeFor(specification) + "Model");
     }
 
-    void appendObjectModel(
-            final ModelImpl swagger,
-            final List<OneToOneAssociation> objectProperties, final List<OneToManyAssociation> objectCollections) {
+    void updateObjectModel(
+            final ModelImpl model,
+            final ObjectSpecification objectSpecification,
+            final List<OneToOneAssociation> objectProperties,
+            final List<OneToManyAssociation> objectCollections) {
 
+        final String objectType = objectTypeFor(objectSpecification);
+        final String className = objectSpecification.getFullIdentifier();
+
+        model
+                .type("object")
+                .description(String.format("%s (%s)", objectType, className));
+
+        for (OneToOneAssociation objectProperty : objectProperties) {
+            model.property(
+                    objectProperty.getId(),
+                    propertyFor(objectProperty.getSpecification()));
+        }
+
+        for (OneToManyAssociation objectCollection : objectCollections) {
+            final ObjectSpecification elementSpec = objectCollection.getSpecification();
+            final String elementModelDefinition = objectTypeFor(elementSpec) + "Model";
+
+            model.property(
+                    objectCollection.getId(),
+                    new ArrayProperty()
+                    .items(new RefProperty("#/definitions/" + elementModelDefinition))
+            );
+        }
+    }
+
+    Property propertyFor(final ObjectSpecification objectSpecification) {
+        final Property property =
+                valuePropertyFactory.newProperty(objectSpecification.getCorrespondingClass());
+        if (property != null) {
+            return property;
+        }
+        else {
+            // assume this is a reference to an entity/view model, meaning we use an href
+            return refToHrefModel();
+        }
     }
 
     static String roSpecForResponseOf(final ObjectAction action) {
@@ -608,7 +734,15 @@ public class SwaggerSpecGenerator {
 
     static ArrayProperty arrayOfLinks() {
         return new ArrayProperty()
-                .items(new RefProperty("#/definitions/LinkModel"));
+                .items(refToLinkModel());
+    }
+
+    static RefProperty refToLinkModel() {
+        return new RefProperty("#/definitions/LinkModel");
+    }
+
+    static RefProperty refToHrefModel() {
+        return new RefProperty("#/definitions/HrefModel");
     }
 
     static ArrayProperty arrayOfStrings() {

http://git-wip-us.apache.org/repos/asf/isis/blob/4502dc10/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/ValuePropertyFactory.java
----------------------------------------------------------------------
diff --git a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/ValuePropertyFactory.java b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/ValuePropertyFactory.java
new file mode 100644
index 0000000..c00990e
--- /dev/null
+++ b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/swagger/internal/ValuePropertyFactory.java
@@ -0,0 +1,174 @@
+/*
+ *  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.
+ */
+package org.apache.isis.core.metamodel.services.swagger.internal;
+
+import java.math.BigDecimal;
+import java.math.BigInteger;
+import java.util.Map;
+import java.util.UUID;
+
+import com.google.common.collect.Maps;
+
+import org.joda.time.DateTime;
+import org.joda.time.LocalDate;
+import org.joda.time.LocalDateTime;
+
+import io.swagger.models.properties.BooleanProperty;
+import io.swagger.models.properties.ByteArrayProperty;
+import io.swagger.models.properties.DateProperty;
+import io.swagger.models.properties.DateTimeProperty;
+import io.swagger.models.properties.DecimalProperty;
+import io.swagger.models.properties.DoubleProperty;
+import io.swagger.models.properties.FloatProperty;
+import io.swagger.models.properties.IntegerProperty;
+import io.swagger.models.properties.LongProperty;
+import io.swagger.models.properties.Property;
+import io.swagger.models.properties.StringProperty;
+import io.swagger.models.properties.UUIDProperty;
+
+public class ValuePropertyFactory {
+
+    private final Map<Class, Factory> propertyFactoryByClass = Maps.newHashMap();
+
+    static interface Factory {
+        Property newProperty();
+    }
+    public ValuePropertyFactory() {
+
+        final Factory booleanFactory = new Factory() {
+            @Override
+            public Property newProperty() {
+                return new BooleanProperty();
+            }
+        };
+        propertyFactoryByClass.put(boolean.class, booleanFactory);
+        propertyFactoryByClass.put(Boolean.class, booleanFactory);
+
+        final Factory integerFactory = new Factory() {
+            @Override
+            public Property newProperty() {
+                return new IntegerProperty();
+            }
+        };
+        propertyFactoryByClass.put(byte.class, integerFactory);
+        propertyFactoryByClass.put(Byte.class, integerFactory);
+        propertyFactoryByClass.put(short.class, integerFactory);
+        propertyFactoryByClass.put(Short.class, integerFactory);
+        propertyFactoryByClass.put(int.class, integerFactory);
+        propertyFactoryByClass.put(Integer.class, integerFactory);
+        propertyFactoryByClass.put(BigInteger.class, integerFactory);
+
+        final Factory longFactory = new Factory() {
+            @Override
+            public Property newProperty() {
+                return new LongProperty();
+            }
+        };
+        propertyFactoryByClass.put(long.class, longFactory);
+        propertyFactoryByClass.put(Long.class, longFactory);
+        propertyFactoryByClass.put(java.sql.Timestamp.class, longFactory);
+
+        final Factory decimalFactory = new Factory() {
+            @Override
+            public Property newProperty() {
+                return new DecimalProperty();
+            }
+        };
+        propertyFactoryByClass.put(BigDecimal.class, decimalFactory);
+
+        final Factory floatFactory = new Factory() {
+            @Override
+            public Property newProperty() {
+                return new FloatProperty();
+            }
+        };
+        propertyFactoryByClass.put(float.class, floatFactory);
+        propertyFactoryByClass.put(Float.class, floatFactory);
+
+        final Factory doubleFactory = new Factory() {
+            @Override
+            public Property newProperty() {
+                return new DoubleProperty();
+            }
+        };
+        propertyFactoryByClass.put(double.class, doubleFactory);
+        propertyFactoryByClass.put(Double.class, doubleFactory);
+
+        final Factory stringFactory = new Factory() {
+            @Override
+            public Property newProperty() {
+                return new StringProperty();
+            }
+        };
+        propertyFactoryByClass.put(char[].class, stringFactory);
+        propertyFactoryByClass.put(String.class, stringFactory);
+
+        final Factory uuidFactory = new Factory() {
+            @Override
+            public Property newProperty() {
+                return new UUIDProperty();
+            }
+        };
+        propertyFactoryByClass.put(UUID.class, uuidFactory);
+
+        final Factory dateTimeFactory = new Factory() {
+            @Override
+            public Property newProperty() {
+                return new DateTimeProperty();
+            }
+        };
+        propertyFactoryByClass.put(java.util.Date.class, dateTimeFactory);
+        propertyFactoryByClass.put(DateTime.class, dateTimeFactory);
+        propertyFactoryByClass.put(LocalDateTime.class, dateTimeFactory);
+        propertyFactoryByClass.put(org.apache.isis.applib.value.DateTime.class, dateTimeFactory);
+
+        final Factory dateFactory = new Factory() {
+            @Override
+            public Property newProperty() {
+                return new DateProperty();
+            }
+        };
+        propertyFactoryByClass.put(java.sql.Date.class, dateFactory);
+        propertyFactoryByClass.put(LocalDate.class, dateFactory);
+        propertyFactoryByClass.put(org.apache.isis.applib.value.Date.class, dateFactory);
+
+        final Factory byteArrayFactory = new Factory() {
+            @Override
+            public Property newProperty() {
+                return new ByteArrayProperty();
+            }
+        };
+        propertyFactoryByClass.put(byte[].class, byteArrayFactory);
+        propertyFactoryByClass.put(org.apache.isis.applib.value.Blob.class, byteArrayFactory);
+    }
+
+    public Property newProperty(Class<?> cls) {
+        if(cls == null) {
+            return null;
+        }
+
+        final Factory factory = propertyFactoryByClass.get(cls);
+        if(factory != null) {
+            return factory.newProperty();
+        }
+
+        return null;
+    }
+
+}

http://git-wip-us.apache.org/repos/asf/isis/blob/4502dc10/example/application/simpleapp/dom/src/main/java/domainapp/dom/simple/SimpleObject.java
----------------------------------------------------------------------
diff --git a/example/application/simpleapp/dom/src/main/java/domainapp/dom/simple/SimpleObject.java b/example/application/simpleapp/dom/src/main/java/domainapp/dom/simple/SimpleObject.java
index 98a485d..bee0af9 100644
--- a/example/application/simpleapp/dom/src/main/java/domainapp/dom/simple/SimpleObject.java
+++ b/example/application/simpleapp/dom/src/main/java/domainapp/dom/simple/SimpleObject.java
@@ -18,10 +18,14 @@
  */
 package domainapp.dom.simple;
 
+import java.util.List;
+
 import javax.jdo.JDOHelper;
 import javax.jdo.annotations.IdentityType;
 import javax.jdo.annotations.VersionStrategy;
 
+import com.google.common.collect.Lists;
+
 import org.apache.isis.applib.DomainObjectContainer;
 import org.apache.isis.applib.annotation.Action;
 import org.apache.isis.applib.annotation.BookmarkPolicy;
@@ -112,6 +116,11 @@ public class SimpleObject implements Comparable<SimpleObject> {
     }
 
 
+    public List<SimpleObject> getOthers() {
+        return Lists.newArrayList();
+    }
+
+
     /**
      * version (derived property)
      */

http://git-wip-us.apache.org/repos/asf/isis/blob/4502dc10/example/application/simpleapp/webapp/src/main/webapp/about/index.html
----------------------------------------------------------------------
diff --git a/example/application/simpleapp/webapp/src/main/webapp/about/index.html b/example/application/simpleapp/webapp/src/main/webapp/about/index.html
index b14a4b3..d243565 100644
--- a/example/application/simpleapp/webapp/src/main/webapp/about/index.html
+++ b/example/application/simpleapp/webapp/src/main/webapp/about/index.html
@@ -73,7 +73,7 @@ th, td {
                         <b><a href="wicket/">wicket/</a></b>
                     </p>
                     <p>
-                        provides accesses to a generic UI for end-users,
+                        provides access to a generic UI for end-users,
                         Isis' <a href="http://isis.apache.org/components/viewers/wicket/about.html" target="_blank">Wicket Viewer</a>.
                         As its name suggests, this viewer is built on top of <a href="http://wicket.apache.org" target="_blank">Apache Wicket</a>&trade;.
                     </p>
@@ -85,14 +85,17 @@ th, td {
                         </b>
                     </p>
                     <p>
-                        provides the Swagger UI access to RESTful API, consuming dynamically generated Swagger
-                        specification files.  There are three versions of this API: <a href="restful/swagger/public">public</a> (third-party) use, for <a href="restful/swagger/private">private</a> (internal) use, and extended version of the private API
-                        that includes <a href="restful/swagger/prototyping">prototyping</a> actions.
+                        provides access to a Swagger UI which uses a subset of the framework's automatically
+                        generated <a href="restful/">RESTful API</a>.  There are three versions of the Swagger
+                        spec files (that drive the UI): <a href="restful/swagger/public">public</a> (for use by
+                        "third-party" apps), <a href="restful/swagger/private">private</a> (for use by internal apps),
+                        and <a href="restful/swagger/prototyping">prototyping</a> (an extended version of the private
+                        API).  The Swagger spec files are themselves dynamically generated and can be used to generate
+                        client-side stubs.
                     </p>
-                    <p>The RESTful API can return both simple representations (suitable for use within custom apps),
-                        and also a richer hypermedia API conformant with the
-                        <a href="http://restfulobjects.org">Restful Objects</a> spec.  The HTTP <code>Accept</code> header
-                        is used to select which representation is required.
+                    <p>The RESTful API can return both simple representations and also richer hypermedia representations
+                        that are conformant with the <a href="http://restfulobjects.org">Restful Objects</a> spec.
+                        The HTTP <code>Accept</code> header is used to select which representation should be generated.
                     </p>
                 </li>
             </ul>